Panchangam Reference

Festival date rules ​

panchangam.festivals

Moment-specific Amanta month, Tithi, weekday, and specialty rules select named festivals.

Assurance ​

LevelCurrent statement
Documented and traceableYes — the canonical record includes the process and a worked example.
Regression or reproduction checkedLinked to 2 repository test file(s).
Independently source-supportedPartial support only; read the provenance note and limitations before generalizing.

Computation method ​

Method type: decision-table

Evaluate maintained Telugu festival rules at each rule family's deciding instant, suppress duplicate day assignment, handle Amanta rollover and Adhika exclusions, and add monthly and solar-ingress observances.

Process ​

  1. Add the Makara Sankranti cluster from solar-ingress day assignment.
  2. For non-Adhika months, evaluate sunrise rules directly and Madhyahna, Aparahna, Pradosha, and Nishita tables at their configured instants.
  3. For moment rules, require the target Tithi now but not at the same moment one day earlier; when sunrise is Amavasya and Pratipat begins by the moment, advance the Amanta month.
  4. Evaluate weekday-in-month and last-weekday-in-Paksha rules.
  5. Evaluate moonrise and Nishita monthly Vratas even in Adhika months, with annual-variant suppression.

Formulae ​

Deciding instants ​

text
Madhyahna = sunrise + 0.5 * daylight
Aparahna = sunrise + 0.7 * daylight
Pradosha = sunset + 0.05 day
Nishita = (sunset + next_sunrise) / 2
  • daylight: sunset - sunrise
  • 0.05 day: 72 clock minutes

Worked example ​

Ugadi, Hyderabad 2026-03-19 ​

Inputs

  • Sunrise Maasam/Tithi: Phalguna Amavasya, index 29
  • Madhyahna Tithi: Shukla Pratipat, index 0
  • Same moment previous day: index 29

Calculation

  1. Ugadi is the Chaitra index-0 Madhyahna rule.
  2. Because sunrise was Amavasya and Pratipat began by Madhyahna, advance moment Maasam from Phalguna to Chaitra.
  3. Previous-day Madhyahna was not index 0, so first-day suppression passes.

Result

  • Festival list includes Ugadi on 2026-03-19

Method notes ​

  • The forward-year fixture mixes independently compared and engine-pinned cells.
  • The tables implement maintained Telugu/Amanta conventions, not a universal regional calendar.

Contract ​

Owning layer: engine-core
Claim kind: regional-convention
Time basis: Festival-specific sunrise, Madhyahna, Aparahna, Pradosha, Nishita, or moonrise rule.

Inputs ​

  • Maasam
  • Tithi at deciding moments
  • weekday
  • adjacent-day facts

Outputs ​

  • festival names

References and evidence ​

Evidence classes: published_panchangam, regional_convention
Verification states: partially_verified

Individual 2026 rules have comparisons; the forward-year fixture contains mixed independent and engine-pinned cells.

festivals.forward_year_2027_2028 ​

Evidence class: published_panchangam
Verification state: partially_verified
Locator: 1 DP_VERIFIED cell; 29 ENGINE_PINNED cells in the fixture

Scope: Only cells marked DP_VERIFIED are independently verified.

Sources ​

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 ​

Run the linked tests, then the complete offline contract:

bash
python tools/verify_project.py

Public surfaces ​

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

Limitations ​

  • The table follows documented Telugu conventions and is not a universal regional festival calendar.

Implementation ​

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