Data & verification
calendar-data: the astronomical engine
3 min readUpdated
Generates and verifies the ground-truth reference data in /data directly from the astronomical definition of the
Solar Hijri calendar, and scores the library evaluation results. Written in pure Rust with zero external dependencies.
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-byteWhat it computes
Link to section: What it computesBy 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:
- Computes the Sun's apparent celestial longitude (
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.
- Finds Nowruz for each year by locating the first day on which the Sun's apparent longitude at true noon on the
52.5° Emeridian lies in[0°, 2°](src/persian.rs). - Derives leap years, the 78-year correction table, and the 8,510 test vectors (
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
Link to section: Verification against independent sources| Reference | Result |
|---|---|
Official leap-year table of the University of Tehran Calendar Center for 1206–1498 AP (data/official) |
All 293 Nowruz dates and leap years match 100% (checked automatically on every run) |
| Independent Python astronomical implementation (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 (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?
Link to section: 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.