API Reference

Core Functions

sgp4jax.tle_to_satrec(line1, line2, gravity=None)

Parse TLE and initialize a SatRec ready for propagation.

Parameters:

  • line1 (str) – First TLE line

  • line2 (str) – Second TLE line

  • gravity (GravityConstants | None) – Gravity constants (default WGS72)

Return type:

SatRec

Returns:

SatRec NamedTuple

sgp4jax.tles_to_satrec(tles, gravity=None)

Parse an array of TLEs and return a batched SatRec.

Parameters:

  • tles (list[list[str]]) – TLE lines with shape (n_sat, 2). Each row contains [line1, line2] as strings.

  • gravity (GravityConstants | None) – Gravity constants (default WGS72).

Return type:

SatRec

Returns:

A single SatRec whose fields are stacked arrays with a leading dimension of n_sat, ready for use with jax.vmap.

sgp4jax.propagate(satrec, tsince)

Propagate satellite to time tsince (minutes from epoch).

Parameters:
Returns:

position vector (3,) in km (TEME frame) v: velocity vector (3,) in km/s (TEME frame) error: error code (0 = success)

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_jd(satrec, jd, fr)

Propagate satellite to Julian Date (jd + fr) in TEME.

Converts the Julian Date to minutes-since-epoch and calls propagate().

Parameters:
Returns:

Position in TEME frame (3,) in km. v: Velocity in TEME frame (3,) in km/s. error: Error code (0 = success).

Return type:

tuple[Array, Array, Array]

Specialized Propagators

These propagators are optimised for specific orbit families and are significantly faster than propagate() for homogeneous batches. Each eliminates the dead-branch computation present in the general propagator:

  • propagate_leo() — near-earth orbits (method=0), removes the deep-space integrator entirely.

  • propagate_sdp4_nr() — deep-space no-resonance orbits (method=1, irez=0, e.g. GPS/GLONASS/Galileo MEO), replaces the 64-step resonance scan with five scalar multiplications.

  • propagate_mixed() — heterogeneous batches of any orbit type; groups satellites by type internally and dispatches each group to the appropriate specialised propagator.

sgp4jax.propagate_leo(satrec, tsince)

Propagate a near-earth (LEO) satellite to time tsince (minutes from epoch).

This is a stripped-down version of sgp4 for near-earth satellites only. The deep-space resonance integrator (dspace) and lunar-solar periodic perturbations (dpper) are removed entirely, reducing XLA graph size and eliminating the dominant runtime cost for LEO orbits.

Warning: Do not use for deep-space satellites (orbital period > 225 min, mean motion < ~6.4 rev/day). Results will be incorrect for GEO/HEO/MEO objects because the deep-space secular and periodic corrections are skipped.

Parameters:

  • satrec (SatRec) – Initialized SatRec (near-earth only; deep-space fields ignored)

  • tsince (Union[Array, ndarray, bool, number, bool, int, float, complex, TypedNdArray]) – Time since epoch in minutes (scalar jnp.ndarray)

Returns:

position vector (3,) in km (TEME frame) v: velocity vector (3,) in km/s (TEME frame) error: error code (0 = success)

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_jd_leo(satrec, jd, fr)

Propagate a near-earth satellite to Julian Date (jd + fr) in TEME.

LEO/near-earth only variant — deep-space code paths are absent. See propagate_leo() for the performance trade-offs and limitations.

Parameters:
Returns:

Position in TEME frame (3,) in km. v: Velocity in TEME frame (3,) in km/s. error: Error code (0 = success).

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_sdp4_nr(satrec, tsince)

Propagate a deep-space, no-resonance (irez=0) satellite to time tsince.

This is a stripped-down version of sgp4 for deep-space satellites with irez=0 (no resonance). This captures MEO navigation satellites (GPS, GLONASS, Galileo, BeiDou MEO) and other deep-space objects that do not fall in the 24-hour synchronous (irez=1) or 12-hour Molniya (irez=2) resonance bands.

