Sidereon.Ephemeris (Sidereon v0.8.0)

Copy Markdown View Source

JPL SPK/BSP ephemeris file reader.

Computes positions of solar system bodies, spacecraft, and minor planets using JPL SPK/BSP kernels (DE421, DE440, Horizons exports, etc.).

Reading is delegated to sidereon_core::astro::spk, the validated SPK reader shared by the rest of the engine. It evaluates SPK segment types 2 (Chebyshev position), 3 (Chebyshev state), and 21 (Extended Modified Difference Arrays), so DE-series planetary kernels and Horizons spacecraft / asteroid kernels are all supported through the same code path.

Example

{:ok, eph} = Sidereon.Ephemeris.load("de421.bsp")
{:ok, {x, y, z}} = Sidereon.Ephemeris.position(eph, :sun, :earth, ~U[2024-01-01 12:00:00Z])

Bodies

Bodies may be given as atoms (:ssb / :solar_system_barycenter, :mercury, :venus, :earth_moon_barycenter / :emb, :mars, :jupiter, :saturn, :uranus, :neptune, :pluto, :sun, :moon, :earth) or as raw NAIF integer codes. Integer codes pass straight through to the reader, which is how spacecraft and minor-planet kernels are queried (e.g. 20000433 for 433 Eros).

Summary

Types

body()
epoch()
load_error()
position_error()
t()
vec3()

Functions

load(path)

Load an SPK/BSP ephemeris file.

load!(path)

Like load/1 but raises on failure.

position(ephemeris, target, observer, datetime)

Compute the position of target relative to observer at the given time.

position!(ephemeris, target, observer, datetime)

Like position/4 but raises on failure.

Types

body()

@type body() :: atom() | integer()

epoch()

@type epoch() :: DateTime.t() | NaiveDateTime.t() | float() | integer()

load_error()

@type load_error() :: {:file_error, File.posix()} | {:invalid_path, term()}

position_error()

@type position_error() ::
  {:invalid_body, term()} | {:invalid_datetime, term()} | {:nif_error, term()}

t()

@type t() :: %Sidereon.Ephemeris{path: String.t()}

vec3()

@type vec3() :: {float(), float(), float()}

Functions

load(path)

@spec load(term()) :: {:ok, t()} | {:error, load_error()}

Load an SPK/BSP ephemeris file.

Returns {:ok, ephemeris} with a handle that can be passed to position/4, or {:error, reason} when the file cannot be loaded. The file is not held open; it is read on each position/4 call.

Example

{:ok, eph} = Sidereon.Ephemeris.load("/path/to/de421.bsp")

load!(path)

@spec load!(String.t()) :: t()

Like load/1 but raises on failure.

position(ephemeris, target, observer, datetime)

@spec position(t(), body(), body(), epoch()) ::
  {:ok, vec3()} | {:error, position_error()}

Compute the position of target relative to observer at the given time.

Returns {:ok, {x, y, z}} in km in the J2000/ICRF reference frame, or {:error, reason}.

The target and observer are body atoms (see module docs) or NAIF integer codes.

The datetime can be a DateTime, a NaiveDateTime, or a Julian Date (TDB) as a float.

Examples

{:ok, {x, y, z}} = Sidereon.Ephemeris.position(eph, :moon, :earth, datetime)

# Raw NAIF code (433 Eros) against a Horizons kernel:
{:ok, {x, y, z}} = Sidereon.Ephemeris.position(eph, 20_000_433, :sun, jd_tdb)

position!(ephemeris, target, observer, datetime)

@spec position!(t(), body(), body(), epoch()) :: vec3()

Like position/4 but raises on failure.