Skip to content

SGP4

SGP4/SDP4 orbit propagator implemented in JAX.

This module provides a JAX-native implementation of the SGP4 (Simplified General Perturbations 4) and SDP4 (Simplified Deep-space Perturbations 4) orbit propagators for propagating Two-Line Element (TLE) sets. The implementation supports JIT compilation and vmap over time arrays.

WGS72 = EarthGravity(tumin=(1.0 / _xke_72), mu=_mu_72, radiusearthkm=_re_72, xke=_xke_72, j2=_j2_72, j3=_j3_72, j4=_j4_72, j3oj2=(_j3_72 / _j2_72)) module-attribute

WGS 72 gravity model (standard for SGP4).

WGS72OLD = EarthGravity(tumin=(1.0 / _xke_72old), mu=_mu_72old, radiusearthkm=_re_72old, xke=_xke_72old, j2=_j2_72old, j3=_j3_72old, j4=_j4_72old, j3oj2=(_j3_72old / _j2_72old)) module-attribute

WGS 72 Old gravity model (legacy).

WGS84 = EarthGravity(tumin=(1.0 / _xke_84), mu=_mu_84, radiusearthkm=_re_84, xke=_xke_84, j2=_j2_84, j3=_j3_84, j4=_j4_84, j3oj2=(_j3_84 / _j2_84)) module-attribute

WGS 84 gravity model.

EarthGravity

Bases: NamedTuple

Earth gravity model constants for SGP4 propagation.

Attributes:

Name Type Description
tumin float

Time units per minute (1/xke).

mu float

Gravitational parameter [km3/s2].

radiusearthkm float

Earth equatorial radius [km].

xke float

Reciprocal of tumin (sqrt(GM) in SGP4 time units).

j2 float

Second zonal harmonic.

j3 float

Third zonal harmonic.

j4 float

Fourth zonal harmonic.

j3oj2 float

Ratio j3/j2.

SGP4Elements dataclass

Parsed orbital elements from a TLE or OMM record.

This is a plain Python dataclass (not a JAX pytree) holding the parsed orbital elements, epoch information, and metadata extracted from a TLE or OMM record. All angular values are stored in their original units as parsed (degrees for user-facing, radians for SGP4-internal).

Attributes:

Name Type Description
satnum_str str

Satellite catalog number as a string (e.g. '25544').

classification str

Classification character ('U', 'C', or 'S').

intldesg str

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

epochyr int

Two-digit epoch year (0-99).

epochdays float

Day of year with fractional day.

ndot float

First derivative of mean motion divided by 2 [rad/min^2].

nddot float

Second derivative of mean motion divided by 6 [rad/min^3].

bstar float

B* drag coefficient [1/earth_radii].

ephtype int

Ephemeris type (typically 0).

elnum int

Element set number.

revnum int

Revolution number at epoch.

inclo float

Inclination [rad].

nodeo float

Right ascension of ascending node [rad].

ecco float

Eccentricity [dimensionless].

argpo float

Argument of perigee [rad].

mo float

Mean anomaly [rad].

no_kozai float

Mean motion (Kozai) [rad/min].

jdsatepoch float

Julian date of epoch (whole days).

jdsatepochF float

Julian date of epoch (fractional day).

TLE

A parsed TLE with SGP4/SDP4 propagation and frame transforms.

Wraps TLE parsing, SGP4 initialization, and propagation into a single object. Provides orbital element properties in user-friendly units and state vector methods in various reference frames.

The propagate method returns raw SGP4 output in km/km/s (for comparison testing). The state_* methods return SI units (m, m/s).

Examples:

from astrojax.sgp4 import TLE

line1 = "1 25544U 98067A   08264.51782528 ..."
line2 = "2 25544  51.6416 247.4627 ..."
sat = TLE(line1, line2)

# Properties
sat.epoch       # Epoch object
sat.n           # mean motion [rev/day]
sat.e           # eccentricity
sat.i           # inclination [deg]

# Raw SGP4 output (km, km/s)
r_km, v_kms = sat.propagate(60.0)

# State in TEME (m, m/s) at epoch + 3600 seconds
x_teme = sat.state_teme(3600.0)