Simplifications over the full sgp4:

  • The resonance integrator (dspace / lax.scan) is removed entirely. For irez=0, dspace reduces to five scalar secular drift terms (dedt, didt, domdt, dnodt, dmdt), which are applied directly.

  • Deep-space satellites always have isimp=1, so the full-drag computation branch is omitted.

  • All jnp.where(is_deep, ...) guards collapse to unconditional deep-space assignments.

  • dpper (lunar-solar periodics) is retained unchanged.

Warning

Do not use for near-earth satellites (period < 225 min), irez=1 (GEO/synchronous), or irez=2 (Molniya/12h resonant) satellites — resonance and drag terms will be missing or zero.

Parameters:

  • satrec (SatRec) – Initialized SatRec (deep-space, irez=0 only)

  • tsince (Union[Array, ndarray, bool, number, bool, int, float, complex, TypedNdArray]) – Time since epoch in minutes (scalar jnp.ndarray)

Returns:

position vector (3,) in km (TEME frame) v: velocity vector (3,) in km/s (TEME frame) error: error code (0 = success)

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_jd_sdp4_nr(satrec, jd, fr)

Propagate a deep-space no-resonance (irez=0) satellite to Julian Date (jd + fr) in TEME.

Deep-space irez=0 only variant — resonance integrator is absent. See propagate_sdp4_nr() for the performance trade-offs and limitations.

Parameters:
Returns:

Position in TEME frame (3,) in km. v: Velocity in TEME frame (3,) in km/s. error: Error code (0 = success).

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_mixed(satrec_batch, times)

Propagate a heterogeneous batch of satellites over a shared array of times.

Groups satellites by type (near-earth / deep-space-no-resonance / deep-space-resonant) and dispatches each group to the appropriate specialized propagator, avoiding dead-branch computation for every group. Results are reassembled into the original satellite ordering.

Note

This function is not JIT-compilable as a whole and does not compose with jax.grad or jax.vmap. For JIT / AD / vmap compatibility, group satellites by type and call the specialized propagators directly (propagate_leo(), propagate_sdp4_nr(), propagate()).

Parameters:
Returns:

Positions in TEME frame, shape (N, M, 3) in km. v: Velocities in TEME frame, shape (N, M, 3) in km/s. error: Error codes, shape (N, M) (0 = success).

Return type:

tuple[Array, Array, Array]

Frame Transformations

sgp4jax.teme_to_gcrf(r_teme, v_teme, jd, fr)

Transform position/velocity from TEME to GCRF (≈ICRS).

Replicates Skyfield’s EarthSatellite._at() transformation chain: M = N @ P @ B, then R = rot_z(theta_GMST1982 - GAST) @ M with the final GCRF vectors obtained via R^T @ r_TEME.

The input Julian date jd + fr is treated as UT1 time (≈UTC). TT and TDB are derived internally using an approximate delta_T model.

Parameters:
Returns:

Position in GCRF frame (3,) in km. v_gcrf: Velocity in GCRF frame (3,) in km/s.

Return type:

tuple[Array, Array]

sgp4jax.itrf_to_gcrf(r_itrf, jd, fr)

Transform position from ITRF (Earth-fixed) to GCRF (≈ICRS).

The rotation is R = M^T @ rot_z(GAST) where M = N @ P @ B is the combined nutation-precession-bias matrix and GAST is the Greenwich Apparent Sidereal Time. Matches Skyfield’s ITRS.rotation_at(t).T to sub-millimetre precision.

The input Julian date jd + fr is treated as UT1 (≈UTC).

Parameters:
Returns:

Position in GCRF frame (3,) in km.

Return type:

Array

sgp4jax.gcrf_to_itrf(r_gcrf, jd, fr)

Transform position from GCRF (≈ICRS) to ITRF (Earth-fixed).

Inverse of itrf_to_gcrf(). The rotation is R = rot_z(-GAST) @ M where M = N @ P @ B. Matches Skyfield’s ITRS.rotation_at(t) to sub-millimetre precision.

The input Julian date jd + fr is treated as UT1 (≈UTC).

Parameters:
Returns:

Position in ITRF frame (3,) in km.

Return type:

Array

sgp4jax.propagate_gcrf(satrec, tsince)

Propagate satellite and return GCRF position/velocity.

Parameters:
Returns:

Position in GCRF frame (3,) in km. v_gcrf: Velocity in GCRF frame (3,) in km/s. error: Error code (0 = success).

