# calendar-data: the astronomical engine

Generates and verifies the ground-truth reference data in [`/data`](https://goudarzjafari.com/persian-calendar/data/) directly from the astronomical definition of the
Solar Hijri calendar, and scores the [library evaluation](https://goudarzjafari.com/persian-calendar/tools/library-evaluation/) results. Written in pure Rust with zero external dependencies.

```sh
cd tools/calendar-data
cargo run --release                          # Regenerate data/*.csv and data/*.txt
cargo run --release -- --check               # Verify data/ files match astronomical calculations and the official table (run in CI)
cargo run --release -- equinox 2025 2026     # Print exact March equinox times (Iran time) and Nowruz dates for Gregorian years
cargo run --release -- score-libraries       # Regenerate tools/library-evaluation/results/SUMMARY.md
cargo test --release                         # Run unit tests + verify files on disk match generated data byte-for-byte
```

## What it computes

By official definition, **1 Farvardin (Nowruz) is the day on which the March equinox occurs before true (apparent) solar noon on the 52.5° E meridian** (Iran Standard Time, `UTC+3:30`). To compute the calendar from first principles, this tool:

1. **Computes the Sun's apparent celestial longitude** ([`src/astronomy.rs`](https://github.com/Goudarz/PersianCalendar/blob/main/tools/calendar-data/src/astronomy.rs)):
   - Evaluates the 49-term periodic series from Bretagnon & Simon, _Planetary Programs and Tables from −4000 to +2800_ (1986), including nutation and aberration corrections;
   - Computes **ΔT** (Dynamical Time − Universal Time) using Meeus's table for 1600–1986 and the Espenak & Meeus (NASA) polynomials for other eras;
   - Computes the **equation of time** and the **obliquity of the ecliptic** from Meeus, _Astronomical Algorithms_ (2nd ed., 1998) to find exact apparent solar noon.
2. **Finds Nowruz for each year** by locating the first day on which the Sun's apparent longitude at true noon on the `52.5° E` meridian lies in `[0°, 2°]` ([`src/persian.rs`](https://github.com/Goudarz/PersianCalendar/blob/main/tools/calendar-data/src/persian.rs)).
3. **Derives leap years, the 78-year correction table, and the 8,510 test vectors** ([`src/data.rs`](https://github.com/Goudarz/PersianCalendar/blob/main/tools/calendar-data/src/data.rs)).

The astronomical model follows E. M. Reingold and N. Dershowitz, _Calendrical Calculations_ (4th ed., Cambridge University Press, 2016), evaluated on the **52.5° E meridian** (Iran Standard Time) rather than Tehran's local meridian (`51.42° E`). Using `52.5° E` is essential to match the official calendar: using Tehran's local longitude gets the leap year of 1469/1470 AP wrong! The Rust code here is an independent implementation written from scratch for this repository.

## Verification against independent sources

| Reference                                                                                                                                                   | Result                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Official leap-year table of the University of Tehran Calendar Center for 1206–1498 AP ([`data/official`](https://goudarzjafari.com/persian-calendar/data/)) | All 293 Nowruz dates and leap years match 100% (checked automatically on every run)                |
| Independent Python astronomical implementation ([roozbehp/persiancalendar](https://github.com/roozbehp/persiancalendar))                                    | Produces byte-for-byte identical output across 1178–3000 AP for all four generated data files      |
| Independent leap-year table for 1–9999 AP in [persian-calendar/calendar](https://github.com/persian-calendar/calendar) (`leaps.txt`)                        | Matches 100% across 1178–3000 AP                                                                   |
| Officially announced turn-of-the-year moments for 1403 and 1404 AP                                                                                          | Agrees to within 30 seconds (`06:36:07` vs. `06:36:26` in 1403; `12:31:08` vs. `12:31:30` in 1404) |

### How certain is the future?

Running `cargo test -- --nocapture` lists every year in 1178–3000 AP where the spring equinox falls within 10 minutes of true solar noon at `52.5° E`. In those borderline years, even a tiny shift in the solar ephemeris model or in **ΔT** (Earth's rotational drift, which cannot be predicted to the exact second centuries ahead) could flip Nowruz by a day:

| Persian Year (AP)  | 1309  | 1470    | 1503    | **1536** | 1569    | **1602** | 1635  | 1701  | 1734  | **2027** | 2060    | **2093** | … | **2584** |
| ------------------ | ----- | ------- | ------- | -------- | ------- | -------- | ----- | ----- | ----- | -------- | ------- | -------- | - | -------- |
| Distance from noon | 8 min | 2.7 min | 3.6 min | **31 s** | 5.8 min | **37 s** | 9 min | 7 min | 8 min | **39 s** | 9.6 min | **42 s** |   | **6 s**  |

The official Calendar Center table covers 1470 AP (where the equinox is 2.7 minutes from noon), and this tool matches the official ruling. Notice that the years where .NET's `PersianCalendar` differs (`1536`, `2027`, `2093`) are the exact years where the equinox is only \~30–40 seconds away from noon! That's why leap years beyond \~1500 AP should be understood as the best astronomical prediction available today rather than physical certainties.

License: MIT.

---

Page: https://goudarzjafari.com/persian-calendar/tools/calendar-data/
License: text CC BY 4.0, code MIT, data CC0 1.0. Version 1.0.0 of https://github.com/Goudarz/PersianCalendar
