# Přesnost výpočtů

## TL;DR

AstroWay API používá **Swiss Ephemeris** (oficiální C-kód od Astrodienst,
tvůrců astro.com) – stejný engine, na kterém profesionální astrologové posledních
30+ let pracují v **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/měsíc) a
Janus**. My jsme ho sestavili do WebAssembly a vystavili přes REST API bez
prostřednického navyšování cen. Každý z výchozích výpočetních endpointů je
pokryt regresními snapshot-testy; přesnost engineu je ověřena **triangulací** ze
tří nezávislých zdrojů + proti **NASA 5-Millennium Eclipse Catalog**:

- **Polohy planet**: `< 0.1 úhlová vteřina` vs oficiálního swetest CGI Astrodienst
- **Kuspidy domů Placidus**: `0.000"` přesná shoda
- **Zatmění**: `< 1 minuta` vs NASA Eclipse Catalog
- **Astro-geografické linie**: `< 1.5 km` na rovníku vs swetest
- **Východ/západ Slunce**: `< 10 sekund` vs timeanddate.com
- **Měsíční VOC, ingressy, konjunkce planet**: přesnost na zlomek vteřiny

## Engine

| Komponenta | Hodnota |
|------------|---------|
| Knihovna | Swiss Ephemeris C code (aloistr/swisseph) |
| Verze | upstream Astrodienst C code |
| Bindings | swisseph-wasm (WebAssembly v Node.js) |
| Efemeridy | DE431 JPL efemeridy (přes .se1 soubory) |
| Fallback | Moshier analytický (pro data mimo 1800–2399) |
| Sdílení kódu | Sdílený `@/core` s app.astroway.info – jeden engine, dva transporty |

## Metodika

Přesnost je ověřována pomocí **triangulace** – porovnáním se třemi nezávislými
zdroji:

### 1. swetest CGI (etalon)

Oficiální referenční implementace Swiss Ephemeris od samotných Astrodienst –
kód, který vytvořil **Astro.com** a který obsluhuje miliony astrologů po celém
světě. Nejautoritativnější veřejný zdroj. Náš engine je **identický** (0.00–0.07
úhlové vteřiny driftu).

### 2. Kerykeion (Python)

Nezávislá Python knihovna používající `pyswisseph` bindings místo našeho WASM.
Ověřuje, že náš WASM-vrstva nezkresluje data.

### 3. Prokerala API

Vzdálené Swiss Ephemeris API (siderický Lahiri). Systémový drift 8–17 úhlových
vteřin souvisí s různými verzemi vzorce Lahiri ayanamsa, nikoliv s přesností
engineu.

## Výsledky triangulace

| Karta | proti swetest (Astrodienst) | proti Kerykeion (Python) | proti Prokerala API |
|-------|------------------------------|---------------------------|---------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (systémový) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (systémový)  |
| Einstein 1879 | 0.07"     | LMT-artifakt Kerykeion | 14.96" (systémový) |

## Regression sada na úrovni endpointů

Každý z výchozích výpočetních endpointů je pokryt zmrazenými snapshot-testy
na 3 referenčních kartách (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount}
snapshotů**.

Snapshot-suite zachycuje:

- **Chyby mapování vstupních dat** – špatné id planety, UT, systém domů
- **Post-processing** – zaokrouhlování, převody jednotek, ztráta znaménka
- **Rozdíly v defaults** – mean vs true node, geocentrický vs topocentrický
- **Schema drift** – validace propustila špatný formát
- **Zastaralé nasazení** – prod dist neodpovídá kódu

Tolerance: `5e-5°` (≈0.18 úhlové vteřiny) jako výchozí pro všechna číselná pole.

## Detailní benchmarky

### Polohy planet (tropický, proti swetest)

| Karta | Datum | Maximální drift |
|-------|-------|-----------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Kuspidy domů Placidus (proti swetest)

