Two-Line Element Sets and SGP-4

class satkit.TLE

Two-Line Element Set (TLE) representing a satellite ephemeris

Stucture representing a Two-Line Element Set (TLE), a satellite ephemeris format from the 1970s that is still somehow in use today and can be used to calculate satellite position and velcocity in the “TEME” frame (not-quite GCRF) using the “Simplified General Perturbations-4” (SGP-4) mathemematical model that is also included in this package.

For details, see: https://en.wikipedia.org/wiki/Two-line_element_set

The TLE format is still commonly used to represent satellite ephemerides, and satellite ephemerides catalogs in this format are publicly availalble at www.space-track.org (registration required)

TLEs sometimes have a “line 0” that includes the name of the satellite

property arg_of_perigee: float

Argument of Perigee, in degrees

property bstar: float

Drag of the satellite

should be rho0 * Cd * A / 2 / m

Units (which are strange) is multiples of 1 / Earth radius

property eccen: float

Satellite eccentricity, in range [0,1]

property epoch: time

TLE epoch

static fit_from_states(states: list[numpy.ndarray], times: list[time] | list[datetime.datetime], epoch: time | datetime.datetime) → tuple[TLE, dict]

Perform non-linear least squares fit of TLE parameters to a list of GCRF states

Parameters:

  • states (list[np.ndarray]) – List of GCRF states to fit to. Each state is a 6-element vector. The first 3

  • second (values are positions in meters. The last 3 values are velocities in meters /)

  • times (list[time] | list[datetime.datetime]) – List of times corresponding to the states

  • epoch (time|datetime.datetime) – Epoch time for the TLE. Must be within range of times

Returns:

Fitted TLE and fitting results in a dictionary

Return type:

tuple[TLE, dict]

Notes

  • SGP4 propagator is used to match TLE to the states

  • Input GCRF states are rotated into TEME frame used by SGP4

  • First and second derivatives of mean motion are ignored, as they are not used by SGP4

  • Non-linear Levenberg-Marquardt optimization is performed to fit the TLE parameters to the provided states.

