spice#

Interface to the SPICE package.

This module provides an interface to NAIF’s SPICE package.

Functions#

convert_julian_date_to_ephemeris_time(...)

Convert a Julian date to ephemeris time (equivalent to TDB in Spice).

convert_ephemeris_time_to_julian_date(...)

Convert ephemeris time (equivalent to TDB) to a Julian date.

convert_date_string_to_ephemeris_time(...)

Converts a date string to ephemeris time.

get_body_cartesian_state_at_epoch(...)

Get Cartesian state of a body, as observed from another body.

get_body_cartesian_position_at_epoch(...)

Get Cartesian position of a body, as observed from another body.

get_cartesian_state_from_tle_at_epoch(epoch, tle)

Get Cartesian state of a satellite from its two-line element set at a specified epoch.

compute_rotation_matrix_derivative_between_frames(...)

Computes time derivative of rotation matrix between two frames.

get_angular_velocity_vector_of_frame_in_original_frame(...)

Computes the angular velocity of one frame w.r.t.

get_body_properties(body_name, property, ...)

Get property of a body from Spice.

get_body_gravitational_parameter(body_name)

Get gravitational parameter of a body.

get_average_radius(body_name)

Get the (arithmetic) mean of the three principal axes of the tri-axial ellipsoid shape.

convert_body_name_to_naif_id(body_name)

Convert a body name to its NAIF identification number.

check_body_property_in_kernel_pool(...)

Check if a certain property of a body is in the kernel pool.

load_standard_kernels([alternative_kernels])

Loads the default spice kernels shopped with tudat.

get_total_count_of_kernels_loaded()

Get the number of spice kernels currently loaded.

load_kernel(kernel_file)

Loads a Spice kernel into the pool.

clear_kernels()

Clear all loaded spice kernels.

convert_julian_date_to_ephemeris_time(julian_date: float) float#

Convert a Julian date to ephemeris time (equivalent to TDB in Spice).

Function to convert a Julian date to ephemeris time, which is equivalent to barycentric dynamical time. A leap second kernel must have been loaded to use this function.

Parameters:

julian_date (int) – Julian date that is to be converted to ephemeris time.

Returns:

ephemeris_time

Return type:

float Julian date calculated from ephemeris time.

convert_ephemeris_time_to_julian_date(ephemeris_time: float) float#

Convert ephemeris time (equivalent to TDB) to a Julian date.

Function to convert ephemeris time, which is nearly equal to barycentric dynamical time, to the Julian date. A leap second kernel must have been loaded to use this function.

Parameters:

ephemeris_time (float) – Ephemeris time that is to be converted to Julian date.

Returns:

julian_date

Return type:

float Julian date calculated from ephemeris time.

convert_date_string_to_ephemeris_time(date_string: str) float#

Converts a date string to ephemeris time.

Function to convert a date string, for instance 1988 June 13, 3:29:48 to ephemeris time, wrapper for str2et_c spice function.

Parameters:

date_string (str) – String representing the date. See documentation of spice function str2et_c for details on supported formats.

Returns:

ephemeris_time

Return type:

str Ephemeris time corresponding to given date_string.

get_body_cartesian_state_at_epoch(target_body_name: str, observer_body_name: str, reference_frame_name: str, aberration_corrections: str, ephemeris_time: float) numpy.ndarray[numpy.float64[6, 1]]#

Get Cartesian state of a body, as observed from another body.

This function returns the state of a body, relative to another body, in a frame specified by the user. Corrections for light-time correction and stellar aberration can be applied to obtain the state of one of the bodies, as observed from the other. Wrapper for spkezr_c spice function.

