Ephemeriden mit Skyfield optimieren und dokumentieren

BERECHNUNGSGRUNDLAGEN.md

@@ -0,0 +1,79 @@
+# Berechnungsgrundlagen
+
+Stand: 12.09.2026
+
+Diese Datei dokumentiert, welche Berechnungsbibliothek beziehungsweise welche
+Datenquelle die einzelnen Seiten verwenden.
+
+## Die drei wichtigsten Grundlagen
+
+### Astronomy Engine
+
+Die lokale Python-Version liegt in `public/py/astronomy.py`. Im Browser wird
+`public/js/astronomy.browser.min.js` verwendet.
+
+Astronomy Engine liefert auf vielen Seiten die Positionen von Sonne, Mond und
+Planeten sowie Ereigniszeiten wie Mondphasen, Finsternisse, Bedeckungen und
+Konjunktionen.
+
+### Skyfield mit `de421.bsp`
+
+Skyfield liegt lokal in `public/py/vendor` beziehungsweise
+`public/py/vendor_linux`. Die verwendete JPL-Ephemeride ist:
+
+`public/py/vendor_data/de421.bsp`
+
+Die zentrale Einrichtung erfolgt in `public/py/astronomical_conversions.py`.
+`de421.bsp` wird derzeit für die Planet-Ephemeriden in `ephemeriden_api.py`
+und für die Dämmerungsgrafik verwendet.
+
+Die Datei enthält Jupiter bis Neptun als Systemschwerpunkte. Die lokale
+`jup365`-Datei wird von den hier dokumentierten Seiten derzeit nicht verwendet.
+
+### Weitere Berechnungen
+
+Nicht jede Berechnung ist Skyfield oder Astronomy Engine:
+
+- Satellitenbahnen werden mit SGP4 aus TLE-Daten berechnet.
+- Kometen und Kleinplaneten werden derzeit aus ihren Bahnelementen mit eigenen
+  Kepler-Berechnungen bestimmt.
+
+## Seitenübersicht
+
+| Seite | Berechnungsgrundlage |
+|---|---|
+| `ephemeriden.php` | **Skyfield + `de421.bsp`** für Sonne, Mond und Planeten. Auf- und Untergang sowie Horizontkoordinaten werden ebenfalls mit Skyfield berechnet. Kometen und Kleinplaneten bleiben bei den eigenen Bahnelement-Berechnungen. Die interaktive Karte nutzt im Browser zusätzlich Astronomy Engine für Horizontberechnungen und Sterne. |
+| `monatsvorhersage.php` | Überwiegend **Astronomy Engine** über `public/py/api.py`. Satellitenereignisse verwenden SGP4. Die Dämmerungsgrafik verwendet Skyfield + `de421.bsp`. Jupiter- und Jupitermond-Ereignisse verwenden aktuell Astronomy Engine. |
+| `wochenvorhersage.php` | **Astronomy Engine** über `public/py/api.py`; je nach Bereich zusätzlich SGP4 für Satelliten. |
+| `jupitersystem.php` | **Astronomy Engine**. Die Darstellung im Browser und die Galileischen Monde werden über Astronomy Engine berechnet. `jup365.bsp` wird hier aktuell nicht geladen. |
+| `sonnenfinsternis.php` | **Astronomy Engine**, einschließlich lokaler Berechnung für den Standardstandort. |
+| `mondfinsternis.php` | **Astronomy Engine**. Der Zeitpunkt der Finsternis ist global; eine lokale Sichtbarkeitsbewertung ist davon getrennt. |
+| `sternbedeckungen.php` | **Astronomy Engine** über die lokale Python-API. Topozentrische Koordinaten und der Standardstandort werden berücksichtigt. |
+| `moonphase.php` | **Astronomy Engine** im Browser beziehungsweise über die lokale Python-API. |
+| `moonyear.php` | **Astronomy Engine** für Mondphasen und Mondpositionen. |
+| `satellitenhimmel.php` | **SGP4** für Satellitenbahnen; Astronomy Engine für astronomischen Kontext wie Sonne, Mond und Dämmerung. |
+| `drehbare_sternkarte.php` | **Astronomy Engine** im Browser für Horizont- und Koordinatenberechnungen. |
+| `sternenhimmel.php` | **Astronomy Engine** im Browser beziehungsweise über die lokale API. |
+| `tagbogen.php` | **Astronomy Engine** für Sonnen-, Mond- und Planetenbahnen. |
+| `solarsystem.php` | **Astronomy Engine** im Browser für das Sonnensystemmodell. |
+| `geocron3d.php` | **Astronomy Engine** im Browser. |
+| `geocron/index.php` | **Astronomy Engine** über das Geocron-Plugin. |
+
+## Zentrale Python-Dateien
+
+| Datei | Aufgabe |
+|---|---|
+| `public/py/api.py` | Allgemeine astronomische Ereignisse; überwiegend Astronomy Engine. Einzelne Dämmerungsberechnungen verwenden Skyfield. |
+| `public/py/ephemeriden_api.py` | Planet-Ephemeriden mit Skyfield + `de421.bsp`; Kleinplaneten und Kometen mit eigenen Bahnelement-Berechnungen. |
+| `public/py/astronomical_conversions.py` | Gemeinsame Skyfield-Konfiguration und Zugriff auf `de421.bsp`. |
+| `public/py/astronomy.py` | Lokale Python-Version der Astronomy Engine. |
+
+## Standort und Lichtlaufzeit
+
+Wo eine Seite einen Standort benötigt, wird grundsätzlich der persönliche
+Standardstandort des angemeldeten Benutzers verwendet. Fehlt dieser, greift
+der konfigurierte Fallback-Standort.
+
+Die Verwendung von Skyfield oder Astronomy Engine sagt allein noch nicht, ob
+eine Berechnung topozentrisch, geozentrisch oder mit Lichtlaufzeit erfolgt.
+Das ist je Ereignis in der jeweiligen Funktion festgelegt.