Representing Orbits with Two-Line Elements (TLEs)¶

Introduction to TLEs¶

A two-line element set (TLE) is a data format containing a set of TEME (True Equator, Mean Equinox) mean orbital elements of an Earth-orbiting object for a given point in time, called the Epoch Time.

These orbital elements are solely for use with the SGP4 propagator as the two are coupled with the underlying analytical orbit theory. [OM1]

See the TLE page in Wikipedia or Space-Track definition for more information.

An example TLE is given as:

ISS (ZARYA)
1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927
2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537

A TLE object is usually initialised from these two lines of strings:

>>> line1 = "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927"
>>> line2 = "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
>>> tle = TLE.from_tle(line1, line2, "ISS (ZARYA)")

Components of a TLE¶

A TLE contains the well-known mean classical (or Keplerian) orbital elements such as Mean Anomaly, Right Ascension of the Ascending Node or Argument of Perigee. A semimajor axis is not directly defined, but the mean motion term given in revolutions/day can be used to derive the semimajor axis in a straightforward fashion. For example, a mean motion of 14.5 revolutions/day is equivalent to an orbital period of 5958.62 seconds, or a mean motion (\(n\)) of 0.00106 radians/second. Then the usual semimajor axis (\(a\)) can be derived from \(a^3 n^2=\mu\), where \(\mu\) is equal to the Gravitational Constant (\(G\)) times the mass of the Earth (\(M\)). In this example, the semimajor axis is equal to 7079.056 km.

In addition to the usual classical orbital elements, other components of the TLE are (adapted from the Space-Track definition):

Satellite catalog number (NORAD ID): The unique string representation of the object in space, assigned by USSTRATCOM. For example, the input integer of 25544 means ISS ZARYA module
International Designator (COSPAR ID or NSSDCA ID): The unique string representation of the object in space. The field in the TLE 98067A means 1998-067A, which means the Object A belonging to the 67th launch in the year 1998.
Ballistic Coefficient: Also called the first derivative of mean motion, this is the daily rate of change in the number of revs the object completes each day, divided by 2. Units are revs/day. This is “catch all” drag term used in the Simplified General Perturbations (SGP4) USSPACECOM predictor.
Second Derivative of Mean Motion: The second derivative of mean motion is a second order drag term in the SGP4 propagator used to model terminal orbit decay. It measures the second time derivative in daily mean motion, divided by 6. Units are \(revs/day^3\).
Drag Term (BSTAR): Also called the radiation pressure coefficient, the parameter is another drag term in the SGP4 predictor. Units are \(1/earth radii\).

Initialising the TLEs¶

While a TLE can be initialised using the regular TLE constructor by specifying the large number of initial parameters, by far the most usual way is to use the TLE.from_tle() method, with the regular two line input from an external source (see Introduction to TLEs Section for an example). Some external sources to retrieve TLEs are listed in TLE Repositories Section.

Another way to initialise the TLE is by orbit type. For example, initialising a geostationary satellite TLE is as easy as defining a reference time and a target longitude:

>>> from astropy import units as u
>>> from satmad.propagation.tle import TLE
>>> tle_geo = TLE.init_geo(Time("2020-06-10T12:13:14.000"), 42 * u.deg)
>>> print(tle_GEO)
No Name
1 99999U 12345A   20162.50918981  .00000000  00000-0  00000+0 0    15
2 99999   0.0000 124.6202 0000000   0.0000   0.0000  1.00273791    04

Similarly, a circular sun-synchronous orbit at 800 km reference altitude (at Equator) and at a Local Time of the Ascending Node (LTAN) at 10:30 can be initialised simply with:

>>> from astropy import units as u
>>> from satmad.propagation.tle import TLE
>>> alt = 800 * u. km
>>> ltan = 10.5
>>> tle_sso = TLE.init_sso(Time("2020-06-10T12:13:14.000"), alt, ltan)
>>> print(tle_sso)
No Name
1 99999U 12345A   20162.50918981  .00000000  00000-0  00000+0 0    15
2 99999  98.6032  56.8119 0000000   0.0000   0.0000 14.27530325    07

Other parameters such as eccentricity, argument of perigee or mean anomaly can be optionally set to initialise with the requested values.

Checking the Orbit Properties¶

Once the TLE is initialised, it is then possible to query orbit parameters such as inclination, eccentricity or node rotation rate (to check whether the satellite is sun-synchronous):

>>> tle.sm_axis()
<Quantity 6796.50623984 km>
>>> tle.period()
<Quantity 5576.21313766 s>

The parameters have their quantities attached, so it is possible to easily convert them to more convenient units:

>>> tle.inclination.to(u.deg)
<Quantity 51.6454 deg>

