Solar and lunar eclipse events

calendar.eclipse-events

Global eclipse searches are combined with per-location visibility and Sutak timing.

Assurance

Level	Current statement
Documented and traceable	Yes — the canonical record includes the process and a worked example.
Regression or reproduction checked	Linked to 1 repository test file(s).
Independently source-supported	Not independently verified at this level; current behavior is regression-pinned.

Computation method

Method type: algorithm

Find Swiss Ephemeris global eclipse phases, assign them to the observer's local civil day, test local visibility, and add Sutak only for a visible event.

Process

1. Search solar and lunar global events and decode subtype bits.
2. Keep an event only when its maximum falls between local midnight and the next local midnight.
3. For solar eclipses, require a matching local eclipse maximum; for lunar eclipses, sample Moon altitude across the phase window and require at least one sample above the horizon.
4. Convert phase boundaries to UTC.
5. If visible, start Sutak 12 hours before solar first contact or 9 hours before lunar first contact and end it at the eclipse end; otherwise leave Sutak null.

Formulae

Visible-event Sutak

sutak_start = eclipse_start - H/24 day; sutak_end = eclipse_end

• H: 12 hours for Solar, 9 hours for Lunar

Worked example

Total lunar eclipse, Hyderabad 2026-03-03

Inputs

• Observer: Hyderabad at zero modeled altitude
• Event kind: Lunar
• Subtype: Total

Calculation

1. At least one of ten sampled instants has Moon altitude above zero, so the event is locally visible.
2. Subtract 9 hours from phase start 09:50:06 UTC.

Result

• Eclipse: 09:50:06-13:17:18 UTC
• Sutak: 00:50:06-13:17:18 UTC

Method notes

• A visible late partial phase is sufficient for lunar visibility even when maximum occurs before local moonrise.

Contract

Owning layer: calendar
Claim kind: deterministic-fact
Time basis: Swiss Ephemeris UTC events; Sutak is a fixed pre-end interval when locally visible.

Inputs

• date or Julian-day range
• observer latitude and longitude

Outputs

• eclipse kind and subtype
• visibility
• start and end
• Sutak window

References and evidence

Evidence classes: astronomical, textual
Verification states: engine_pinned

Event calculations are regression-pinned; the Sutak convention is a separate textual claim.

panchangam.eclipse_events

Evidence class: astronomical
Verification state: engine_pinned
Locator: tests/test_eclipses.py

Scope: The eclipse event pipeline is regression-tested against Swiss Ephemeris calculations. The ledger does not yet contain an independent event-by-event comparison fixture, so this is engine-pinned rather than externally verified.

Sources

• Swiss Ephemeris — Astrodienst; Swiss Ephemeris 2.10 Programmer's Documentation and pyswisseph runtime used by the repository; authority type: astronomical_reference

The complete machine-readable source registry is available in provenance.json. A regression fixture or same-code reproduction is not independent verification.

Reproduce and review

• tests/test_eclipses.py

Run the linked tests, then the complete offline contract:

python tools/verify_project.py

Public surfaces

• python-library
• mcp
• ics
• website
• generated-data

Limitations

• Local visibility is modeled and Sutak is omitted when the eclipse is not visible, but the current observer altitude is fixed to zero.

Implementation

• owner: telugu_panchangam/eclipses.py — list_eclipses_in_range
• owner: telugu_panchangam/eclipses.py — get_eclipse_from_precomputed
• owner: telugu_panchangam/eclipses.py — get_eclipse_for_date

This route is generated from computations.json. Edit the registry and canonical reference prose in the same pull request as a behavior change.