# Précision des calculs

## TL;DR

L'API AstroWay utilise **Swiss Ephemeris** (le code C officiel d'Astrodienst,
les créateurs d'astro.com) — le même moteur sur lequel les astrologues
professionnels travaillent depuis plus de 30 ans avec **Solar Fire ($495),
Kepler ($995), Astro Gold ($29.99/mois) et Janus**. Nous l'avons compilé en
WebAssembly et l'avons exposé via une couche REST, sans frais intermédiaires.
Chaque endpoint de calcul de base est couvert par des tests de régression
snapshot ; la précision du moteur est vérifiée par **triangulation** avec trois
sources indépendantes + contre le **NASA 5-Millennium Eclipse Catalog** :

- **Positions planétaires** : `< 0,1 seconde d'arc` vs le CGI swetest officiel d'Astrodienst
- **Cuspides des maisons Placidus** : `0,000"` correspondance exacte
- **Éclipses** : `< 1 minute` vs le catalogue d'éclipses de la NASA
- **Lignes ACG** : `< 1,5 km` à l'équateur vs swetest
- **Lever/coucher du Soleil** : `< 10 secondes` vs timeanddate.com
- **VOC de la Lune, ingressions, conjonctions planétaires** : précision à la fraction de seconde

## Moteur

| Composant | Valeur |
|-----------|--------|
| Bibliothèque | Code C Swiss Ephemeris (aloistr/swisseph) |
| Version | Code C amont d'Astrodienst |
| Bindings | swisseph-wasm (WebAssembly dans Node.js) |
| Éphémérides | Éphémérides JPL DE431 (via fichiers .se1) |
| Fallback | Analytique Moshier (pour les dates hors 1800-2399) |
| Partage de code | Partagé `@/core` avec app.astroway.info — un seul moteur, deux transports |

## Méthodologie

La précision est vérifiée par **triangulation** — comparaison avec trois sources
indépendantes :

### 1. swetest CGI (référence)

