Core API

ITRF(pos, lon)

Bases: ITRS

Location in ITRF. ITRF is one implementation of ITRS.

ITRS(pos, lon)

Bases: BatchableObject

Location in ITRS.

This class stores Cartesian site coordinates in ITRS in meters and a longitude in radians.

Parameters:

Name	Type	Description	Default
pos	Float[ArrayLike, '... 3']	Geocentric equatorial rectangular coordinates in meters.	required
lon	Float[ArrayLike, ...]	Site longitude in radians.	required

Initialize an ITRS location from position and longitude.

Parameters:

Name	Type	Description	Default
pos	Float[ArrayLike, '... 3']	Geocentric equatorial rectangular coordinates in meters.	required
lon	Float[ArrayLike, ...]	Site longitude in radians.	required

geodetic_lat property

Geodetic latitude in radians.

geocentric_lat property

Geocentric latitude in radians.

geodetic_alt property

Ellipsoidal height in meters.

geocentric_dist property

Geocentric distance in meters.

shape property

Return the batch shape.

from_geodetic(lon, lat, alt) classmethod

Build an ITRS location from geodetic coordinates.

Parameters:

Name	Type	Description	Default
lon	Float[ArrayLike, ...]	Geodetic longitude in degrees.	required
lat	Float[ArrayLike, ...]	Geodetic latitude in degrees.	required
alt	Float[ArrayLike, ...]	Ellipsoid height in meters.	required

Returns:

Type	Description
``ITRS``	Site position in ITRS.

References

1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq.7.131.

from_geocentric(lon, parallax_const1, parallax_const2) classmethod

Build an ITRS location from geocentric constants.

Parameters:

Name	Type	Description	Default
lon	Float[ArrayLike, ...]	Geocentric longitude in degrees.	required
parallax_const1	Float[ArrayLike, ...]	rho cos(phi') where phi' is the geocentric latitude and rho is the geocentric distance in Earth radii.	required
parallax_const2	Float[ArrayLike, ...]	rho sin(phi') where phi' is the geocentric latitude and rho is the geocentric distance in Earth radii.	required

Returns:

Type	Description
``ITRS``	Site position in ITRS.

Notes

The parallax constants follow the Minor Planet Center observatory code definition (https://www.minorplanetcenter.net/iau/lists/ObsCodesF.html).

References

1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq.7.131.

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

Convert the location in ITRS to one requested frame.

Parameters:

Name	Type	Description	Default
t	Time	Time.	required
frame	Frame	Target output frame.	``GCRS``
sun	EphemerisBody	Sun ephemeris body used when frame touches the SUN origin.	None
earth	EphemerisBody	Earth ephemeris body used when converting from the canonical GCRS origin to another origin.	None
grid	bool	If False, broadcast location and time inputs together. If True, build the Cartesian product of location and time inputs.	False

Returns:

Type	Description
State	Location in frame at the corresponding TDB epoch.

Raises:

Type	Description
ValueError	If converting the canonical GCRS state to frame requires the Sun or Earth and the corresponding ephemeris body is not available.

References

1. Sean Urban and P. Kenneth Seidelmann, Explanatory Supplement to the Astronomical Almanac, 2012, Sec. 7.4.3.
2. Kaplan, G. H. (2005). The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models. Sec. 6.4.

KepElement(tdb, p, e, inc, node, peri, m)

Bases: BatchableObject

Osculating Keplerian elements.

The stored elements are (p, e, inc, node, peri, m) at a TDB epoch. Here p is the semi-latus rectum. All angles are stored in radians.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch of the osculating elements in TDB.	required
p	Float[ArrayLike, ...]	Semi-latus rectum in au.	required
e	Float[ArrayLike, ...]	Eccentricity.	required
inc	Float[ArrayLike, ...]	Inclination in radians.	required
node	Float[ArrayLike, ...]	Longitude of ascending node in radians.	required
peri	Float[ArrayLike, ...]	Argument of perihelion in radians.	required
m	Float[ArrayLike, ...]	Mean anomaly in radians.	required

See Also

from_classical Build from the classical (a, e, i, node, peri, M) elements set. from_true_anomaly Build from (p, e, i, node, peri, v) elements set. from_equinoctial_elements Build from equinoctial elements. from_helio_eclip_j2000 Build from a heliocentric JPL Horizons ecliptic-of-J2000 state vector.

Examples:

>>> from difforb.core.element import KepElement
>>> from difforb.core.time.timescale import Time
>>> tdb = Time.from_tdb_date(2025, 1, 1).tdb()
>>> elem = KepElement.from_classical(tdb, 2.0, 0.1, 5.0, 30.0, 40.0, 10.0)
>>> elem.array.shape
(6,)

Initialize heliocentric ecliptic J2000 Keplerian elements.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
p	Float[ArrayLike, ...]	Semi-latus rectum in au.	required
e	Float[ArrayLike, ...]	Eccentricity.	required
inc	Float[ArrayLike, ...]	Inclination in radians.	required
node	Float[ArrayLike, ...]	Longitude of ascending node in radians.	required
peri	Float[ArrayLike, ...]	Argument of perihelion in radians.	required
m	Float[ArrayLike, ...]	Mean anomaly in radians.	required

a property

Semi-major axis in au. Returns inf for parabolic cases.

v property

True anomaly in radians.

References

1. For elliptical Kepler equation solving: Vallado, D. A. (2022). Fundamentals of Astrodynamics and Applications. Algorithm 2.
2. For hyperbolic Kepler equation solving: Vallado, D. A. (2022). Fundamentals of Astrodynamics and Applications. Algorithm 4.
3. For parabolic Kepler equation solving: https://github.com/CelesTrak/fundamentals-of-astrodynamics/blob/main/software/python/src/valladopy/astro/twobody/newton.py#L161.
4. For elliptical conversion from eccentric anomaly to true anomaly: 吴连大, 《人造卫星与空间碎片的轨道和探测》, p.44-45.
5. For hyperbolic conversion from hyperbolic anomaly to true anomaly: https://github.com/CelesTrak/fundamentals-of-astrodynamics/blob/main/software/python/src/valladopy/astro/twobody/newton.py#L156
6. For parabolic conversion from Barker variable to true anomaly: https://github.com/CelesTrak/fundamentals-of-astrodynamics/blob/main/software/python/src/valladopy/astro/twobody/newton.py#L165

period property

Orbital period in days. Returns inf for non-periodic cases.

perit_jd property

Perihelion time in Julian Date. Returns nan for non-periodic cases.

array property

Return the stacked element array.

Returns:

Type	Description
Float[Array, 'N 6']	Array ordered as [..., p, e, inc, node, peri, m].

shape property

Return the batch shape.

from_classical(tdb, a, e, inc, node, peri, m, degrees=True) classmethod

Build from the classical (a, e, i, node, peri, M) elements set.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
a	Float[ArrayLike, ...]	Semi-major axis in au.	required
e	Float[ArrayLike, ...]	Eccentricity.	required
inc	Float[ArrayLike, ...]	Inclination.	required
node	Float[ArrayLike, ...]	Longitude of ascending node.	required
peri	Float[ArrayLike, ...]	Argument of perihelion.	required
m	Float[ArrayLike, ...]	Mean anomaly.	required
degrees	bool	If True, angle inputs are in degrees else in radians.	True

Returns:

Type	Description
KepElement	Element object stored as (p, e, inc, node, peri, m).

from_true_anomaly(tdb, p, e, inc, node, peri, v, degrees=True) classmethod

Build from (p, e, i, node, peri, v) elements set.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
p	Float[ArrayLike, ...]	Semi-latus rectum in au.	required
e	Float[ArrayLike, ...]	Eccentricity.	required
inc	Float[ArrayLike, ...]	Inclination.	required
node	Float[ArrayLike, ...]	Longitude of ascending node.	required
peri	Float[ArrayLike, ...]	Argument of perihelion.	required
v	Float[ArrayLike, ...]	True anomaly.	required
degrees	bool	If True, angle inputs are in degrees.	True

Returns:

Type	Description
KepElement	Element object with mean anomaly derived from v.

References

1. For elliptical case: 吴连大, 《人造卫星与空间碎片的轨道和探测》, p.44-45.
2. For other cases: Vallado, D. A. (2022). Fundamentals of Astrodynamics and Applications. Algorithm 5.

from_equinoctial_elements(tt, a, g, f, k, h, M) classmethod

Build from equinoctial elements.

Parameters:

Name	Type	Description	Default
tt	TTView	Epoch in TT.	required
a	Float[ArrayLike, ...]	Semi-major axis in au.	required
g	Float[ArrayLike, ...]	e * sin(peri + node) term.	required
f	Float[ArrayLike, ...]	e * cos(peri + node) term.	required
k	Float[ArrayLike, ...]	tan(inc / 2) * sin(node) term.	required
h	Float[ArrayLike, ...]	tan(inc / 2) * cos(node) term.	required
M	Float[ArrayLike, ...]	Sum node + peri + m in radians.	required

Returns:

Type	Description
KepElement	Equivalent element set at the corresponding TDB epoch.

References

1. https://spsweb.fltops.jpl.nasa.gov/portaldataops/mpg/MPG_Docs/Source%20Docs/EquinoctalElements-modified.pdf.

from_state(state, *, sun=None, earth=None) classmethod

Build from one frame-aware Cartesian state.

Parameters:

Name	Type	Description	Default
state	State	Input state at a TDB epoch. The state is converted internally to canonical HELIO_ECLIP_J2000 before element extraction.	required
sun	EphemerisBody	Sun ephemeris body used if state must be shifted from SSB or EARTH to the heliocentric origin.	None
earth	EphemerisBody	Earth ephemeris body used if state must be shifted from EARTH to another origin before the final heliocentric conversion.	None

Returns:

Type	Description
KepElement	Osculating element set for state in the library canonical element convention.

Raises:

Type	Description
ValueError	If converting state to canonical HELIO_ECLIP_J2000 requires the Sun or Earth and the corresponding ephemeris body is not available.

Notes

The canonical Cartesian boundary of :class:KepElement is heliocentric JPL Horizons ecliptic-of-J2000. This method converts the input state to that frame first and then applies the Cartesian-to-element mapping.

References

1. Vallado, D. A. (2022). Fundamentals of Astrodynamics and Applications. Algorithm 9, pp. 115-116.

from_array(tdb, array) classmethod

Build from a stacked element array.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
array	Float[ArrayLike, '... 6']	Array with shape (..., 6) ordered as [..., p, e, inc, node, peri, m].	required

Returns:

Type	Description
KepElement	Element object of the receiving class.

state()

Convert elements to the canonical Cartesian state.

Returns:

Type	Description
State	Heliocentric JPL Horizons ecliptic-of-J2000 state at the same epoch.

Notes

This is the canonical Cartesian boundary of :class:KepElement. The returned state uses the HELIO_ECLIP_J2000 frame of :mod:difforb.core.state.

References

1. Vallado, D. A. (2022). Fundamentals of Astrodynamics and Applications. Algorithm 10.

WGS84(pos, lon)

Bases: ITRS

Location in WGS84. WGS84 is one implementation of ITRS.