# State in GCRF at a specific Epoch
x_gcrf = sat.state_gcrf(some_epoch, eop=eop_data)

Parameters:

Name Type Description Default
line1 str

First TLE line.

required
line2 str

Second TLE line.

required
gravity str | EarthGravity

Gravity model name or :class:EarthGravity instance.

'wgs72'

M property

Mean anomaly [degrees].

argp property

Argument of perigee [degrees].

bstar property

B* drag coefficient [1/earth_radii].

e property

Eccentricity [dimensionless].

epoch property

TLE epoch as an :class:Epoch object.

i property

Inclination [degrees].

method property

Propagation method: 'n' (near-earth) or 'd' (deep-space).

n property

Mean motion [rev/day].

params property

Raw SGP4 parameter array (for advanced use).

raan property

Right ascension of ascending node [degrees].

satnum property

NORAD catalog number (string, e.g. '25544').

from_elements(elements, gravity='wgs72') classmethod

Create a TLE from pre-parsed SGP4 orbital elements.

Parameters:

Name Type Description Default
elements SGP4Elements

Parsed orbital elements from parse_tle or parse_omm.

required
gravity str | EarthGravity

Gravity model name or :class:EarthGravity instance.

'wgs72'

Returns:

Type Description
TLE

A new :class:TLE instance.

from_gp_record(record, gravity='wgs72') classmethod

Create a TLE from a GPRecord.

Parameters:

Name Type Description Default
record GPRecord

A GP record from CelesTrak or SpaceTrack.

required
gravity str | EarthGravity

Gravity model name or :class:EarthGravity instance.

'wgs72'

Returns:

Type Description
TLE

A new :class:TLE instance.

Raises:

Type Description
KeyError

If the record is missing required fields.

from_omm(fields, gravity='wgs72') classmethod

Create a TLE from OMM (Orbit Mean-Elements Message) fields.

Parameters:

Name Type Description Default
fields dict[str, str]

Dictionary mapping OMM field names to string values. See :func:~astrojax.sgp4.parse_omm for required keys.

required
gravity str | EarthGravity

Gravity model name or :class:EarthGravity instance.

'wgs72'

Returns:

Type Description
TLE

A new :class:TLE instance.

Raises:

Type Description
KeyError

If a required OMM field is missing.

propagate(tsince_min)

Propagate using SGP4 and return raw output.

Parameters:

Name Type Description Default
tsince_min float | ArrayLike

Time since TLE epoch in minutes.

required

Returns:

Type Description
Array

Tuple (r_km, v_kms) — position [km] and velocity [km/s]

Array

in the TEME frame.

state(t)

Compute state in the TEME frame (alias for :meth:state_teme).

Parameters:

Name Type Description Default
t Epoch | float | ArrayLike

:class:Epoch (absolute time) or seconds since TLE epoch.

required

Returns:

Type Description
Array

6-element TEME state [x, y, z, vx, vy, vz] in m and m/s.

state_gcrf(t, eop=None)

Compute state in the GCRF frame.

Parameters:

Name Type Description Default
t Epoch | float | ArrayLike

:class:Epoch (absolute time) or seconds since TLE epoch.

required
eop EOPData | None

EOP data. If None, uses zero EOP (no polar motion).

None

Returns:

Type Description
Array

6-element GCRF state [x, y, z, vx, vy, vz] in m and m/s.

state_itrf(t, eop=None)

Compute state in the ITRF frame.

Parameters:

Name Type Description Default
t Epoch | float | ArrayLike

:class:Epoch (absolute time) or seconds since TLE epoch.

required
eop EOPData | None

EOP data. If None, uses zero EOP (no polar motion).

None

Returns:

Type Description
Array

6-element ITRF state [x, y, z, vx, vy, vz] in m and m/s.

state_pef(t)

Compute state in the PEF frame.

Parameters:

Name Type Description Default
t Epoch | float | ArrayLike

:class:Epoch (absolute time) or seconds since TLE epoch.

required

Returns:

Type Description
Array

6-element PEF state [x, y, z, vx, vy, vz] in m and m/s.

state_teme(t)

Compute state in the TEME frame.

Parameters:

Name Type Description Default
t Epoch | float | ArrayLike

