Two-Body States – ephemerista.coords.twobody

The twobody.py module.

This provides the Cartesian and Keplerian classes for defining the state of a spacecraft in a two-body problem.

pydantic model ephemerista.coords.twobody.Cartesian

The Cartesian class.

This class models the state of a spacecraft as a set of cartesian position and velocity vectors.

Fields:
field frame: ReferenceFrame = ReferenceFrame(abbreviation='ICRF')

Reference frame of the coordinate system

field state_type: Literal['cartesian'] = 'cartesian' (alias 'type')

The type of two-body state

field vx: float [Required]

velocity in x direction

field vy: float [Required]

velocity in y direction

field vz: float [Required]

velocity in z direction

field x: float [Required]

x coordinate of the position vector [km]

field y: float [Required]

y coordinate of the position vector [km]

field z: float [Required]

z coordinate of the position vector [km]

classmethod from_rv(time, r, v, origin=Origin(name='Earth'), frame=ReferenceFrame(abbreviation='ICRF'))

Construct the Cartesian state from position and velocity vectors.

Return type:

Self

isclose(cart2, atol_p=1e-06, atol_v=1e-09)

Check if the state is close to another state within some tolerance.

Return type:

bool

rotation_lvlh()

Return the rotation matrix to the local velocity/local horizon (LVLH) frame.

Return type:

ndarray

to_cartesian()

Convert to a Cartesian state.

Return type:

Cartesian

to_dataframe()

Convert the state to a Pandas data frame.

to_frame(frame)

Rotate the state to a different reference frame.

Return type:

Cartesian

to_keplerian()

Convert to a Keplerian state.

Return type:

Keplerian

to_origin(origin)

Translate the state to a different coordinate origin.

Return type:

Cartesian

property position: ndarray

position.

Type:

numpy.ndarray

property velocity: ndarray

velocity.

Type:

numpy.ndarray

pydantic model ephemerista.coords.twobody.GEO

Geostationary Orbit class.

Simplified orbit definition for geostationary orbits requiring only longitude position.

Fields:
field anomaly: float = 0.0

True anomaly [degrees]

field eccentricity: float = 0.0

Orbital eccentricity (should be 0 for true GEO)

field inclination: float = 0.0

Orbital inclination [degrees] (should be 0 for true GEO)

field longitude: float [Required]

Longitude position [degrees East]

field periapsis_argument: float = 0.0 (alias 'periapsisArgument')

Argument of periapsis [degrees]

field state_type: Literal['geo'] = 'geo' (alias 'type')
to_cartesian()

Convert to Cartesian coordinates.

Return type:

Cartesian

to_dataframe()

Convert to DataFrame.

Return type:

DataFrame

to_keplerian()

Convert to Keplerian elements.

Return type:

Keplerian

property altitude: float

Geostationary altitude (approximately 35,786 km).

pydantic model ephemerista.coords.twobody.Inclination

The Inclination class.

This class the models the inclination of an orbit.

Fields:
field degrees: float [Required]
Constraints:

  • ge = 0

  • le = 180

pydantic model ephemerista.coords.twobody.Keplerian

The Keplerian class.

This class models the state of a spacecraft as Keplerian elements.

Fields:
field anomaly: AnomalyType [Required]
field arg: Angle [Required] (alias 'periapsisArgument')
field inc: Inclination [Required] (alias 'inclination')
field node: Angle [Required] (alias 'ascendingNode')
field shape: shapes.Shape [Required]
field state_type: Literal['keplerian'] = 'keplerian' (alias 'type')
classmethod from_altitudes(time, apoapsis_altitude, periapsis_altitude, inclination, ascending_node, periapsis_argument, anomaly, origin=Origin(name='Earth'), angle_unit='degrees', anomaly_type='true')

Construct the Keplerian state with apsides altitudes.

Return type:

Self

classmethod from_elements(time, semi_major_axis, eccentricity, inclination, ascending_node, periapsis_argument, anomaly, origin=Origin(name='Earth'), angle_unit='degrees', anomaly_type='true')

Construct the Keplerian state from the classical orbital elements.

Return type:

Self

classmethod from_radii(time, apoapsis_radius, periapsis_radius, inclination, ascending_node, periapsis_argument, anomaly, origin=Origin(name='Earth'), angle_unit='degrees', anomaly_type='true')

Construct the Keplerian state with apsides radii.

Return type:

Self

static is_physical(semi_major_axis=None, eccentricity=None, inclination=None, periapsis_argument=None, origin=None, *, allow_hyperbolic=False)

Perform basic physicality checks.

All arguments are optional.

Parameters:

  • (float (argument_of_periapsis) – Semi-major axis of the orbit, in meters. Should be greater than 0.

  • optional) – Semi-major axis of the orbit, in meters. Should be greater than 0.

  • (float – Eccentricity of the orbit. Should be between 0 and 1 for closed orbits.

  • optional) – Eccentricity of the orbit. Should be between 0 and 1 for closed orbits.

  • (float – Inclination of the orbit in degrees. Should be between 0 and 180 by default.

  • optional) – Inclination of the orbit in degrees. Should be between 0 and 180 by default.

  • (float – Argument of periapsis in degrees. Should be between 0 and 360 by default.

  • optional) – Argument of periapsis in degrees. Should be between 0 and 360 by default.