Return type:

tuple[Array, Array, Array]

sgp4jax.propagate_jd_gcrf(satrec, jd, fr)

Propagate satellite to Julian Date (jd + fr) and return GCRF.

The input time jd + fr is interpreted as UTC, matching the time scale of TLE epochs and Measurement Set timestamps. The same UTC value is used for SGP4 propagation and, as an approximation to UT1, for the TEME → GCRF frame transformation (the UT1 − UTC difference is at most 0.9 s, introducing < 1 m frame error).

Parameters:
Returns:

Position in GCRF frame (3,) in km. v_gcrf: Velocity in GCRF frame (3,) in km/s. error: Error code (0 = success).

Return type:

tuple[Array, Array, Array]

Keplerian Propagation (no perturbations)

Pure two-body Keplerian motion using only the six classical TLE elements (inclination, RAAN, eccentricity, argument of perigee, mean anomaly, mean motion). All perturbations are ignored. Fully differentiable.

Note

TLE elements are Brouwer mean elements. Because SGP4 adds short-period corrections when converting to osculating elements, Keplerian positions will differ from SGP4 by O(1–50 km). This is expected behaviour, not a bug.

sgp4jax.kepler_gcrf_positions(satrec, times_jd)

Propagate one satellite to multiple times using pure Keplerian motion.

No perturbations are applied. Only the six TLE orbital elements (inclo, nodeo, ecco, argpo, mo, no_kozai) and the epoch (jdsatepoch, jdsatepochF) are used.

The function is JIT-compiled and differentiable with respect to all fields of satrec and with respect to times_jd.

Parameters:
Returns:

GCRF positions, shape (n_times, 3), in km. v_gcrf: GCRF velocities, shape (n_times, 3), in km/s.

Return type:

tuple[Array, Array]

Note

The TEME → GCRF rotation uses the input Julian dates as UT1 (UTC is an approximation accurate to < 1 s). For sub-arcsecond frame accuracy call utc_to_ut1() first and pass the UT1 dates.

sgp4jax.kepler_gcrf_positions_multi(satrec, times_jd)

Propagate multiple satellites to multiple times using pure Keplerian motion.

No perturbations are applied. The outer vmap iterates over satellites, the inner over times.

The function is JIT-compiled and differentiable with respect to all fields of satrec and with respect to times_jd.

Parameters:
Returns:

GCRF positions, shape (n_sat, n_times, 3), in km. v_gcrf: GCRF velocities, shape (n_sat, n_times, 3), in km/s.

Return type:

tuple[Array, Array]

Note

The TEME → GCRF rotation uses the input Julian dates as UT1 (UTC is an approximation accurate to < 1 s). For sub-arcsecond frame accuracy call utc_to_ut1() first and pass the UT1 dates.

Batch GCRF Convenience Functions

These functions propagate one or more satellites to an array of UTC Julian dates and return positions and velocities in the GCRF frame. Choose the variant that matches the orbit type of your satellite batch for best performance:

sgp4jax.gcrf_positions(satrec, times_jd)

Propagate a single satellite to multiple UTC Julian dates.

Parameters:
Returns:

Positions in GCRF frame, shape (n_times, 3) in km. v_gcrf: Velocities in GCRF frame, shape (n_times, 3) in km/s.

Return type:

tuple[Array, Array]

sgp4jax.gcrf_positions_multi(satrec, times_jd)

Propagate multiple satellites to multiple UTC Julian dates.

Parameters:
Returns:

Positions in GCRF, shape (n_sat, n_times, 3) in km. v_gcrf: Velocities in GCRF, shape (n_sat, n_times, 3) in km/s.

Return type:

tuple[Array, Array]

sgp4jax.gcrf_positions_multi_leo(satrec, times_jd)

Propagate a near-earth (LEO) satellite batch to multiple UTC Julian dates in GCRF.

Use this for homogeneous batches of near-earth satellites (method=0). For heterogeneous batches, use gcrf_positions_mixed().

Parameters:
Returns:

Positions in GCRF, shape (n_sat, n_times, 3) in km. v_gcrf: Velocities in GCRF, shape (n_sat, n_times, 3) in km/s.