:class:Epoch (absolute time) or seconds since TLE epoch.

required

Returns:

Type Description
Array

6-element TEME state [x, y, z, vx, vy, vz] in m and m/s.

compute_checksum(line)

Compute the TLE checksum for a line.

The checksum is the sum of all digit characters plus 1 for each minus sign, modulo 10, computed over the first 68 characters.

Parameters:

Name Type Description Default
line str

A TLE line string (at least 68 characters).

required

Returns:

Type Description
int

The checksum digit (0-9).

create_sgp4_propagator(line1, line2, gravity='wgs72')

Create a JIT-compatible SGP4 propagator from TLE lines.

This is the functional API that returns a parameter array and a propagation closure suitable for jax.jit and jax.vmap.

Parameters:

Name Type Description Default
line1 str

First TLE line.

required
line2 str

Second TLE line.

required
gravity str | EarthGravity

Gravity model name ('wgs72', 'wgs84', 'wgs72old') or an EarthGravity instance.

'wgs72'

Returns:

Type Description
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]

Tuple of (params, propagate_fn) where: - params is a flat jnp.array of satellite parameters - propagate_fn(tsince) takes time since epoch in minutes and returns (r_km, v_kms) in the TEME frame

create_sgp4_propagator_from_elements(elements, gravity='wgs72')

Create a JIT-compatible SGP4 propagator from pre-parsed elements.

Accepts an :class:SGP4Elements dataclass (e.g. from parse_tle or parse_omm) and returns a parameter array and propagation closure.

Parameters:

Name Type Description Default
elements SGP4Elements

Parsed orbital elements from parse_tle or parse_omm.

required
gravity str | EarthGravity

Gravity model name ('wgs72', 'wgs84', 'wgs72old') or an EarthGravity instance.

'wgs72'

Returns:

Type Description
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]

Tuple of (params, propagate_fn) where: - params is a flat jnp.array of satellite parameters - propagate_fn(tsince) takes time since epoch in minutes and returns (r_km, v_kms) in the TEME frame

create_sgp4_propagator_from_gp_record(record, gravity='wgs72')

Create a JIT-compatible SGP4 propagator from a GPRecord.

Accepts a :class:~astrojax.GPRecord (e.g. from CelesTrak or SpaceTrack) and returns a parameter array and propagation closure.

Parameters:

Name Type Description Default
record GPRecord

A GP record from CelesTrak or SpaceTrack.

required
gravity str | EarthGravity

Gravity model name ('wgs72', 'wgs84', 'wgs72old') or an EarthGravity instance.

'wgs72'

Returns:

Type Description
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]

Tuple of (params, propagate_fn) where: - params is a flat jnp.array of satellite parameters - propagate_fn(tsince) takes time since epoch in minutes and returns (r_km, v_kms) in the TEME frame

Raises:

Type Description
KeyError

If the record is missing required fields.

create_sgp4_propagator_from_omm(fields, gravity='wgs72')

Create a JIT-compatible SGP4 propagator from OMM fields.

Accepts a dictionary of OMM (Orbit Mean-Elements Message) field names and string values, as would be parsed from a CSV or XML OMM record.

Parameters:

Name Type Description Default
fields dict[str, str]

Dictionary mapping OMM field names to string values. See :func:~astrojax.sgp4.parse_omm for required keys.

required
gravity str | EarthGravity

Gravity model name ('wgs72', 'wgs84', 'wgs72old') or an EarthGravity instance.

'wgs72'

Returns:

Type Description
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]

Tuple of (params, propagate_fn) where: - params is a flat jnp.array of satellite parameters - propagate_fn(tsince) takes time since epoch in minutes and returns (r_km, v_kms) in the TEME frame

Raises:

Type Description
KeyError

If a required OMM field is missing.

elements_to_array(elements)

Convert SGP4Elements to a flat JAX array for use with sgp4_init_jax.

The returned array has shape (11,) with elements in the order: jdsatepoch, jdsatepochF, no_kozai, ecco, inclo, nodeo, argpo, mo, bstar, ndot, nddot.

Parameters:

Name Type Description Default
elements SGP4Elements

Parsed TLE elements from parse_tle or parse_omm.

required

Returns:

Type Description
Array

