libera_utils.libera_spice.kernel_manager#

SPICE Kernel Manager

This module provides a clean interface for managing SPICE kernels for the Libera instrument. It separates kernel lifecycle management from computation logic to improve maintainability and performance.

Classes

KernelManager([temp_dir_base, ...])

Manages SPICE kernel loading and lifecycle for Libera geolocation calculations.
class libera_utils.libera_spice.kernel_manager.KernelManager(temp_dir_base: str | Path | None = None, download_naif_url: str = 'https://naif.jpl.nasa.gov/pub/naif/generic_kernels/', use_test_naif_url: bool = False, use_high_precision_earth: bool = True, cache_timeout_days: int = 7)#

Manages SPICE kernel loading and lifecycle for Libera geolocation calculations.

Parameters:

  • temp_dir_base (str | Path | None) – Base directory for temporary kernel files. If None, uses platform default. Can also be controlled via LIBERA_TEMP_DIR environment variable.

  • max_path_length (int) – Maximum allowed path length when validation is enabled (default: 80 to match SPICE requirements).

Methods

ensure_known_kernels_are_furnished()

Method to verify all known kernels are furnished by SPICE.

load_libera_dynamic_kernels(...[, ...])

Load dynamic kernels from an explicit sequence of sources (typically manifest order).

load_naif_kernels([cache_time_out])

Load NAIF generic kernels into SPICE.

load_static_kernels()

Load Libera static kernels into SPICE.

unload_all()

Unload all SPICE kernels and clean up resources.
_create_temporary_static_kernels() → Path#

Curryer uses json based kernel configuration files to generate SPICE kernels. These configuration files need to be processed into actual SPICE kernel files before they can be loaded. This method creates a temporary directory, copies the necessary configuration files, and generates the static kernels into that directory.

This method will start by furnishing the naif kernels to ensure the leap second kernel is available, as it is required for static kernel generation.

Returns:

Path to the created temporary directory containing static kernels.

Return type:

Path

Raises:

RuntimeError – If kernel creation fails or path exceeds length limit.

_delete_temporary_static_kernels() → None#

Delete the temporary static kernels directory.

Safely removes the directory and all contents. Logs warnings but doesn’t raise exceptions to allow cleanup to proceed.

static _output_basename_for_static_kernel_config(config_path: Path) → str#

Binary kernel filename produced by make_kernel for a static JSON config.

_prepare_static_kernel_workspace() → None#

Ensure user-cache copies of generated static kernels exist, building on cache miss.

static _static_generated_kernel_basenames() → list[str]#

Basenames of generated static binaries from LIBERA_KERNEL_STATIC_CONFIGS.

ensure_known_kernels_are_furnished() → None#

Method to verify all known kernels are furnished by SPICE.

Raises:

RuntimeError – If kernels are not properly loaded.

load_libera_dynamic_kernels(dynamic_kernel_sources: Sequence[str | Path | S3Path], *, needs_static_kernels: bool = True, needs_naif_kernels: bool = True) → None#

Load dynamic kernels from an explicit sequence of sources (typically manifest order).

This will load static and NAIF kernels first when requested and they are not already loaded.

Every source is materialized through KernelFileCache with max_cache_age equal to cache_timeout_days from construction.

Parameters:

  • dynamic_kernel_sources (sequence of str, pathlib.Path, or cloudpathlib.S3Path) – One cache entry per element; see KernelFileCache for local paths vs remote URLs. Use [single_path] or ["https://..."] — bare Path / str / bytes arguments are rejected because str is a Python Sequence.

  • needs_static_kernels (bool) – Whether to ensure static kernels are loaded before loading dynamic kernels (default: True).

  • needs_naif_kernels (bool) – Whether to ensure NAIF kernels are loaded before loading dynamic kernels (default: True).

Raises:

  • FileNotFoundError – If paths do not exist, or the sequence is empty.

  • ValueError – If an entry resolves to a directory instead of a kernel file.

  • TypeError – If dynamic_kernel_sources is not a non-string sequence (pass Path objects inside a tuple/list).

load_naif_kernels(cache_time_out: int | None = None) → None#

Load NAIF generic kernels into SPICE. This method will first look in the generic kernel directory, and if no local versions of the needed kernels are found, it will download them from the NAIF server and cache them locally.

These include leap seconds, planetary ephemeris, and Earth orientation data.

Raises:
load_static_kernels() → None#

Load Libera static kernels into SPICE.

Static kernels include instrument orientation and configuration data that doesn’t change with time. This only needs to be called once. This method also guarantees NAIF kernels are loaded (including leap-second setup) so callers can rely on a consistent initialization contract for both static cache-hit and static rebuild paths.

Raises:

  • FileNotFoundError – If kernel files cannot be found at expected paths.

  • RuntimeError – If kernel loading fails or paths exceed length limits.

unload_all() → None#

Unload all SPICE kernels and clean up resources.

This should be called when done with calculations to free memory and ensure clean state for subsequent operations.