The Methodology Behind Our Chinese Almanac (Tung Shing)
How every date on 12zodiacs is computed: JPL DE440s astronomy at minute precision, the 1739 Qianlong imperial canon, four-tier god arbitration, and machine-verified assertions.
Our Chinese Almanac is computed from JPL's DE440s ephemeris at minute precision — validated against the Purple Mountain Observatory (Start of Autumn 2026: Aug 7, 19:42:26, matching to the minute) — structured by the Qianlong imperial canon Xie Ji Bian Fang Shu (1739), and machine-verified with 121/121 independent day-level assertions. Every auspicious date passes a four-tier veto system before publication.
1. Astronomical Foundation
Most English-language almanac sites copy table books or round solar terms to the nearest day. We compute them from first principles. Solar term instants are solved with the skyfield astronomy library loading JPL's DE440s ephemeris (the short planetary ephemeris covering 1849–2150), by bisection root-finding on the Sun's apparent geocentric ecliptic longitude at exact 15° multiples — resolved to the minute, expressed in UTC+8.
Validation anchor: our computed Start of Autumn (立秋) 2026 falls on August 7 at 19:42:26 CST, matching the official Purple Mountain Observatory value to the minute. A total of 4,824 term instants (201 years × 24 terms) are precomputed and shipped as an immutable JSON dataset.
Why minute precision matters
A day-level error near a term boundary flips the exact month branch — which cascades into the 12 Day Officers, the Yellow/Black Belt deities, and ultimately the auspiciousness verdict for that date. Minute-precision astronomy is what keeps 建除十二神 aligned with the observatory-grade calendar instead of a calendar-date approximation.
2. The Five Computational Layers
| Layer | Computation | Integrity Mechanism |
|---|---|---|
| 1 · Day Pillar | Continuous sexagenary (60-cycle) count anchored to a known Julian Day Number reference — no per-year drift, valid 1901–2100 | Anchor-day regression tests |
| 2 · Month Branch | Derived from exact solar-term boundaries, never calendar-month approximations | ±1-day boundary sampling in QA |
| 3 · Lunar Calendar | Astronomy-derived 201-year table (1900–2100) including leap months | 9 anchor points incl. Chinese New Year dates |
| 4 · 28 Mansions | 廿八宿 rotation on a 7-day cycle | Weekday axiom: each weekday permits exactly 4 candidate mansions — asserted per day |
| 5 · Officers & Belts | 12 Day Officers (建除十二神) indexed by month branch; Yellow/Black Belt (黄道/黑道) deities per day and per hour pillar | Completeness assertions on every rendered day |
3. The Four-Tier God Arbitration State Machine
Traditional almanacs list dozens of auspicious and inauspicious "gods" (神煞) per day, often contradicting each other. Following Xie Ji Bian Fang Shu Vol. 36, our engine resolves every conflict through a deterministic four-tier state machine:
| Tier | Rule | Effect |
|---|---|---|
| Tier 1 — Hard Veto | Year Break (岁破), Month Break (月破), Four Departures & Extinctions (四离四绝), Yang Gong's Thirteen Taboos (杨公忌) | Date disqualified entirely — never listed as auspicious |
| Tier 2 — Supreme Virtue | Heavenly Virtue (天德), Monthly Virtue (月德), Heavenly Amnesty (天赦) | "德盖百煞" — dissolves lower-tier taboos canonically |
| Tier 3 — Scoped Taboo | Earth Sovereign (土王用事), Away Day (往亡), Monthly Taboo (月忌日 — lunar 5th/14th/23rd), San Niang Sha (三娘煞 — weddings only) | Blocks only in-scope activities; safe activities proceed |
| Tier 4 — Hour Remediation | Yellow Belt hour pillars on an otherwise compromised day | Salvageable time windows surfaced explicitly |
This is why our auspicious-date lists are shorter than competitors': generic almanacs surface Black Belt days or San Niang Sha dates as "lucky" because they skip arbitration. We disqualify them.
4. Verification & Quality Assurance
- 121 sampled days across 2024–2026 — including the 2025 leap sixth-month boundary, ±1 day around three solar-term transitions, and Chinese New Year edges — passed 121/121 assertions.
- Axiom assertions per day: mansion–weekday consistency (4-candidate rule), Sha-direction triple-harmony self-consistency (三合局煞方), and Day Officer / Belt completeness.
- 9 lunar-calendar anchor points validated against published observatory calendars.
- Competitor cross-validation: September wedding-date lists cross-checked against a leading English almanac site — overlapping dates agree; our stricter canon additionally excludes San Niang Sha and Black Belt days theirs include.
5. Timezone & Day-Boundary Policy
- Solar terms and the traditional calendar are computed in UTC+8 — the astronomical standard the Chinese lunisolar calendar is defined against.
- Site day boundary follows America/New_York for our primary audience; the daily almanac is statically regenerated every night at 00:07 ET with automatic CDN cache purge.
- Hour pillars follow the local mean-time convention of traditional practice; for hour-level personal refinement we recommend a full BaZi reading.
6. Canonical Sources
- Xie Ji Bian Fang Shu (钦定协纪辨方书) — the Qianlong-era imperial compendium of date selection, 1739; primary authority for god arbitration.
- JPL Solar System Dynamics — DE440s planetary ephemeris.
- Purple Mountain Observatory (紫金山天文台) annual calendar publications — anchor validation reference.
Frequently Asked Questions
How accurate is the Chinese lunar calendar?
As astronomy, extremely: the lunisolar calculation is exact, and our implementation computes solar terms from JPL's DE440s ephemeris with minute-level precision — validated against the Purple Mountain Observatory (Start of Autumn 2026: August 7, 19:42:26, matching to the minute). The interpretive layer (which days are lucky for what) is canon, not physics — our methodology page keeps the two clearly separated.
Who created the Chinese calendar?
It evolved over three millennia of imperial astronomy; the sexagenary cycle dates to Shang-dynasty oracle bones (~1250 BCE). The version we follow — the twelve Day Officers and god arbitration — was codified in the Qianlong-era imperial compendium Xie Ji Bian Fang Shu (1739). Our methodology page documents both lineages and how the engine implements each.
Why does minute precision matter for solar terms?
Near a term boundary, a one-day error changes the month branch — which flips the Day Officer, the Belt deities, and ultimately the verdict for that date. Minute-precision astronomy keeps the entire downstream chain aligned with the observatory-grade calendar. Generic almanac sites that round to the nearest day get boundary days wrong; we compute them to the minute.
What is the difference between Tung Shing and Tong Shu?
Same book, different readings: Tung Shing (通勝, "all victories") is the Cantonese name — the version most overseas Chinese families grew up with, deliberately auspicious-sounding; Tong Shu (通書, "all records") is the Mandarin reading. Our pages blend both dialect traditions, and cover 1900–2100 with 4,824 precomputed term instants.
How is the chinese calendar calculated?
Five computational layers: day pillars on a continuous 60-cycle count anchored to a Julian Day reference; month branches from exact solar-term boundaries; a 201-year astronomy-derived lunar table including leap months; the 28 mansions on their 7-day rotation; then officers and deity belts assembled with the four-tier arbitration state machine. Each layer has its own assertion suite — 121 sampled days across 2024–2026 all pass.
Can I verify your calculations?
Partially, yes: solar-term instants against any published observatory calendar (we match Purple Mountain to the minute), and day pillars against any standard conversion table. The god arbitration follows the 1739 canon, whose tables are published. Our methodology page documents every rule the engine applies — that transparency is the point.