Array of shape (11,) containing the numeric orbital elements.

gp_record_to_array(record)

Convert a GPRecord to a flat JAX array for use with sgp4_init_jax.

This is a convenience wrapper that calls record.to_sgp4_elements() followed by elements_to_array.

Parameters:

Name Type Description Default
record GPRecord

A GP record from CelesTrak or SpaceTrack.

required

Returns:

Type Description
Array

Array of shape (11,) containing the numeric orbital elements.

Raises:

Type Description
KeyError

If the record is missing required fields.

omm_to_array(fields)

Convert OMM fields dict to a flat JAX array for use with sgp4_init_jax.

This is a convenience wrapper that calls parse_omm followed by elements_to_array.

Parameters:

Name Type Description Default
fields dict[str, str]

Dictionary mapping OMM field names to string values. See :func:~astrojax.sgp4.parse_omm for required keys.

required

Returns:

Type Description
Array

Array of shape (11,) containing the numeric orbital elements.

Raises:

Type Description
KeyError

If a required OMM field is missing.

parse_omm(fields)

Parse OMM (Orbit Mean-Elements Message) fields into SGP4 orbital elements.

Accepts a dictionary of OMM field names and string values, as would be parsed from a CSV or XML OMM record.

Parameters:

Name Type Description Default
fields dict[str, str]

Dictionary mapping OMM field names to string values. Required keys: EPOCH, MEAN_MOTION, ECCENTRICITY, INCLINATION, RA_OF_ASC_NODE, ARG_OF_PERICENTER, MEAN_ANOMALY, NORAD_CAT_ID, BSTAR. Optional keys: CLASSIFICATION_TYPE, OBJECT_ID, EPHEMERIS_TYPE, ELEMENT_SET_NO, REV_AT_EPOCH, MEAN_MOTION_DOT, MEAN_MOTION_DDOT.

required

Returns:

Type Description
SGP4Elements

Parsed orbital elements ready for SGP4 initialization.

Raises:

Type Description
KeyError

If a required field is missing.

parse_tle(line1, line2)

Parse a Two-Line Element set into SGP4 orbital elements.

Follows the fixed-column TLE format specification. Angular values are converted to radians and mean motion to rad/min for SGP4 internal use.

Parameters:

Name Type Description Default
line1 str

First TLE line (69 characters including checksum).

required
line2 str

Second TLE line (69 characters including checksum).

required

Returns:

Type Description
SGP4Elements

Parsed orbital elements ready for SGP4 initialization.

Raises:

Type Description
ValueError

If lines fail format validation, checksum check, or satellite numbers don't match.

sgp4_init(elements, gravity=WGS72, opsmode='i')

Initialize SGP4 satellite parameters from parsed TLE elements.

This function runs at Python time (not under JIT). It computes all the intermediate parameters needed by the SGP4 propagator and packs them into a flat JAX array.

Parameters:

Name Type Description Default
elements SGP4Elements

Parsed TLE elements from parse_tle or parse_omm.

required
gravity EarthGravity

Earth gravity model constants.

WGS72
opsmode str

Operation mode ('i' for improved, 'a' for AFSPC).

'i'

Returns:

Type Description
Array

Tuple of (params, method) where params is a flat

str

jnp.array of shape (_NUM_PARAMS,) and method is

tuple[Array, str]

'n' (near-Earth) or 'd' (deep-space).

sgp4_init_jax(elements, gravity=WGS72, opsmode='i')

Initialize SGP4 satellite parameters (JAX, JIT-compatible).

Unlike sgp4_init, this function is compatible with jax.jit, jax.vmap, and jax.grad. It accepts a flat array of numeric orbital elements and returns a flat parameter array with an embedded method flag (0.0 = near-earth, 1.0 = deep-space).

Use with jax.jit::

init_jit = jax.jit(sgp4_init_jax, static_argnames=('gravity', 'opsmode'))
params = init_jit(elements_arr)

Parameters:

Name Type Description Default
elements Array

Array of shape (11,) containing the numeric orbital elements. Use elements_to_array to convert from SGP4Elements. Order: jdsatepoch, jdsatepochF, no_kozai, ecco, inclo, nodeo, argpo, mo, bstar, ndot, nddot.