| Karta | drift ASC | drift MC | Maximální drift kuspidu |
|-------|-----------|----------|--------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Zatmění (proti NASA 5-Millennium Catalog)

| Událost | Maximální NASA | Náš maximální | Drift |
|---------|----------------|---------------|-------|
| 2025-03-14 Lunární úplné  | 06:58 UT | 06:58 UT | 0.8 min |
| 2025-03-29 Částečné sluneční | 10:47 UT | 10:47 UT | 0.5 min |
| 2025-09-07 Lunární úplné  | 18:11 UT | 18:11 UT | 0.8 min |
| 2025-09-21 Částečné sluneční | 19:41 UT | 19:42 UT | 1.0 min |

### Astro-kartografie (proti vzorci RA ze swetest)

Všechny linie MC/IC/ASC/DSC používají správný vzorec `longitude = RA − GMST`
(standard Kenneth Bowser). Drift od etalonu: **< 1.5 km** na rovníku pro
všechny planety.

### Východ / západ Slunce (proti timeanddate.com)

| Lokalita | Datum | Parametr | Drift |
|----------|-------|----------|-------|
| Londýn | 2026-04-15 | Východ Slunce | 0.6 s |
| Londýn | 2026-04-15 | Západ Slunce  | 9 s   |

**Polární lokality** (|zem. šířka| > 66.5°) automaticky vrací `polarState` +
varování, že běžné planetary hours nejsou definovány.

### Orby aspektů

AstroWay používá **proměnlivé orby per-planet** (pravidlo MIN dvou planet),
jako v ZET9 a astro.com. Orby jako výchozí (pro nativní kartu):

| Aspekt | Slunce | Měsíc | Vnitřní | Jupiter | Vnější |
|--------|--------|-------|---------|---------|--------|
| Konjunkce | 12°  | 10° | 5° | 8° | 5° |
| Sextil     | 6.5° | 6°  | 5° | 5° | 5° |
| Kvadrát    | 10°  | 8°  | 5° | 7° | 5° |
| Trinus     | 12°  | 8°  | 5° | 5° | 5° |
| Opozice    | 12°  | 10° | 5° | 8° | 5° |

Minor aspekty (36°, 40°, 45°, 72°, 108°, 135°, 144°) jsou **výchozí vypnuté**.
Zapínají se explicitně přes `ALL_ASPECTS`.

## Polární šířky

Pro |zem. šířka| > 66.5° systémy Placidus / Koch / Regiomontanus nejsou
matematicky definovány. V takových případech Swiss Ephemeris automaticky
vrací Porphyry a náš API přidává varování:

```json
{
  "system": "P",
  "warning": "Systém Placidus není definován pro lat=68.96° (> 66.5°). Swiss Ephemeris použil Porphyry..."
}
```

## Kontinuální ověřování

Regression je ověřována **na každý PR** přes CI:

- `api-calc/tests/endpoints/` – {siteMeta.snapshotCount} snapshotů proti referenčním kartám (Monroe / Diana / Einstein) + synastrie / kompozit / Davison
- `.github/workflows/api-accuracy.yml` – automatický běh na PR
- Triangulace proti swetest CGI + Kerykeion – každý týden
- Monitorování upstream Swiss Ephemeris přes Dependabot

## Známá omezení

- **Data mimo rozsah** (před 1800 a po 2399): používá se Moshier analytický,
  přesnost ~0.1" (oproti < 0.01" pro SWIEPH s DE431 soubory)
- **True Lilith (id=13) vs Mean Lilith (id=12)**: rozdíl až 12° – jako výchozí
  Mean Lilith (stabilní chování), True Lilith je dostupný přes
  `planetIds: [13]`
- **Topocentrický vs geocentrický**: jako výchozí geocentrický

## Odkazy

- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- Katalog zatmění NASA: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/

## Kontakty

Na dotazy ohledně přesnosti piš na support@astroway.info s daty karty
a očekávaným etalonem (astro.com nebo jiné autoritativní zdroje).