Astronomical Twilight Duration implementation

Binding contract

This record describes what an executable surface must bind and validate. It does not claim that a public calculator, package, or production route is deployed.

Record owner

Guth Instruments

Lifecycle

verified-with-binding-errata

Evidence ID

t6-090

Effect

Computation or source lookup only

Input and validation requirements

• Missing timezone or explicit UTC output can shift every displayed time by hours.
• Longitude sign convention and degree-versus-radian handling must be validated; a 180° longitude is an especially important wraparound case.
• The hour-angle formula divides by cos(latitude)cos(declination); it becomes singular or numerically unstable near the poles and must use an explicit no-event/continuous-event policy.
• Each threshold requires checking whether the computed acos argument lies in [-1,1]. Outside that interval, the corresponding twilight event does not occur rather than producing NaN or a fabricated time.
• Near the poles and near threshold boundaries, floating-point rounding can incorrectly switch between an event and no event.
• Atmospheric refraction, elevation above sea level, solar radius, and terrain horizon can change event times by more than the claimed one-minute accuracy.
• Date handling must include leap years, UTC date boundaries, and equation-of-time/date conversion. A date without timezone and calendar specification is not sufficient.
• The honest label should say approximately one minute only after the exact solar-position algorithm and environmental assumptions are documented; otherwise the accuracy claim is unsupported.

Required corrections

[
  {
    "vector": "3,4",
    "field": "civil/astronomical hour_angle_deg",
    "wrong": "98.503 / 115.921",
    "correct": "98.5009 / 115.9136",
    "cause": "micro acos slips at lat 45; nautical is exact"
  }
]

Inspectable interface fixture

The sample below is evidence for interface and validation tests, not a production implementation.

{
  "inputs": {
    "lat_deg": 0,
    "lon_deg": 0,
    "date": "idealized_equinox",
    "solar_declination_deg": 0,
    "timezone": "UTC",
    "model": "geometric hour-angle check"
  },
  "expected_outputs": {
    "civil": {
      "begin": "05:36:00 UTC",
      "end": "18:24:00 UTC",
      "hour_angle_deg": 96
    },
    "nautical": {
      "begin": "05:12:00 UTC",
      "end": "18:48:00 UTC",
      "hour_angle_deg": 102
    },
    "astronomical": {
      "begin": "04:48:00 UTC",
      "end": "19:12:00 UTC",
      "hour_angle_deg": 108
    }
  },
  "working": "For latitude 0° and declination 0°, sin(phi)sin(delta)=0 and cos(phi)cos(delta)=1, so cos(H)=cos(Z). Therefore H=Z. Civil: Z=90°+6°=96°; 96°/15=6.4 h=6 h 24 min, so 12:00-06:24=05:36 and 12:00+06:24=18:24. Nautical: Z=102°; 102/15=6.8 h=6 h 48 min, so 05:12 and 18:48. Astronomical: Z=108°; 108/15=7.2 h=7 h 12 min, so 04:48 and 19:12."
}

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
• tranche errata record