Orbital States

Representations of orbital states in Cartesian, Keplerian, and equinoctial forms.

Quick Example

import lox_space as lox

t = lox.Time("TAI", 2024, 1, 1)

# Array pattern — position in meters, velocity in m/s
state = lox.Cartesian(
    time=t,
    position=[6678e3, 0.0, 0.0],
    velocity=[0.0, 7730.0, 0.0],
)

# Elementwise pattern — unitful keyword arguments
state = lox.Cartesian(
    time=t,
    x=6678.0 * lox.km,
    y=0.0 * lox.km,
    z=0.0 * lox.km,
    vx=0.0 * lox.km_per_s,
    vy=7.73 * lox.km_per_s,
    vz=0.0 * lox.km_per_s,
)

# Access as numpy arrays (meters, m/s)
pos = state.position()  # shape (3,)
vel = state.velocity()  # shape (3,)

# Access as unitful scalars
print(f"x = {state.x.to_kilometers():.1f} km")

# Convert to Keplerian elements (raises ValueError for states with zero angular momentum)
kep = state.to_keplerian()
# semi_major_axis() returns None for parabolic orbits
print(f"a = {kep.semi_major_axis().to_kilometers():.1f} km")
print(f"e = {kep.eccentricity():.6f}")
print(f"i = {kep.inclination().to_degrees():.2f} deg")

# Create from Keplerian elements (semi-major axis + eccentricity)
kep = lox.Keplerian(
    time=t,
    semi_major_axis=6678.0 * lox.km,
    eccentricity=0.001,
    inclination=51.6 * lox.deg,
)
state = kep.to_cartesian()

# Create from the semi-parameter, which also supports parabolic orbits
kep = lox.Keplerian(
    time=t,
    semi_parameter=14000.0 * lox.km,
    eccentricity=1.0,
)

# Create from periapsis/apoapsis radii
kep = lox.Keplerian(
    time=t,
    periapsis_radius=7000.0 * lox.km,
    apoapsis_radius=7400.0 * lox.km,
)

# Create from periapsis/apoapsis altitudes
kep = lox.Keplerian(
    time=t,
    periapsis_altitude=600.0 * lox.km,
    apoapsis_altitude=1000.0 * lox.km,
)

# Derived quantities
print(f"hp = {kep.periapsis_altitude().to_kilometers():.1f} km")
print(f"ha = {kep.apoapsis_altitude().to_kilometers():.1f} km")
print(f"n = {float(kep.mean_motion()):.3e} rad/s")
print(f"energy = {kep.specific_orbital_energy():.3f} km²/s²")

# Create a circular orbit from altitude
circ = lox.Keplerian.circular(
    t,
    altitude=800 * lox.km,
    inclination=51.6 * lox.deg,
)

# Create a Sun-synchronous orbit from altitude
eop = lox.EOPProvider("finals.csv")
sso = lox.Keplerian.sso(
    t,
    altitude=800 * lox.km,
    ltan=(13, 30),
    provider=eop,
)

# Equinoctial elements are non-singular for circular and equatorial orbits.
# Retrograde orbits use the retrograde set (retrograde factor I = -1) automatically.
eq = state.to_equinoctial()  # closed orbits only, raises ValueError otherwise
print(f"λ = {eq.mean_longitude().to_degrees():.3f} deg, retrograde = {eq.retrograde()}")

# Modified equinoctial elements also cover parabolic and hyperbolic orbits
mee = state.to_modified_equinoctial()
state = mee.to_equinoctial().to_cartesian()

# Work with trajectories
trajectory = lox.Trajectory([state1, state2, state3])
interpolated = trajectory.at(t + lox.TimeDelta(100))

# Queries up to 1 ms before the first or after the last state are
# extrapolated, queries beyond raise a ValueError. Widen the limit on demand:
extended = trajectory.with_extrapolation_limit(lox.TimeDelta(10))

# Use step_by_inclusive to sample an interval including its end
times = lox.Interval(t, t + lox.TimeDelta(150)).step_by_inclusive(lox.TimeDelta(60))

Cartesian

Represents an orbital state (position and velocity) at a specific time.

Parameters:

time
–

The epoch of this state.
position
–

