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.

class ephemerista.coords.twobody.Cartesian(cartesian=None, *, time, origin=Origin(name='Earth'), type='cartesian', frame=ReferenceFrame(abbreviation='ICRF'), x, y, z, vx, vy, vz)

The Cartesian class.

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

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

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property position: ndarray

position.

Type:

numpy.ndarray

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 velocity: ndarray

velocity.

Type:

numpy.ndarray

class ephemerista.coords.twobody.GEO(*, time, origin=Origin(name='Earth'), type='geo', longitude, inclination=0.0, eccentricity=0.0, periapsisArgument=0.0, anomaly=0.0)

Geostationary Orbit class.

Simplified orbit definition for geostationary orbits requiring only longitude position.

property altitude: float

Geostationary altitude (approximately 35,786 km).

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

class ephemerista.coords.twobody.Inclination(*, degrees)

The Inclination class.

This class the models the inclination of an orbit.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ephemerista.coords.twobody.Keplerian(keplerian=None, *, time, origin=Origin(name='Earth'), type='keplerian', shape, inclination, ascendingNode, periapsisArgument, anomaly)

The Keplerian class.

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

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

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

property inclination: float

inclination [rad].

Type:

float

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.

property mean_anomaly: float

mean anomaly [rad].

Type:

float

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

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 true_anomaly: float

true anomaly [rad].

Type:

float

class ephemerista.coords.twobody.LEO(*, time, origin=Origin(name='Earth'), type='leo', altitude, inclination=51.6, eccentricity=0.0, ascendingNode=0.0, periapsisArgument=0.0, anomaly=0.0)

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.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

classmethod validate_leo_altitude(v)

Validate that altitude is within LEO range.

Return type:

float

class ephemerista.coords.twobody.MEO(*, time, origin=Origin(name='Earth'), type='meo', altitude, inclination=55.0, eccentricity=0.0, ascendingNode=0.0, periapsisArgument=0.0, anomaly=0.0)

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.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

classmethod validate_meo_altitude(v)

Validate that altitude is within MEO range.

Return type:

float

class ephemerista.coords.twobody.SSO(*, time, origin=Origin(name='Earth'), type='sso', altitude, ltan, eccentricity=0.0, anomaly=0.0, periapsisArgument=0.0)

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.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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

class ephemerista.coords.twobody.TwoBody(*, time, origin=Origin(name='Earth'))

Abstract base class for two-body states.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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