Skip to content

Orbital States

Representations of orbital states in Cartesian and Keplerian forms.

Quick Example

import lox_space as lox

# Create a Cartesian state
t = lox.Time("TAI", 2024, 1, 1)
state = lox.State(
    time=t,
    position=(6678.0, 0.0, 0.0),  # km
    velocity=(0.0, 7.73, 0.0),    # km/s
)

# Convert to Keplerian elements
kep = state.to_keplerian()
print(f"a = {kep.semi_major_axis():.1f} km")
print(f"e = {kep.eccentricity():.6f}")
print(f"i = {kep.inclination():.4f} rad")

# Create from Keplerian elements
kep = lox.Keplerian(
    time=t,
    semi_major_axis=6678.0,
    eccentricity=0.001,
    inclination=0.5,
    longitude_of_ascending_node=0.0,
    argument_of_periapsis=0.0,
    true_anomaly=0.0,
)
state = kep.to_cartesian()

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

State

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

Parameters:

  • time

    –

    The epoch of this state.

  • position

    –

    Position vector (x, y, z) in km.

  • velocity

    –

    Velocity vector (vx, vy, vz) in km/s.

  • origin

    –

    Central body (default: Earth).

  • frame

    –

    Reference frame (default: ICRF).

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1)
>>> state = lox.State(
...     t,
...     position=(6678.0, 0.0, 0.0),
...     velocity=(0.0, 7.73, 0.0),
... )

Methods:

  • origin –

    Return the central body (origin) of this state.

  • position –

    Return the position vector as a numpy array [x, y, z] in km.

  • 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_frame –

    Transform this state to a different reference frame.

  • to_ground_location –

    Convert this state to a ground location.

  • to_keplerian –

    Convert this Cartesian state to Keplerian orbital elements.

  • to_origin –

    Transform this state to a different central body.

  • velocity –

    Return the velocity vector as a numpy array [vx, vy, vz] in km/s.

origin 

origin() -> Origin

Return the central body (origin) of this state.

position 

position() -> ndarray

Return the position vector as a numpy array [x, y, z] in km.

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_frame 

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

Transform this state to a different reference frame.

to_ground_location 

to_ground_location() -> GroundLocation

Convert this state to a ground location.

to_keplerian 

to_keplerian() -> Keplerian

Convert this Cartesian state to Keplerian orbital elements.

to_origin 

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

Transform this state to a different central body.

velocity 

velocity() -> ndarray

Return the velocity vector as a numpy array [vx, vy, vz] in km/s.

Keplerian

Represents an orbit using Keplerian (classical) orbital elements.

Parameters:

  • time

    –

    Epoch of the elements.

  • semi_major_axis

    –

    Semi-major axis in km.

  • eccentricity

    –

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

  • inclination

    –

    Inclination in radians.

  • longitude_of_ascending_node

    –

    RAAN in radians.

  • argument_of_periapsis

    –

    Argument of periapsis in radians.

  • true_anomaly

    –

    True anomaly in radians.

  • origin

    –

    Central body (default: Earth).

Examples:

>>> import math
>>> t = lox.Time("TAI", 2024, 1, 1)
>>> orbit = lox.Keplerian(
...     t,
...     semi_major_axis=6678.0,
...     eccentricity=0.001,
...     inclination=math.radians(51.6),
...     longitude_of_ascending_node=0.0,
...     argument_of_periapsis=0.0,
...     true_anomaly=0.0,
... )

Methods:

argument_of_periapsis 

argument_of_periapsis() -> float

Return the argument of periapsis in radians.

eccentricity 

eccentricity() -> float

Return the orbital eccentricity.

inclination 

inclination() -> float

Return the inclination in radians.

longitude_of_ascending_node 

longitude_of_ascending_node() -> float

Return the longitude of the ascending node (RAAN) in radians.

orbital_period 

orbital_period() -> TimeDelta

Return the orbital period.

origin 

origin() -> Origin

Return the central body (origin) of this orbit.

semi_major_axis 

semi_major_axis() -> float

Return the semi-major axis in km.

time 

time() -> Time

Return the epoch of these elements.

to_cartesian 

to_cartesian() -> State

Convert these Keplerian elements to a Cartesian state.

true_anomaly 

true_anomaly() -> float

Return the true anomaly in radians.

Trajectory

A time-series of orbital states with interpolation support.

Parameters:

  • states

    –

    List of State objects in chronological order.

Examples:

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

Methods:

  • find_events –

    Find events where a function crosses zero.

  • find_windows –

    Find time windows where a function is positive.

  • from_numpy –

    Create a Trajectory from a numpy array.

  • interpolate –

    Interpolate the trajectory at a specific time.

  • 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.

  • to_origin –

    Transform all states to a different central body.

find_events 

find_events(func: Callable[[State], float]) -> list[Event]

Find events where a function crosses zero.

find_windows 

find_windows(func: Callable[[State], float]) -> list[Window]

Find time windows where a function is positive.

from_numpy classmethod 

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

Create a Trajectory from a numpy array.

Parameters:

  • start_time

    (Time) –

    Reference epoch for the trajectory.

  • states

    (ndarray) –

    2D array with columns [t, x, y, z, vx, vy, vz].

  • origin

    (Origin | None, default: None ) –

    Central body (default: Earth).

  • frame

    (Frame | None, default: None ) –

    Reference frame (default: ICRF).

interpolate 

interpolate(time: Time | TimeDelta) -> State

Interpolate the trajectory at a specific time.

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[State]

Return the list of states in this trajectory.

to_frame 

to_frame(frame: 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.

to_origin 

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

Transform all states to a different central body.

Ensemble

Collection of named trajectories for batch visibility analysis.

Parameters:

  • ensemble

    –

    Dictionary mapping spacecraft names to their trajectories.

Examples:

>>> ensemble = lox.Ensemble({
...     "SC1": trajectory1,
...     "SC2": trajectory2,
... })
>>> results = lox.visibility_all(times, ground_stations, ensemble, spk)