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. |
classification |
str
|
Classification character ( |
intldesg |
str
|
International designator (e.g. |
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: |
'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 |
required |
gravity
|
str | EarthGravity
|
Gravity model name or :class: |
'wgs72'
|
Returns:
| Type | Description |
|---|---|
TLE
|
A new :class: |
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: |
'wgs72'
|
Returns:
| Type | Description |
|---|---|
TLE
|
A new :class: |
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: |
required |
gravity
|
str | EarthGravity
|
Gravity model name or :class: |
'wgs72'
|
Returns:
| Type | Description |
|---|---|
TLE
|
A new :class: |
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 |
Array
|
in the TEME frame. |
state(t)
¶
state_gcrf(t, eop=None)
¶
Compute state in the GCRF frame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t
|
Epoch | float | ArrayLike
|
:class: |
required |
eop
|
EOPData | None
|
EOP data. If |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
6-element GCRF state |
state_itrf(t, eop=None)
¶
Compute state in the ITRF frame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t
|
Epoch | float | ArrayLike
|
:class: |
required |
eop
|
EOPData | None
|
EOP data. If |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
6-element ITRF state |
state_pef(t)
¶
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'
|
Returns:
| Type | Description |
|---|---|
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]
|
Tuple of |
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 |
required |
gravity
|
str | EarthGravity
|
Gravity model name ( |
'wgs72'
|
Returns:
| Type | Description |
|---|---|
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]
|
Tuple of |
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'
|
Returns:
| Type | Description |
|---|---|
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]
|
Tuple of |
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: |
required |
gravity
|
str | EarthGravity
|
Gravity model name ( |
'wgs72'
|
Returns:
| Type | Description |
|---|---|
tuple[Array, Callable[[ArrayLike], tuple[Array, Array]]]
|
Tuple of |
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 |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Array of shape |
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 |
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: |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Array of shape |
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: |
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 |
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 |
str
|
|
tuple[Array, str]
|
|
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 |
required |
gravity
|
EarthGravity
|
Earth gravity model constants. Treated as a static
argument under JIT (use |
WGS72
|
opsmode
|
str
|
Operation mode ('i' for improved, 'a' for AFSPC). Treated as a static argument under JIT. |
'i'
|
Returns:
| Type | Description |
|---|---|
Array
|
Flat |
Array
|
parameters, including a method flag at index |
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 |
required |
tsince
|
ArrayLike
|
Time since epoch in minutes. |
required |
method
|
str
|
|
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 |
200
|
Returns:
| Type | Description |
|---|---|
Array
|
Tuple of |
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 |
required |
tsince
|
ArrayLike
|
Time since epoch in minutes. |
required |
method
|
str
|
|
required |
Returns:
| Type | Description |
|---|---|
Array
|
Tuple of |
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 |
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 |
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 |
required |
tsince
|
ArrayLike
|
Time since epoch in minutes. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Tuple of |
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. |