@spec default_kernel_files() :: [String.t()]

Returns the list of kernel filenames required by the default v0.1 kernel set.

@spec load_kernels() :: {:ok, map()} | {:error, term()}

Loads the default v0.1 SPICE kernel set from priv/kernels/.

Equivalent to load_kernels([]).

Returns

• {:ok, metadata} on success, where metadata is a map describing the loaded kernel set.
• {:error, :worker_not_available} if the native binary has not been compiled.
• {:error, :kernels_already_loaded} if kernels are already loaded and :replace was not set.

@spec load_kernels(keyword() | [String.t()]) :: {:ok, map()} | {:error, term()}

Loads SPICE kernels from explicit paths or using options.

Variants

load_kernels(opts) — load default kernel set with options

opts is a keyword list. Supported keys:

• :base_path — directory containing the kernel files (default: "#{File.cwd!()}/priv/kernels").
• :replace — when true, clears any previously loaded kernels before loading (default: false).

load_kernels(paths) — load explicit kernel file paths

paths is a list of absolute file path strings. Use load_kernels/2 to pass options alongside explicit paths.

Returns

• {:ok, metadata} on success.
• {:error, {:invalid_kernel_set, reason}} for invalid paths or missing files.
• {:error, :worker_not_available} if the native binary has not been compiled.
• {:error, :kernels_already_loaded} if kernels are already loaded and :replace was not set.
• {:error, {:unsupported_option, option}} for unknown options.

@spec load_kernels(
  [String.t()],
  keyword()
) :: {:ok, map()} | {:error, term()}

Loads SPICE kernels from explicit paths with options.

paths must be a list of absolute file path strings that form a valid v0.1 kernel set. opts supports :replace (boolean, default false).

Returns

• {:ok, metadata} on success.
• {:error, {:invalid_kernel_set, reason}} for invalid paths or missing files.
• {:error, :kernels_already_loaded} if kernels are loaded and :replace is false.
• {:error, {:unsupported_option, option}} for unknown options.

@spec metadata() :: {:ok, map() | nil}

Returns the metadata map for the currently loaded kernel set, or nil if no kernels have been loaded.

Returns

• {:ok, map() | nil}

@spec state(String.t(), float(), keyword()) :: {:ok, map()} | {:error, term()}

Returns the SPICE state (position, velocity, ecliptic coordinates) for a target.

target must be a SPICE target name string. et is ephemeris time in seconds past J2000 as returned by utc_to_et/1. Requires kernels to be loaded.

Options

All state options are fixed to the v0.1 defaults in this release. Passing non-default values returns {:error, {:unsupported_option, option}}.

Returns

• {:ok, map()} — state map with position/velocity/ecliptic keys.
• {:error, :invalid_et} when et is not a number.
• {:error, :invalid_target} when target is not a binary.
• {:error, :kernels_not_loaded} if no kernels have been loaded.

@spec utc_to_et(DateTime.t()) :: {:ok, float()} | {:error, term()}

Converts a UTC %DateTime{} to an ephemeris time (ET) seconds-past-J2000 float.

Requires kernels to be loaded via load_kernels/0.

Returns

• {:ok, float()} — ET value in seconds past J2000.
• {:error, :invalid_datetime} if the argument is not a %DateTime{}.
• {:error, :kernels_not_loaded} if no kernels have been loaded.