libera_utils.spice_utils

Modules for SPICE kernel creation, management, and usage

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
find_most_recent_naif_kernel(naif_base_url, ...)	Retrieves the name of the most recent kernel at NAIF.
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

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[, names, module, qualname, ...])	Enum containing SPICE IDs for ephemeris bodies that we use.
SpiceFrame(value[, names, module, qualname, ...])	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[, names, module, ...])	Enum containing SPICE IDs for instrument geometries configured in the Instrument Kernel (IK)

class libera_utils.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.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.spice_utils.SpiceBody(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum containing SPICE IDs for ephemeris bodies that we use.

class libera_utils.spice_utils.SpiceFrame(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum containing SPICE IDs for reference frames, possibly defined in the Frame Kernel (FK)

class libera_utils.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.spice_utils.SpiceInstrument(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum containing SPICE IDs for instrument geometries configured in the Instrument Kernel (IK)

libera_utils.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:

1. Try simply calling the wrapped function naively.

   • SUCCESS? Great! We’re done.

   • SpiceyError? Go to step 2.

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

1. 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

3. 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.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.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.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.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