# Quizzman Astro — Ephemeris engine (detailed)

- Markdown: https://astro.quizzman.com/about-engine.md
- Audit paper: https://astro.quizzman.com/paper
- Bench JSON: https://astro.quizzman.com/paper/report.json
- Product overview: https://astro.quizzman.com/about.md
- Human guide: https://astro.quizzman.com/guide/ENGINE.md

## One-sentence definition

The **Quizzman Astro engine** is a layered solar-system ephemeris stack (Rust + shared Node test harness) that converts civil time and observer location into sky coordinates, calendar almanac fields, and Explorer relative positions — with published Level-3 parity tests against NASA/JPL/IAU-class references.

## Layered computation model

| Layer | Method | Role |
|-------|--------|------|
| Time scales | JD UT, TT, ΔT lookup/polynomial, optional EOP UT1−UTC | Civil ↔ dynamical time |
| Planets | **VSOP87D** heliocentric ecliptic series | Analytical planetary theory |
| Moon | **ELP/MPP02** | Lunar longitude/latitude/distance |
| High precision | **JPL DE440** SPK (DAF + Chebyshev) | Cartesian states when kernel covers JD |
| Apparent place | Nutation, aberration / light-time as implemented | Observed directions |
| Coordinates | Equatorial · horizontal · galactic · ecliptic; precession | Frame transforms |
| Atmosphere | Refraction model + elevation dip | Sunrise / altitude near horizon |
| Catalog | Bright stars + DSO JSON; IAU constellation polygons | Labels & membership |
| Satellites | TLE (e.g. ISS) | Low-Earth orbit track |
| Zodiac support | Tropical/sidereal ecliptic longitudes, Asc/MC, events | Consumer APIs |

**Honesty rule:** JSON from `/viewer/sky` exposes `ephemeris_backend` (`de440` vs analytical fallback). Agents must not claim DE440 for dates outside the installed kernel.

## Runtime

| Item | Value |
|------|--------|
| Binary | `rust/target/release/astro-serve` |
| Process | PM2 `qm-astro-serve` |
| Public host | https://astro.quizzman.com |
| Health | `GET /health` → `qm-astro` / version |
| DE440 path | Env `EPHEM_DE440_PATH` → `de440s.bsp` |

Rebuild (ops):

```bash
cargo build --release --manifest-path /opt/qm-astro/rust/Cargo.toml
pm2 restart qm-astro-serve
```

## Level-3 accuracy program

Target and achieved level: **3** (see `/paper/report.json`).

| Suite (examples) | Role |
|------------------|------|
| accuracy-benchmark | Calendar / TZ / golden civil cases |
| level3-bench | Sunrise, EOP/UT1, constellation, eclipse contacts, … |
| lunar-core | New moon / lunar regression (108-class) |
| ephemeris | DE440 / analytical checks |
| viewer-sky | Frame payload integrity |

**Summary (2026-07-27 report):** `pass: 237`, `fail: 0`, `skip: 0`.

### What Level 3 covers (high level)

- Ephemeris parity fixtures (e.g. Horizons J2000 vectors when DE440 present)  
- Sunrise/set vs public reference APIs (target tens of seconds with refraction + elevation)  
- IAU constellation boundary membership (polygon catalog)  
- Earth orientation (finals2000A-class UT1−UTC)  
- Eclipse contact timing (geocentric reference cases)  
- Proper-motion-aware star paths where implemented  

Public narrative: https://astro.quizzman.com/paper  
Repo notes: `backend/docs/NASA_PARITY_AUDIT.md`, `ENGINE_TECHNICAL_REFERENCE.md`, `ACCURACY_BENCHMARK_REPORT.md`.

## Civil almanac (`/astro/day-sky`)

For a local `YYYY-MM-DD` + timezone (`VN` = UTC+7, `CN` = UTC+8) + longitude:

- Julian day at local noon / JDN  
- Current solar term  
- Previous / next new moon  
- Synodic age  

This feeds calendrics UIs and the Sky Viewer’s date picker path. Details: https://astro.quizzman.com/about-api.md

## Explorer mathematics (conceptual)

When `center ≠ earth`, bodies are expressed in an **explorer ecliptic** Cartesian frame with the center body at the origin; distances in **AU**. This supports teaching heliocentric / planetocentric layouts without claiming surface-horizon rendering on other worlds.

## Relationship to Lab “Quizzman Calendar”

Lab about-calendar documents Meeus/Hồ Ngọc Đức abridged VSOP87 for Vietnam/China civil calendars (**108/108** cultural golden tests).  
Astro is the **service-grade** stack: full VSOP87D series files, ELP/MPP02, optional DE440, Sky Viewer, and Level-3 NASA/JPL harness. Cite Astro for planetarium/API precision; cite Lab for VN↔CN civil calendar UX and Tết divergence pedagogy.

## What the engine is not

- Not an LLM predicting positions  
- Not a substitute for JPL Horizons for arbitrary spacecraft kernels beyond installed DE440  
- Not claiming milliarcsecond Gaia-grade star catalog completeness (bright-star + DSO subset)