Golden Hour / Sun Position Calculator mechanism

Model scope

The concept is scientifically reasonable, but the spec is not deterministic enough to verify as written. It needs one exact algorithm/version, explicit blue-hour and golden-hour conventions, a defined azimuth reference, a timezone/DST contract, and documented polar-event behavior. The test vectors use a reduced, fully stated model so their arithmetic is independently reproducible; they are not a substitute for specifying the production NOAA/Meeus implementation.

• “NOAA/Meeus solar position equations” identifies a family of algorithms, not one deterministic formula; the exact declination, equation-of-time, sidereal-time, refraction, and azimuth equations are unspecified.
• Golden hour is not fully defined by “elevation between -4° and 6°”: the start/end ordering, morning/evening windows, and whether the interval is clipped at sunrise/sunset are unspecified. It is not necessarily one hour.
• Blue hour has no stated elevation thresholds. A common convention is -6° to -4°, but that must be explicitly declared.
• Timezone handling is underspecified: the input needs an IANA timezone or an explicit UTC offset plus daylight-saving-date behavior. Longitude alone does not determine civil clock time.
• The date/calendar convention, time scale, equation-of-time treatment, and handling of dates near the International Date Line are unspecified.
• Solar azimuth convention is unspecified; it should state whether azimuth is degrees clockwise from true north, magnetic north, or another convention.

Units and conventions

• Latitude and longitude are decimal degrees; north and east are positive.
• Times in the test vectors use the stated civil timezone, including the stated fixed UTC offset and no DST unless explicitly noted.
• For deterministic checks below, the reduced standard solar-geometry model is used: solar declination is the stated value, equation of time is 0, atmospheric sunrise elevation is -0.833°, and solar elevation is asin(sin(latitude)sin(declination)+cos(latitude)cos(declination)cos(hour angle)).
• Hour angle is 15° per solar hour, with solar noon at hour angle 0°.
• Golden-hour thresholds are interpreted as the window from elevation -4° through +6°; blue-hour thresholds are explicitly set to -6° through -4° for these test vectors.
• Azimuth, where supplied, is degrees clockwise from true north. Times are rounded to the nearest second; decimal-hour arithmetic is shown.

Inspectable vector

One of 4 source-bound review vectors:

{
  "inputs": {
    "latitude_deg": 0,
    "longitude_deg": 0,
    "date": "2025-03-20",
    "timezone": "UTC",
    "declination_deg": 0,
    "equation_of_time_min": 0,
    "blue_hour_thresholds_deg": [
      -6,
      -4
    ],
    "golden_hour_thresholds_deg": [
      -4,
      6
    ],
    "algorithm_assumptions": "reduced model stated in unit_assumptions"
  },
  "expected_outputs": {
    "sunrise": "05:56:40 UTC",
    "sunset": "18:03:20 UTC",
    "golden_hour_morning": "05:44:00–06:24:00 UTC",
    "golden_hour_evening": "17:36:00–18:16:00 UTC",
    "blue_hour_morning": "05:36:00–05:44:00 UTC",
    "blue_hour_evening": "18:16:00–18:24:00 UTC",
    "curve_samples": [
      {
        "utc": "09:00",
        "elevation_deg": 45,
        "azimuth_deg": 90
      },
      {
        "utc": "15:00",
        "elevation_deg": 45,
        "azimuth_deg": 270
      }
    ]
  },
  "working": "At the equator with declination 0°, sin(elevation)=cos(hour angle). Sunrise: cos(H)=sin(-0.833°)=-0.01454, so H=acos(-0.01454)=90.833°. Time from noon=90.833/15=6.05553 h, hence sunrise=12-6.05553=5.94447 h=05:56:40 and sunset=18.05553 h=18:03:20. For +6°: H=acos(sin 6°)=acos(0.104528)=84°, giving 12-84/15=6.40000 h and 17.60000 h. For -4°: H=acos(sin -4°)=acos(-0.069756)=94°, giving 5.73333 h and 18.26667 h. For -6°: H=acos(-0.104528)=96°, giving 5.60000 h and 18.40000 h. At 09:00, H=-45°, elevation=asin(cos(-45°))=45°; before solar noon the equatorial azimuth is 90°. At 15:00, H=+45°, elevation=45° and azimuth=270°."
}

Failure boundary

• Division by zero or invalid inverse-trigonometric arguments can occur if an implementation does not clamp floating-point values to [-1,1] or mishandles polar-day/polar-night cases.
• A fixed -0.833° sunrise altitude mixes geometric altitude with an atmospheric-refraction and solar-radius convention; the same convention must be used consistently for event times.
• Near the poles, event ordering and date assignment can be discontinuous; null or all-day statuses need an explicit schema.
• Longitude degrees, UTC offsets, and hours must not be mixed without the factor 15 degrees per hour or 4 minutes per degree.
• Automatic CoreLocation fill is unavailable in pure offline mode unless the operating system supplies the location; the calculator should clearly distinguish unavailable location from a computed result.
• No local terrain or obstruction model is included, consistent with the honest label, but the UI should not present calculated sunrise or golden-hour times as observed local visibility.

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche6/tranche6-results.json