Please see the example Analysis of a Repeating Sun-Synchronous Orbit_ for more information. See [OM2] for more information on Sun-Synchronous Orbits.

Common TLE Repositories¶

Space-Track: https://www.space-track.org/
Celestrak: http://celestrak.com/NORAD/elements/
Heavens Above: https://heavens-above.com

Reference/API¶

Two-Line-Elements to represent satellites in Earth orbit.

class satmad.propagation.tle.TLE(epoch, inclination, raan, eccentricity, arg_perigee, mean_anomaly, mean_motion, bstar, n_dot, n_dotdot=0.0, name='NONAME', intl_designator='12345A', sat_num=99999, classification='U', rev_nr=0, el_nr=1)¶

A two-line element set (TLE) is a data format encoding a list of TEME (True Equator, Mean Equinox) mean orbital elements of an Earth-orbiting object for a given point in time, called the Epoch Time.

These orbital elements are solely for use with the SGP4 propagator due to the analytical orbit theory used in its derivation.

See the TLE page in Wikipedia or Space-Track definition for more information.

The TLEs are usually generated by external sources and are used to propagate the orbits with the initial condition encapsulated by the TLE.

Parameters

epoch (Time) – Epoch Time corresponding to the orbital elements (nominally very near the time of true ascending node passage)
inclination (float or Quantity) – TEME mean inclination of the orbit [rad]
raan (float or Quantity) – TEME mean right ascension of ascending node (RAAN) of the orbit [rad]
eccentricity (float or Quantity) – mean eccentricity of the orbit [dimensionless]
arg_perigee (float or Quantity) – TEME mean argument of perigee [rad]
mean_anomaly (float or Quantity) – mean anomaly of the orbit [rad]
mean_motion (float or Quantity) – mean motion of the orbit [rad/sec]
bstar (float or Quantity) – sgp4 type drag coefficient [1 / earth radius] (see TLE class documentation)
n_dot (float or Quantity) – First time derivative of the mean motion or Ballistic Coefficient [revs/day] (see TLE class documentation)
n_dotdot (float or Quantity) – Second time derivative of the mean motion (see TLE class documentation)
name (str) – Common name of the satellite
intl_designator (str) – international designator on card 1 (up to 8 characters) (see class definition)
sat_num (int) – satellite catalog number (see TLE class documentation)
classification (str) – Classification (U for Unclassified, C for Classified, S for Secret)
rev_nr (int) – Revolution number of the object at Epoch Time [revolutions]
el_nr (int) – Element set number. Incremented when a new TLE is generated for this object.

property arg_perigee¶

Gets and sets the TEME mean argument of perigee [rad].

Argument of perigee should be in range 0 <= argp < 2*PI. Raises a ValueError otherwise.

property argp_rotation_rate¶

Argument of Perigee (or eccentricity vector) rotation rate due to J2.

Note that, WGS72 constants for J2 and Earth Radius (R_E) are used in the computation for consistency with the orbital elements definition.

Returns: Arg of Perigee rotation rate (deg/day)
Return type: Quantity

property bstar¶: Returns the sgp4 type drag coefficient [1 / earth radius].

property classification¶

Gets or sets the classification of the satellite.

Classification type can only be U, C or S. Raises a ValueError otherwise.

property eccentricity¶

Gets and sets the mean eccentricity of the orbit.

Input can be a Quantity (dimensionless) or float. Getter value is a float.

Eccentricity should be in range 0 <= e < 1.0. Raises a ValueError otherwise.

property el_nr¶

Gets and sets the Element set number.

Incremented when a new TLE is generated for this object.

Element set number should be in range 0 <= el_nr < 10000. Raises a ValueError otherwise.

property epoch¶: Returns the epoch time associated with the orbital parameters.

export_tle()¶

Exports the TLE to line1 and line2.

A sample output looks like this:

line1 = "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927"
line2 = "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"

Returns: line1, line2 – strings containing line 1, line 2
Return type: (str, str)

classmethod from_tle(line1, line2, name='No Name')¶

Initialises the TLE from two strings.

Parameters

line1 (str) – First line of the TLE
line2 (str) – Second line of the TLE
name (str) – Name of the object / satellite

Returns

TLE object initialised with the two line input.

Return type

TLE

property inclination¶

Gets and sets the TEME mean inclination of the orbit [rad].

Inclination should be in range 0 <= om < PI. Raises a ValueError otherwise.

classmethod init_geo(epoch, longitude, name='No Name', intl_designator='12345A', sat_num=99999, classification='U', rev_nr=0, el_nr=1)¶

Initialises a geostationary satellite TLE.

Due to the nature of the Earth’s geopotential, the orbit may drift off by some degrees within weeks.

Parameters

