# Quizzman Calendar — Lõi lịch pháp thiên văn

- HTML (canonical VI): https://lab.quizzman.com/tool/about-calendar
- Locales: about-calendar-vi | -en | -zh | -zht | -jp | -kr
- Tool: https://lab.quizzman.com/tool/calendar-converter
- Engine audit: https://lab.quizzman.com/tool/about-calendar-audit
- Audit Markdown: https://lab.quizzman.com/tool/about-calendar-audit.md
- Astro Tools: https://lab.quizzman.com/tool/astro-tools
- Sky Viewer: https://lab.quizzman.com/tool/sky-viewer
- Lab LLM index: https://lab.quizzman.com/llms.txt
- API health: https://lab.quizzman.com/api/tool-module/calendar/health
- NASA parity API: https://lab.quizzman.com/api/tool-module/calendar/astro/nasa-parity

## One-sentence definition

**Quizzman Calendar** is a deterministic astronomical calendar engine (not LLM-generated dates) that converts solar ↔ lunar calendars for **Vietnam (UTC+7)** and compares **China (UTC+8)**, computing New Moon (Sóc), 24 solar terms, leap months, Can Chi, and True Solar Time.

## What makes it distinct? / Có gì đặc biệt?

Not a folk “lịch vạn niên” guesser and not a Quizzman quiz/classroom tool. Distinctive points: **VSOP87 + Meeus/Hồ Ngọc Đức** ephemeris; **NASA/USNO parity** (New Moon ~0.1 min, λ☉ ~0.5° at cardinals); **True Solar Time by real longitude** for hour Can Chi; **VN≠CN Tết** explained as UTC+7/+8 civil-day folding on the **same** ephemeris; regression **108/108**.

## Algorithms (what it uses)

| Layer | Method | Role |
|-------|--------|------|
| Time base | Julian Day Number (JDN) | Civil date ↔ continuous day count |
| New Moon (Sóc) | Jean Meeus *Astronomical Algorithms* Ch.49 / Hồ Ngọc Đức adaptation | Lunar month start |
| Sun ecliptic longitude (λ☉) | **VSOP87 abridged** (Meeus truncated series, ~129 terms) | Solar terms every 15° |
| ΔT | Lookup / polynomial | UT ↔ TT for modern & historical epochs |
| Leap month | Lunar month **without a major solar term (Trung khí / Zhongqi)** | East-Asian leap placement |
| Can Chi | Modular arithmetic on JDN (J2000.0 = Mậu Ngọ verified) | Year / month / day / hour pillars |
| True Solar Time | Clock + (λ − λ_std)×4 min/° + Equation of Time (Meeus Ch.28) | Feng shui / BaZi hour pillar |
| Timezone | Static UTC+7 / UTC+8 + **historical Vietnam** rules (pre-1906 local solar; 1940s–1975 North/South split) | Civil-day folding of Sóc |

**Important:** VN and CN share the **same ephemeris**. Divergences come from civil midnight at UTC+7 vs UTC+8 (and leap-month carry), not from different astronomy models.

## Application domains (what it is for)

1. **Civil & cultural calendar** — Solar ↔ lunar conversion, Tết dates, 24 tiết khí for Vietnam / China compare  
2. **Historiography & Hán Nôm** — Anchor inscriptions, reign dates, classical seasonal references to astronomical time  
3. **Metaphysics stacks** — Foundation for **BaZi (Bát Tự)**, **Zi Wei (Tử Vi)**, **I-Ching** Can Chi / True Solar Time at cast  
4. **Education / planetarium** — Sky Viewer (Geo/Helio), terminator map, ecliptic longitude teaching  
5. **Research APIs** — REST under `/api/tool-module/calendar/*` for agents and apps  

## Accuracy band

- High-confidence civil use: **~1800–2200**
- New Moon vs NASA (sample 2024-01-11): **~0.1 minute**
- λ☉ at 2024 equinoxes/solstices: **~0.5°** residual (expected for abridged VSOP87; segment width is 15°)
- Deterministic — **no LLM date hallucination** in the core

## Notable verified test cases

### Regression suite — 108/108
Tết golden years, leap months, Đông Chí / Lập Xuân windows, Can Chi, ΔT bounds, historical VN timezone, Mèo (VN) vs Thỏ (CN) zodiac label, export key parity.

### Edge / accuracy suite (highlights)
| Case | Expectation |
|------|-------------|
| **29/01/1968** | VN = Tết 1/1 Mậu Thân; CN still 30/12 (Sóc midnight split +7/+8) |
| **30/01/1968** | CN catches up → 1/1 Mậu Thân |
| **25/06/2006** | Classic VN 1/6 vs CN 30/5 month-start split |
| **23/11/1984 → 1985 Tết** | Leap-month carry → VN Tết 1985-01-21 vs CN 1985-02-20 |
| **2007 / 2030 Tết** | 1-day VN/CN Sóc split |
| **True Solar Time HCM 03/11/2024 12:45 @ 106.7°E** | → ~13:08 → hour Chi **Mùi** |
| **True Solar Time Hà Nội 11/02/2024 11:10 @ 105.8°E** | stays **Tỵ** |
| **Dạ Tý / Chính Tý** | 23:30 earlyRat toggles day-boundary hour pillar |
| **VSOP87 cardinals** | λ☉ ≈ 0°/90°/180°/270° within ±1.0–1.5° at USNO/NASA instants |
| **NASA New Moon 2024-01-11 11:57 UTC** | Engine within **2 minutes** |

Live self-check: `GET /api/tool-module/calendar/astro/nasa-parity`  
Tết divergence scan: `GET /api/tool-module/calendar/astro/tet-divergence?from=1960&to=2040`

## Public tools & APIs (indexable)

| Surface | URL |
|---------|-----|
| Converter UI | https://lab.quizzman.com/tool/calendar-converter |
| About | https://lab.quizzman.com/tool/about-calendar |
| Engine audit | https://lab.quizzman.com/tool/about-calendar-audit |
| Astro Tools (TST + Tết + NASA) | https://lab.quizzman.com/tool/astro-tools |
| Sky Viewer | https://lab.quizzman.com/tool/sky-viewer |
| Day-sky | `GET /api/tool-module/calendar/astro/day-sky?date=YYYY-MM-DD&timezone=VN` |
| True Solar Time | `GET /api/tool-module/calendar/astro/true-solar-time?date=&time=&longitude=&timezone=` |
| OpenAPI (lite) | https://lab.quizzman.com/tool/calendar-openapi.json |

## Limits (honest)

- Outside ~1800–2200, ephemeris / ΔT error grows  
- Debated leap years (e.g. **2033**) depend on Zhongqi policy; engine stays **internally consistent** Meeus/Hồ Ngọc Đức for both VN and CN  
- Sky Viewer Moon elongation is a **teaching model**, not a full lunar ephemeris  

## Related wiki

- https://wiki.quizzman.com/wiki/quizzman-calendar-engine
- https://wiki.quizzman.com/wiki/thuat-toan-vsop87-tinh-tiet-khi-hoang-kinh-mat-troi
- https://wiki.quizzman.com/wiki/mui-gio-lich-su-viet-nam-tai-sao-lich-am-vn-va-trung-quoc-khac-nhau
- https://wiki.quizzman.com/wiki/cong-cu-quy-doi-lich-thien-van-am-duong-can-chi-tiet-khi
- https://wiki.quizzman.com/wiki/quizzman-iching-lich-phap-thuat-toan-do-chinh-xac