This project tests the Tychos model's ability to predict historical solar and lunar eclipses. For each eclipse in NASA's authoritative catalogs, it computes Sun and Moon positions in both the Tychos geometric model and the standard JPL ephemeris, derives a predicted reference geometry directly from the catalog's published gamma and magnitude, and reports each model's angular error against that reference.

1. Get the eclipse catalogs. Parse NASA's Five Millennium Canon of solar and lunar eclipses (1901–2100) into JSON, giving us ~900 eclipses with exact times in Julian Day (TT), plus per-eclipse gamma, magnitude, and Saros series number.

2. Derive a predicted reference geometry. For each catalog eclipse, server/services/predicted_geometry.py converts the published gamma and magnitude into the expected Sun-Moon (or Moon-to-shadow) angular separation and disk/shadow radii — pure geometry, no Skyfield, no Tychos. This becomes the per-eclipse ground-truth reference stored in the predicted_reference table.

3. Set up two models via Skyfield. Initialize the Tychos geometric model (tychos_skyfield) and the standard heliocentric model (JPL DE440s ephemeris via Skyfield). Both produce Sun and Moon RA/Dec positions in the ICRF/J2000 frame.

4. Scan each model for closest approach. For each catalog eclipse, scan for minimum Sun-Moon separation in the Tychos model around the catalog time, and record the corresponding JPL geometry at the same instant.

5. Score against the predicted reference. Compute tychos_error_arcmin and jpl_error_arcmin as the angular distance between each model's predicted Sun-Moon separation and the catalog-derived reference separation. There is no pass/fail — the metric is continuous.

6. Store and visualize. Results go into a SQLite database. The admin dashboard provides per-eclipse geometry diagrams (predicted / tychos / jpl side-by-side), error-based filtering, Saros-series grouping, and dataset browsing.

Local development (FastAPI server + worker + admin SPA dev server):

git clone --recurse-submodules https://github.com/the-real-adammork/tychos.git
cd tychos
python3 -m venv tychos_skyfield/.venv
source tychos_skyfield/.venv/bin/activate
pip install -r server/requirements.txt -r tychos_skyfield/requirements.txt -r requirements.txt
(cd admin && npm install)

# First boot only — required to seed the initial admin user
export TYCHOS_ADMIN_USER=you@example.com
export TYCHOS_ADMIN_PASSWORD='something-strong'

./dev.sh

This starts the API at http://localhost:8000, the admin UI at http://localhost:5173, and the background worker. Hit /login with the credentials you exported above. The first boot runs migrations, downloads de440s.bsp, parses the NASA catalogs, derives the predicted reference geometry, and queues the seeded parameter sets for runs — give it a minute.

For deploying as a long-lived service behind Cloudflare Tunnel + Access, see local_deploy/README.md.

⚠️ The bare API server has open registration and no built-in access control. It's only safe to expose publicly behind an external auth gate. The local deploy uses Cloudflare Access with an email allowlist.

GPL v2. See LICENSE. The tychos_skyfield submodule is also GPL v2.