TLE parameters used in fit include:

  • Inclination

  • Eccentricity

  • Right Ascension of Ascending Node

  • Argument of Perigee

  • Mean Anomaly

  • Mean motion

  • Drag (bstar)

  • Rust crate “rmpfit” is used to perform the optimization (https://crates.io/crates/rmpfit)

  • Results dictionary includes the following keys:

    • success : “mpsuccess” value describing result of minimization

    • best_norm: Final chi-squared value

    • orig_norm: Initial chi-squared value

    • n_iter: Number of iterations performed

    • n_fev: Number of function evaluations performed

    • n_par: Total number of parameters being optimized

    • n_free: Number of free parameters

    • n_pegged: Number of pegged parameters

    • n_func: Number of residuals

    • resid: Final residuals

    • xerror: Final parameter uncertanties (1-sigma)

    • covar: Final parameter covariance matrix

static from_file(filename: str) → list[TLE] | TLE

Load TLEs from input text file Return a list of TLES loaded from input text file.

If the file contains lines only represent a single TLE, the TLE will be output, rather than a list with a single TLE element

Parameters:

filename (str) – name of textfile lines for TLE(s) to load

Returns:

a list of TLE objects or a single TLE of lines for only 1 are passed in

Return type:

list[TLE] | TLE

static from_lines(lines: list[str]) → list[TLE] | TLE

Return a list of TLES loaded from input list of lines

If the file contains lines only represent a single TLE, the TLE will be output, rather than a list with a single TLE element

Parameters:

lines (list[str]) – list of strings with lines for TLE(s) to load

Returns:

a list of TLE objects or a single TLE of lines for only 1 are passed in

Return type:

list[TLE] | TLE

property inclination: float

Inclination, in degrees

property mean_anomaly: float

Mean anomaly in degrees

property mean_motion: float

Mean motion in revs / day

property mean_motion_dot: float

1/2 of first derivative of mean motion, in revs/day^2

Note

the “1/2” is because that is how number is stored in the TLE

property mean_motion_dot_dot: float

1/6 of 2nd derivative of mean motion, in revs/day^3

Note

The “1/6” is because that is how number is stored in the TLE

property name: str

The name of the satellite

property raan: float

Right Ascension of Ascending Node, in degrees

property satnum: int

Satellite number, or equivalently the NORAD ID

to_2line() → list[str]

Output as 2 canonical TLE Lines

Returns:

2 canonical TLE Lines

Return type:

list[str]

to_3line() → list[str]

Output as 2 canonical TLE lines preceded by a name line (3-line element set)

Returns:

3-line element set, name line then 2 canonical TLE lines

Return type:

list[str]

class satkit.sgp4_opsmode

Ops Mode for SGP4 Propagation

afspc() → int

afspc (Air Force Space Command), the default

property improved: int

Improved

class satkit.sgp4_gravconst

Gravity constant to use for SGP4 propagation

wgs72() → sgp4_gravconst

WGS-72

wgs72old() → sgp4_gravconst

WGS-72 Old

wgs84() → sgp4_gravconst

WGS-84

satkit.sgp4(tle: TLE | list[TLE] | dict, tm: time | list[time] | numpy.typing.ArrayLike, **kwargs) → tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

SGP-4 propagator for TLE

Note

Run Simplified General Perturbations (SGP)-4 propagator on Two-Line Element Set to output satellite position and velocity at given time in the “TEME” coordinate system

A detailed description is at: https://celestrak.org/publications/AIAA/2008-6770/AIAA-2008-6770.pdf

Parameters:

  • tle (TLE | list[TLE] | dict) – TLE or OMM (or list of TLES) on which to operate

  • tm (time | list[time] | npt.ArrayLike[time]) – time(s) at which to compute position and velocity

Keyword Arguments:

  • gravconst (satkit.sgp4_gravconst) – gravity constant to use. Default is gravconst.wgs72

  • opsmode (satkit.sgp4_opsmode) – opsmode.afspc (Air Force Space Command) or opsmode.improved. Default is opsmode.afspc

  • errflag (bool) – whether or not to output error conditions for each TLE and time output. Default is False (this is likely rarely needed, but can be useful for debugging) (this may also flag a typing error … I can’t figure out how to get rid of it)

Returns:

position and velocity in meters and meters/second, respectively, in the TEME frame at each of the “Ntime” input times and each of the “Ntle” tles

Additional return value if errflag is True: list[sgp4_error]: list of errors for each TLE and time output, if errflag is True

Return type:

tuple[npt.ArrayLike[np.float64], npt.ArrayLike[np.float64]]

Note

Now supports propagation of OMM (Orbital Mean-Element Message) dictionaries The dictionaries must follow the structure used by https://www.celestrak.org or https://www.space-track.org.

Example

>>> lines = [
>>>        "0 INTELSAT 902",
>>>     "1 26900U 01039A   06106.74503247  .00000045  00000-0  10000-3 0  8290",
>>>     "2 26900   0.0164 266.5378 0003319  86.1794 182.2590  1.00273847 16981"
>>> ]
>>>
>>> tle = satkit.TLE.single_from_lines(lines)
>>>
>>> # Compute TEME position & velocity at epoch
>>> pteme, vteme = satkit.sgp4(tle, tle.epoch)
>>>
>>> # Rotate to ITRF frame
>>> q = satkit.frametransform.qteme2itrf(tm)
>>> pitrf = q * pteme
>>> vitrf = q * vteme - np.cross(np.array([0, 0, satkit.univ.omega_earth]), pitrf)
>>>
>>> # convert to ITRF coordinate object
>>> coord = satkit.itrfcoord.from_vector(pitrf)
>>>
>>> # Print ITRF coordinate object location
>>> print(coord)
ITRFCoord(lat:  -0.0363 deg, lon:  -2.2438 deg, hae: 35799.51 km)
Example 2:
>>> import requests
>>> import json
>>>
>>> # Query ephemeris for the International Space Station (ISS)
>>> url = 'https://celestrak.org/NORAD/elements/gp.php?CATNR=25544&FORMAT=json'
>>> with requests.get(url) as response:
>>>     omm = response.json()
>>> # Get a representative time from the output
>>> epoch = sk.time(omm[0]['EPOCH'])
>>> # Compute TEME position & velocity at epoch
>>> pteme, vteme = satkit.sgp4(omm[0], epoch)