Position vector as array-like [x, y, z] in meters.
velocity
–

Velocity vector as array-like [vx, vy, vz] in m/s.
x, y, z
–

Individual position components as Distance (keyword-only, alternative to position).
vx, vy, vz
–

Individual velocity components as Velocity (keyword-only, alternative to velocity).
origin
–

Central body (default: Earth).
frame
–

Reference frame (default: ICRF).

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> # Array pattern (meters, m/s)
>>> state = lox.Cartesian(
...     t,
...     position=[6678e3, 0.0, 0.0],
...     velocity=[0.0, 7730.0, 0.0],
... )
>>> # Elementwise pattern (unitful)
>>> state = lox.Cartesian(
...     t,
...     x=6678.0 * lox.km, y=0.0 * lox.km, z=0.0 * lox.km,
...     vx=0.0 * lox.km_per_s, vy=7.73 * lox.km_per_s, vz=0.0 * lox.km_per_s,
... )

Methods:

is_physical –

Return whether the state is physical.
origin –

Return the central body (origin) of this state.
position –

Return the position vector as a numpy array in meters, shape (3,).
reference_frame –

Return the reference frame of this state.
rotation_lvlh –

Compute the rotation matrix from inertial to LVLH frame.
time –

Return the epoch of this state.
to_ellipsoid_location –

Convert this state to a ground location.
to_equinoctial –

Convert this Cartesian state to equinoctial elements.
to_frame –

Transform this state to a different reference frame.
to_keplerian –

Convert this Cartesian state to Keplerian orbital elements.
to_modified_equinoctial –

Convert this Cartesian state to modified equinoctial elements.
to_origin –

Transform this state to a different central body.
velocity –

Return the velocity vector as a numpy array in m/s, shape (3,).

Attributes:

vx (Velocity) –

Return the x component of the velocity.
vy (Velocity) –

Return the y component of the velocity.
vz (Velocity) –

Return the z component of the velocity.
x (Distance) –

Return the x component of the position.
y (Distance) –

Return the y component of the position.
z (Distance) –

Return the z component of the position.

vx `property`

vx: Velocity

Return the x component of the velocity.

vy `property`

vy: Velocity

Return the y component of the velocity.

vz `property`

vz: Velocity

Return the z component of the velocity.

x `property`

x: Distance

Return the x component of the position.

y `property`

y: Distance

Return the y component of the position.

z `property`

z: Distance

Return the z component of the position.

is_physical

is_physical() -> bool

Return whether the state is physical.

A state is physical if its position lies within the observable universe and its speed is below the speed of light. Non-finite states are not physical. The conversions to orbital elements raise ValueError for unphysical states.

The check is only meaningful in a quasi-inertial frame. In a rotating frame, distant objects move faster than light, e.g. a probe near Saturn in a frame rotating with the Earth.

origin

origin() -> Origin

Return the central body (origin) of this state.

position

position() -> ndarray

Return the position vector as a numpy array in meters, shape (3,).

reference_frame

reference_frame() -> Frame

Return the reference frame of this state.

rotation_lvlh

rotation_lvlh() -> ndarray

Compute the rotation matrix from inertial to LVLH frame.

time

time() -> Time

Return the epoch of this state.

to_ellipsoid_location

to_ellipsoid_location() -> EllipsoidLocation

Convert this state to a ground location.

to_equinoctial

to_equinoctial() -> Equinoctial

Convert this Cartesian state to equinoctial elements.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.
ValueError –

If the frame is not quasi-inertial, the state is not physical (see is_physical), the orbit is not closed, or the state has zero angular momentum.

to_frame

to_frame(frame: str | Frame, provider: EOPProvider | None = None) -> Self

Transform this state to a different reference frame.

to_keplerian

to_keplerian() -> Keplerian

Convert this Cartesian state to Keplerian orbital elements.

Raises:

ValueError –

If the frame is not quasi-inertial, the state is not physical (see is_physical), or it cannot be represented by Keplerian elements, e.g. because its angular momentum is zero.
UndefinedOriginPropertyError –

If the origin has no gravitational parameter.

to_modified_equinoctial

to_modified_equinoctial() -> ModifiedEquinoctial

Convert this Cartesian state to modified equinoctial elements.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.
ValueError –