Return type:

tuple[Array, Array]

sgp4jax.gcrf_positions_multi_sdp4_nr(satrec, times_jd)

Propagate a deep-space no-resonance satellite batch to multiple UTC Julian dates in GCRF.

Use this for homogeneous batches of deep-space irez=0 satellites (GPS/GLONASS/Galileo/BeiDou MEO constellations). For heterogeneous batches, use gcrf_positions_mixed().

Parameters:
Returns:

Positions in GCRF, shape (n_sat, n_times, 3) in km. v_gcrf: Velocities in GCRF, shape (n_sat, n_times, 3) in km/s.

Return type:

tuple[Array, Array]

sgp4jax.gcrf_positions_mixed(satrec_batch, times_jd)

Propagate a heterogeneous satellite batch to multiple UTC Julian dates in GCRF.

Groups satellites by type and dispatches each group to its specialized propagator (near-earth / deep-space-no-resonance / deep-space-resonant), then rotates all results to the GCRF frame. Results are reassembled in the original satellite ordering.

Note

Like propagate_mixed(), this function is not JIT-compilable as a whole.

Parameters:
Returns:

Positions in GCRF frame, shape (N, M, 3) in km. v_gcrf: Velocities in GCRF frame, shape (N, M, 3) in km/s.

Return type:

tuple[Array, Array]

Earth Orientation (IERS)

These functions manage the IERS Bulletin A table used for UTC → UT1 conversion, which is needed for accurate ITRF ↔ GCRF frame transformations.

sgp4jax.update_iers_table(cache_path=None, url=None)

Download the latest IERS finals2000A table and refresh the cache.

Fetches the file from the IERS data centre (falling back to USNO), parses the Bulletin A UT1-UTC values, writes a compact .npz cache, and immediately loads the result into the module-level interpolation table used by utc_to_ut1().

Parameters:

  • cache_path (str | Path | None) – Destination for the .npz cache (default: ~/.cache/sgp4jax/finals2000A.npz).

  • url (str | None) – Override the download URL.

Return type:

None

sgp4jax.load_iers_table(cache_path=None)

Load the IERS table from the local .npz cache.

Called automatically at module import if the default cache exists. Re-call with an explicit cache_path to load from a non-default location or to reload after update_iers_table().

Parameters:

cache_path (str | Path | None) – Path to the .npz cache file (default: ~/.cache/sgp4jax/finals2000A.npz).

Raises:

FileNotFoundError – Cache file not found. Call update_iers_table() to download it.

Return type:

None

sgp4jax.utc_to_ut1(jd_utc, fr_utc)

Convert a UTC Julian date to UT1 using the IERS finals2000A table.

Interpolates DUT1 = UT1 − UTC (seconds) from the Bulletin A column of the loaded IERS table and adjusts the fractional Julian date. Matches Skyfield’s t.dut1 values to better than 1 µs for all dates within the table’s coverage (~1972 to ~1 year ahead).

The function is JAX-traceable and works inside jax.jit and jax.vmap after the table has been loaded.

Parameters:
Returns:

UT1 Julian date, whole part (same value as jd_utc). fr_ut1: UT1 Julian date, fractional part.

Return type:

tuple[Array, Array]

Raises:

RuntimeError – IERS table not loaded — call update_iers_table() or load_iers_table() first.

Data Structures

