Ephemeris N16-Erzeuger 0.5.5
================================

Zweck
-----

Diese eigenständige Kommandozeilenanwendung erzeugt die optionale
N16-Zustandstabelle für den Ephemeris-Rechenkern. N16 bezeichnet die 16
massereichen Asteroiden Ceres, Pallas, Juno, Vesta, Iris, Hygiea, Eunomia,
Psyche, Euphrosyne, Europa, Cybele, Sylvia, Thisbe, Camilla, Davida und
Interamnia.

Der Erzeuger lädt beim ausdrücklichen Start für jedes dieser Objekte eine
offizielle SPK-Datei von JPL Horizons sowie die Horizons-GM-Datei. Er liest die
SPK-Daten des Typs 21 selbst, tastet die Zustandsvektoren auf einem gemeinsamen
Zeitgitter ab und schreibt:

  n16-states-f64.bin
  manifest.json
  core-data\n16\n16-2000-2004.bin bis n16-2040-2040.bin
  core-data\n16\index.json

Python, .NET und CSPICE müssen auf dem Zielrechner nicht installiert sein. Die
sechs ausgelieferten Programme enthalten die benötigte .NET-Laufzeit.

Unterstützte Pakete
-------------------

  Windows 10/11 x64       win-x64
  Windows 11 ARM64        win-arm64
  Linux x64               linux-x64
  Linux ARM64             linux-arm64
  macOS Intel             osx-x64
  macOS Apple Silicon     osx-arm64

Die Anwendung besitzt keine grafische Oberfläche. Sie schreibt Fortschritt,
Fehler und das Ergebnis in das Terminal.

Schnellstart unter Windows
--------------------------

Öffnen Sie PowerShell im entpackten Verzeichnis:

  .\Ephemeris-N16-Generator.exe

Ein eigenes Zielverzeichnis wird so angegeben:

  .\Ephemeris-N16-Generator.exe --output D:\Ephemeris-Daten\n16

Ein vorhandenes Ergebnis wird ohne Internetzugriff geprüft:

  .\Ephemeris-N16-Generator.exe --verify --output D:\Ephemeris-Daten\n16

Welche Dateien der Rechenkern verwendet
---------------------------------------

Die große Datei n16-states-f64.bin ist das vollständige, sprachneutrale
Zwischenergebnis. Die veröffentlichten Sprachkerne lesen dagegen die neun
fertigen Dateien im Unterordner core-data\n16. Der Erzeuger legt diese Dateien
bei den Standardeinstellungen automatisch an.

Ein vollständiger Datenwurzelordner des Rechenkerns sieht so aus:

  ephemeris-data\
    planets\
      de440s-2000-2004.bin
      ...
    n16\
      n16-2000-2004.bin
      ...
      n16-2040-2040.bin
      index.json

Kopieren Sie daher nach der Erzeugung den vollständigen Ordner

  D:\Ephemeris-Daten\n16\core-data\n16

als Unterordner n16 neben den bereits vorhandenen Planetenordner. Übergeben
Sie den übergeordneten Ordner ephemeris-data als Datenwurzel an den jeweiligen
Sprachkern und schalten Sie dort includeN16 ein. Die genaue Schreibweise des
Konstruktor- und Funktionsaufrufs steht im Handbuch des Sprachpakets.

Wichtig: Der N16-Erzeuger erzeugt keine Planetendaten. Der Ordner planets muss
bereits vollständig vorhanden sein. Ohne Planetenblöcke kann der Rechenkern
auch mit N16 keine Ephemeride berechnen.

Schnellstart unter Linux
------------------------

Nach dem Entpacken muss das Ausführungsrecht je nach ZIP-Programm einmal
gesetzt werden:

  chmod +x Ephemeris-N16-Generator
  ./Ephemeris-N16-Generator

Schnellstart unter macOS
------------------------

Nach dem Entpacken:

  chmod +x Ephemeris-N16-Generator
  ./Ephemeris-N16-Generator

Die veröffentlichte Datei ist nicht mit einer Apple-Entwickleridentität
signiert und nicht notarisiert. macOS kann deshalb beim ersten Start eine
Sicherheitsabfrage anzeigen. Prüfen Sie zuvor die veröffentlichte
SHA-256-Prüfsumme und erlauben Sie die Anwendung anschließend in den
macOS-Datenschutz- und Sicherheitseinstellungen.

Standard-Zielverzeichnisse
--------------------------

Ohne --output werden folgende benutzerspezifischen Verzeichnisse verwendet:

Windows:

  %LOCALAPPDATA%\AmrumSoftware\Ephemeris\n16

macOS:

  ~/Library/Application Support/AmrumSoftware/Ephemeris/n16

Linux:

  $XDG_DATA_HOME/AmrumSoftware/Ephemeris/n16

Wenn XDG_DATA_HOME nicht gesetzt ist:

  ~/.local/share/AmrumSoftware/Ephemeris/n16

Die Umgebungsvariable EPHEMERIS_N16_DIRECTORY überschreibt dieses
Standardverzeichnis.

Kommandozeilenparameter
-----------------------

--start JJJJ-MM-TT

  Gewünschter Beginn der SPK-Abdeckung. Standard ist 1850-01-01.

--stop JJJJ-MM-TT

  Gewünschtes Ende der SPK-Abdeckung. Standard ist 2150-01-01. Das Enddatum
  muss nach dem Startdatum liegen.

--output VERZEICHNIS

  Ziel für n16-states-f64.bin, manifest.json, die direkt verwendbaren Dateien
  unter core-data/n16 und vorübergehend heruntergeladene Quelldateien.

