Propagators

Orbit propagation methods for predicting future states.

Available Propagators

Propagator	Description	Use Case
`Vallado`	Analytical Kepler propagator	Two-body motion
`J2`	Numerical J2 perturbation propagator	Oblateness effects
`TLE`	Two-Line Element set parser	Satellite catalog data
`SGP4`	Simplified General Perturbations	TLE-based propagation
`GroundPropagator`	Ground station state	Earth-fixed locations

Quick Example

import lox_space as lox

# Analytical (Kepler) propagation
t = lox.Time("TAI", 2024, 1, 1)
state = lox.Cartesian(
    t,
    position=(6678.0 * lox.km, 0.0 * lox.km, 0.0 * lox.km),
    velocity=(0.0 * lox.km_per_s, 7.73 * lox.km_per_s, 0.0 * lox.km_per_s),
)

propagator = lox.Vallado(state)

# Propagate to a single time
future = propagator.propagate(t + lox.TimeDelta.from_hours(1))

# Propagate to multiple times
times = [t + lox.TimeDelta(i * 60) for i in range(100)]
trajectory = propagator.propagate(times)

# Numerical J2 propagation (accounts for oblateness)
j2 = lox.J2(state)

# Propagate over a time interval (adaptive steps)
t_end = t + lox.TimeDelta.from_hours(2)
trajectory = j2.propagate(t, end=t_end)

# Custom solver tolerances
j2_tight = lox.J2(state, rtol=1e-12, atol=1e-10)

# SGP4 propagation from TLE
tle = """ISS (ZARYA)
1 25544U 98067A   24001.50000000  .00016717  00000-0  30472-3 0  9993
2 25544  51.6400  10.3600 0005000  50.0000 310.0000 15.50000000000010"""

sgp4 = lox.SGP4(tle)
state = sgp4.propagate(t)

Vallado

Semi-analytical Keplerian orbit propagator using Vallado's method.

Parameters:

initial_state
–

Initial orbital state (must be in an inertial frame).
max_iter
–

Maximum iterations for Kepler's equation solver.

Examples:

>>> state = lox.Cartesian(t,
...     position=(6678.0 * km, 0.0 * km, 0.0 * km),
...     velocity=(0.0 * km_per_s, 7.73 * km_per_s, 0.0 * km_per_s))
>>> prop = lox.Vallado(state)
>>> trajectory = prop.propagate([t1, t2, t3])

Methods:

propagate –

Propagate the orbit to one or more times.

propagate

propagate(steps: Time) -> Cartesian

propagate(steps: list[Time]) -> Trajectory

propagate(
    steps: Time | list[Time],
    end: Time | None = None,
    frame: str | Frame | None = None,
    provider: EOPProvider | None = None,
) -> Cartesian | Trajectory

Propagate the orbit to one or more times.

J2

Numerical J2 orbit propagator using Dormand-Prince 8(5,3) integration.

Parameters:

initial_state
–

Initial orbital state.
rtol
–

Relative tolerance (default: 1e-8).
atol
–

Absolute tolerance (default: 1e-6).
h_max
–

Maximum step size in seconds (default: auto from orbital timescale).
h_min
–

Minimum step size in seconds (default: 1e-6).
max_steps
–

Maximum number of integration steps (default: 100000).

Methods:

propagate –

Propagate the orbit to one or more times.

propagate

propagate(steps: Time) -> Cartesian

propagate(steps: list[Time]) -> Trajectory

propagate(
    steps: Time | list[Time],
    end: Time | None = None,
    frame: str | Frame | None = None,
    provider: EOPProvider | None = None,
) -> Cartesian | Trajectory

Propagate the orbit to one or more times.

TLE

Two-Line Element set (TLE) for satellite orbit data.

Parses and exposes the orbital elements from a NORAD Two-Line Element set.

Parameters:

tle
–

TLE as a string (2 or 3 lines) or a list of 2–3 strings.

Methods:

argument_of_perigee –

Argument of perigee.
classification –

Classification: 'U' (unclassified), 'C' (classified), or 'S' (secret).
drag_term –

BSTAR drag term (earth radii⁻¹).
eccentricity –

Orbital eccentricity (dimensionless).
element_set_number –

Element set number.
ephemeris_type –

Ephemeris type (always 0 in distributed data).
epoch –

TLE epoch as a Time (TAI scale).
inclination –

Orbital inclination.
international_designator –

International designator (e.g. '98067A').
mean_anomaly –

Mean anomaly.
mean_motion –

Mean motion in revolutions per day (Kozai convention).
mean_motion_ddot –

