giant.utilities.spice_interface

This module provides utility functions and classes for quickly creating callable objects to NAIF spice functions as well as a function to convert a datetime object to spice ephemeris time without using spice itself.

There are 2 different interfaes made available in this module. The perfered interface is a set of 3 classes plus two functions. The classes, SpicePosition, SpiceState, and SpiceOrientation are wrappers around calls to spice through the third party library spiceypy <https://spiceypy.readthedocs.io/en/master/> which compute the relative position vector, relative state vector (position and velocity), and rotation with preset options. This makes it really easy to use spice to drive SceneObject instances in GIANT (among other things). These only work when spiceypy is installed, but that should almost always be the case. They also require you to load the appropriate data before calling them using the furnsh <https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/spicelib/furnsh.html> spice function as is typical for spice. If you don’t load the data you will get a 'SpiceyError'.

Suppose we would frequently like to retrieve the position of the Moon with respect to the Earth in the J2000 inertial frame. Each time that we want to get this value we could do something like

>>> import spiceypy
>>> import datetime
>>> spiceypy.furnsh('/path/to/metakernel.tm')
>>> observation_date = datetime.datetime.now()
>>> et = spiceypy.str2et(observation_date.isoformat())
>>> pos, _ = spiceypy.spkpos('Moon', et, 'J2000', 'LT+S', 'Earth')

Or, if we use this interface we could do something like the following:

>>> import giant.utilities.spice_interface as spint
>>> moon_pos_earth = spint.SpicePosition("Moon", "J2000", "LT+S", "Earth")
>>> pos = moon_pos_earth(observation_date)

The 2 functions in the prefered interface, leap_seconds() and datetime_to_et() are useful time operations that are available whether spice is being used or not. The leap_seconds() function inputs a datetime object and outputs the number of leap seconds that occurred between the input observation_date and the J2000 epoch. The datetime_to_et() function converts and input datetime object into its corresponding ephemeris time.

The next group of functions are not prefered and also are only available when spiceypy is part of the current python installation and you have loaded the apropriate data. These functions create callable objects (actually partial function objects) that only take in a time and return a position, state, or orientation. The first function, create_callable_position(), returns a partial function object wrapped around the spkpos spice routine that accepts a ephemeris time as input and returns a position. The next function, create_callable_state(), does the same thing but returns a state vector (position and velocity) instead of just a position vector (and wraps the spkezr routine instead of spkpos). create_callable_orientation() wraps the pxform routine and returns a partial function which outputs a rotation given as an Rotation object when given an ephemeris time float as input. The final function, et_callable_to_datetime_callable() takes a callable object that inputs an ephemeris time as a float as input (most likely the result of one of the previous functions) and outputs a callable object (a function object) that accepts a datetime object as input instead. While this interface is fully functional, it does not play nicely with pickle due to the partial functions being anonymous, thus why we recommend the class interface instead which does work with pickle.

We could use these (not recommended) routines in this module and do something like

>>> moon_pos_earth_et = spint.create_callable_position('Moon', 'J2000', 'LT+S', 'EARTH')
>>> moon_pos_earth = spint.et_callable_to_datetime_callable(moon_pos_earth_et)
>>> pos = moon_pos_earth(observation_date)

Note that in the above, the light time output is dropped from the call to spkpos.

Note that all GIANT routines that require a function to return position, state, or orientation requires that the function work with only a datetime object input, making this module extremely useful (both interfaces).

Classes

SpicePosition	This class creates a callable that returns the position (in km) of one object to another given a python datetime.
SpiceState	This class creates a callable that returns the state vector (position and velocity, km and km/s respectively) of one object to another given a python datetime.
SpiceOrientation	This class creates a callable that returns the rotation from one frame to another as a Rotation given a python datetime.

Functions

leap_seconds	This function returns the number of leap seconds between observation_date and January 1, 12:00:00.000 (TDB).
datetime_to_et	This function converts a python datetime object to ephemeris time correcting for leap seconds
create_callable_position	This function generates a partial function of the spkpos method from spice with the target, frame, abcorr, and observer inputs already set (so that the only remaining input is the ephemeris time).
create_callable_state	This function generates a partial function of the spkezr method from spice with the target, frame, abcorr, and observer inputs already set (so that the only remaining input is the ephemeris time).
create_callable_orientation	This function generates a partial function of the pxform function from spice with the from and the to frames specified.
et_callable_to_datetime_callable	This function takes a callable object that takes a time in ephemeris time and returns a callable object that takes a time as a python datetime object.

Constants

HAS_SPICE	This flag specifies whether spiceypy is available in the current python environment
J2000_EPOCH	The UTC Epoch for spice ephemeris time
LEAP_SECONDS_LIST	A numpy datetime64 array of leap seconds taken from naif0012.tls