Return type:

tuple[bool, str]

Returns:

tuple: A tuple containing a boolean indicating whether the parameters are physical, and a string message.

to_cartesian()

Convert the state to a Cartesian state.

Return type:

Cartesian

to_dataframe(name=None)

Convert the state to a Pandas data frame.

Return type:

DataFrame

to_keplerian()

Convert the state to a Keplerian state.

Return type:

Keplerian

property apoapsis_radius: float

apoapsis radius [km].

Type:

float

property ascending_node: float

right ascension of the ascending node [rad].

Type:

float

property eccentricity: float

eccentricity.

Type:

float

property inclination: float

inclination [rad].

Type:

float

property mean_anomaly: float

mean anomaly [rad].

Type:

float

property orbital_period: TimeDelta

orbital period [s].

Type:

float

property periapsis_argument: float

argument of periapsis [rad].

Type:

float

property periapsis_radius: float

periapsis radius [km].

Type:

float

property semi_major_axis: float

semi-major axis [km].

Type:

float

property true_anomaly: float

true anomaly [rad].

Type:

float

pydantic model ephemerista.coords.twobody.LEO

Low Earth Orbit class.

Simplified orbit definition for low Earth orbits requiring only altitude and optional inclination.

LEO altitude range: 160-2000 km above Earth’s surface.

Fields:
Validators:
field altitude: float [Required]

Orbital altitude above Earth’s surface [km] (160.0-2000.0 km for LEO)

Validated by:
field anomaly: float = 0.0

True anomaly [degrees]

field ascending_node: float = 0.0 (alias 'ascendingNode')

Longitude of ascending node [degrees]

field eccentricity: float = 0.0

Orbital eccentricity (default: 0 for circular)

field inclination: float = 51.6

Orbital inclination [degrees] (default: ISS inclination)

field periapsis_argument: float = 0.0 (alias 'periapsisArgument')

Argument of periapsis [degrees]

field state_type: Literal['leo'] = 'leo' (alias 'type')
validator validate_leo_altitude  »  altitude

Validate that altitude is within LEO range.

Return type:

float

to_cartesian()

Convert to Cartesian coordinates.

Return type:

Cartesian

to_dataframe()

Convert to DataFrame.

Return type:

DataFrame

to_keplerian()

Convert to Keplerian elements.

Return type:

Keplerian

pydantic model ephemerista.coords.twobody.MEO

Medium Earth Orbit class.

Simplified orbit definition for medium Earth orbits requiring only altitude and optional inclination.

MEO altitude range: 2000-35,786 km above Earth’s surface.

Fields:
Validators:
field altitude: float [Required]

Orbital altitude above Earth’s surface [km] (2000.0-35786.0 km for MEO)

Validated by:
field anomaly: float = 0.0

True anomaly [degrees]

field ascending_node: float = 0.0 (alias 'ascendingNode')

Longitude of ascending node [degrees]

field eccentricity: float = 0.0

Orbital eccentricity (default: 0 for circular)

field inclination: float = 55.0

Orbital inclination [degrees] (default: GPS constellation)

field periapsis_argument: float = 0.0 (alias 'periapsisArgument')

Argument of periapsis [degrees]

field state_type: Literal['meo'] = 'meo' (alias 'type')
validator validate_meo_altitude  »  altitude

Validate that altitude is within MEO range.

Return type:

float

to_cartesian()

Convert to Cartesian coordinates.

Return type:

Cartesian

to_dataframe()

Convert to DataFrame.

Return type:

DataFrame

to_keplerian()

Convert to Keplerian elements.

Return type:

Keplerian

pydantic model ephemerista.coords.twobody.SSO

Sun-Synchronous Orbit class.

Simplified orbit definition for sun-synchronous orbits requiring only altitude and local time of ascending node (LTAN).

Typical SSO altitudes range from 600-900 km for Earth observation satellites, though sun-synchronous orbits are theoretically possible at higher altitudes.

Fields:
field altitude: float [Required]

Orbital altitude above Earth’s surface [km]

field anomaly: float = 0.0

True anomaly [degrees]

field eccentricity: float = 0.0

Orbital eccentricity (default: 0 for circular)

field ltan: float [Required]

Local Time of Ascending Node [hours, 0-24]

field periapsis_argument: float = 0.0 (alias 'periapsisArgument')

Argument of periapsis [degrees]

field state_type: Literal['sso'] = 'sso' (alias 'type')
to_cartesian()

Convert to Cartesian coordinates.

Return type:

Cartesian

to_dataframe()

Convert to DataFrame.

Return type:

DataFrame

to_keplerian()

Convert to Keplerian elements.

Return type:

Keplerian

pydantic model ephemerista.coords.twobody.TwoBody

Abstract base class for two-body states.

Fields:
field origin: Origin = Origin(name='Earth')

Origin of the coordinate system

field time: Time [Required]

Epoch of the state vector

abstractmethod to_cartesian()

Convert to Cartesian state.

Return type:

Cartesian

abstractmethod to_dataframe()

Convert to DataFrame.

Return type:

DataFrame

abstractmethod to_keplerian()

Convert to Keplerian state.

Return type:

Keplerian