Second derivative of mean motion (rev/day³).
mean_motion_dot –

First derivative of mean motion (rev/day²).
norad_id –

NORAD catalog number.
object_name –

Satellite name, if present (line 0 of a 3-line TLE).
revolution_number –

Revolution number at epoch.
right_ascension –

Right ascension of the ascending node (RAAN).

argument_of_perigee

argument_of_perigee() -> Angle

Argument of perigee.

classification

classification() -> str

Classification: 'U' (unclassified), 'C' (classified), or 'S' (secret).

drag_term

drag_term() -> float

BSTAR drag term (earth radii⁻¹).

eccentricity

eccentricity() -> float

Orbital eccentricity (dimensionless).

element_set_number

element_set_number() -> int

Element set number.

ephemeris_type

ephemeris_type() -> int

Ephemeris type (always 0 in distributed data).

epoch

epoch() -> Time

TLE epoch as a Time (TAI scale).

inclination

inclination() -> Angle

Orbital inclination.

international_designator

international_designator() -> str | None

International designator (e.g. '98067A').

mean_anomaly

mean_anomaly() -> Angle

Mean anomaly.

mean_motion

mean_motion() -> float

Mean motion in revolutions per day (Kozai convention).

mean_motion_ddot

mean_motion_ddot() -> float

Second derivative of mean motion (rev/day³).

mean_motion_dot

mean_motion_dot() -> float

First derivative of mean motion (rev/day²).

norad_id

norad_id() -> int

NORAD catalog number.

object_name

object_name() -> str | None

Satellite name, if present (line 0 of a 3-line TLE).

revolution_number

revolution_number() -> int

Revolution number at epoch.

right_ascension

right_ascension() -> Angle

Right ascension of the ascending node (RAAN).

SGP4

SGP4 (Simplified General Perturbations 4) orbit propagator.

SGP4 is the standard propagator for objects tracked by NORAD/Space-Track. It uses Two-Line Element (TLE) data.

Parameters:

tle
–

TLE object, string (2 or 3 lines), or list of 2–3 strings.

Examples:

>>> tle = '''ISS (ZARYA)
... 1 25544U 98067A   24001.50000000  .00016717  00000-0  10270-3 0  9002
... 2 25544  51.6400 208.9163 0006703  40.7490  46.4328 15.49952307    11'''
>>> sgp4 = lox.SGP4(tle)
>>> trajectory = sgp4.propagate([t1, t2, t3])

Methods:

propagate –

Propagate the orbit to one or more times.
time –

Return the TLE epoch time.
tle –

Return the parsed TLE.

propagate

propagate(steps: Time, provider: EOPProvider | None = None) -> Cartesian

propagate(steps: list[Time], provider: EOPProvider | None = None) -> Trajectory

propagate(
    steps: Time | list[Time],
    end: Time | None = None,
    frame: str | Frame | None = None,
    provider: EOPProvider | None = None,
) -> Cartesian | Trajectory

Propagate the orbit to one or more times.

time

time() -> Time

Return the TLE epoch time.

tle

tle() -> TLE

Return the parsed TLE.

GroundPropagator

Propagator for ground station positions.

Parameters:

location
–

The ground location to propagate.

Examples:

>>> gs = lox.GroundLocation(lox.Origin("Earth"), lon, lat, alt)
>>> prop = lox.GroundPropagator(gs)
>>> trajectory = prop.propagate([t1, t2, t3])

Methods:

propagate –

Propagate the ground station to one or more times.

propagate

propagate(steps: Time) -> Cartesian

propagate(steps: list[Time]) -> Trajectory

propagate(
    steps: Time | list[Time],
    end: Time | None = None,
    frame: str | Frame | None = None,
    provider: EOPProvider | None = None,
) -> Cartesian | Trajectory

Propagate the ground station to one or more times.

Propagators

Available Propagators

Quick Example

Vallado

initial_state

max_iter

propagate

J2

initial_state

rtol

atol

h_max

h_min

max_steps

propagate

TLE

tle

argument_of_perigee

classification

drag_term

eccentricity

element_set_number

ephemeris_type

epoch

inclination

international_designator

mean_anomaly

mean_motion

mean_motion_ddot

mean_motion_dot

norad_id

object_name

revolution_number

right_ascension

SGP4

tle

propagate

time

tle

GroundPropagator

location

propagate

`initial_state`

`max_iter`

`initial_state`

`rtol`

`atol`

`h_max`

`h_min`

`max_steps`

`tle`

`tle`

`location`