spice

This is a thread-safe, read only re-implementation of a SPICE kernel interpreter. Outputs of this exactly match the common cSPICE interpreter, but can be easily used among an arbitrary number of cores. SPICE kernel files are loaded directly into RAM.

Note

This does not use cSPICE, or any original SPICE library code.

cSPICE is difficult to use in a thread safe manner which is limiting when performing orbit calculations on millions of objects.

Data files which are automatically included:

DE440 - A SPICE file containing the planets within a few hundred years.

BSP files are also automatically included for the 5 largest asteroids, which are used for numerical integrations when the correct flags are set.

PCK Files which enable coordinate transformations between Earths surface and the common inertial frames.

class kete.spice.SpkInfo(name, jd_start, jd_end, center, frame, spk_type)

Information contained within a Spice Kernel.

center: Reference Center NAIF ID.

count(value, /): Return number of occurrences of value.

frame: Frame of reference.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

jd_end: JD date of the end of the spice segment.

jd_start: JD date of the start of the spice segment.

name: Name of the object.

spk_type: SPK Segment Type ID.

kete.spice.earth_pos_to_ecliptic(jd, geodetic_lat, geodetic_lon, height_above_surface, name=None, center='Sun')

Given a position in the frame of the Earth at a specific time, convert that to Sun centered ecliptic state.

This uses the WGS84 model of Earth’s shape to compute state. This uses Geodetic latitude and longitude, not geocentric.

The frame conversion is done using a high precision PCK file from the NAIF/JPL website. The file provided in kete is valid from ~2000 to ~2024. This file gives positional error on the scale of a few cm. Additionally a lower resolution file is provided which is valid until 2099, and will be used automatically when querying past the end of the high resolution file.

Parameters:

jd (float | Time) – Julian time (TDB) of the desired state.
geodetic_lat (float) – Latitude on Earth’s surface in degrees.
geodetic_lon (float) – Latitude on Earth’s surface in degrees.
height_above_surface (float) – Height of the observer above the surface of the Earth in km.
name (str | None) – Optional name of the position on Earth.
center (str) – The new center point, this defaults to being heliocentric.

Returns:

Returns the equatorial state of the target in AU and AU/days.

Return type:

State

kete.spice.get_state(target, jd, center='Sun', frame=Frames.Ecliptic)

Calculates the State of the target object at the specified time jd.

This defaults to the ecliptic heliocentric state, though other centers may be chosen.

Parameters:

target (str | int) – The names of the target object, this can include any object name listed in loaded_objects()
jd (float | Time) – Julian time (TDB) of the desired record.
center (str) – The center point, this defaults to being heliocentric.
frame (Frames) – Coordinate frame of the state, defaults to ecliptic.

Returns:

Returns the ecliptic state of the target in AU and AU/days.

Return type:

State

Raises:

ValueError – If the desired time is outside of the range of the source binary file.

kete.spice.kernel_fetch_from_url(url, force_download=False)

Download the target url into the cache folder of spice kernels.

Parameters:: force_download (bool)

kete.spice.kernel_header_comments(filename)

Return the comments contained within the header of the provided DAF file, this includes SPK and PCK files.

This does not load the contents of the file into memory, it only prints the header contents.

Parameters:: filename (str) – Path to a DAF file.

kete.spice.kernel_ls(): List all files contained within the kernels cache folder.

kete.spice.kernel_reload(filenames=None, include_cache=False)

Load the specified spice kernels into memory, this resets the currently loaded kernels.

If include_cache is true, this will reload the kernels contained within the kete cache folder as well.

Parameters:

filenames (list[str] | None) – Paths to the specified files to load, this must be a list of filenames.
include_cache – This decides if all of the files contained within the kete cache should be loaded in addition to the specified files.

kete.spice.loaded_object_info(desig)

Return the available SPK information for the target object.

Parameters:: desig (int | str) – Name or integer id value of the object.
Return type:: list[SpkInfo]

kete.spice.loaded_objects()

Return the name of all objects which are currently loaded in the SPICE kernels.

Return type:: list[tuple[str, int]]

kete.spice.moon_illumination_frac(jd, observer='399')

Compute the fraction of the moon which is illuminated at the specified time.

This is a simple approximation using basic spherical geometry, and defaults to having the observer located at the geocenter of the Earth.

>>> float(kete.spice.moon_illumination_frac(Time.from_ymd(2024, 2, 24)))
0.9964936478732302

Parameters:

jd (float | Time) – Julian time (TDB) of the desired state.
observer (str) – NAIF ID of the observer location, defaults to Earth geocenter.

Returns:

Fraction between 0 and 1 of the moons visible surface which is illuminated.

Return type:

State

kete.spice.mpc_code_to_ecliptic(obs_code, jd, center='Sun', full_name=False)

Load an MPC Observatory code as an ecliptic state.

This only works for ground based observatories.

Parameters:

obs_code (str) – MPC observatory code or name of observatory.
jd (float | Time) – Julian time (TDB) of the desired state.
center (str) – The new center point, this defaults to being heliocentric.
full_name – Should the final state include the full name of the observatory or just its code.

Returns:

Returns the equatorial state of the observatory in AU and AU/days.

Return type:

State

kete.spice.name_lookup(name)

Given the provided partial name or integer, find the full name contained within the loaded SPICE kernels.

>>> kete.spice.name_lookup("jupi")
('jupiter barycenter', 5)

>>> kete.spice.name_lookup(10)
('sun', 10)

If there are multiple names, but an exact match, the exact match is returned. In the case of Earth, there is also Earth Barycenter, but asking for Earth will return the exact match. Putting eart will raise an exception as there are 2 partial matches.

>>> kete.spice.name_lookup("Earth")
('earth', 399)

>>> kete.spice.name_lookup("Earth b")
('earth barycenter', 3)

Parameters:: name (int | str) – Name, partial name, or integer id value of the object.
Returns:: Two elements in the tuple, the full name and the integer id value.
Return type:: tuple

kete.spice.state_to_earth_pos(state)

Convert a [State] to the Earth’s surface lat/lon/height on the WGS84 reference.

This requires the earth_000101_*.pck file to be loaded which contains the instantaneous earth frame information. The one provided by kete has dates from around 2000 to early 2024, along with predicts into the future. New files may be downloaded from the NAIF website for additional precision or years of epoch.

Parameters:: state (State) – Convert the given state to latitude, longitude, and height in km on the WGS84 reference.