libera_utils.libera_spice.spice_utils#

Core SPICE utilities for kernel creation, inspection, and time conversions.

This module is home to the core SPICE and kernel utilities in libera_utils, providing the make_kernel() wrapper around Curryer’s KernelCreator, kernel file caching and furnishing via KernelFileCache, the ensure_spice decorator, SPICE-based time conversion wrappers, and kernel inspection helpers.

Functions

`ensure_spice`([f_py, time_kernels_only])	Before trying to understand this piece of code, read this: https://stackoverflow.com/questions/5929107/decorators-with-parameters/60832711#60832711
`et2utc_wrapper`(et, fmt, prec)	Convert ephemeris times to UTC ISO strings.
`et_2_datetime`(et)	Convert ephemeris time to a python datetime object by first converting it to a UTC timestamp.
`et_2_timestamp`(et[, fmt])	Convert ephemeris time to a custom formatted timestamp (default is lowercase version of ISO).
`find_most_recent_naif_kernel`(naif_base_url, ...)	Retrieves the name of the most recent kernel at NAIF.
`ls_all_kernel_coverage`([as_datetime, verbose])	List time coverage of all furnished kernels
`ls_kernel_coverage`(kernel_type[, verbose])	List time coverage of all furnished kernels of a given type
`ls_kernels`([verbose, log])	List all furnished spice kernels.
`ls_spice_constants`([verbose])	List all constants in the Spice constant pool
`make_kernel`(config_file, output_kernel[, ...])	Create a binary SPICE kernel (CK or SPK) from a JSON configuration file and input data.
`sce2s_wrapper`(et)	Convert ephemeris times to SCLK string https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/sce2s_c.html Decorated wrapper for spiceypy.sce2s that will automatically furnish the latest metakernel and retry if the first call raises an exception.
`scs2e_wrapper`(sclk_str)	Convert SCLK strings to ephemeris time.
`utc2et_wrapper`(iso_str)	Convert UTC ISO strings to ephemeris times.

Classes

`KernelFileCache`(kernel_url[, max_cache_age, ...])	Class for downloading, caching, and furnishing SPICE kernel files locally.
`KernelFileRecord`(kernel_type, file_name)	Tuple for keeping track of kernel files with default kernel_level
`SpiceBody`(value)	Enum containing SPICE IDs for ephemeris bodies that we use.
`SpiceFrame`(value)	Enum containing SPICE IDs for reference frames, possibly defined in the Frame Kernel (FK)
`SpiceId`(strid, numid)	Class that represents a unique identifier in the NAIF SPICE library
`SpiceInstrument`(value)	Enum containing SPICE IDs for instrument geometries configured in the Instrument Kernel (IK)

class libera_utils.libera_spice.spice_utils.KernelFileCache(kernel_url: str, max_cache_age: timedelta = datetime.timedelta(days=1), fallback_kernel: Path = None)#

Class for downloading, caching, and furnishing SPICE kernel files locally.

It attempts to find a cached kernel file in the user’s cache directory (OS-specific location). If that file is not there or is old, it attempts to download it from the specified location. If it is unable to do that, it can optionally read a fallback file included in the libera_utils package but this is not recommended.

Attributes:

cache_dir: Property that calls out to get the proper local cache directory
kernel_basename: Base filename of the kernel.
kernel_path: Return the local path location of the kernel if it exists.

Methods

`clear`()	Remove cached kernel file
`download_kernel`(kernel_url[, allowed_attempts])	Downloads a kernel from a URL or an S3 location to the system cache location.
`furnsh`()	Furnish the cached kernel
`is_cached`([include_stale])	Check the cache directory for kernel file that is within cache age limit.

property cache_dir#

Property that calls out to get the proper local cache directory

Returns:: Path to the proper local cache for the system.
Return type:: pathlib.Path

clear()#: Remove cached kernel file

download_kernel(kernel_url: str, allowed_attempts: int = 3) → Path#

Downloads a kernel from a URL or an S3 location to the system cache location.

Parameters:

kernel_url (str) – Filename of kernel on NAIF site, as discovered by find_most_recent_naif_kernel
allowed_attempts (int, Optional) – Number of allowed download times for naif kernel default = 3

Returns:

Location of downloaded file

Return type:

pathlib.Path

furnsh()#: Furnish the cached kernel

is_cached(include_stale: bool = False) → bool#

Check the cache directory for kernel file that is within cache age limit. If present, return True.

Parameters:: include_stale (bool) – Default False. If True, results include kernel that are past the max age.
Returns:: Returns True if kernel is present locally and within the age limit.
Return type:: bool

property kernel_basename#

Base filename of the kernel.

Return type:: str