epoch (Time) – Epoch Time corresponding to the orbital elements (nominally very near the time of true ascending node passage)
longitude (float or Quantity) – initial longitude of the satellite
name (str) – Common name of the satellite
intl_designator (str) – international designator on card 1 (up to 8 characters) (see class definition)
sat_num (int) – satellite catalog number (see TLE class documentation)
classification (str) – Classification (U for Unclassified, C for Classified, S for Secret)
rev_nr (int) – Revolution number of the object at Epoch Time [revolutions]
el_nr (int) – Element set number. Incremented when a new TLE is generated for this object.

Returns

TLE object initialised with the required GEO parameters.

Return type

TLE

classmethod init_sso(epoch, altitude, ltan, eccentricity=1e-09, arg_perigee=<Quantity 0. deg>, mean_anomaly=<Quantity 0. deg>, earth_radius=<Quantity 6378137. m>, bstar=0, name='No Name', intl_designator='12345A', sat_num=99999, classification='U', rev_nr=0, el_nr=1)¶

Initialises a sun-synchronous Earth orbit TLE.

Sets the inclination in accordance with the target node rotation rate that satisfies sun-synchronous conditions up to J2. Sets the RAAN in accordance with the requested Local Time of the Ascending Node (LTAN).

Target node rotation rate is 360 deg / 365.2421897 days (See Fundamentals of Astrodynamics Vallado 4th ed pg. 863)

Parameters

epoch (Time) – Epoch Time corresponding to the orbital elements (nominally very near the time of true ascending node passage)
altitude (float or Quantity) – altitude above earth_radius around Equator [km]
ltan (float or Quantity) – Local Time of the Ascending Node defined as [0, 24) or a hour angle
earth_radius (float or Quantity) – Earth radius at equator - defines the semimajor axis together with the altitude parameter [km]
eccentricity (float) – mean eccentricity of the orbit [dimensionless]
arg_perigee (float or Quantity) – TEME mean argument of perigee [rad]
mean_anomaly (float or Quantity) – mean anomaly of the orbit [rad]
bstar (float or Quantity) – sgp4 type drag coefficient [1 / earth radius] (see TLE class documentation)
name (str) – Common name of the satellite
intl_designator (str) – international designator on card 1 (up to 8 characters) (see class definition)
sat_num (int) – satellite catalog number (see TLE class documentation)
classification (str) – Classification (U for Unclassified, C for Classified, S for Secret)
rev_nr (int) – Revolution number of the object at Epoch Time [revolutions]
el_nr (int) – Element set number. Incremented when a new TLE is generated for this object.

Returns

TLE object initialised with the required SSO parameters.

Return type

TLE

property intl_designator¶

Gets or sets the international designator of the satellite.

International Designator can only be between 0 and 100000 (exclusive at both ends). Raises a ValueError otherwise.

property mean_anomaly¶

Gets and sets the mean anomaly of the orbit [rad].

Mean Anomaly should be in range 0 <= m_anom < 2*PI. Raises a ValueError otherwise.

property mean_motion¶

Gets and sets the mean motion of the orbit [rad/sec].

Setter input can be in float [rad/sec] or Quantity. Getter output is in Quantity.

Mean Motion in revs/day should be in range 0 < n <= 17.0. Raises a ValueError otherwise.

property n_dot¶

Gets and sets the first time derivative of the mean motion or Ballistic Coefficient [revs/day].

Absolute value of the first time derivative of the mean motion can only be less than 1.0 (exclusive). Raises a ValueError otherwise.

property n_dotdot¶: Returns the Second time derivative of the mean motion.

property name¶

Gets and sets the common name of the satellite.

Satellite name cannot be None or empty, “NO NAME” is then assigned automatically.

property node_rotation_rate¶

Node (or orbital plane) rotation rate due to J2.

Note that, WGS72 constants for J2 and Earth Radius (R_E) are used in the computation for consistency with the orbital elements definition.

Returns: Node rotation rate (deg/day)
Return type: Quantity

property period¶: Computes the satellite period [sec].

property raan¶

Gets and sets the TEME mean right ascension of ascending node (RAAN) of the orbit [rad].

RAAN should be in range 0 <= om < 2*PI. Raises a ValueError otherwise.

property rev_nr¶

Gets or sets the Revolution Number of the object at Epoch Time [revolutions].

Revolution Number can only be between 0 and 100000 (exclusive at both ends). Raises a ValueError otherwise.

property sat_number¶: Returns the satellite catalog number.

property satrec¶: Returns the underlying Satrec object. This is for internal use only, for use with the SGP4 propagator.

property sm_axis¶

Computes the semimajor axis [km].

Note that the \(mu\) value used in the computation of the semimajor axis is that of WGS72 for consistency with the orbital elements definition.