If the frame is not quasi-inertial, the state is not physical (see is_physical), or it has zero angular momentum.

to_origin

to_origin(target: str | int | Origin, ephemeris: SPK) -> Self

Transform this state to a different central body.

velocity

velocity() -> ndarray

Return the velocity vector as a numpy array in m/s, shape (3,).

Keplerian

Represents an orbit using Keplerian (classical) orbital elements.

The orbital shape can be specified in four ways:

semi_major_axis + eccentricity
semi_parameter + eccentricity (keyword-only), which also supports parabolic orbits
periapsis_radius + apoapsis_radius (keyword-only)
periapsis_altitude + apoapsis_altitude (keyword-only)

Parameters:

time
–

Epoch of the elements.
semi_major_axis
–

Semi-major axis as Distance.
eccentricity
–

Orbital eccentricity (0 = circular, <1 = elliptical).
inclination
–

Inclination as Angle (default 0).
longitude_of_ascending_node
–

RAAN as Angle (default 0).
argument_of_periapsis
–

Argument of periapsis as Angle (default 0).
true_anomaly
–

True anomaly as Angle (default 0).
origin
–

Central body (default: Earth).
semi_parameter
–

Semi-parameter (semi-latus rectum) as Distance (keyword-only).
periapsis_radius
–

Periapsis radius as Distance (keyword-only).
apoapsis_radius
–

Apoapsis radius as Distance (keyword-only).
periapsis_altitude
–

Periapsis altitude as Distance (keyword-only).
apoapsis_altitude
–

Apoapsis altitude as Distance (keyword-only).
mean_anomaly
–

Mean anomaly as Angle (keyword-only, mutually exclusive with true_anomaly).

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> orbit = lox.Keplerian(
...     t,
...     semi_major_axis=6678.0 * lox.km,
...     eccentricity=0.001,
...     inclination=51.6 * lox.deg,
... )

From the semi-parameter, e.g. for a parabolic orbit:

>>> orbit = lox.Keplerian(
...     t,
...     semi_parameter=14000.0 * lox.km,
...     eccentricity=1.0,
... )

From radii:

>>> orbit = lox.Keplerian(
...     t,
...     periapsis_radius=7000.0 * lox.km,
...     apoapsis_radius=7400.0 * lox.km,
... )

From altitudes:

>>> orbit = lox.Keplerian(
...     t,
...     periapsis_altitude=600.0 * lox.km,
...     apoapsis_altitude=1000.0 * lox.km,
... )

Methods:

apoapsis_altitude –

Return the apoapsis altitude above the origin's mean radius, or None for open orbits.
apoapsis_radius –

Return the apoapsis radius, or None for open orbits.
argument_of_latitude –

Return the argument of latitude in the interval [0, 2π).
argument_of_periapsis –

Return the argument of periapsis.
circular –

Construct a circular orbit.
eccentricity –

Return the orbital eccentricity.
flight_path_angle –

Return the flight-path angle.
inclination –

Return the inclination.
longitude_of_ascending_node –

Return the longitude of the ascending node (RAAN).
mean_longitude –

Return the mean longitude.
mean_motion –

Return the mean motion, i.e. the rate of change of the mean anomaly.
orbital_period –

Return the orbital period.
origin –

Return the central body (origin) of this orbit.
periapsis_altitude –

Return the periapsis altitude above the origin's mean radius.
periapsis_radius –

Return the periapsis radius.
semi_major_axis –

Return the semi-major axis, or None for parabolic orbits.
semi_parameter –

Return the semi-parameter (semi-latus rectum).
specific_angular_momentum –

Return the magnitude of the specific angular momentum in km²/s.
specific_orbital_energy –

Return the specific orbital energy in km²/s².
sso –

Construct a Sun-synchronous orbit.
time –

Return the epoch of these elements.
to_cartesian –

Convert these Keplerian elements to a Cartesian state.
to_equinoctial –

Convert these Keplerian elements to equinoctial elements.
to_modified_equinoctial –

Convert these Keplerian elements to modified equinoctial elements.
true_anomaly –

Return the true anomaly.
true_longitude –

Return the true longitude in the interval [0, 2π).

apoapsis_altitude