Parameters:
  • target_body_name (str) – Name of the body of which the state is to be obtained. A kernel with the ephemeris of this body must have been loaded. The string must be a spice-recognized name or ID.

  • observer_body_name (str) – Name of the body relative to which the state is to be obtained. A kernel with the ephemeris of this body must have been loaded. The string must be a spice-recognized name or ID.

  • reference_frame_name (str) – The spice-recognized name of the reference frame in which the state is to be returned. Spice kernel(s) required to perform the necessary conversion from the states of the target and observer bodies to this frame need to have been loaded.

  • aberration_corrections (str) –

    Setting for correction for setting corrections. See Spice documentation for extended discussion. Short summary:

    • NONE: none

    • LT: light time corrected (one iteration for calculation)

    • CN: light time corrected (multiple iterations, max 3) for calculation

    • S: Stellar aberration corrected.

    • XLT and XCN: can be provided to make the ephemeris time input argument the transmission time, instead of reception time. Arguments can be combined (i.e.”LT+S” or “XCN+S”).

  • ephemeris_time (float) – Observation time (or transmission time of observed light, see description of aberrationCorrections).

Returns:

cartesian_state_vector

Return type:

np.ndarray[6,] Cartesian state vector (x,y,z, position+velocity).

get_body_cartesian_position_at_epoch(target_body_name: str, observer_body_name: str, reference_frame_name: str, aberration_corrections: str, ephemeris_time: float) numpy.ndarray[numpy.float64[3, 1]]#

Get Cartesian position of a body, as observed from another body.

This function returns the position of a body, relative to another body, in a frame specified by the user. Corrections for light-time correction and stellar aberration can be applied to obtain the state of one of the bodies, as observed from the other. Wrapper for spkpos_c spice function.

Parameters:
  • target_body_name (str) – Name of the body of which the state is to be obtained. A kernel with the ephemeris of this body must have been loaded. The string must be a spice-recognized name or ID.

  • observer_body_name (str) – Name of the body relative to which the state is to be obtained. A kernel with the ephemeris of this body must have been loaded. The string must be a spice-recognized name or ID.

  • reference_frame_name (str) – The spice-recognized name of the reference frame in which the state is to be returned. Spice kernel(s) required to perform the necessary conversion from the states of the target and observer bodies to this frame need to have been loaded.

  • aberration_corrections (str) –

    Setting for correction for setting corrections. See Spice documentation for extended discussion. Short summary:

    • NONE: none

    • LT: light time corrected (one iteration for calculation)

    • CN: light time corrected (multiple iterations, max 3) for calculation,

    • S: Stellar aberration corrected.

    • XLT and XCN: can be provided to make the ephemeris time input argument the transmission time, instead of reception time. Arguments can be combined (i.e.”LT+S” or “XCN+S”).

  • ephemeris_time (float) – Observation time (or transmission time of observed light, see description of aberrationCorrections).

get_cartesian_state_from_tle_at_epoch(epoch: float, tle: tudat::ephemerides::Tle) numpy.ndarray[numpy.float64[6, 1]]#

Get Cartesian state of a satellite from its two-line element set at a specified epoch.

This function retrieves the state of a satellite at a certain epoch by propagating the SGP or SDP models (near-Earth resp. deep space) with the given two-line elements (TLE). This function serves as a wrapper for the ev2lin_ function in CSpice.

Parameters:
  • epoch (float) – Time in seconds since J2000 at which the state is to be retrieved.

  • tle (Tle) – Shared pointer to a Tle object containing the SGP/SDP model parameters as derived from the element set.

Returns:

cartesian_state_vector

Return type:

np.ndarray[6,] Cartesian state vector (x,y,z, position+velocity).

compute_rotation_matrix_derivative_between_frames(original_frame: str, new_frame: str, ephemeris_time: float) numpy.ndarray[numpy.float64[3, 3]]#

Computes time derivative of rotation matrix between two frames.

This function computes the derivative of the rotation matrix between two frames at a given time instant. kernels defining the two frames, as well as any required intermediate frames, at the requested time must have been loaded. Wrapper for (part of) sxform_c spice function.

Parameters:
  • original_frame – Reference frame from which the rotation is made.

  • new_frame – Reference frame to which the rotation is made.

  • ephemeris_time – Value of ephemeris time at which rotation is to be determined.

Returns:

Return type:

Time derivative of rotation matrix from original to new frame at given time.

get_angular_velocity_vector_of_frame_in_original_frame(original_frame: str, new_frame: str, ephemeris_time: float) numpy.ndarray[numpy.float64[3, 1]]#

Computes the angular velocity of one frame w.r.t. to another frame.

