Ephemeris API

ApsidesTable

Bases: BatchableObject

Apsides events.

Parameters:

Name	Type	Description	Default
is_valid	Bool[Array, ...]	Valid-event mask.	required
t_apsides	TDBView	Event epochs in TDB.	required
event_type	Int[Array, ...]	Event types. 0 means periapsis and 1 means apoapsis.	required
distance	Float[Array, ...]	Apsides distances in au.	required

Notes

This table has a fixed output length. If the actual number of events is smaller than the allocated length, the remaining slots are padding. is_valid marks valid events and invalid padding events.

CloseApproachTable

Bases: BatchableObject

Close-approach events.

Parameters:

Name	Type	Description	Default
is_valid	Bool[Array, ...]	Valid-event mask.	required
t_close	TDBView	Event epochs in TDB.	required
distance	Float[Array, ...]	Close-approach distances in au.	required
relative_velocity	Float[Array, ...]	Relative speeds in au / day.	required

Notes

This table has a fixed output length. If the actual number of events is smaller than the allocated length, the remaining slots are padding. is_valid marks valid events and invalid padding events.

EphemerisGenerator(target)

Bases: Module

High-level generator for ephemeris tables.

Initialize the ephemeris generator.

Parameters:

Name	Type	Description	Default
target	SmallBody	Target body with the propagated trajectory.	required

optical_table(t_obs, observer, apply_refraction=False, weather=WeatherParams(), grid=False)

Build optical tables.

Parameters:

Name	Type	Description	Default
t_obs	Time	Observation epochs at the observer.	required
observer	Site	Observer sites.	required
apply_refraction	bool	If True, apply atmospheric refraction for ground observers.	False
weather	WeatherParams	Weather model used by the refraction correction.	WeatherParams()
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
OpticalTable	Optical tables for the target. The astrometric angles use the solved down-leg direction in ICRS. The apparent angles add solar light bending and stellar aberration, then rotate to the true equator and equinox of date. For ground observers, azimuth, elevation, and the apparent angles also include atmospheric refraction when apply_refraction=True.

Raises:

Type	Description
RuntimeError	If the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.generate_optical_table_single.

radar_table(t_rec, rx, tx=None, tx_freq=0.0, grid=False)

Build radar tables.

Parameters:

Name	Type	Description	Default
t_rec	Time	Receive epochs at the receiver site. Epochs before 1962-01-01 are not supported.	required
rx	Site	Receiver sites.	required
tx	Site	Transmitter sites. If None, use rx.	None
tx_freq	Float[Array, ...]	Transmit frequencies in Hz.	0
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
RadarTable	Radar tables for the target.

Raises:

Type	Description
RuntimeError	Raised when any receive epoch is earlier than 1962-01-01, or when the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.generate_radar_table_single.

vector_table(t_obs, observer, grid=False)

Build vector tables.

Parameters:

Name	Type	Description	Default
t_obs	Time	Observation epochs at the observer.	required
observer	Site	Observer sites.	required
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
VectorTable	Geometric, astrometric, and apparent vectors for the target. The astrometric state uses the solved down-leg light time. The apparent state adds stellar aberration on top of the astrometric state, but it does not apply solar light bending or rotation to an equator-of-date frame.

Raises:

Type	Description
TypeError	Raised when t_obs is not a supported Earth-rotation time scale.
RuntimeError	If the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.generate_vector_table_single.

elements_table(tdb, grid=False)

Build osculating element tables.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epochs in TDB.	required
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
KepElement	Osculating Keplerian elements in the JPL Horizons ecliptic-of-J2000 reference system.

Raises:

Type	Description
TypeError	Raised when t is not in TDB.
RuntimeError	If the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.generate_elements_single.

find_apsides(t_start, t_end, center, max_events=5, grid=False)

Find apsides events.

Parameters:

Name	Type	Description	Default
t_start	TDBView	Search interval in TDB.	required
t_end	TDBView	Search interval in TDB.	required
center	EphemerisBody	Center body.	required
max_events	int	Maximum number of returned events.	5
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
ApsidesTable	Periapsis and apoapsis events for the target.