apoapsis_altitude() -> Distance | None

Return the apoapsis altitude above the origin's mean radius, or None for open orbits.

Raises:

UndefinedOriginPropertyError –

If the origin has no mean radius.

apoapsis_radius

apoapsis_radius() -> Distance | None

Return the apoapsis radius, or None for open orbits.

argument_of_latitude

argument_of_latitude() -> Angle

Return the argument of latitude in the interval [0, 2π).

argument_of_periapsis

argument_of_periapsis() -> Angle

Return the argument of periapsis.

circular `classmethod`

circular(
    time: Time,
    *,
    semi_major_axis: Distance | None = None,
    altitude: Distance | None = None,
    inclination: Angle | None = None,
    longitude_of_ascending_node: Angle | None = None,
    true_anomaly: Angle | None = None,
    origin: str | int | Origin | None = None,
) -> Self

Construct a circular orbit.

Exactly one of semi_major_axis or altitude must be provided. Eccentricity is always 0 and argument of periapsis is always 0.

Parameters:

time
(Time) –

Epoch of the orbit.
semi_major_axis
(Distance | None, default: None ) –

Semi-major axis (mutually exclusive with altitude).
altitude
(Distance | None, default: None ) –

Orbital altitude (mutually exclusive with semi_major_axis).
inclination
(Angle | None, default: None ) –

Inclination (default 0).
longitude_of_ascending_node
(Angle | None, default: None ) –

RAAN (default 0).
true_anomaly
(Angle | None, default: None ) –

True anomaly (default 0).
origin
(str | int | Origin | None, default: None ) –

Central body (default: Earth).

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> orbit = lox.Keplerian.circular(
...     t,
...     altitude=800 * lox.km,
...     inclination=51.6 * lox.deg,
... )

eccentricity

eccentricity() -> float

Return the orbital eccentricity.

flight_path_angle

flight_path_angle() -> Angle

Return the flight-path angle.

The angle between the velocity vector and the local horizontal. It is positive while the orbit is moving away from periapsis.

inclination

inclination() -> Angle

Return the inclination.

longitude_of_ascending_node

longitude_of_ascending_node() -> Angle

Return the longitude of the ascending node (RAAN).

mean_longitude

mean_longitude() -> Angle

Return the mean longitude.

For closed orbits the result lies in the interval [0, 2π). The mean anomaly it is based on depends on the orbit type, see mean_motion.

Raises:

ValueError –

If the true anomaly cannot be converted to a mean anomaly.

mean_motion

mean_motion() -> AngularRate

Return the mean motion, i.e. the rate of change of the mean anomaly.

The mean anomaly is normalised differently for elliptic, parabolic and hyperbolic orbits, so the mean motion is discontinuous at the parabolic threshold: for a fixed semi-parameter it tends to zero as the eccentricity approaches one, but is 2·√(µ/p³) for parabolic orbits. Mean anomalies and mean motions are only comparable between orbits of the same type.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.

orbital_period

orbital_period() -> TimeDelta

Return the orbital period.

origin

origin() -> Origin

Return the central body (origin) of this orbit.

periapsis_altitude

periapsis_altitude() -> Distance

Return the periapsis altitude above the origin's mean radius.

Raises:

UndefinedOriginPropertyError –

If the origin has no mean radius.

periapsis_radius

periapsis_radius() -> Distance

Return the periapsis radius.

semi_major_axis

semi_major_axis() -> Distance | None

Return the semi-major axis, or None for parabolic orbits.

The semi-major axis is negative for hyperbolic orbits.

semi_parameter

semi_parameter() -> Distance

Return the semi-parameter (semi-latus rectum).

specific_angular_momentum

specific_angular_momentum() -> float

Return the magnitude of the specific angular momentum in km²/s.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.

specific_orbital_energy

specific_orbital_energy() -> float

Return the specific orbital energy in km²/s².

The energy is negative for closed orbits, zero for parabolic orbits, and positive for hyperbolic orbits.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.

sso `classmethod`

sso(
    time: Time,
    *,
    altitude: Distance | None = None,
    semi_major_axis: Distance | None = None,
    inclination: Angle | None = None,
    eccentricity: float = 0.0,
    ltan: tuple[int, int] | None = None,
    ltdn: tuple[int, int] | None = None,
    argument_of_periapsis: Angle | None = None,
    true_anomaly: Angle | None = None,
    provider: EOPProvider | None = None,
) -> Self