class sgp4jax.SatRec(bstar: Array, ecco: Array, argpo: Array, inclo: Array, mo: Array, no_kozai: Array, nodeo: Array, ndot: Array, nddot: Array, j2: Array, j3: Array, j4: Array, j3oj2: Array, xke: Array, mu: Array, radiusearthkm: Array, tumin: Array, jdsatepoch: Array, jdsatepochF: Array, no_unkozai: Array, a: Array, alta: Array, altp: Array, con41: Array, cc1: Array, cc4: Array, cc5: Array, d2: Array, d3: Array, d4: Array, delmo: Array, eta: Array, argpdot: Array, omgcof: Array, sinmao: Array, t2cof: Array, t3cof: Array, t4cof: Array, t5cof: Array, x1mth2: Array, x7thm1: Array, mdot: Array, nodedot: Array, xlcof: Array, xmcof: Array, nodecf: Array, aycof: Array, gsto: Array, d2201: Array, d2211: Array, d3210: Array, d3222: Array, d4410: Array, d4422: Array, d5220: Array, d5232: Array, d5421: Array, d5433: Array, dedt: Array, del1: Array, del2: Array, del3: Array, didt: Array, dmdt: Array, dnodt: Array, domdt: Array, e3: Array, ee2: Array, peo: Array, pgho: Array, pho: Array, pinco: Array, plo: Array, se2: Array, se3: Array, sgh2: Array, sgh3: Array, sgh4: Array, sh2: Array, sh3: Array, si2: Array, si3: Array, sl2: Array, sl3: Array, sl4: Array, xfact: Array, xgh2: Array, xgh3: Array, xgh4: Array, xh2: Array, xh3: Array, xi2: Array, xi3: Array, xl2: Array, xl3: Array, xl4: Array, xlamo: Array, xli: Array, xni: Array, zmol: Array, zmos: Array, atime: Array, method: Array, isimp: Array, irez: Array)

JAX-compatible satellite record.

All fields are jnp.ndarray scalars (float64). String flags are encoded as floats:

  • method: 0.0 = near-earth, 1.0 = deep-space

  • isimp: 0.0 = full perturbations, 1.0 = simplified

  • irez: 0.0 = no resonance, 1.0 = synchronous, 2.0 = half-day

bstar: Array

Alias for field number 0

ecco: Array

Alias for field number 1

argpo: Array

Alias for field number 2

inclo: Array

Alias for field number 3

mo: Array

Alias for field number 4

no_kozai: Array

Alias for field number 5

nodeo: Array

Alias for field number 6

ndot: Array

Alias for field number 7

nddot: Array

Alias for field number 8

j2: Array

Alias for field number 9

j3: Array

Alias for field number 10

j4: Array

Alias for field number 11

j3oj2: Array

Alias for field number 12

xke: Array

Alias for field number 13

mu: Array

Alias for field number 14

radiusearthkm: Array

Alias for field number 15

tumin: Array

Alias for field number 16

jdsatepoch: Array

Alias for field number 17

jdsatepochF: Array

Alias for field number 18

no_unkozai: Array

Alias for field number 19

a: Array

Alias for field number 20

alta: Array

Alias for field number 21

altp: Array

Alias for field number 22

con41: Array

Alias for field number 23

cc1: Array

Alias for field number 24

cc4: Array

Alias for field number 25

cc5: Array

Alias for field number 26

d2: Array

Alias for field number 27

d3: Array

Alias for field number 28

d4: Array

Alias for field number 29

delmo: Array

Alias for field number 30

eta: Array

Alias for field number 31

argpdot: Array

Alias for field number 32

omgcof: Array

Alias for field number 33

sinmao: Array

Alias for field number 34

t2cof: Array

Alias for field number 35

t3cof: Array

Alias for field number 36

t4cof: Array

Alias for field number 37

t5cof: Array

Alias for field number 38

x1mth2: Array

Alias for field number 39

x7thm1: Array

Alias for field number 40

mdot: Array

Alias for field number 41

nodedot: Array

Alias for field number 42

xlcof: Array

Alias for field number 43

xmcof: Array

Alias for field number 44

nodecf: Array

Alias for field number 45

aycof: Array

Alias for field number 46

gsto: Array

Alias for field number 47

d2201: Array

Alias for field number 48

d2211: Array

Alias for field number 49

d3210: Array

Alias for field number 50

d3222: Array

Alias for field number 51

d4410: Array

Alias for field number 52

d4422: Array

Alias for field number 53

d5220: Array

Alias for field number 54

d5232: Array

Alias for field number 55

d5421: Array

Alias for field number 56

d5433: Array

Alias for field number 57

dedt: Array

Alias for field number 58

del1: Array

Alias for field number 59

del2: Array

Alias for field number 60

del3: Array

Alias for field number 61

didt: Array

Alias for field number 62

dmdt: Array

Alias for field number 63

dnodt: Array

Alias for field number 64

domdt: Array

Alias for field number 65

e3: Array

