# Nauwkeurigheid van berekeningen

## TL;DR

De AstroWay API gebruikt **Swiss Ephemeris** (de officiële C-code van Astrodienst,
de makers van astro.com) — dezelfde engine waar professionele astrologen al 30+
jaar mee werken in **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/maand)**
en Janus. Wij hebben deze engine gecompileerd naar WebAssembly en voorzien van
een REST API-laag, zonder tussenliggende opslagkosten. Elke basisberekenings-
endpoint wordt gedekt door regression snapshot-tests; de nauwkeurigheid van de
engine is geverifieerd via **triangulatie** met drie onafhankelijke bronnen +
tegen de **NASA 5-Millennium Eclipse Catalog**:

- **Planetaire posities**: `< 0.1 boogseconde` vs de officiële swetest CGI van Astrodienst
- **Huiscusps Placidus**: `0.000"` exacte match
- **Eclipsen**: `< 1 minuut` vs NASA Eclipse Catalog
- **ACG-lijnen**: `< 1.5 km` op de evenaar vs swetest
- **Zonsopgang/-ondergang**: `< 10 seconden` vs timeanddate.com
- **Moon VOC, ingresses, planetaire conjuncties**: nauwkeurigheid tot op fracties van een seconde

## De engine

| Component | Waarde |
|-----------|--------|
| Bibliotheek | Swiss Ephemeris C-code (aloistr/swisseph) |
| Versie | upstream Astrodienst C-code |
| Bindings | swisseph-wasm (WebAssembly in Node.js) |
| Ephemeris | DE431 JPL ephemeris (via .se1-bestanden) |
| Fallback | Moshier analytisch (voor data buiten 1800-2399) |
| Code sharing | Gedeelde `@/core` met app.astroway.info — één engine, twee transports |

## Methodiek

De nauwkeurigheid wordt gecontroleerd via **triangulatie** — vergelijking met drie
onafhankelijke bronnen:

### 1. swetest CGI (referentie)

De officiële reference-implementatie van Swiss Ephemeris van Astrodienst zelf —
de code die **Astro.com** heeft gemaakt en die miljoenen astrologen wereldwijd
gebruiken. De meest gezaghebbende publieke bron. Onze engine is **identiek**
(0.00–0.07 boogseconde drift).

### 2. Kerykeion (Python)

Een onafhankelijke Python-bibliotheek die `pyswisseph`-bindings gebruikt in plaats
van onze WASM-laag. Bevestigt dat onze WASM-laag de data niet vervormt.

### 3. Prokerala API

Een externe Swiss Ephemeris API (sidereal Lahiri). Systemische drift van 8–17
boogseconden is gerelateerd aan verschillende versies van de Lahiri ayanamsa-
formule, en **niet** aan de nauwkeurigheid van de engine.

## Triangulatie-resultaten

| Kaart | vs swetest (Astrodienst) | vs Kerykeion (Python) | vs Prokerala API |
|-------|---------------------------|-----------------------|------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (systemisch) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (systemisch)  |
| Einstein 1879 | 0.07"     | LMT-artefact Kerykeion | 14.96" (systemisch) |

## Regression-set op endpoint-niveau

Elke basisberekenings-endpoint wordt gedekt door bevroren snapshot-tests op 3
referentiekaarten (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount} snapshots**.

De snapshot-suite detecteert:

- **Fouten in datamapping** — verkeerde planeet-id, UT, huizensysteem
- **Post-processing** — afronding, eenhedenconversie, verlies van teken
- **Verschillen in standaardwaarden** — mean vs true node, geocentrisch vs topocentrisch
- **Schema drift** — validatie miste een verkeerde vorm
- **Verouderde deployment** — prod-dist komt niet overeen met de code

Tolerantie: `5e-5°` (≈0.18 boogseconde) standaard voor alle numerieke velden.

## Gedetailleerde benchmarks

### Planetaire posities (tropisch, vs swetest)

| Kaart | Datum | Maximale drift |
|-------|-------|----------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Huiscusps Placidus (vs swetest)