Raises:

Type	Description
TypeError	Raised when t_start or t_end is not in TDB.
RuntimeError	If the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.find_apsides_single.

find_close_approaches(t_start, t_end, center, max_distance=0.5, max_events=5, grid=False)

Find close-approach events.

Parameters:

Name	Type	Description	Default
t_start	TDBView	Search interval in TDB.	required
t_end	TDBView	Search interval in TDB.	required
center	EphemerisBody	Center body.	required
max_distance	float	Maximum close-approach distance in au.	0.5
max_events	int	Maximum number of returned events.	5
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
CloseApproachTable	Close-approach events for the target.

Raises:

Type	Description
TypeError	Raised when t_start or t_end is not in TDB.
RuntimeError	If the target trajectory is not initialized or the requested epoch is outside the propagated coverage.

Notes

Vectorize :func:difforb.ephemeris.core.find_close_approaches_single.

OpticalTable

Bases: BatchableObject

Optical table.

Parameters:

Name	Type	Description	Default
t_obs	Time	Observation epoch at the observer.	required
astrometric_ra	Float[Array, ...]	Astrometric right ascension and declination in degrees. These angles come from the solved down-leg direction in ICRS. The light-time solver also includes the Sun Shapiro delay.	required
astrometric_dec	Float[Array, ...]	Astrometric right ascension and declination in degrees. These angles come from the solved down-leg direction in ICRS. The light-time solver also includes the Sun Shapiro delay.	required
apparent_ra	Float[Array, ...]	Apparent right ascension and declination in degrees. These angles start from the astrometric direction, then apply solar light bending and stellar aberration, and then rotate to the true equator and equinox of date. For ground observers, they also include atmospheric refraction when apply_refraction=True.	required
apparent_dec	Float[Array, ...]	Apparent right ascension and declination in degrees. These angles start from the astrometric direction, then apply solar light bending and stellar aberration, and then rotate to the true equator and equinox of date. For ground observers, they also include atmospheric refraction when apply_refraction=True.	required
azimuth	Float[Array, ...]	Topocentric azimuth (from north to east) and elevation in degrees. These values come from the apparent topocentric direction. For ground observers, they also include atmospheric refraction when apply_refraction=True.	required
elevation	Float[Array, ...]	Topocentric azimuth (from north to east) and elevation in degrees. These values come from the apparent topocentric direction. For ground observers, they also include atmospheric refraction when apply_refraction=True.	required
delta	Float[Array, ...]	Target-observer distance in au.	required
r	Float[Array, ...]	Target-Sun distance in au.	required
phase_angle	Float[Array, ...]	Sun-target-observer phase angle in degrees.	required
elongation	Float[Array, ...]	Solar elongation in degrees.	required
mag	Float[Array, ...]	Modeled apparent magnitude.	required

RadarTable

Bases: BatchableObject

Radar table.

Parameters:

Name	Type	Description	Default
t_rec	Time	Receive epoch at the receiver site.	required
radar_delay	Float[Array, ...]	Two-way light time in microseconds.	required
radar_doppler	Float[Array, ...]	Two-way Doppler shift in Hz.	required
radar_range	Float[Array, ...]	Two-way range in au.	required
radar_rate	Float[Array, ...]	Two-way range rate in au / day.	required

VectorTable

Bases: BatchableObject

Geometric, astrometric, and apparent vector table.

Parameters:

Name	Type	Description	Default
t_obs	Time	Observation epoch at the observer.	required
geometric	RelativeState	Geometric relative state in fixed ICRS axes. The target and observer are both evaluated at the observed epoch, with no light-time correction.	required
astrometric	RelativeState	Astrometric relative state in fixed ICRS axes. This state uses the solved down-leg light time. The light-time solver also includes the Sun Shapiro delay.	required
apparent	RelativeState	Apparent relative state in fixed ICRS axes. This state starts from astrometric and then applies stellar aberration. It does not apply solar light bending or any rotation to an equator-of-date frame.	required
light_time	Float[Array, ...]	One-way down-leg light time in days. This is the same light time used by astrometric and apparent.	required