"use strict";

function round2(x) { return Math.round(x * 100) / 100; }
const DEG2RAD = Math.PI / 180;
const RAD2DEG = 180 / Math.PI;

function dayLengthHours(latDeg, decDeg) {
  const cosH = -Math.tan(latDeg * DEG2RAD) * Math.tan(decDeg * DEG2RAD);
  if (cosH <= -1) return 24; // midnight sun
  if (cosH >= 1) return 0; // polar night
  const hDeg = Math.acos(cosH) * RAD2DEG;
  return (2 * hDeg) / 15; // 15 degrees of hour angle per hour
}

module.exports = {
  slug: "day-length-from-latitude-and-declination",
  title: "Day length from latitude and solar declination",
  deck_category: "astronomy",
  description: "Estimates the length of daylight for a given latitude and solar declination using the simple sunrise-equation hour angle.",
  inputs: [
    { name: "latitude_deg", type: "number", unit: "degrees", required: true, description: "Latitude, positive north, negative south.", min: -90, max: 90 },
    { name: "declination_deg", type: "number", unit: "degrees", required: true, description: "Solar declination for the date (see the sun-declination-by-day-of-year card).", min: -23.45, max: 23.45 }
  ],
  outputs: [
    { name: "day_length_hours", unit: "hours", description: "Estimated hours of daylight from sunrise to sunset." }
  ],
  steps: [
    "Sunrise equation: cos(H) = -tan(latitude) * tan(declination), where H is the hour angle of sunrise/sunset in degrees.",
    "If the product makes cos(H) <= -1, the location has continuous daylight (midnight sun); if cos(H) >= 1, continuous night (polar night).",
    "Otherwise H = arccos(cos(H)) in degrees.",
    "Day length in hours = 2 * H / 15, because Earth's rotation moves the hour angle 15 degrees per hour.",
    "Round to 2 decimals.",
    "This is the simple, geometric-horizon classroom version (it ignores atmospheric refraction and the sun's angular radius, both of which the estate's own sunrise card handles with the full NOAA method); treat this card's output as an approximation good to a few minutes."
  ],
  constants: [
    { name: "degrees_per_hour", value: 15, unit: "degrees/hour", source: 0 }
  ],
  sources: [
    { kind: "edition_page", value: "Duffie, J.A. and Beckman, W.A. Solar Engineering of Thermal Processes, 4th ed. Wiley, 2013, eq. 1.6.10.", title: "Solar Engineering of Thermal Processes, 4th ed., the sunrise equation", publisher: "Wiley", retrieved_utc: "2026-09-30T19:43:00Z", note: "Standard textbook derivation of cos(H) = -tan(latitude)*tan(declination)." }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `Using the simple sunrise-equation hour angle, what is the approximate day length at latitude ${inputs.latitude_deg} degrees when the solar declination is ${inputs.declination_deg} degrees?`;
  },
  run(inputs) {
    const lat = inputs && inputs.latitude_deg;
    const dec = inputs && inputs.declination_deg;
    if (typeof lat !== "number" || lat < -90 || lat > 90) throw new Error("latitude_deg must be a number between -90 and 90");
    if (typeof dec !== "number" || dec < -23.45 || dec > 23.45) throw new Error("declination_deg must be a number between -23.45 and 23.45");
    const hours = round2(dayLengthHours(lat, dec));
    return { answer: `${hours.toFixed(2)} hours`, values: { day_length_hours: hours } };
  },
  examples: [
    {
      name: "worked example",
      inputs: { latitude_deg: 40, declination_deg: 23.45 },
      expected: { answer: "14.85 hours" },
      check: "By hand: tan(40deg)=0.8391, tan(23.45deg)=0.4335, product=0.3638, so cos(H)=-0.3638, H=acos(-0.3638)=111.34 degrees, day length=2*111.34/15=14.85 hours, consistent with the well known fact that New York City (about 40N) has roughly 15 hours of daylight at the June solstice."
    },
    {
      name: "test vector: winter solstice at the same latitude",
      inputs: { latitude_deg: 40, declination_deg: -23.45 },
      expected: { answer: "9.15 hours" },
      check: "By hand: tan(40deg)*tan(-23.45deg)=-0.3638, so cos(H)=0.3638, H=acos(0.3638)=68.66 degrees, day length=2*68.66/15=9.15 hours, consistent with the well known fact that New York City has roughly 9 hours of daylight at the December solstice."
    }
  ]
};