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.

Kernel paths are validated against the SPICE 80-character limit (see Notes). Short temporary workspaces (temp_dir_base) help generated kernels stay within that limit.

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.

  • download_naif_url (str) – Base URL for NAIF generic kernel downloads.

  • use_test_naif_url (bool) – When True, use a flat test index layout instead of NAIF subdirectory structure.

  • use_high_precision_earth (bool) – When True (default), load the NAIF ITRF93 Earth-orientation bundle: association FK, extended predict binary PCK (earth_*_predict.bpc), and ops high-precision binary PCK (earth_000101_*.bpc). Files are discovered in GENERIC_KERNEL_DIR or downloaded from NAIF. When False, only base kernels (leap seconds, DE, text PCK) are loaded; use only when ITRF93 / Libera+JPSS geolocation is not required. The name is historical; this flag gates the full ITRF93 stack, not a precision-only toggle.

  • cache_timeout_days (int) – Maximum age in days before cached NAIF kernels are refreshed.

Notes

The path length limit is fixed by the class attribute _max_path_length (80) and is not a constructor argument. load_static_kernels validates paths before furnishing kernels.

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. When use_high_precision_earth is True, ITRF93 kernels (association FK, predict and ops binary PCK) are included; see KernelManager parameter documentation.

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.