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 73,414/73,414 day-level assertions — every single day from 1900 to 2100. Every auspicious date passes a four-tier veto system before publication.
Three Systems, One Platform
12Zodiacs separates Chinese metaphysics into three distinct systems, each with its own theoretical boundary, inputs, and methodology. This page covers the almanac system; the other two have their own methodology pages.
| System | Inputs | Answers | Methodology |
|---|---|---|---|
| Zodiac Horoscope | Zodiac sign only (birth year) | "For people born under this sign, what does today / this week / this month indicate?" | Per-page methodology & score waterfall (every sign page shows its full calculation) |
| Almanac / Tung Shing | Date (no birth data) | "What does this date carry, and is it suited for this activity?" | This page — astronomical foundation, four-tier arbitration |
| BaZi (Four Pillars) | Full birth date, time & place | "For this specific person, how does the configuration interact with their individual chart?" | BaZi methodology & calculator |
The three systems share one astronomical-calendrical data layer (JPL DE440s solar terms, lunar calendar, ganzhi cycles) but keep their interpretation logic separate. A zodiac forecast is not a personalized BaZi reading.
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, safer, and canon-correct: generic almanacs surface Black Belt days or San Niang Sha dates as "lucky" because they skip arbitration — table-lookup is never wrong about astronomy, but it is always surface-grade about verdicts. We disqualify exactly what the 1739 imperial canon disqualifies. Nothing less.
Veto days on this site: when a Tier-1 veto is active, the day's Yi (宜) board is demoted to routine, low-stakes matters and the officer's usual recommendations are shown as suppressed — a veto always overrides the surface grade of the Day Officer and Belt.
A note on direction gods: daily Wealth (财神), Fortune (福神) and Joy (喜神) directions follow the Xie Ji Bian Fang Shu school (e.g. Bing/Ding days → wealth god due west; Jia/Yi days → wealth god southwest). Popular wan-nian-li sites following the Yu Xia Ji (玉匣记) folk tradition place some of these differently (e.g. Bing/Ding → southwest) — a known variant tradition, not a computation error.
A real-world example: the Year Break most almanacs miss
On August 18, 2026 (a 甲子 Rat day in the 丙午 Horse year), the day branch clashes head-on with the year branch — a classic Year Break (岁破), one of the most serious veto conditions in the canon. That day also happens to be a Stable (定) day under the Azure Dragon (青龙) Yellow Belt deity — which looks excellent if you only read the surface signals.
Side-by-side, a popular Chinese wan-nian-li (perpetual calendar) site marked that same day as suitable for marriage, moving house, groundbreaking, and burial — recommending the four heaviest life events on a Year Break day, a textbook Shen-Sha misjudgment. Our engine flagged the Year Break, triggered the Tier-1 veto, and output "All major undertakings — veto day", demoting the day's recommendations to routine matters only (2026-08-31: 全站宜忌层已与 veto 联动, 重大事项一律压制). Same astronomical data, radically different verdicts — the difference is arbitration, not astronomy.
This is precisely the failure mode Xie Ji Bian Fang Shu Vol. 36 was written to prevent: surface-grade "good day" labels without checking the veto layer first.
Table-lookup vs. arbitration: why commercial almanacs disagree with us
The disagreement is generational, not accidental. Consumer calendar sites (科技紫微网, 老黄历网, and most generic almanac APIs) run single-layer table lookup: a Stable (定) day with Yellow Belt and Trine (三合) spirits automatically inherits the tag library "marriage, betrothal, contracts" — and that label ships to the front end even on a Year Break day, because no conflict-resolution step exists in the pipeline. The 1739 imperial canon runs multi-layer arbitration (裁成法则): "岁破、月破，诸煞之首，大事皆避" — Year and Month Breaks are chiefs of all calamities before which all major affairs must yield. Same input calendar, radically different verdicts; the difference is not astronomy but adjudication. When our lists are shorter than a commercial site's, the missing dates are vetoed by the canon that site never consulted.
4. Verification & Quality Assurance
- Full 201-year sweep, re-verified August 2026 — every day from 1900 to 2100 (73,414 consecutive days, including both century non-leap years, all 49 leap days, term boundaries, and Chinese New Year edges) passed 73,414/73,414 day-level 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.
- Live veto-layer audit (Aug 2026): on the Year Break day of 2026-08-18, our engine correctly vetoed all major undertakings while a popular perpetual-calendar site recommended marriage and groundbreaking on the same day — see the case study in Section 3.
- Hong Kong Observatory cross-check (Sep 2026): all 24 solar terms of 2026 verified against the HKO official solar-term table — 24/24 within ±1 minute (11 exact to the minute, including Start of Spring 2026: Feb 4, 04:02 — matching to the minute). HKO computes from HM Nautical Almanac Office / USNO data; the residual ±1-min on some terms reflects the known ΔT (Earth-rotation) prediction spread between JPL DE440s and the almanac offices — two observatory-grade ephemerides agreeing to one minute, both far beyond the day-level rounding most calendar sites use.
Don't trust it — run it. The engine behind every date on 12zodiacs is public and deterministic: the same code that produced the 73,414/73,414 sweep above.
- MCP server:
npm install -g chinese-almanac-mcp— npmjs.com/package/chinese-almanac-mcp (v1.0.3; auspicious date picking, daily almanac, hour pillars, solar terms) - Source code: github.com/yonlandwu/chinese-almanac-mcp
- How to verify: the solar-term litmus test — compare our term instants against the Hong Kong Observatory table, the public astronomical reference for the Hong Kong printed-almanac tradition. 2026: all 24 terms within ±1 minute. Or run the engine against Purple Mountain Observatory published calendars, any standard Ten-Thousand-Year conversion table, or the 1739 Xie Ji Ban Fang Shu tables themselves. Deterministic output means your run will match ours exactly, for every one of the 73,414 days.
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 Beijing time (UTC+8), matching the traditional Tung Shing convention — a new almanac day begins at Beijing midnight (with the 23:00 Zi-hour carry-over window of classical practice). The daily almanac is statically regenerated every night at 00:07 UTC+8 with automatic CDN cache purge. Visitors outside China see lucky-hour windows auto-converted to their local timezone, with a one-tap switch back to Beijing time.
- 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 — a full 201-year sweep re-verified August 2026: every day from 1900 to 2100 passes, 73,414/73,414 day-level assertions.
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.
Why do other almanac sites give different answers for the same day?
Two layers of divergence. First, arbitration: most consumer calendar sites aggregate static tags (Stable day → "marriage, contracts") without running the canon's conflict resolution, so a Year Break (岁破) day can still carry a "lucky for marriage" label — the failure mode Xie Ji Bian Fang Shu Vol. 36 was written to prevent. Second, direction gods: the Wealth god (财神) placement differs by school — the imperial canon places Bing/Ding days due west, while the folk Yu Xia Ji (玉匣记) tradition places them southwest; we follow the imperial canon and note the variant. When sites disagree with us, check which layer they compute and which school they cite.
What is the裁成法则 (arbitration rule) in date selection?
Cai Cheng (裁成) — "adjudicate and complete" — is the principle that conflicting spirit indications must be resolved into one verdict, not printed side by side. The 1739 canon implements it as a hierarchy: Tier-1 hard vetoes (Year/Month Break, Four Departures, Yang Gong) override everything; Major Virtues (天德/月德) dissolve lower taboos; scoped taboos block only in-scope activities; Yellow Belt hours salvage compromised days. Our engine is a software implementation of exactly this arbitration chain.