Construct a Sun-synchronous orbit.

Exactly one of altitude, semi_major_axis, or inclination must be provided. The remaining orbital elements are derived from the SSO constraint.

Parameters:

time
(Time) –

Epoch of the orbit.
altitude
(Distance | None, default: None ) –

Orbital altitude (mutually exclusive with semi_major_axis/inclination).
semi_major_axis
(Distance | None, default: None ) –

Semi-major axis (mutually exclusive with altitude/inclination).
inclination
(Angle | None, default: None ) –

Inclination (mutually exclusive with altitude/semi_major_axis).
eccentricity
(float, default: 0.0 ) –

Eccentricity (default 0.0).
ltan
(tuple[int, int] | None, default: None ) –

Local time of ascending node as (hours, minutes) tuple.
ltdn
(tuple[int, int] | None, default: None ) –

Local time of descending node as (hours, minutes) tuple.
argument_of_periapsis
(Angle | None, default: None ) –

Argument of periapsis (default 0.0).
true_anomaly
(Angle | None, default: None ) –

True anomaly (default 0.0).
provider
(EOPProvider | None, default: None ) –

EOP provider for time scale conversions.

Examples:

>>> eop = lox.EOPProvider("finals.csv")
>>> t = lox.UTC(2020, 2, 18).to_scale("TDB")
>>> orbit = lox.Keplerian.sso(
...     t,
...     altitude=800 * lox.km,
...     ltan=(13, 30),
...     provider=eop,
... )

time

time() -> Time

Return the epoch of these elements.

to_cartesian

to_cartesian() -> Cartesian

Convert these Keplerian elements to a Cartesian state.

to_equinoctial

to_equinoctial() -> Equinoctial

Convert these Keplerian elements to equinoctial elements.

Raises:

ValueError –

If the orbit is not closed.

to_modified_equinoctial

to_modified_equinoctial() -> ModifiedEquinoctial

Convert these Keplerian elements to modified equinoctial elements.

Raises:

ValueError –

If the true anomaly of an open orbit lies too close to its asymptotes.

true_anomaly

true_anomaly() -> Angle

Return the true anomaly.

true_longitude

true_longitude() -> Angle

Return the true longitude in the interval [0, 2π).

Equinoctial

Represents an orbit using equinoctial elements.

Equinoctial elements are non-singular for circular (e = 0) and equatorial (i = 0 or i = 180°) orbits. They are defined for closed orbits only; use ModifiedEquinoctial for open orbits.

The elements are h = e·sin(ω + I·Ω), k = e·cos(ω + I·Ω), p = tanᴵ(i/2)·sin(Ω), q = tanᴵ(i/2)·cos(Ω), and the mean longitude λ = M + ω + I·Ω, where the retrograde factor I is -1 for the retrograde set and +1 otherwise.

Parameters:

time
–

Epoch of the elements.
a
–

Semi-major axis as Distance.
h
–

Eccentricity vector component e·sin(ω + I·Ω).
k
–

Eccentricity vector component e·cos(ω + I·Ω).
p
–

Node vector component tanᴵ(i/2)·sin(Ω).
q
–

Node vector component tanᴵ(i/2)·cos(Ω).
mean_longitude
–

Mean longitude λ as Angle.
origin
–

Central body (default: Earth).
frame
–

Reference frame (default: ICRF).
retrograde
–

Use the retrograde set of elements (retrograde factor I = -1), which is singular at i = 0 instead of i = 180° (default: False).

Raises:

ValueError –

If the semi-major axis is not positive, an element is not finite, the orbit is not closed, or the frame is not quasi-inertial.

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> eq = lox.Equinoctial(
...     t,
...     a=7000.0 * lox.km,
...     h=0.001,
...     k=0.0,
...     p=0.2,
...     q=0.3,
...     mean_longitude=45.0 * lox.deg,
... )

Methods:

a –

Return the semi-major axis a.
eccentric_longitude –

Return the eccentric longitude F = E + ω + I·Ω, in the same revolution as the mean longitude.
eccentricity –