required
gravity EarthGravity

Earth gravity model constants. Treated as a static argument under JIT (use static_argnames).

WGS72
opsmode str

Operation mode ('i' for improved, 'a' for AFSPC). Treated as a static argument under JIT.

'i'

Returns:

Type Description
Array

Flat jnp.array of shape (_NUM_PARAMS,) with all SGP4

Array

parameters, including a method flag at index _IDX["method"].

sgp4_propagate(params, tsince, method, max_dspace_iters=200)

Propagate a satellite using SGP4/SDP4.

This is the main propagation entry point. The method flag selects near-Earth ('n') or deep-space ('d') code path at Python trace time, making it compatible with jax.jit.

Parameters:

Name Type Description Default
params Array

Flat parameter array from sgp4_init.

required
tsince ArrayLike

Time since epoch in minutes.

required
method str

'n' for near-Earth SGP4, 'd' for deep-space SDP4.

required
max_dspace_iters int

Maximum number of deep-space resonance integration steps. Each step covers 720 minutes. Default 200 (≈100 days). Only used when method='d'.

200

Returns:

Type Description
Array

Tuple of (r, v) where r is position [km] and v is

Array

velocity [km/s], both as 3-element arrays in the TEME frame.

sgp4_propagate_unbounded(params, tsince, method)

Propagate a satellite using SGP4/SDP4 with unbounded deep-space integration.

This variant uses jax.lax.while_loop for deep-space resonance integration, imposing no upper bound on propagation time. It supports forward-mode AD (jax.jacfwd / jax.jvp) but not reverse-mode AD (jax.grad / jax.vjp).

For near-earth satellites (method='n'), the behavior is identical to :func:sgp4_propagate.

Parameters:

Name Type Description Default
params Array

Flat parameter array from sgp4_init.

required
tsince ArrayLike

Time since epoch in minutes.

required
method str

'n' for near-Earth SGP4, 'd' for deep-space SDP4.

required

Returns:

Type Description
Array

Tuple of (r, v) where r is position [km] and v is

Array

velocity [km/s], both as 3-element arrays in the TEME frame.

sgp4_propagate_unified(params, tsince, max_dspace_iters=200)

Propagate a satellite using SGP4/SDP4 with auto-detection (JAX, JIT-compatible).

Unlike sgp4_propagate, this function does not require a separate method string. It reads the method flag from params (set by sgp4_init_jax or sgp4_init) and dispatches to the correct propagation branch using jax.lax.cond.

This enables vmap over satellites with mixed near-earth and deep-space orbits in a single batch.

Parameters:

Name Type Description Default
params Array

Flat parameter array from sgp4_init or sgp4_init_jax.

required
tsince ArrayLike

Time since epoch in minutes.

required
max_dspace_iters int

Maximum number of deep-space resonance integration steps. Each step covers 720 minutes. Default 200 (≈100 days).

200

Returns:

Type Description
Array

Tuple of (r, v) where r is position [km] and v is

Array

velocity [km/s], both as 3-element arrays in the TEME frame.

sgp4_propagate_unified_unbounded(params, tsince)

Propagate a satellite using SGP4/SDP4 with unbounded deep-space integration and auto-detection.

This variant uses jax.lax.while_loop for deep-space resonance integration, imposing no upper bound on propagation time. It supports forward-mode AD (jax.jacfwd / jax.jvp) but not reverse-mode AD (jax.grad / jax.vjp).

Unlike :func:sgp4_propagate_unbounded, this function does not require a separate method string. It reads the method flag from params and dispatches using jax.lax.cond.

Parameters:

Name Type Description Default
params Array

Flat parameter array from sgp4_init or sgp4_init_jax.

required
tsince ArrayLike

Time since epoch in minutes.

required

Returns:

Type Description
Array

Tuple of (r, v) where r is position [km] and v is

Array

velocity [km/s], both as 3-element arrays in the TEME frame.

validate_tle_line(line, line_number)

Validate a TLE line's format and checksum.

Parameters:

Name Type Description Default
line str

A TLE line string.

required
line_number int

Expected line number (1 or 2).

required

Raises:

Type Description
ValueError

If the line fails format or checksum validation.