Body API

EphemerisBody(naif_name, eph=None)

Bases: Module

Body based on SPK ephemeris segments.

Parameters:

Name	Type	Description	Default
naif_name	str	NAIF body name.	required
eph	Ephemeris	Ephemeris object. If omitted, the default ephemeris is used.	None

Initialize an ephemeris body.

Parameters:

Name	Type	Description	Default
naif_name	str	NAIF body name.	required
eph	Ephemeris	Ephemeris object. If omitted, the default project ephemeris is used.	None

Raises:

Type	Description
ValueError	If the requested body name is not available in the ephemeris.
RuntimeError	If the body does not have a stored gravitational parameter in :mod:difforb.body.gm.

state(tdb, frame=BCRS, *, sun=None, earth=None)

Return the state at the given epoch in one requested frame.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
frame	Frame	Target output frame.	``BCRS``
sun	EphemerisBody	Sun ephemeris body used when frame touches the SUN origin.	None
earth	EphemerisBody	Earth ephemeris body used when frame touches the EARTH origin.	None

Returns:

Type	Description
State	State in frame. Position is in au and velocity is in au / day.

Raises:

Type	Description
TypeError	If tdb is not an instance of :class:TDBView.
ValueError	If converting the canonical BCRS state to frame requires the Sun or Earth and the corresponding ephemeris body is not available.

Notes

The native ephemeris output is canonical BCRS. This method evaluates that state first and then converts it through :class:difforb.core.state.state.State.

Orbit = Union[KepElement, State] module-attribute

Site(kind_ids, itrs_pos, itrs_lon, gcrs_pos, gcrs_vel, *, raw_keys=None, codes=None, identity_keys=None, display_labels=None)

Bases: BatchableObject

Observer sites stored as a uniform numerical batch.

A Site may contain fixed ground, roving ground, and space observers in the same batch. Ground rows store ITRS positions. Space rows store canonical GCRS position and velocity. String metadata is static PyTree data; numerical state is stored in JAX arrays.

Initialize a site batch from canonical numerical fields.

shape property

Batch shape of the stored site set.

is_fixed_ground property

Mask fixed ground rows.

is_roving_ground property

Mask roving ground rows.

is_ground property

Mask all ground rows.

is_space property

Mask space rows.

ground_itrs property

Ground coordinates stored as WGS84.

Space rows contain dummy zeros. Use :meth:require_ground when a caller requires every row to be terrestrial.

from_code(keys) classmethod

Build sites from observer keys.

Parameters:

Name	Type	Description	Default
keys	str or list[str] or ndarray	Observer keys. Fixed ground keys are plain observatory codes. Roving ground keys use "code @ lon_deg, lat_deg, alt_m". Space keys use "code # x_au, y_au, z_au".	required

Returns:

Type	Description
Site	Site batch represented by uniform numerical arrays.

from_geodetic(lon, lat, alt, type=WGS84) classmethod

Build ground sites from geodetic coordinates.

from_geocentric(lon, parallax_const1, parallax_const2, type=WGS84) classmethod

Build ground sites from geocentric observatory constants.

from_itrs(itrs) classmethod

Build ground sites from ITRS coordinates.

from_gcrs(pos_au, vel_au_per_d=None) classmethod

Build space sites from canonical GCRS coordinates.

from_state(state) classmethod

Build space sites from a canonical GCRS state.

require_ground()

Return self after validating that all rows are ground sites.

state(t, frame=GCRS, *, sun=None, earth=None, grid=False)

Return site states in one requested frame.

Ground rows are evaluated through the stored ITRS coordinates and Earth-rotation model. Space rows are broadcast from their canonical GCRS position and velocity payloads.

__getitem__(idx)

Return a sliced site object.

SmallBody(orbit0, mag_model=None)

Bases: BatchableObject

Small body with an initial orbit and an optional propagated trajectory.

Parameters:

Name	Type	Description	Default
orbit0	State	Initial state in canonical BCRS form. Position is in au and velocity is in au / day.	required
mag_model	MagModel	Photometric model attached to the body.	None

Notes

The stored epoch is in TDB. The trajectory field is empty until :meth:propagate is called.

Initialize a small body from an initial canonical BCRS state.

Parameters:

Name	Type	Description	Default
orbit0	State	Initial state in canonical BCRS form.	required
mag_model	MagModel	Photometric model attached to the body.	None

Raises:

Type	Description
TypeError	If orbit0 is not an instance of :class:difforb.core.state.state.State.
ValueError	If orbit0.frame is not BCRS.

shape property

Batch shape of the stored initial state.

create(orbit, mag_model=None, *, sun=None, earth=None) classmethod

Build a small body from one supported orbit representation.

Parameters:

Name	Type	Description	Default
orbit	Orbit	Initial orbit given as a Keplerian element set or a frame-aware Cartesian state.	required
mag_model	MagModel	Photometric model attached to the body.	None
sun	EphemerisBody	Sun ephemeris body used when orbit must be shifted from a heliocentric origin to BCRS.	None
earth	EphemerisBody	Earth ephemeris body used when orbit must be shifted from a geocentric origin to BCRS.	None

Returns:

Type	Description
SmallBody	Small body built from orbit.

Raises:

Type	Description
TypeError	If orbit is not a supported orbit type.
ValueError	If converting the provided Cartesian state to BCRS requires the Sun or Earth and the corresponding ephemeris body is not available.

Notes

The internal stored orbit is always canonical BCRS. Non-BCRS Cartesian inputs are converted through :meth:difforb.core.state.state.State.to.

propagate(t_start, t_end, force_model, integrator, grid=False)

Propagate the orbit and store the trajectory interpolator.

Parameters:

Name	Type	Description	Default
t_start	TDBView	Start and end epoch in TDB.	required
t_end	TDBView	Start and end epoch in TDB.	required
force_model	ForceModel	Dynamical model used in the equations of motion.	required
integrator	NumericalIntegrator	Numerical integrator used to build the trajectory.	required
grid	bool	If True, use the Cartesian product of the body batch and the time batch. If False, use point-wise broadcasting.	False

Returns:

Type	Description
SmallBody	New object with the trajectory field set.

Raises:

Type	Description
TypeError	If t_start or t_end is not a :class:TDB epoch.

state(tdb, frame=BCRS, *, sun=None, earth=None, grid=False)

Evaluate the propagated orbit in one requested frame.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Target epoch in TDB.	required
frame	Frame	Target output frame.	``BCRS``
sun	EphemerisBody	Sun ephemeris body used when the target frame touches the SUN origin.	None
earth	EphemerisBody	Earth ephemeris body used when the target frame touches the EARTH origin.	None
grid	bool	If True, use the Cartesian product of the body batch and the time batch. If False, use point-wise broadcasting.	False

Returns:

Type	Description
State	Interpolated state in frame.

Raises:

Type	Description
TypeError	If tdb is not a :class:TDBView.
RuntimeError	If the trajectory has not been initialized, or if tdb falls outside the propagated coverage interval.
ValueError	If the target frame touches the SUN origin and sun is not provided, or touches the EARTH origin and earth is not provided.

Notes

This method first evaluates the propagated orbit in canonical BCRS form with the internal :meth:_bcrs_pv_jd evaluator, and then converts the result to frame through :class:difforb.core.state.state.State.