Return the orbital eccentricity.
frame –

Return the reference frame.
h –

Return h = e·sin(ω + I·Ω).
inclination –

Return the orbital inclination.
k –

Return k = e·cos(ω + I·Ω).
mean_longitude –

Return the mean longitude λ = M + ω + I·Ω.
origin –

Return the central body (origin) of this orbit.
p –

Return p = tanᴵ(i/2)·sin(Ω).
q –

Return q = tanᴵ(i/2)·cos(Ω).
retrograde –

Return whether the elements use the retrograde set (retrograde factor I = -1).
time –

Return the epoch of this orbit.
to_cartesian –

Convert these equinoctial elements to a Cartesian state.
to_keplerian –

Convert these equinoctial elements to Keplerian orbital elements.
to_modified_equinoctial –

Convert these equinoctial elements to modified equinoctial elements.
true_longitude –

Return the true longitude L = ν + ω + I·Ω, in the same revolution as the mean longitude.

a

a() -> Distance

Return the semi-major axis a.

eccentric_longitude

eccentric_longitude() -> Angle

Return the eccentric longitude F = E + ω + I·Ω, in the same revolution as the mean longitude.

Raises:

ValueError –

If Kepler's equation cannot be solved.

eccentricity

eccentricity() -> float

Return the orbital eccentricity.

frame

frame() -> Frame

Return the reference frame.

h

h() -> float

Return h = e·sin(ω + I·Ω).

inclination

inclination() -> Angle

Return the orbital inclination.

k

k() -> float

Return k = e·cos(ω + I·Ω).

mean_longitude

mean_longitude() -> Angle

Return the mean longitude λ = M + ω + I·Ω.

origin

origin() -> Origin

Return the central body (origin) of this orbit.

p

p() -> float

Return p = tanᴵ(i/2)·sin(Ω).

q

q() -> float

Return q = tanᴵ(i/2)·cos(Ω).

retrograde

retrograde() -> bool

Return whether the elements use the retrograde set (retrograde factor I = -1).

time

time() -> Time

Return the epoch of this orbit.

to_cartesian

to_cartesian() -> Cartesian

Convert these equinoctial elements to a Cartesian state.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.
ValueError –

If Kepler's equation cannot be solved.

to_keplerian

to_keplerian() -> Keplerian

Convert these equinoctial elements to Keplerian orbital elements.

Raises:

ValueError –

If Kepler's equation cannot be solved.

to_modified_equinoctial

to_modified_equinoctial() -> ModifiedEquinoctial

Convert these equinoctial elements to modified equinoctial elements.

Raises:

ValueError –

If Kepler's equation cannot be solved.

true_longitude

true_longitude() -> Angle

Return the true longitude L = ν + ω + I·Ω, in the same revolution as the mean longitude.

Raises:

ValueError –

If Kepler's equation cannot be solved.

ModifiedEquinoctial

Represents an orbit using Modified Equinoctial Elements (MEE).

Modified Equinoctial Elements are non-singular for circular (e = 0), equatorial (i = 0 or i = 180°), and parabolic (e = 1) orbits.

The elements are f = e·cos(ω + I·Ω), g = e·sin(ω + I·Ω), h = tanᴵ(i/2)·cos(Ω), k = tanᴵ(i/2)·sin(Ω), and the true longitude l = ν + ω + I·Ω, where the retrograde factor I is -1 for the retrograde set and +1 otherwise.

Parameters:

time
–

Epoch of the elements.
p
–

Semi-latus rectum (semi-parameter) as Distance.
f
–

Eccentricity vector component e·cos(ω + I·Ω).
g
–

Eccentricity vector component e·sin(ω + I·Ω).
h
–

Node vector component tanᴵ(i/2)·cos(Ω).
k
–

Node vector component tanᴵ(i/2)·sin(Ω).
l
–

True longitude as Angle.
origin
–

Central body (default: Earth).
frame
–

Reference frame (default: ICRF).
retrograde
–

Use the retrograde set of elements (retrograde factor I = -1), which is singular at i = 0 instead of i = 180° (default: False).

Raises:

ValueError –