--refresh

  Vorhandene SPK-Quelldateien nicht wiederverwenden, sondern neu laden.

--request-delay SEKUNDEN

  Pause zwischen zwei Horizons-Anfragen. Standard ist 1 Sekunde. Negative
  Werte sind nicht zulässig.

--sample-step-days TAGE

  Gewünschter Abstand der Tabellenpunkte. Standard ist 2 Tage. Der Erzeuger
  passt den tatsächlichen Abstand geringfügig an, damit Anfang und Ende genau
  auf dem gemeinsamen Gitter liegen. Der genaue Wert steht im Manifest.

--keep-source-spk

  Die heruntergeladenen Objekt-SPKs und die GM-Datei nach erfolgreicher
  Erzeugung im Unterverzeichnis source-spk behalten.

--remove-source-spk

  Die heruntergeladenen Quelldateien nach erfolgreicher Erzeugung löschen.
  Dies ist die Voreinstellung. Die erzeugte Tabelle und das Manifest bleiben
  erhalten.

--verify

  Vorhandene Ausgabedaten prüfen. Zusammen mit --output verwenden. Dabei wird
  nichts heruntergeladen und nichts verändert.

--licenses

  Kurze Lizenzinformation ausgeben.

--data-terms

  Herkunft und rechtliche Abgrenzung der astronomischen Daten anzeigen.

--version

  Programmversion anzeigen.

--help oder -h

  Kurzhilfe anzeigen.

Beispiele
---------

Standarddaten erzeugen:

  Ephemeris-N16-Generator

Nur 2000 bis 2040 erzeugen und Quelldateien behalten:

  Ephemeris-N16-Generator --start 2000-01-01 --stop 2040-01-01 \
    --keep-source-spk --output ./n16

Ergebnis prüfen:

  Ephemeris-N16-Generator --verify --output ./n16

Netzwerk, Laufzeit und Speicher
-------------------------------

Nur die Erzeugung benötigt Internetzugriff. Die Prüfung und die spätere
Ephemeridenrechnung arbeiten lokal. Für den Standardzeitraum werden 16
Objekt-SPKs und eine kleine GM-Datei geladen. Der Umfang und die Rechenzeit
können sich durch Änderungen bei Horizons ändern.

Während der Erzeugung ist zusätzlicher Platz für Quelldateien und eine
temporäre Ausgabedatei nötig. Mit der Voreinstellung werden die SPKs erst nach
erfolgreicher Prüfung gelöscht. Bei einem Fehler bleiben sie erhalten, damit
der nächste Lauf sie wiederverwenden kann.

Ausgabeformat
-------------

n16-states-f64.bin besteht aus Little-Endian-float64-Werten. Die Reihenfolge
lautet:

  Zeitpunkt
    Asteroid
      x, y, z, vx, vy, vz

Positionen werden in AE und Geschwindigkeiten in AE pro Tag gespeichert. Das
Bezugssystem ist sonnenzentriert J2000. Die vollständige Reihenfolge der
Asteroiden, Abdeckung, Schrittweite, Dimensionen, Quellen und SHA-256-Werte
stehen in manifest.json. Programme sollen diese Angaben aus dem Manifest
lesen und nicht erraten.

Prüfung und Fehlerbehandlung
----------------------------

Der Erzeuger prüft nach dem Schreiben:

  die Manifeststruktur
  die festgelegte Reihenfolge der 16 Asteroiden
  Dateigröße und Dimensionen
  Zeitabdeckung und Schrittweite
  SHA-256 der Binärdatei

Er ersetzt die endgültige Binärdatei erst nach vollständig geschriebenem
temporärem Ergebnis. Bei einem Fehler endet das Programm mit Rückgabewert 1,
bei einer fehlgeschlagenen --verify-Prüfung mit Rückgabewert 2 und bei Erfolg
mit Rückgabewert 0.

Fehlersuche
-----------

Horizons-Anfrage fehlgeschlagen:

  Internetverbindung und Systemzeit prüfen, später erneut versuchen und die
  Anfragefrequenz nicht unnötig erhöhen.

Zugriff verweigert:

  Ein beschreibbares --output-Verzeichnis verwenden. Keine geschützten
  Programmverzeichnisse als Datenziel wählen.

Datei beschädigt:

  --refresh verwenden. Danach wird die Quelle erneut von Horizons geladen.

Falsches Plattformpaket:

  Betriebssystem und Prozessorarchitektur prüfen. x64 und ARM64 sind nicht
  austauschbar.

Lizenzen und Daten
------------------

Der Projektcode steht unter Apache License 2.0. Das Paket enthält die
vollständige Lizenz sowie die Hinweise für die eingebettete .NET-Laufzeit und
die zur Prüfung verwendete SPK-Typ-21-Referenzimplementierung.

Die von JPL Horizons geladenen SPKs und die lokal daraus erzeugte Tabelle
werden durch das Projekt nicht unter Apache 2.0 neu lizenziert. Wer diese
Daten weitergibt, muss die jeweils geltenden JPL-, Horizons- und NAIF-Regeln
selbst prüfen. Siehe DATA-SOURCES-AND-TERMS.md.

Links
-----

Ephemeris-Webseite:

  https://www.jostjahn.de/amrum-software/ephemeris/

JPL-Horizons-API:

  https://ssd-api.jpl.nasa.gov/doc/horizons.html

NAIF-SPK-Dokumentation:

  https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/spk.html
