Ephemeris N16 Generator 0.5.5
==============================

Purpose
-------

This self-contained command-line application creates the optional N16 state
table for the Ephemeris calculation core. N16 is the set of 16 massive
asteroids Ceres, Pallas, Juno, Vesta, Iris, Hygiea, Eunomia, Psyche,
Euphrosyne, Europa, Cybele, Sylvia, Thisbe, Camilla, Davida and Interamnia.

When explicitly started, the generator downloads an official object-specific
SPK file from JPL Horizons for each asteroid and the Horizons GM file. It
reads SPK data type 21 itself, samples all state vectors on one common time
grid and writes:

  n16-states-f64.bin
  manifest.json
  core-data/n16/n16-2000-2004.bin through n16-2040-2040.bin
  core-data/n16/index.json

Python, .NET and CSPICE do not have to be installed on the target computer.
Each of the six distributed programs contains the required .NET runtime.

Supported packages
------------------

  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

This application has no graphical interface. Progress, errors and the final
result are written to the terminal.

Quick start on Windows
----------------------

Open PowerShell in the extracted directory:

  .\Ephemeris-N16-Generator.exe

Specify a different destination:

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

Verify an existing result without network access:

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

Files used by the calculation core
----------------------------------

The large n16-states-f64.bin file is the complete language-neutral
intermediate result. The released language cores instead read the nine ready
files in core-data/n16. The generator creates those files automatically when
the default settings are used.

A complete data root for the calculation core looks like this:

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

After generation, copy the complete directory

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

as the n16 subdirectory next to the existing planets directory. Pass the
parent ephemeris-data directory as the data root to the selected language core
and enable includeN16. The exact constructor and function syntax is documented
in the manual for that language package.

Important: The N16 generator does not create planet data. The planets directory
must already be complete. Without the planet chunks, the core cannot calculate
an ephemeris even when N16 is available.

Quick start on Linux
--------------------

Depending on the ZIP extractor, set the executable bit once:

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

Quick start on macOS
--------------------

After extraction:

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

The published file is not signed with an Apple developer identity and is not
notarized. macOS may therefore display a security prompt on first launch.
Check the published SHA-256 checksum first and then allow the application in
the macOS Privacy & Security settings.

Default destination directories
-------------------------------

Without --output, the following per-user directories are used:

Windows:

  %LOCALAPPDATA%\AmrumSoftware\Ephemeris\n16

macOS:

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

Linux:

  $XDG_DATA_HOME/AmrumSoftware/Ephemeris/n16

If XDG_DATA_HOME is unset:

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

The EPHEMERIS_N16_DIRECTORY environment variable overrides this default.

Command-line parameters
-----------------------

--start YYYY-MM-DD

  Requested start of SPK coverage. The default is 1850-01-01.

--stop YYYY-MM-DD

  Requested end of SPK coverage. The default is 2150-01-01. The stop date
  must be later than the start date.

--output DIRECTORY

  Destination for n16-states-f64.bin, manifest.json, directly usable files
  below core-data/n16 and temporarily downloaded source files.

--refresh

  Download all source files again instead of reusing local SPKs.

--request-delay SECONDS

  Pause between Horizons requests. The default is 1 second. Negative values
  are rejected.

--sample-step-days DAYS

  Requested spacing of table points. The default is 2 days. The generator
  adjusts the actual interval slightly so both coverage endpoints lie exactly
  on the shared grid. The exact value is recorded in the manifest.

--keep-source-spk

  Retain the downloaded object SPKs and the GM file in the source-spk
  subdirectory after successful generation.

--remove-source-spk

  Remove downloaded sources after successful generation. This is the
  default. The generated table and manifest are retained.

--verify

  Verify existing output data. Use together with --output. This mode neither
  downloads nor changes files.

--licenses

  Display concise software-license information.

--data-terms

  Display the source and legal boundary of the astronomical data.

--version

  Display the program version.

--help or -h

  Display concise help.

Examples
--------

Generate the default data set:

  Ephemeris-N16-Generator

Generate only 2000 through 2040 and retain source files:

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

Verify the result:

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

Network, run time and storage
-----------------------------

Only generation requires Internet access. Verification and subsequent
ephemeris calculations run locally. For the default interval, 16 object SPKs
and one small GM file are downloaded. Their size and the run time may change
when Horizons changes its output.

Generation needs additional space for source files and a temporary output
file. By default, SPKs are removed only after successful verification. They
are retained after an error so that the next run can reuse them.

Output format
-------------

n16-states-f64.bin contains little-endian float64 values in this order:

  epoch
    asteroid
      x, y, z, vx, vy, vz

Positions are stored in AU and velocities in AU per day. The frame is
Sun-centred J2000. manifest.json records the complete asteroid order,
coverage, step, dimensions, sources and SHA-256 values. Consumers should read
these values from the manifest rather than guessing them.

Verification and errors
-----------------------

After writing, the generator verifies:

  manifest structure
  fixed order of the 16 asteroids
  file size and dimensions
  time coverage and step
  SHA-256 of the binary file

The final binary is replaced only after the temporary output was written
completely. The process returns exit code 1 for a generation error, 2 for a
failed --verify check and 0 for success.

Troubleshooting
---------------

Horizons request failed:

  Check the Internet connection and system time, retry later and do not
  increase the request rate unnecessarily.

Access denied:

  Use a writable --output directory. Do not use a protected program
  directory as the data destination.

Damaged file:

  Use --refresh to download the source again from Horizons.

Wrong platform package:

  Check the operating system and processor architecture. x64 and ARM64
  packages are not interchangeable.

Licences and data
-----------------

The project code is licensed under Apache License 2.0. The package includes
the complete licence and notices for the embedded .NET runtime and the SPK
type-21 reference implementation used during validation.

SPKs downloaded from JPL Horizons and the table generated locally from them
are not relicensed under Apache 2.0 by this project. Anyone redistributing
those data must independently review the current JPL, Horizons and NAIF
rules. See DATA-SOURCES-AND-TERMS.md.

Links
-----

Ephemeris website:

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

JPL Horizons API:

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

NAIF SPK documentation:

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