If the semi-parameter is not positive, an element is not finite, the true longitude lies outside the asymptotes of an open orbit, or the frame is not quasi-inertial.

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> mee = lox.ModifiedEquinoctial(
...     t,
...     p=7000.0 * lox.km,
...     f=0.001,
...     g=0.001,
...     h=0.0,
...     k=0.0,
...     l=0.0 * lox.deg,
... )

Methods:

eccentricity –

Return the orbital eccentricity.
f –

Return f = e·cos(ω + I·Ω).
frame –

Return the reference frame.
g –

Return g = e·sin(ω + I·Ω).
h –

Return h = tanᴵ(i/2)·cos(Ω).
inclination –

Return the orbital inclination.
k –

Return k = tanᴵ(i/2)·sin(Ω).
l –

Return the true longitude l = ν + ω + I·Ω.
origin –

Return the central body (origin) of this orbit.
p –

Return the semi-latus rectum (semi-parameter) p.
retrograde –

Return whether the elements use the retrograde set (retrograde factor I = -1).
time –

Return the epoch of this orbit.
to_cartesian –

Convert these modified equinoctial elements to a Cartesian state.
to_equinoctial –

Convert these modified equinoctial elements to equinoctial elements.
to_keplerian –

Convert these modified equinoctial elements to Keplerian orbital elements.

eccentricity

eccentricity() -> float

Return the orbital eccentricity.

f

f() -> float

Return f = e·cos(ω + I·Ω).

frame

frame() -> Frame

Return the reference frame.

g

g() -> float

Return g = e·sin(ω + I·Ω).

h

h() -> float

Return h = tanᴵ(i/2)·cos(Ω).

inclination

inclination() -> Angle

Return the orbital inclination.

k

k() -> float

Return k = tanᴵ(i/2)·sin(Ω).

l

l() -> Angle

Return the true longitude l = ν + ω + I·Ω.

origin

origin() -> Origin

Return the central body (origin) of this orbit.

p

p() -> Distance

Return the semi-latus rectum (semi-parameter) p.

retrograde

retrograde() -> bool

Return whether the elements use the retrograde set (retrograde factor I = -1).

time

time() -> Time

Return the epoch of this orbit.

to_cartesian

to_cartesian() -> Cartesian

Convert these modified equinoctial elements to a Cartesian state.

Raises:

UndefinedOriginPropertyError –

If the origin has no gravitational parameter.

to_equinoctial

to_equinoctial() -> Equinoctial

Convert these modified equinoctial elements to equinoctial elements.

Raises:

ValueError –

If the orbit is not closed.

to_keplerian

to_keplerian() -> Keplerian

Convert these modified equinoctial elements to Keplerian orbital elements.

Raises:

ValueError –

If the elements of an open orbit lie too close to its asymptotes.

Trajectory

A time-series of orbital states with interpolation support.

Parameters:

states
–

List of Cartesian objects in chronological order.

Examples:

>>> trajectory = propagator.propagate(times)
>>> state = trajectory.at(t)
>>> arr = trajectory.to_numpy()

Methods:

at –

Interpolate the trajectory at a specific time.
extrapolation_limit –

Return how far the trajectory is extrapolated before the first and after the last state (default: 1 ms).
from_numpy –

Create a Trajectory from a numpy array.
origin –

Return the central body (origin) of this trajectory.
reference_frame –

Return the reference frame of this trajectory.
states –

Return the list of states in this trajectory.
to_frame –

Transform all states to a different reference frame.
to_numpy –

Export trajectory to a numpy array with columns [t(s), x(m), y(m), z(m), vx(m/s), vy(m/s), vz(m/s)].
to_origin –

Transform all states to a different central body.
with_extrapolation_limit –

Return a copy of the trajectory with a different extrapolation limit.

at

at(time: Time | TimeDelta) -> Cartesian

Interpolate the trajectory at a specific time.

Parameters:

time
(Time | TimeDelta) –

Either a Time (absolute) or TimeDelta (relative to trajectory start).

Raises:

ValueError –

If the time argument is invalid or lies beyond the extrapolation limit.

extrapolation_limit

extrapolation_limit() -> TimeDelta

Return how far the trajectory is extrapolated before the first and after the last state (default: 1 ms).

from_numpy `classmethod`