property kernel_path: Path#: Return the local path location of the kernel if it exists. If not, try downloading it. If that fails, return the fallback kernel, if allowed.

class libera_utils.libera_spice.spice_utils.KernelFileRecord(kernel_type: str, file_name: str)#

Tuple for keeping track of kernel files with default kernel_level

Methods

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

file_name: str#: Alias for field number 1

kernel_type: str#: Alias for field number 0

class libera_utils.libera_spice.spice_utils.SpiceBody(value)#: Enum containing SPICE IDs for ephemeris bodies that we use.

class libera_utils.libera_spice.spice_utils.SpiceFrame(value)#: Enum containing SPICE IDs for reference frames, possibly defined in the Frame Kernel (FK)

class libera_utils.libera_spice.spice_utils.SpiceId(strid: str, numid: int)#

Class that represents a unique identifier in the NAIF SPICE library

Methods

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

numid: int#: Alias for field number 1

strid: str#: Alias for field number 0

class libera_utils.libera_spice.spice_utils.SpiceInstrument(value)#: Enum containing SPICE IDs for instrument geometries configured in the Instrument Kernel (IK)

libera_utils.libera_spice.spice_utils.ensure_spice(f_py: Callable = None, time_kernels_only: bool = False)#

Before trying to understand this piece of code, read this: https://stackoverflow.com/questions/5929107/decorators-with-parameters/60832711#60832711

Decorator/wrapper that tries to ensure that a metakernel is furnished in as complete a way as possible.

Control flow overview:

Try simply calling the wrapped function naively.
- SUCCESS? Great! We’re done.
- SpiceyError? Go to step 2.
Furnish metakernel at SPICE_METAKERNEL
- SUCCESS? Great, return the original function again (so it can be re-run).
- KeyError? Seems like SPICE_METAKERNEL isn’t set, no problem. Go to step 3.

Usage:

Three ways to use this object

A decorator with no arguments

@ensure_spice
def my_spicey_func(a, b):
    pass

2. A decorator with parameters. This is useful if we only need the latest SCLK and LSK kernels for the function involved.

@ensure_spice(time_kernels_only=True)
def my_spicey_time_func(a, b):
    pass

An explicit wrapper function, providing a dynamically set value for parameters, e.g. time_kernels_only

wrapped = ensure_spice(spicey_func, time_kernels_only=True)
result = wrapped(*args, **kwargs)

Parameters:

f_py (Callable) – The function requiring SPICE that we are going to wrap if being used explicitly, Otherwise None, in which case ensure_spice is being used, not as a function wrapper (see l2a_processing.py) but as a true decorator without an explicit function argument.
time_kernels_only (bool, Optional) – Specify that we only need to furnish time kernels (if SPICE_METAKERNEL is set, we still just furnish that metakernel and assume the time kernels are included.

Returns:

Decorated function, with spice error handling

Return type:

Callable

libera_utils.libera_spice.spice_utils.et2utc_wrapper(et: float | Collection[float] | ndarray, fmt: str, prec: int) → str | Collection[str]#

Convert ephemeris times to UTC ISO strings. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/et2utc_c.html Decorated wrapper for spiceypy.et2utc that will automatically furnish the latest metakernel and retry if the first call raises an exception.

Parameters:

et (Union[float, Collection[float], numpy.ndarray]) – The ephemeris time value to be converted to UTC.
fmt (str) – Format string defines the format of the output time string. See CSPICE docs.
prec (int) – Number of digits of precision for fractional seconds.

Returns:

UTC time string(s)

Return type:

Union[numpy.ndarray, str]

libera_utils.libera_spice.spice_utils.et_2_datetime(et: float | Collection[float] | np.ndarray) → datetime | np.ndarray#

Convert ephemeris time to a python datetime object by first converting it to a UTC timestamp.

Parameters:: et (float or Collection or numpy.ndarray) – Ephemeris times to be converted.
Returns:: Object representation of ephemeris times.
Return type:: datetime.datetime or numpy.ndarray

libera_utils.libera_spice.spice_utils.et_2_timestamp(et: float | Collection[float] | ndarray, fmt: str = '%Y%m%dT%H%M%S.%f') → str | Collection[str]#

Convert ephemeris time to a custom formatted timestamp (default is lowercase version of ISO).

Parameters:

et (Union[float, Collection[float], numpy.ndarray]) – Ephemeris Time to be converted.
fmt (str, Optional) – Format string as defined by the datetime.strftime() function.

Returns:

Formatted timestamps

Return type:

Union[str, Collection[str]]

libera_utils.libera_spice.spice_utils.find_most_recent_naif_kernel(naif_base_url: str, kernel_file_regex: str, allowed_attempts: int = 3) → str#

Retrieves the name of the most recent kernel at NAIF.

Parameters:

naif_base_url (str) – URL to search for filenames matching kernel_file_regex
kernel_file_regex (str) – Regular expression to match filenames on the naif website
allowed_attempts (int, Optional) – Number of allowed download times for naif page default = 3

Returns:

Returns the file name of the latest kernel on the naif page (e.g., “naif0012.tls”)

Return type:

str

libera_utils.libera_spice.spice_utils.ls_all_kernel_coverage(as_datetime: bool = True, verbose: bool = False) → dict#

List time coverage of all furnished kernels

Parameters:: verbose (bool) – If True, print to stdout also
Returns:: Key is filename, value is a list of tuples giving the start and end times in ET.
Return type:: dict

libera_utils.libera_spice.spice_utils.ls_kernel_coverage(kernel_type: str, verbose: bool = False) → dict#

List time coverage of all furnished kernels of a given type

Parameters:

kernel_type (str) – Either ‘CK’ or ‘SPK’
verbose (bool) – If True, print to stdout also

Returns:

Key is filename, value is a list of tuples giving the start and end times in ET.

Return type:

dict

libera_utils.libera_spice.spice_utils.ls_kernels(verbose: bool = False, log: bool = False) → list#

List all furnished spice kernels.

Parameters:

verbose (bool) – If True, print to stdout also
log (bool) – Whether or not to log the current kernel pool (this gets called a lot)

Returns:

A list of KernelFileRecord named tuples.

Return type:

list

libera_utils.libera_spice.spice_utils.ls_spice_constants(verbose: bool = False) → dict#

List all constants in the Spice constant pool

Parameters:: verbose – If true, print to stdout also
Returns:: Dictionary of kernel constants
Return type:: dict

Create a binary SPICE kernel (CK or SPK) from a JSON configuration file and input data.

This is a low-level utility that wraps Curryer’s KernelCreator, which drives the NAIF command-line tools mkspk (for SPK ephemeris kernels) and msopck (for CK attitude kernels). It is used for creating binary CK and SPK kernels, including fixed-offset static SPKs and dynamic CK/SPK kernels.

This function does NOT create text kernels such as LSKs (.tls), PCKs (.tpc), frame kernels (.tf), instrument kernels (.ti), or clock kernels (.tsc). Those are plain-text files managed separately.

Callers are responsible for ensuring required kernels (especially LSK and any relevant frame kernels) are furnished before calling this function.

Parameters:

config_file (str | Path) – JSON configuration file defining how to create the kernel.
output_kernel (str | PathType) – Output directory or file to create the kernel. If a directory, the file name will be based on the config_file, but with the SPICE file extension.
input_data (pd.DataFrame | None) – pd.DataFrame containing kernel input data. If not supplied, the config is assumed to reference an input data file.
overwrite (bool) – Option to overwrite an existing file.
append (bool | int) – Option to append to an existing file. Anything truthy will be treated as True.

Returns:

Output kernel file path

Return type:

PathType

Notes

This function requires a leap second kernel (LSK) to be furnished by SPICE before it can convert times. Callers should use KernelManager.load_naif_kernels() or similar to ensure kernels are ready before calling this function.

libera_utils.libera_spice.spice_utils.sce2s_wrapper(et: float | Collection[float] | ndarray) → str | ndarray#

Convert ephemeris times to SCLK string https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/sce2s_c.html Decorated wrapper for spiceypy.sce2s that will automatically furnish the latest metakernel and retry if the first call raises an exception.

Parameters:: et (Union[float, Collection[float], numpy.ndarray]) – Ephemeris time
Returns:: SCLK string
Return type:: Union[str, Collection[str]]

libera_utils.libera_spice.spice_utils.scs2e_wrapper(sclk_str: str | Collection[str]) → float | ndarray#

Convert SCLK strings to ephemeris time. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/scs2e_c.html Decorated wrapper for spiceypy.scs2e that will automatically furnish the latest metakernel and retry if the first call raises an exception.

Parameters:: sclk_str (Union[str, Collection[str]]) – Spacecraft clock string
Returns:: Ephemeris time
Return type:: Union[float, numpy.ndarray]

libera_utils.libera_spice.spice_utils.utc2et_wrapper(iso_str: str | Collection[str]) → float | ndarray#

Convert UTC ISO strings to ephemeris times. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/utc2et_c.html Decorated wrapper for spiceypy.utc2et that will automatically furnish the latest metakernel and retry if the first call raises an exception.

Parameters:: iso_str (Union[str, Collection[str]]) – The UTC to convert to ephemeris time
Returns:: Ephemeris time
Return type:: float or numpy.ndarray

libera_utils.libera_spice.spice_utils#

This Page