State API

Axes

Bases: str, Enum

Supported Cartesian axis families for state vectors.

The enum values represent only the orientation of the coordinate axes. Origin semantics are handled separately by the origin layer of state.

Attributes:

Name	Type	Description
``ICRS``		International Celestial Reference System axes.
J2000		J2000 mean-equator axes with the fixed bias relative to ICRS.
ECLIP_J2000		JPL Horizons ecliptic-of-J2000 axes. It is produced by rotating around the ICRS x-axis by a standard fixed obliquity angle of 84381.448 arcseconds (IAU 76 precession-nutation model). It is not the same as the mean J2000 ecliptic reference system.

BCRS = Frame(axes=(Axes.ICRS), origin=(Origin.SSB), name='BCRS') module-attribute

Frame(axes, origin, name=None) dataclass

Cartesian frame defined by one axis family and one origin.

Parameters:

Name	Type	Description	Default
axes	Axes	Axis family used by the state vector.	required
origin	Origin	Origin used by the state vector.	required
name	str	Human-facing short label for the frame. If omitted, the repr falls back to the explicit origin and axes pair.	None

GCRS = Frame(axes=(Axes.ICRS), origin=(Origin.EARTH), name='GCRS') module-attribute

HELIO_ECLIP_J2000 = Frame(axes=(Axes.ECLIP_J2000), origin=(Origin.SUN), name='HELIO_ECLIP_J2000') module-attribute

HELIO_ICRS = Frame(axes=(Axes.ICRS), origin=(Origin.SUN), name='HELIO_ICRS') module-attribute

HELIO_J2000 = Frame(axes=(Axes.J2000), origin=(Origin.SUN), name='HELIO_J2000') module-attribute

Origin

Bases: str, Enum

Supported Cartesian origins for state vectors.

Attributes:

Name	Type	Description
SSB		Solar System Barycenter.
SUN		Sun center of mass.
EARTH		Earth center of mass.

RelativeState(tdb, pos, vel)

Bases: BatchableObject

Relative Cartesian state at one TDB epoch in fixed ICRS axes.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
pos	Float[ArrayLike, '... 3']	Relative position vector in au.	required
vel	Float[ArrayLike, '... 3']	Relative velocity vector in au / day.	required

Notes

This class is intended for products such as observer-relative geometric, astrometric, and apparent vectors. It does not store an origin and does not support frame conversion.

Initialize a relative Cartesian state from epoch, position, and velocity.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
pos	Float[ArrayLike, '... 3']	Relative position vector in au.	required
vel	Float[ArrayLike, '... 3']	Relative velocity vector in au / day.	required

shape property

Return the batch shape.

array property

Return the stacked Cartesian array.

Returns:

Type	Description
Float[Array, '... 6']	Array ordered as [..., x, y, z, vx, vy, vz] in au and au / day.

dist property

Distance of the relative position vector in au.

lt property

Light time of the relative distance in days.

from_array(tdb, array) classmethod

Build a relative state from one stacked Cartesian array.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
array	Float[ArrayLike, '... 6']	Array ordered as [..., x, y, z, vx, vy, vz] in au and au / day.	required

Returns:

Type	Description
RelativeState	Relative state object of cls.

State(tdb, pos, vel, frame)

Bases: BatchableObject

Cartesian state vector at one TDB epoch in one explicit frame.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
pos	Float[ArrayLike, '... 3']	Position in the canonical distance unit of the library, au.	required
vel	Float[ArrayLike, '... 3']	Velocity in the canonical speed unit of the library, au / day.	required
frame	Frame	Frame that defines the axis orientation and the origin of pos and vel.	required

Initialize a Cartesian state from epoch, position, velocity, and frame.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
pos	Float[ArrayLike, '... 3']	Position in au.	required
vel	Float[ArrayLike, '... 3']	Velocity in au / day.	required
frame	Frame	Frame attached to the state vector.	required

shape property

Return the batch shape.

array property

Return the stacked Cartesian array.

Returns:

Type	Description
Float[Array, '... 6']	Array ordered as [..., x, y, z, vx, vy, vz] in au and au / day.

dist property

Distance from the current frame origin in au.

lt property

Light time for the current origin distance in days.

from_array(tdb, array, frame) classmethod

Build a state from one stacked Cartesian array.

Parameters:

Name	Type	Description	Default
tdb	TDBView	Epoch in TDB.	required
array	Float[ArrayLike, '... 6']	Array ordered as [..., x, y, z, vx, vy, vz] in au and au / day.	required
frame	Frame	Frame attached to the state vector.	required

Returns:

Type	Description
State	State object of cls in frame.

to(frame, *, sun=None, earth=None)

Convert the state to another frame.

Parameters:

Name	Type	Description	Default
frame	Frame	Target frame.	required
sun	EphemerisBody	Sun ephemeris body used when the source or target origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source or target origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in frame.

Raises:

Type	Description
ValueError	If the conversion touches the SUN origin and sun is not provided, or touches the EARTH origin and earth is not provided.

Notes

The conversion always passes through the canonical intermediate representation with ICRS axes and the SSB origin.

bcrs(*, sun=None, earth=None)

Convert the state to BCRS.

Parameters:

Name	Type	Description	Default
sun	EphemerisBody	Sun ephemeris body used when the source origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in BCRS.

gcrs(*, sun=None, earth=None)

Convert the state to GCRS.

Parameters:

Name	Type	Description	Default
sun	EphemerisBody	Sun ephemeris body used when the source origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source or target origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in GCRS.

helio_icrs(*, sun=None, earth=None)

Convert the state to heliocentric ICRS.

Parameters:

Name	Type	Description	Default
sun	EphemerisBody	Sun ephemeris body used when the source or target origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in heliocentric ICRS.

helio_j2000(*, sun=None, earth=None)

Convert the state to heliocentric J2000.

Parameters:

Name	Type	Description	Default
sun	EphemerisBody	Sun ephemeris body used when the source or target origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in heliocentric J2000.

helio_eclip_j2000(*, sun=None, earth=None)

Convert the state to heliocentric ecliptic J2000.

Parameters:

Name	Type	Description	Default
sun	EphemerisBody	Sun ephemeris body used when the source or target origin is SUN.	None
earth	EphemerisBody	Earth ephemeris body used when the source origin is EARTH.	None

Returns:

Type	Description
State	Same physical state expressed in heliocentric ecliptic J2000.