L'implémentation de référence officielle de Swiss Ephemeris d'Astrodienst — les
commandes qui ont créé **Astro.com** et qui dessert des millions d'astrologues
dans le monde entier. La source publique la plus autoritaire. Notre moteur est
**identique** (dérive de 0,00 à 0,07 seconde d'arc).

### 2. Kerykeion (Python)

Une bibliothèque Python indépendante utilise les bindings `pyswisseph` au lieu de
notre WASM. Elle confirme que notre couche WASM ne déforme pas les données.

### 3. API Prokerala

Une API Swiss Ephemeris à distance (ayanamsa sidéral Lahiri). Une dérive
systémique de 8 à 17 secondes d'arc est liée aux différentes versions de la
formule d'ayanamsa de Lahiri, et **pas** à la précision du moteur.

## Résultats de la triangulation

| Carte | vs swetest (Astrodienst) | vs Kerykeion (Python) | vs API Prokerala |
|-------|---------------------------|------------------------|------------------|
| Monroe 1926   | **0,00"** | 0,19" | 16,95" (systémique) |
| Diana 1961    | **0,00"** | 0,69" | 8,18" (systémique)  |
| Einstein 1879 | 0,07"     | Artefact LMT de Kerykeion | 14,96" (systémique) |

## Jeu de régression au niveau des endpoints

Chaque endpoint de calcul de base est couvert par des tests snapshot figés sur
3 cartes de référence (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount} snapshots**.

La suite de snapshots détecte :

- **Les bugs de mappage des données d'entrée** — mauvais id de planète, UT, système de maisons
- **Le post-traitement** — arrondi, conversion d'unités, perte de signe
- **Les divergences par défaut** — nœud moyen vs vrai, géocentrique vs topocentrique
- **Les décalages de schéma** — la validation a laissé passer une mauvaise forme
- **Les déploiements obsolètes** — la dist prod ne correspond pas au code

Tolérance : `5e-5°` (≈0,18 seconde d'arc) par défaut pour tous les champs numériques.

## Benchmarks détaillés

### Positions planétaires (tropique, vs swetest)

| Carte | Date | Dérive maximale |
|-------|------|-----------------|
| Marilyn Monroe  | 1926-06-01 | **0,00"** |
| Princesse Diana  | 1961-07-01 | **0,00"** |
| Albert Einstein | 1879-03-14 | 0,07"     |

### Cuspides des maisons Placidus (vs swetest)

| Carte | dérive ASC | dérive MC | Dérive maximale de cuspide |
|-------|------------|-----------|----------------------------|
| Monroe | 0,000" | 0,000" | 0,000" |
| Diana  | 0,000" | 0,000" | 0,000" |

### Éclipses (vs NASA 5-Millennium Catalog)

| Événement | Maximum NASA | Notre maximum | Dérive |
|-----------|--------------|---------------|--------|
| Éclipse lunaire totale 2025-03-14  | 06:58 UT | 06:58 UT | 0,8 min |
| Éclipse solaire partielle 2025-03-29 | 10:47 UT | 10:47 UT | 0,5 min |
| Éclipse lunaire totale 2025-09-07  | 18:11 UT | 18:11 UT | 0,8 min |
| Éclipse solaire partielle 2025-09-21 | 19:41 UT | 19:42 UT | 1,0 min |

### Astro-cartographie (vs formule RA de swetest)

Toutes les lignes MC/IC/ASC/DSC utilisent la bonne formule `longitude = RA − GMST`
(standard Kenneth Bowser). Dérive par rapport à la référence : **< 1,5 km** à
l'équateur pour toutes les planètes.

### Lever / Coucher du Soleil (vs timeanddate.com)

| Lieu | Date | Paramètre | Dérive |
|------|------|-----------|--------|
| Londres | 2026-04-15 | Lever du Soleil | 0,6 s |
| Londres | 2026-04-15 | Coucher du Soleil  | 9 s   |

**Lieux polaires** (|lat| > 66,5°) renvoient automatiquement `polarState` +
un avertissement indiquant que les heures planétaires classiques ne sont pas définies.

### Orbites d'aspects

AstroWay utilise des **orbites variables** par planète (règle MIN de deux planètes),
comme dans ZET9 et astro.com. Les orbites par défaut (pour une carte natale) :

| Aspect | Soleil | Lune | Planètes intérieures | Jupiter | Planètes extérieures |
|--------|--------|------|----------------------|---------|----------------------|
| Conjonction | 12°  | 10° | 5° | 8° | 5° |
| Sextile     | 6,5° | 6°  | 5° | 5° | 5° |
| Carré        | 10°  | 8°  | 5° | 7° | 5° |
| Trine       | 12°  | 8°  | 5° | 5° | 5° |
| Opposition  | 12°  | 10° | 5° | 8° | 5° |

Les aspects mineurs (36°, 40°, 45°, 72°, 108°, 135°, 144°) sont **désactivés par
défaut**. Ils s'activent explicitement via `ALL_ASPECTS`.

## Latitudes polaires

Pour |lat| > 66,5°, les systèmes Placidus / Koch / Regiomontanus ne sont pas
mathématiquement définis. Dans ces cas, Swiss Ephemeris renvoie automatiquement
Porphyry, et notre API ajoute un avertissement :

```json
{
  "system": "P",
  "warning": "Le système Placidus n'est pas défini pour lat=68,96° (> 66,5°). Swiss Ephemeris a substitué Porphyry..."
}
```

## Vérification continue

La régression est vérifiée **à chaque PR** via CI :

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshots contre les cartes de référence (Monroe / Diana / Einstein) + synastrie / composite / Davison
- `.github/workflows/api-accuracy.yml` — exécution automatique sur PR
- Triangulation vs swetest CGI + Kerykeion — chaque semaine
- Surveillance de Swiss Ephemeris amont via Dependabot

## Limitations connues

- **Dates hors plage** (avant 1800 et après 2399) : utilisation de l'analytique Moshier,
  précision ~0,1" (contre < 0,01" pour SWIEPH avec les fichiers DE431)
- **Lilith vrai (id=13) vs Lilith moyen (id=12)** : différence jusqu'à 12° — par défaut
  Lilith moyen (comportement stable), Lilith vrai disponible via `planetIds: [13]`
- **Topocentrique vs géocentrique** : géocentrique par défaut

## Liens

- Swiss Ephemeris : https://www.astro.com/swisseph/
- swetest CGI : https://www.astro.com/swisseph/swetest.htm
- Catalogue d'éclipses de la NASA : https://eclipse.gsfc.nasa.gov/
- Kerykeion : https://github.com/g-battaglia/kerykeion
- Astrodienst : https://www.astro.com/

## Contact

Pour toute question sur la précision : écris à support@astroway.info avec les
données de ta carte et la référence attendue (astro.com ou autre source
autoritaire).