Daily eclipse and Sutak field

panchangam.eclipse-sutak

The range-calendar eclipse result is attached to the local Panchangam day.

Assurance

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

Computation method

Method type: algorithm

Each engine conditionally requests the canonical location-aware eclipse calculation for the civil date and attaches the returned EclipseInfo unchanged to PanchangamDay.

Process

1. When include_eclipse is false, skip the lookup and attach null.
2. Otherwise pass the input civil date and Location to get_eclipse_for_date.
3. The canonical calculator keeps an event only when its maximum falls within the location's two civil-midnight Julian bounds.
4. Attach kind, subtype, visibility, UTC phase instants, and visibility-dependent Sutak fields to the day.
5. Presentation layers convert UTC instants to the requested timezone.

Worked example

Hyderabad, 2026-02-17

Inputs

• include_eclipse=true
• Canonical event: annular solar eclipse
• Local visibility: false

Calculation

1. The event maximum falls within the Hyderabad civil date, so attach EclipseInfo.
2. Because it is not locally visible, leave Sutak start/end null.

Result

• kind=Solar; subtype=Annular; visible=false
• sutak_start=null; sutak_end=null

Method notes

• This page documents day attachment; astronomical search, visibility, and Sutak calculation are separately inventoried.

Contract

Owning layer: engine-core
Claim kind: deterministic-fact
Time basis: Local Panchangam date with UTC event instants converted for presentation.

Inputs

• date
• location
• calendar eclipse result

Outputs

• PanchangamDay.eclipse

References and evidence

Evidence classes: astronomical, textual
Verification states: engine_pinned

This is the daily projection of the canonical eclipse calculation.

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
• tests/test_integration.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

• This record owns attachment to the day; event calculation is separately inventoried.

Implementation

• owner: telugu_panchangam/engines/drik.py — DrikGanitaEngine.calculate
• owner: telugu_panchangam/engines/surya_siddhanta.py — SuryaSiddhantaEngine.calculate
• owner: telugu_panchangam/engines/vakya.py — VakyaEngine.calculate

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