| Kaart | drift ASC | drift MC | Maximale huiscus-drift |
|-------|-----------|----------|------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Eclipsen (vs NASA 5-Millennium Catalog)

| Gebeurtenis | NASA maximum | Ons maximum | Drift |
|-------------|--------------|-------------|-------|
| 2025-03-14 Maansverduistering totaal | 06:58 UT | 06:58 UT | 0.8 min |
| 2025-03-29 Zonsverduistering gedeeltelijk | 10:47 UT | 10:47 UT | 0.5 min |
| 2025-09-07 Maansverduistering totaal | 18:11 UT | 18:11 UT | 0.8 min |
| 2025-09-21 Zonsverduistering gedeeltelijk | 19:41 UT | 19:42 UT | 1.0 min |

### Astrocartografie (vs formule RA van swetest)

Alle lijnen MC/IC/ASC/DSC gebruiken de juiste formule `longitude = RA − GMST`
(standaard Kenneth Bowser). Drift ten opzichte van de referentie: **< 1.5 km**
op de evenaar voor alle planeten.

### Zonsopgang/-ondergang (vs timeanddate.com)

| Locatie | Datum | Parameter | Drift |
|---------|-------|-----------|-------|
| Londen | 2026-04-15 | Zonsopgang | 0.6 s |
| Londen | 2026-04-15 | Zonsondergang | 9 s   |

**Poolgebieden** (|breedtegraad| > 66.5°) retourneren automatisch `polarState` +
een waarschuwing dat normale planetaire uren niet gedefinieerd zijn.

### Orbes van aspecten

AstroWay gebruikt **variabele orbes per planeet** (regel MIN van twee planeten),
zoals in ZET9 en astro.com. Standaard orbes (voor een natalkaart):

| Aspect | Zon | Maan | Binnenplaneten | Jupiter | Buitenplaneten |
|--------|-----|------|----------------|---------|----------------|
| Conjunctie | 12°  | 10° | 5° | 8° | 5° |
| Sextiel    | 6.5° | 6°  | 5° | 5° | 5° |
| Vierkant   | 10°  | 8°  | 5° | 7° | 5° |
| Driehoek   | 12°  | 8°  | 5° | 5° | 5° |
| Oppositie  | 12°  | 10° | 5° | 8° | 5° |

Minder belangrijke aspecten (36°, 40°, 45°, 72°, 108°, 135°, 144°) zijn **standaard
uitgeschakeld**. Ze worden expliciet ingeschakeld via `ALL_ASPECTS`.

## Poolgebieden

Voor |breedtegraad| > 66.5° zijn de Placidus / Koch / Regiomontanus-systemen wiskundig
niet gedefinieerd. In dergelijke gevallen retourneert Swiss Ephemeris automatisch
Porphyry, en onze API voegt een waarschuwing toe:

```json
{
  "system": "P",
  "warning": "Het Placidus-systeem is niet gedefinieerd voor breedtegraad=68.96° (> 66.5°). Swiss Ephemeris heeft Porphyry gebruikt..."
}
```

## Continue controle

Regression wordt **op elke PR** gecontroleerd via CI:

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshots tegen referentiekaarten (Monroe / Diana / Einstein) + synastrie / composiet / Davison
- `.github/workflows/api-accuracy.yml` — automatisch starten op PR
- Triangulatie tegen swetest CGI + Kerykeion — wekelijks
- Monitoring van upstream Swiss Ephemeris via Dependabot

## Bekende beperkingen

- **Data buiten het bereik** (voor 1800 en na 2399): er wordt gebruikgemaakt van de
  Moshier analytische methode, nauwkeurigheid ~0.1" (vs < 0.01" voor SWIEPH met DE431-bestanden)
- **True Lilith (id=13) vs Mean Lilith (id=12)**: verschil tot 12° — standaard Mean
  Lilith (stabiel gedrag), True Lilith is beschikbaar via `planetIds: [13]`
- **Topocentrisch vs geocentrisch**: standaard geocentrisch

## Links

- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- NASA Eclipse Catalog: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/