Computes the angular velocity of one frame w.r.t. to another frame. at a given time instant. kernels defining the two frames, as well as any required intermediate frames, at the requested time must have been loaded. Wrapper for xf2rav_c spice function (utilizing sxform_c).

Parameters:
  • original_frame – Reference frame from which the rotation is made.

  • new_frame – Reference frame to which the rotation is made.

  • ephemeris_time – Value of ephemeris time at which rotation is to be determined.

Returns:

Return type:

Angular velocity of newFrame w.r.t. originalFrame, expressed in originalFrame.

get_body_properties(body_name: str, property: str, max_n_val: int) List[float]#

Get property of a body from Spice.

Function to retrieve a property of a body from Spice, wraps the bodvrd_c Spice function.

Parameters:
  • body_name – Name of the body of which the property is to be retrieved.

  • property

    Name of the property that is to be retrieved. Naming conventions can be found in the bodvrd_c function documentation.

  • maximum_number_of_values (int) – Number of values by which the property is expressed (i.e. 1 for gravitational parameter, 3 for tri-axial ellipsoid principal axes).

Returns:

Return type:

Property value(s) expressed in an STL vector of doubles.

Notes

Function returns values with distance unit km, not m!

get_body_gravitational_parameter(body_name: str) float#

Get gravitational parameter of a body.

This function retrieves the gravitational parameter of a body. Wraps the bodvrd_c spice function with “GM” as property type.

Parameters:

body – Name of the body of which the parameter is to be retrieved.

Returns:

Return type:

Gravitational parameter of requested body.

get_average_radius(body_name: str) float#

Get the (arithmetic) mean of the three principal axes of the tri-axial ellipsoid shape.

Returns the (arithmetic) mean of the three principal axes of the tri-axial ellipsoid shape of the requested body. Uses the bodvrd_c spice function with “RADII” as property type.

Parameters:

body – Name of the body of which the average radius is to be retrieved.

Returns:

Return type:

Arithmetic mean of principal axes of tri-axial ellipsoid shape model of body.

convert_body_name_to_naif_id(body_name: str) int#

Convert a body name to its NAIF identification number.

This function converts a body name to its NAIF identification number. The NAIF id number is required for a number of spice functions, whereas the name is easily interpretable by the user. Wrapper for the bods2c_c function.

Parameters:

body_name – Name of the body for which NAIF id is to be retrieved.

Returns:

Return type:

NAIF id number for the body with bodyName.

check_body_property_in_kernel_pool(body_name: str, body_property: str) bool#

Check if a certain property of a body is in the kernel pool.

This function checks if a certain property of a body is in the kernel pool. These properties are defined in PCK kernels. Their names are given in the kernel file, typical names can be found in the Spice documentation. Wrapper for the bodfnd_c function.

Parameters:
  • body_name – Name of the body of which the property is to be checked.

  • body_property – Name of the property of which the presence is to be checked, not case-sensitive.

Returns:

True if property is in pool, false if not.

Return type:

bool

load_standard_kernels(alternative_kernels: List[str] = []) None#

Loads the default spice kernels shopped with tudat.

Loads the default spice kernels shopped with tudat. The kernels that are loaded are (in order):

  • pck00010.tpc - Orientation and size/shape data for natural bodies, based mainly on IAU Working Group on Cartographic Coordinates and Rotational Elements, obtained from here

  • inpop19a_TDB_m100_p100_spice.tpc - Masses of solar system planets and large asteroids, as determined in INPOP19a ephemerides, obtained from here

  • NOE-4-2020.tpc - Mars and Martian moon masses; Mars rotation model, as determined/used in NOE Martian satellite ephemerides, obtained from here

  • NOE-5-2021.tpc - Jupiter and selected Jovian moon (Io, Europa, Ganymede, Callisto, Amalthea) masses; Jupiter rotation model, as determined/used in NOE Jovian satellite ephemerides, obtained from here

  • NOE-6-2018-MAIN-v2.tpc - Saturn and selected Saturnian moon (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus) masses; Saturn rotation model, as determined/used in NOE Saturnian satellite ephemerides, obtained from here

  • codes_300ast_20100725.bsp - Ephemerides of 300 of of the largest asteroids, obtained from here

  • inpop19a_TDB_m100_p100_spice.bsp - Ephemerides of Solar system planetary system barycenters, Sun, Moon, Earth and Pluto, as determined in INPOP19a ephemerides, obtained from here

  • NOE-4-2020.bsp - Mars, Phobos and Deimos ephemerides (w.r.t. Martian system barycenter), as determined/used in NOE Martian satellite ephemerides, obtained from here

  • NOE-5-2021.bsp - Jupiter, Io, Europa, Ganymede, Callisto, Amalthea ephemerides (w.r.t. Jovian system barycenter), as determined/used in NOE Jovian satellite ephemerides, obtained from here

  • NOE-6-2018-MAIN-v2.bsp - Saturn, Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus ephemerides (w.r.t. Saturnian system barycenter), as determined/used in NOE Saturnian satellite ephemerides, obtained from here

  • naif0012.tls - Leap second kernel, obtained from here