Alias for field number 66

ee2: Array

Alias for field number 67

peo: Array

Alias for field number 68

pgho: Array

Alias for field number 69

pho: Array

Alias for field number 70

pinco: Array

Alias for field number 71

plo: Array

Alias for field number 72

se2: Array

Alias for field number 73

se3: Array

Alias for field number 74

sgh2: Array

Alias for field number 75

sgh3: Array

Alias for field number 76

sgh4: Array

Alias for field number 77

sh2: Array

Alias for field number 78

sh3: Array

Alias for field number 79

si2: Array

Alias for field number 80

si3: Array

Alias for field number 81

sl2: Array

Alias for field number 82

sl3: Array

Alias for field number 83

sl4: Array

Alias for field number 84

xfact: Array

Alias for field number 85

xgh2: Array

Alias for field number 86

xgh3: Array

Alias for field number 87

xgh4: Array

Alias for field number 88

xh2: Array

Alias for field number 89

xh3: Array

Alias for field number 90

xi2: Array

Alias for field number 91

xi3: Array

Alias for field number 92

xl2: Array

Alias for field number 93

xl3: Array

Alias for field number 94

xl4: Array

Alias for field number 95

xlamo: Array

Alias for field number 96

xli: Array

Alias for field number 97

xni: Array

Alias for field number 98

zmol: Array

Alias for field number 99

zmos: Array

Alias for field number 100

atime: Array

Alias for field number 101

method: Array

Alias for field number 102

isimp: Array

Alias for field number 103

irez: Array

Alias for field number 104

sgp4jax.make_satrec(**kwargs)

Create a SatRec with defaults of 0.0 for unspecified fields.

Return type:

SatRec

Gravity Constants

class sgp4jax._constants.GravityConstants(tumin: float, mu: float, radiusearthkm: float, xke: float, j2: float, j3: float, j4: float, j3oj2: float)

Earth gravity model constants for use with SGP4.

tumin

Minutes per canonical time unit (= 1 / xke).

mu

Gravitational parameter (km³/s²).

radiusearthkm

Earth equatorial radius (km).

xke

Square root of gravitational parameter in canonical units (ER^1.5/min).

j2, j3, j4

Zonal harmonics (dimensionless).

j3oj2

Ratio j3 / j2 (precomputed for efficiency).

sgp4jax.WGS84 = (13.446851082044981, 398600.5, 6378.137, 0.07436685316871385, 0.00108262998905, -2.53215306e-06, -1.61098761e-06, -0.0023388905587420003)

Earth gravity model constants for use with SGP4.

tumin

Minutes per canonical time unit (= 1 / xke).

mu

Gravitational parameter (km³/s²).

radiusearthkm

Earth equatorial radius (km).

xke

Square root of gravitational parameter in canonical units (ER^1.5/min).

j2, j3, j4

Zonal harmonics (dimensionless).

j3oj2

Ratio j3 / j2 (precomputed for efficiency).

sgp4jax.WGS72 = (13.446839696959309, 398600.8, 6378.135, 0.07436691613317342, 0.001082616, -2.53881e-06, -1.65597e-06, -0.002345069720011528)

Earth gravity model constants for use with SGP4.

tumin

Minutes per canonical time unit (= 1 / xke).

mu

Gravitational parameter (km³/s²).

radiusearthkm

Earth equatorial radius (km).

xke

Square root of gravitational parameter in canonical units (ER^1.5/min).

j2, j3, j4

Zonal harmonics (dimensionless).

j3oj2

Ratio j3 / j2 (precomputed for efficiency).

sgp4jax.WGS72OLD = (13.446839702957643, 398600.79964, 6378.135, 0.0743669161, 0.001082616, -2.53881e-06, -1.65597e-06, -0.002345069720011528)

Earth gravity model constants for use with SGP4.

tumin

Minutes per canonical time unit (= 1 / xke).

mu

Gravitational parameter (km³/s²).

radiusearthkm

Earth equatorial radius (km).

xke

Square root of gravitational parameter in canonical units (ER^1.5/min).

j2, j3, j4

Zonal harmonics (dimensionless).

j3oj2

Ratio j3 / j2 (precomputed for efficiency).