from_numpy(
    start_time: Time,
    array: ndarray,
    origin: str | int | Origin | None = None,
    frame: str | Frame | None = None,
) -> Self

Create a Trajectory from a numpy array.

Parameters:

start_time
(Time) –

Reference epoch for the trajectory.
array
(ndarray) –

2D array with columns [t(s), x(m), y(m), z(m), vx(m/s), vy(m/s), vz(m/s)].
origin
(str | int | Origin | None, default: None ) –

Central body (default: Earth).
frame
(str | Frame | None, default: None ) –

Reference frame (default: ICRF).

Raises:

ValueError –

If the array has invalid shape, has fewer than 2 rows, its times are not strictly increasing, or it contains non-finite values.

origin

origin() -> Origin

Return the central body (origin) of this trajectory.

reference_frame

reference_frame() -> Frame

Return the reference frame of this trajectory.

states

states() -> list[Cartesian]

Return the list of states in this trajectory.

to_frame

to_frame(frame: str | Frame, provider: EOPProvider | None = None) -> Self

Transform all states to a different reference frame.

to_numpy

to_numpy() -> ndarray

Export trajectory to a numpy array with columns [t(s), x(m), y(m), z(m), vx(m/s), vy(m/s), vz(m/s)].

to_origin

to_origin(target: str | int | Origin, ephemeris: SPK) -> Self

Transform all states to a different central body.

with_extrapolation_limit

with_extrapolation_limit(limit: TimeDelta) -> Self

Return a copy of the trajectory with a different extrapolation limit.

Extrapolation continues the cubic of the first or last interval, so its accuracy degrades quickly beyond a fraction of the step size.

Parameters:

limit
(TimeDelta) –

How far to extrapolate before the first and after the last state. A negative limit is treated as zero.

Orbital States

Quick Example

Cartesian

time

position

velocity

x, y, z

vx, vy, vz

origin

frame

vx property

vy property

vz property

x property

y property

z property

is_physical

origin

position

reference_frame

rotation_lvlh

time

to_ellipsoid_location

to_equinoctial

to_frame

to_keplerian

to_modified_equinoctial

to_origin

velocity

Keplerian

time

semi_major_axis

eccentricity

inclination

longitude_of_ascending_node

argument_of_periapsis

true_anomaly

origin

semi_parameter

periapsis_radius

apoapsis_radius

periapsis_altitude

apoapsis_altitude

mean_anomaly

apoapsis_altitude

apoapsis_radius

argument_of_latitude

argument_of_periapsis

circular classmethod

time

semi_major_axis

altitude

inclination

longitude_of_ascending_node

true_anomaly

origin

eccentricity

flight_path_angle

inclination

longitude_of_ascending_node

mean_longitude

mean_motion

orbital_period

origin

periapsis_altitude

periapsis_radius

semi_major_axis

semi_parameter

specific_angular_momentum

specific_orbital_energy

sso classmethod

time

altitude

semi_major_axis

inclination

eccentricity

ltan

ltdn

argument_of_periapsis

true_anomaly

`time`

`position`

`velocity`

`x, y, z`

`vx, vy, vz`

`origin`

`frame`

vx `property`

vy `property`

vz `property`

x `property`

y `property`

z `property`

`time`

`semi_major_axis`

`eccentricity`

`inclination`

`longitude_of_ascending_node`

`argument_of_periapsis`

`true_anomaly`

`origin`

`semi_parameter`

`periapsis_radius`

`apoapsis_radius`

`periapsis_altitude`

`apoapsis_altitude`

`mean_anomaly`

circular `classmethod`

`time`

`semi_major_axis`

`altitude`

`inclination`

`longitude_of_ascending_node`

`true_anomaly`

`origin`

sso `classmethod`

`time`

`altitude`

`semi_major_axis`

`inclination`

`eccentricity`

`ltan`

`ltdn`

`argument_of_periapsis`

`true_anomaly`

`provider`

`time`

`a`

`h`

`k`

`p`

`q`

`mean_longitude`

`origin`

`frame`

`retrograde`

`time`

`p`

`f`

`g`

`h`

`k`

`l`

`origin`

`frame`

`retrograde`

`states`

`time`

from_numpy `classmethod`

`start_time`

`array`

`origin`