Parameters:

kernel_paths (list[str], default = None) – Optional alternative ephemeris kernels to be loaded, instead of the default ephemeris kernels. Note that using this input automatically prevents all of the above .bsp (ephemeris) kernels from loading.

get_total_count_of_kernels_loaded() int#

Get the number of spice kernels currently loaded.

This function returns the amount of Spice kernels that are loaded into the kernel pool. The same kernel can be loaded multiple times. Wrapper for the ktotal_c function.

Returns:

n_kernels

Return type:

int Number of spice kernels currently loaded.

load_kernel(kernel_file: str) None#

Loads a Spice kernel into the pool.

This function loads a Spice kernel into the kernel pool, from which it can be used by the various internal spice routines. Matters regarding the manner in which Spice handles different kernels containing the same information can be found in the spice required reading documentation, kernel section. Wrapper for the furnsh_c function.

Parameters:

file_path (str) – Path to the spice kernel to be loaded.

clear_kernels() None#

Clear all loaded spice kernels.

This function removes all Spice kernels from the kernel pool. Wrapper for the kclear_c function.

Returns:

None

Return type:

None

Classes#

SpiceEphemeris

Ephemeris derived class which retrieves the state of a body directly from the SPICE library.

class SpiceEphemeris#

Ephemeris derived class which retrieves the state of a body directly from the SPICE library.

The body of which the ephemeris is to be retrieved, as well as the origin and orientation of the reference frame in which the states are returned, and any corrections that are applied, are defined once during object construction.

__init__(self: tudatpy.kernel.interface.spice.SpiceEphemeris, target_body_name: str, observer_body_name: str, correct_for_stellar_aberration: bool = False, correct_for_light_time_aberration: bool = True, converge_light_time_aberration: bool = False, reference_frame_name: str = 'ECLIPJ2000', reference_julian_day: float = 2451545.0) None#

Constructor.

Sets the input variables for the calls to the spice function to retrieve state.

Parameters:
  • target_body_name (str) – Name of body of which the ephemeris is to be calculated.

  • observer_body_name (str) – Name of body relative to which the ephemeris is to be calculated.

  • correct_for_stellar_aberration (bool, default = False) – Boolean whether to correct for stellar Aberration in retrieved values of (observed state).

  • correct_for_light_time_aberration (bool, default = True) – Boolean whether to correct for light time in retrieved values of (observed state).

  • converge_light_time_aberration (bool, default = False) – Boolean whether to use single iteration or max. 3 iterations for calculating light time.

  • reference_frame_name (str, default = "ECLIPJ2000") – Name of the reference frame in which the ephemeris is to be calculated.

  • reference_julian_day (float, default = constants.JULIAN_DAY_ON_J2000) – Reference julian day w.r.t. which ephemeris is evaluated.

get_cartesian_state(self: tudatpy.kernel.interface.spice.SpiceEphemeris, seconds_since_epoch: float) numpy.ndarray[numpy.float64[6, 1]]#

Get Cartesian state from ephemeris.

Returns Cartesian state from ephemeris at given Julian day.

Parameters:

seconds_since_epoch (float) – Seconds since epoch at which ephemeris is to be evaluated.