{"author":"Brandon Rhodes","author_email":"brandon@rhodesmill.org","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Science/Research","License :: OSI Approved :: MIT License","Programming Language :: Python :: 2","Programming Language :: Python :: 2.7","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering :: Astronomy"],"description":"\nThis package compiles the official C++ code from `Revisiting Spacetrack\nReport #3`_ (AIAA 2006-6753) — specifically, the 2023 May 09 release\nfrom David Vallado’s `Fundamentals of Astrodynamics and Applications`_\nwebpage — and uses it to compute the positions of satellites in Earth\norbit. Satellite orbital elements can be loaded from either a legacy\nTLE file or from a modern OMM element set, both of which you can fetch\nfrom a site like `CelesTrak `_.\n\n.. _Revisiting Spacetrack Report #3: https://celestrak.org/publications/AIAA/2006-6753/\n\n.. _Fundamentals of Astrodynamics and Applications: https://celestrak.org/software/vallado-sw.php\n\nWhat we today call ‘SGP4’ in fact merges together what in the 1970s were\noriginally two separate satellite propagation routines, but which are\nnow selected automatically:\n\n* SGP4 — the ‘Simplified General Perturbations' model is used for\n satellites close enough to Earth that their orbit takes less than\n 225 minutes (3 hours 45 minutes) to complete.\n\n* SDP4 — the ‘Simplified Deep Space Perturbations' model is used for\n satellites farther from Earth, which take 225 minutes or longer to\n compete an orbit.\n\nIf your machine can’t install or compile the C++ code, then this package\nfalls back to using a slower pure-Python implementation of the library.\nTests make sure that its positions **agree to within 0.1 mm** with the\nstandard version of the algorithm — an error far less than the\n1–3 km/day by which satellites themselves deviate from the ideal orbits\ndescribed in TLE files.\n\nAn accelerated routine is available that, given a series of times and of\nsatellites, computes a whole array of output positions using a fast C++\nloop. See the “Array Acceleration” section below.\n\nNote that the SGP4 propagator returns raw *x,y,z* Cartesian coordinates\nin a “True Equator Mean Equinox” (TEME) reference frame that’s centered\non the Earth but does not rotate with it — an “Earth centered inertial”\n(ECI) reference frame. The SGP4 propagator itself does not implement\nthe math to convert these positions into more official ECI frames like\nJ2000 or the ICRS, nor into any Earth-centered Earth-fixed (ECEF) frames\nlike the ITRS, nor into latitudes and longitudes through an Earth\nellipsoid like WGS84. For conversions into these other coordinate\nframes, look for a comprehensive astronomy library, like the `Skyfield\n`_ library that is built atop this one\n(see the `section on Earth satellites\n`_ in its\ndocumentation).\n\nUsage\n-----\n\nYou will probably first want to to check whether your machine has\nsuccessfully installed the fast SGP4 C++ code, or is using the slow\nPython version (in which case this value will be false):\n\n>>> from sgp4.api import accelerated\n>>> print(accelerated)\nTrue\n\nThis library uses the same function names as the official C++ code, to\nhelp users who are already familiar with SGP4 in other languages. Here\nis how to compute the x,y,z position and velocity for the International\nSpace Station at 20:42:00 on 2019 December 9:\n\n>>> from sgp4.api import Satrec\n>>>\n>>> s = '1 25544U 98067A 19343.69339541 .00001764 00000-0 38792-4 0 9991'\n>>> t = '2 25544 51.6439 211.2001 0007417 17.6667 85.6398 15.50103472202482'\n>>> satellite = Satrec.twoline2rv(s, t)\n>>>\n>>> jd, fr = 2458826.5, 0.8625\n>>> e, r, v = satellite.sgp4(jd, fr)\n>>> e\n0\n>>> print(r) # True Equator Mean Equinox position (km)\n(-6088.92..., -936.13..., -2866.44...)\n>>> print(v) # True Equator Mean Equinox velocity (km/s)\n(-1.525..., -5.538..., 5.068...)\n\nAs input, you can provide either:\n\n* A simple floating-point Julian Date for ``jd`` and the value 0.0 for\n ``fr``, if you are happy with the precision of a 64-bit floating point\n number. Note that modern Julian Dates are greater than 2,450,000\n which means that nearly half of the precision of a 64-bit float will\n be consumed by the whole part that specifies the day. The remaining\n digits will provide a precision for the fraction of around 20.1 µs.\n This should be no problem for the accuracy of your result — satellite\n positions are usually off by a few kilometers anyway, far less than a\n satellite moves in 20.1 µs — but if you run a solver that dives down\n into the microseconds while searching for a rising or setting time,\n the solver might be bothered by the 20.1 µs plateau between each jump\n in the satellite’s position.\n\n* Or, you can provide a coarse date ``jd`` plus a very precise fraction\n ``fr`` that supplies the rest of the value. The Julian Date for which\n the satellite position is computed is the sum of the two values. One\n common practice is to provide the whole number as ``jd`` and the\n fraction as ``fr``; another is to have ``jd`` carry the fraction 0.5\n since UTC midnight occurs halfway through each Julian Date. Either\n way, splitting the value allows a solver to run all the way down into\n the nanoseconds and still see SGP4 respond smoothly to tiny date\n adjustments with tiny changes in the resulting satellite position.\n\nHere is how to intrepret the results:\n\n* ``e`` will be a non-zero error code if the satellite position could\n not be computed for the given date. You can ``from sgp4.api import\n SGP4_ERRORS`` to access a dictionary mapping error codes to error\n messages explaining what each code means.\n\n* ``r`` measures the satellite position in **kilometers** from the\n center of the earth in the idiosyncratic True Equator Mean Equinox\n coordinate frame used by SGP4.\n\n* ``v`` velocity is the rate at which the position is changing,\n expressed in **kilometers per second**.\n\nIf your application does not natively handle Julian dates, you can\ncompute ``jd`` and ``fr`` from calendar dates using ``jday()``.\n\n>>> from sgp4.api import jday\n>>> jd, fr = jday(2019, 12, 9, 20, 42, 0)\n>>> jd\n2458826.5\n>>> fr\n0.8625\n\nDouble-checking your TLE lines\n------------------------------\n\nBecause TLE is an old punch-card fixed-width format, it’s very sensitive\nto whether exactly the right number of spaces are positioned in exactly\nthe right columns. If you suspect that your satellite elements aren’t\ngetting loaded correctly, try calling the slow pure-Python version of\n``twoline2rv()``, which performs extra checks that the fast C++ doesn’t:\n\n>>> from sgp4.earth_gravity import wgs72\n>>> from sgp4.io import twoline2rv\n>>> assert twoline2rv(s, t, wgs72)\n\nAny TLE formatting errors will be raised as a ``ValueError``.\n\nUsing OMM elements instead of TLE\n---------------------------------\n\nThe industry is migrating away from the original TLE format, because it\nwill soon run out of satellite numbers.\n\n* Some TLE files now use a new “Alpha-5” convention that expands the\n range of satellite numbers by using an initial letter; for example,\n “E8493” means satellite 148493. This library supports the Alpha-5\n convention and should return the correct integer in Python.\n\n* Some authorities are now distributing satellite elements in an “OMM”\n Orbit Mean Elements Message format that replaces the TLE format. You\n can learn about OMM in Dr. T.S. Kelso’s `“A New Way to Obtain GP Data”\n `_ at\n the CelesTrak site.\n\nYou can already try out experimental support for OMM:\n\n>>> from sgp4 import omm\n\nReading OMM data takes two steps, because OMM supports several different\ntext formats. First, parse the input text to recover the field names\nand values that it stores; second, build a Python satellite object from\nthose field values. The fastest and most efficient format is usually\nCSV, since the column names are only given once, on the first line:\n\n>>> with open('sample_omm.csv') as f:\n... for fields in omm.parse_csv(f):\n... sat = Satrec()\n... omm.initialize(sat, fields)\n\nThe JSON format is more verbose because it repeats the field names over\nagain in every single record:\n\n>>> import json\n>>> with open('sample_omm.json') as f:\n... record_list = json.load(f)\n>>> for fields in record_list:\n... sat = Satrec()\n... omm.initialize(sat, fields)\n\nThe most verbose format is XML:\n\n>>> with open('sample_omm.xml') as f:\n... for fields in omm.parse_xml(f):\n... sat = Satrec()\n... omm.initialize(sat, fields)\n\nEither way, the satellite object should wind up properly initialized and\nready to start producing positions.\n\nIf you are interested in saving satellite parameters using the new OMM\nformat, then read the section on “Export” below.\n\nEpoch\n-----\n\nOver a given satellite’s lifetime, dozens or hundreds of different TLE\nrecords will be produced as its orbit evolves. Each TLE record\nspecifies the “epoch date” for which it is most accurate. Typically a\nTLE is only useful for a couple of weeks to either side of its epoch\ndate, beyond which its predictions become unreliable.\n\nSatellite objects natively provide their epoch as a two-digit year and\nthen a fractional number of days into the year:\n\n>>> satellite.epochyr\n19\n>>> satellite.epochdays\n343.69339541\n\nBecause Sputnik was launched in 1957, satellite element sets will never\nrefer to an earlier year, so years 57 through 99 mean 1957–1999 while 0\nthrough 56 mean 2000–2056. The TLE format will presumably be obsolete\nin 2057 and have to be upgraded to 4-digit years.\n\nTo turn the number of days and its fraction into a calendar date and\ntime, use the ``days2mdhms()`` function.\n\n>>> from sgp4.api import days2mdhms\n>>> month, day, hour, minute, second = days2mdhms(19, 343.69339541)\n>>> month\n12\n>>> day\n9\n>>> hour\n16\n>>> minute\n38\n>>> second\n29.363424\n\nThe SGP4 library also translates those two numbers into a Julian date\nand fractional Julian date, since Julian dates are more commonly used in\nastronomy.\n\n>>> satellite.jdsatepoch\n2458826.5\n>>> satellite.jdsatepochF\n0.69339541\n\nFinally, a convenience function is available in the library if you need\nthe epoch date and time as Python ``datetime``.\n\n>>> from sgp4.conveniences import sat_epoch_datetime\n>>> sat_epoch_datetime(satellite)\ndatetime.datetime(2019, 12, 9, 16, 38, 29, 363423, tzinfo=UTC)\n\nArray Acceleration\n------------------\n\nTo avoid the expense of running a Python loop when you have many dates\nand times for which you want a position, you can pass your Julian dates\nas arrays. The array routine is only faster if your machine has\nsuccessfully installed or compiled the SGP4 C++ code, so you might want\nto check first:\n\n>>> from sgp4.api import accelerated\n>>> print(accelerated)\nTrue\n\nTo call the array routine, make NumPy arrays for ``jd`` and ``fr`` that\nare the same length:\n\n>>> import numpy as np\n>>> np.set_printoptions(precision=2)\n\n>>> jd = np.array((2458826, 2458826, 2458826, 2458826))\n>>> fr = np.array((0.0001, 0.0002, 0.0003, 0.0004))\n\n>>> e, r, v = satellite.sgp4_array(jd, fr)\n\n>>> print(e)\n[0 0 0 0]\n>>> print(r)\n[[-3431.31 2620.15 -5252.97]\n [-3478.86 2575.14 -5243.87]\n [-3526.09 2529.89 -5234.28]\n [-3572.98 2484.41 -5224.19]]\n>>> print(v)\n[[-5.52 -5.19 1.02]\n [-5.49 -5.22 1.08]\n [-5.45 -5.25 1.14]\n [-5.41 -5.28 1.2 ]]\n\nTo avoid the expense of Python loops when you have many satellites and\ndates, build a ``SatrecArray`` from several individual satellites. Its\n``sgp4()`` method will expect both ``jd`` and ``fr`` to be NumPy arrays,\nso if you only have one date, be sure to provide NumPy arrays of length\none. Here is a sample computation for 2 satellites and 4 dates:\n\n>>> u = '1 20580U 90037B 19342.88042116 .00000361 00000-0 11007-4 0 9996'\n>>> w = '2 20580 28.4682 146.6676 0002639 185.9222 322.7238 15.09309432427086'\n>>> satellite2 = Satrec.twoline2rv(u, w)\n\n>>> from sgp4.api import SatrecArray\n>>> a = SatrecArray([satellite, satellite2])\n>>> e, r, v = a.sgp4(jd, fr)\n\n>>> np.set_printoptions(precision=2)\n>>> print(e)\n[[0 0 0 0]\n [0 0 0 0]]\n>>> print(r)\n[[[-3431.31 2620.15 -5252.97]\n [-3478.86 2575.14 -5243.87]\n [-3526.09 2529.89 -5234.28]\n [-3572.98 2484.41 -5224.19]]\n\n [[ 5781.85 2564. -2798.22]\n [ 5749.36 2618.59 -2814.63]\n [ 5716.35 2672.94 -2830.78]\n [ 5682.83 2727.05 -2846.68]]]\n>>> print(v)\n[[[-5.52 -5.19 1.02]\n [-5.49 -5.22 1.08]\n [-5.45 -5.25 1.14]\n [-5.41 -5.28 1.2 ]]\n\n [[-3.73 6.33 -1.91]\n [-3.79 6.3 -1.88]\n [-3.85 6.28 -1.85]\n [-3.91 6.25 -1.83]]]\n\nExport\n------\n\nIf you have a ``Satrec`` you want to share with friends or persist to a\nfile, there’s an export routine that will turn it back into a TLE:\n\n>>> from sgp4 import exporter\n>>> line1, line2 = exporter.export_tle(satellite)\n>>> line1\n'1 25544U 98067A 19343.69339541 .00001764 00000-0 38792-4 0 9991'\n>>> line2\n'2 25544 51.6439 211.2001 0007417 17.6667 85.6398 15.50103472202482'\n\nHappily, these are exactly the two TLE lines that we used to create this\nsatellite object:\n\n>>> (s == line1) and (t == line2)\nTrue\n\nAnother export routine is available that produces the fields defined by\nthe new OMM format (see the “OMM” section above):\n\n>>> from pprint import pprint\n>>> fields = exporter.export_omm(satellite, 'ISS (ZARYA)')\n>>> pprint(fields)\n{'ARG_OF_PERICENTER': 17.6667,\n 'BSTAR': 3.8792e-05,\n 'CENTER_NAME': 'EARTH',\n 'CLASSIFICATION_TYPE': 'U',\n 'ECCENTRICITY': 0.0007417,\n 'ELEMENT_SET_NO': 999,\n 'EPHEMERIS_TYPE': 0,\n 'EPOCH': '2019-12-09T16:38:29.363423',\n 'INCLINATION': 51.6439,\n 'MEAN_ANOMALY': 85.6398,\n 'MEAN_ELEMENT_THEORY': 'SGP4',\n 'MEAN_MOTION': 15.501034720000002,\n 'MEAN_MOTION_DDOT': 0.0,\n 'MEAN_MOTION_DOT': 1.764e-05,\n 'NORAD_CAT_ID': 25544,\n 'OBJECT_ID': '1998-067A',\n 'OBJECT_NAME': 'ISS (ZARYA)',\n 'RA_OF_ASC_NODE': 211.2001,\n 'REF_FRAME': 'TEME',\n 'REV_AT_EPOCH': 20248,\n 'TIME_SYSTEM': 'UTC'}\n\nGravity\n-------\n\nThe SGP4 algorithm operates atop a set of constants specifying how\nstrong the Earth’s gravity is. The most recent official paper on SGP4\n(see below) specifies that “We use WGS-72 as the default value”, so this\nPython module uses the same default. But in case you want to use either\nthe old legacy version of the WGS-72 constants, or else the non-standard\nbut more modern WGS-84 constants, the ``twoline2rv()`` constructor takes\nan optional argument:\n\n>>> from sgp4.api import WGS72OLD, WGS72, WGS84\n>>> satellite3 = Satrec.twoline2rv(s, t, WGS84)\n\nYou will in general get less accurate results if you choose WGS-84.\nEven though it reflects more recent and accurate measures of the Earth,\nsatellite TLEs across the industry are most likely generated with WGS-72\nas their basis. The positions you generate will better agree with the\nreal positions of each satellite if you use the same underlying gravity\nconstants as were used to generate the TLE.\n\nProviding your own elements\n---------------------------\n\nIf instead of parsing a TLE you want to specify orbital elements\ndirectly, you can pass them as floating point numbers to a satellite\nobject’s ``sgp4init()`` method. For example, here’s how to build the\nsame International Space Station orbit that we loaded from a TLE in the\nfirst code example above:\n\n>>> satellite2 = Satrec()\n>>> satellite2.sgp4init(\n... WGS72, # gravity model\n... 'i', # 'a' = old AFSPC mode, 'i' = improved mode\n... 25544, # satnum: Satellite number\n... 25545.69339541, # epoch: days since 1949 December 31 00:00 UT\n... 3.8792e-05, # bstar: drag coefficient (1/earth radii)\n... 0.0, # ndot: ballistic coefficient (radians/minute^2)\n... 0.0, # nddot: mean motion 2nd derivative (radians/minute^3)\n... 0.0007417, # ecco: eccentricity\n... 0.3083420829620822, # argpo: argument of perigee (radians 0..2pi)\n... 0.9013560935706996, # inclo: inclination (radians 0..pi)\n... 1.4946964807494398, # mo: mean anomaly (radians 0..2pi)\n... 0.06763602333248933, # no_kozai: mean motion (radians/minute)\n... 3.686137125541276, # nodeo: R.A. of ascending node (radians 0..2pi)\n... )\n\nYou might notice that these numbers don’t look the same as the numbers\nin the TLE above. For example, the inclination was 51.6439 in the TLE,\nbut is 0.901356 here. That’s because ``sgp4init()`` uses different\nunits than the TLE format: angles are in radians rather than degrees.\nBut this is the same orbit and will produce the same positions.\n\nIf you want to double-check that your elements are valid, you can run\nthe function ``check_satrec()``, which will raise a ``ValueError`` with\nan informative error message if any of the angles are out of bounds. If\nthe satellite is fine, it simply returns, without raising an exception:\n\n>>> from sgp4.conveniences import check_satrec\n>>> check_satrec(satellite2)\n\nNote that ``ndot`` and ``nddot`` are ignored by the SGP4 propagator, so\nyou can leave them ``0.0`` without any effect on the resulting satellite\npositions. But they do at least get saved to the satellite object, and\nwritten out if you write the parameters to a TLE or OMM file (see the\n“Export” section, above).\n\nTo compute the “epoch” argument, take the epoch’s Julian date and\nsubtract 2433281.5 days.\n\nWhile the underlying ``sgp4init()`` routine leaves the attributes\n``epochyr``, ``epochdays``, ``jdsatepoch``, and ``jdsatepochF`` unset,\nthis library goes ahead and sets them anyway for you, using the epoch\nyou provided.\n\nSee the next section for the complete list of attributes that are\navailable from the satellite record once it has been initialized.\n\nAttributes\n----------\n\nThere are several dozen ``Satrec`` attributes that expose data from the\nunderlying C++ SGP4 record. They fall into the following categories.\n\n*Identification*\n\nThese are copied directly from the TLE record but aren’t used by the\npropagation math.\n\n| ``satnum_str`` — Satellite number, as a 5-character string.\n| ``satnum`` — Satellite number, converted to an integer.\n| ``classification`` — ``'U'``, ``'C'``, or ``'S'``\n indicating the element set is Unclassified, Classified, or Secret.\n| ``ephtype`` — Integer “ephemeris type”, used internally by space\n agencies to mark element sets that are not ready for publication;\n this field should always be ``0`` in published TLEs.\n| ``elnum`` — Element set number.\n| ``revnum`` — Satellite’s revolution number at the moment of the epoch,\n presumably counting from 1 following launch.\n\n*Orbital Elements*\n\nThese are the orbital parameters, copied verbatim from the text of the\nTLE record. They describe the orbit at the moment of the TLE’s epoch\nand so remain constant even as the satellite record is used over and\nover again to propagate positions for different times.\n\n| ``epochyr`` — Epoch date: the last two digits of the year.\n| ``epochdays`` — Epoch date: the number of days into the year,\n including a decimal fraction for the UTC time of day.\n| ``ndot`` — First time derivative of the mean motion\n (loaded from the TLE, but otherwise ignored).\n| ``nddot`` — Second time derivative of the mean motion\n (loaded from the TLE, but otherwise ignored).\n| ``bstar`` — Ballistic drag coefficient B* (1/earth radii).\n| ``inclo`` — Inclination (radians 0 ≤ i < pi).\n| ``nodeo`` — Right ascension of ascending node (radians 0 ≤ Ω < 2pi).\n| ``ecco`` — Eccentricity.\n| ``argpo`` — Argument of perigee (radians 0 ≤ ω < 2pi).\n| ``mo`` — Mean anomaly (radians 0 ≤ M < 2pi).\n| ``no_kozai`` — Mean motion (radians/minute).\n| ``no`` — Alias for ``no_kozai``, for compatibility with old code.\n\nYou can also access the epoch as a Julian date:\n\n| ``jdsatepoch`` — Whole part of the epoch’s Julian date.\n| ``jdsatepochF`` — Fractional part of the epoch’s Julian date.\n\n*Computed Orbit Properties*\n\nThese are computed when the satellite is first loaded,\nas a convenience for callers who might be interested in them.\nThey aren’t used by the SGP4 propagator itself.\n\n| ``a`` — Semi-major axis (earth radii).\n| ``altp`` — Altitude of the satellite at perigee\n (earth radii, assuming a spherical Earth).\n| ``alta`` — Altitude of the satellite at apogee\n (earth radii, assuming a spherical Earth).\n| ``argpdot`` — Rate at which the argument of perigee is changing\n (radians/minute).\n| ``gsto`` — Greenwich Sidereal Time at the satellite’s epoch (radians).\n| ``mdot`` — Rate at which the mean anomaly is changing (radians/minute)\n| ``nodedot`` — Rate at which the right ascension of the ascending node\n is changing (radians/minute).\n\n*Propagator Mode*\n\n| ``operationmode`` — A single character that directs SGP4\n to either operate in its modern ``'i'`` improved mode\n or in its legacy ``'a'`` AFSPC mode.\n| ``method`` — A single character, chosen automatically\n when the orbital elements were loaded, that indicates whether SGP4\n has chosen to use its built-in ``'n'`` Near Earth\n or ``'d'`` Deep Space mode for this satellite.\n\n*Result of Most Recent Propagation*\n\n| ``t`` —\n The time you gave when you most recently asked SGP4\n to compute this satellite’s position,\n measured in minutes before (negative) or after (positive)\n the satellite’s epoch.\n| ``error`` —\n Error code produced by the most recent SGP4 propagation\n you performed with this element set.\n\nThe possible ``error`` codes are:\n\n0. No error.\n1. Mean eccentricity is outside the range 0 ≤ e < 1.\n2. Mean motion has fallen below zero.\n3. Perturbed eccentricity is outside the range 0 ≤ e ≤ 1.\n4. Length of the orbit’s semi-latus rectum has fallen below zero.\n5. (No longer used.)\n6. Orbit has decayed: the computed position is underground.\n (The position is still returned, in case the vector is helpful\n to software that might be searching for the moment of re-entry.)\n\n*Mean Elements From Most Recent Propagation*\n\nEach time the SGP4 routine generates a satellite position, it also saves\na set of “singly averaged mean elements” that describe shape of the\nsatellite's orbit at that moment. They are averaged with respect to the\nmean anomaly and include the effects of secular gravity, atmospheric\ndrag, and — in Deep Space mode — of those pertubations from the Sun and\nMoon that SGP4 averages over an entire revolution of each of those\nbodies. They omit both the shorter-term and longer-term periodic\npertubations from the Sun and Moon that SGP4 applies right before\ncomputing each position.\n\n| ``am`` — Average semi-major axis (earth radii).\n| ``em`` — Average eccentricity.\n| ``im`` — Average inclination (radians).\n| ``Om`` — Average right ascension of ascending node (radians).\n| ``om`` — Average argument of perigee (radians).\n| ``mm`` — Average mean anomaly (radians).\n| ``nm`` — Average mean motion (radians/minute).\n\n*Gravity Model Parameters*\n\nWhen the satellite record is initialized, your choice of gravity model\nresults in a slate of eight constants being copied in:\n\n| ``tumin`` — Minutes in one “time unit”.\n| ``xke`` — The reciprocal of ``tumin``.\n| ``mu`` — Earth’s gravitational parameter (km³/s²).\n| ``radiusearthkm`` — Radius of the earth (km).\n| ``j2``, ``j3``, ``j4`` — Un-normalized zonal harmonic values J₂, J₃, and J₄.\n| ``j3oj2`` — The ratio J₃/J₂.\n\nPrinting satellite attributes\n-----------------------------\n\nIf you want to print out a satellite, this library provides a convenient\n“attribute dump” routine that takes a satellite and generates lines that\nlist its attributes::\n\n from sys import stdout\n from sgp4.conveniences import dump_satrec\n\n stdout.writelines(dump_satrec(satellite))\n\nIf you want to compare two satellites, then simply pass a second\nargument; the second satellite’s attributes will be printed in a second\ncolumn next to those of the first. ::\n\n stdout.writelines(dump_satrec(satellite, satellite2))\n\nValidation against the official algorithm\n-----------------------------------------\n\nThis implementation passes all of the automated tests in the August 2010\nrelease of the reference implementation of SGP4 by Vallado et al., who\noriginally published their revision of SGP4 in 2006:\n\n Vallado, David A., Paul Crawford, Richard Hujsak, and T.S. Kelso,\n “Revisiting Spacetrack Report #3,” presented at the AIAA/AAS\n Astrodynamics Specialist Conference, Keystone, CO, 2006 August\n 21–24.\n\nIf you would like to review the paper, it is `available online\n`_. You can\nalways download the latest version of their code for comparison against\nthis Python module (or other implementations) at `AIAA-2006-6753.zip\n`_.\n\nFor developers\n--------------\n\nDevelopers can check out this full project from GitHub:\n\nhttps://github.com/brandon-rhodes/python-sgp4\n\nTo run its unit tests, install Python 2, Python 3, and the ``tox``\ntesting tool. The tests runing in Python 2 will exercise the fallback\npure-Python version of the routines, while Python 3 exercises the fast\nnew C++ accelerated code::\n\n cd python-sgp4\n tox\n\nLegacy API\n----------\n\nBefore this library pivoted to wrapping Vallado's official C++ code and\nwas operating in pure Python only, it had a slightly quirkier API, which\nis still supported for compatibility with older clients. You can learn\nabout it by reading the documentation from version 1.4 or earlier:\n\nhttps://pypi.org/project/sgp4/1.4/\n\nChangelog\n---------\n\n2024-02-15 — 2.24\n\n* The documentation now specifies the acceptable range for orbital\n element angles like inclination and mean anomaly, and a new function\n ``check_satrec(sat)`` will tell the caller if any of the angles are\n out of bounds.\n\n* The documentation now gives an example of loading elements from JSON.\n\n* Tweaked the fallback Python code to accept TLE lines without a final\n checksum character in the 69th column, to match the C++ code.\n\n2023-10-01 — 2.23\n\n* Tweaked tests to resolve breakage introduced by Python 3.12.\n\n2023-04-27 — 2.22\n\n* Added a ``satnum_str`` attribute, exposing the fact that the C++ now\n stores the satellite number as a string; and check that ``satnum`` is\n never greater than 339999.\n\n* Fixed the units of the ``nddot`` attribute when the value is loaded\n from an OMM record. (Since the TLE computation itself ignores this\n attribute, this did not affect any satellite positions.)\n\n* Enhanced the fallback Python version of ``twoline2rv()`` to verify\n that TLE lines are ASCII, and added documentation using it to\n double-check TLEs that might suffer from non-ASCII characters.\n\n* If the user doesn’t set a satellite’s ``classification``, it now\n defaults to ``'U'`` for ‘unclassified’.\n\n2022-04-06 — 2.21\n\n* Added ``dump_satrec()`` to the ``sgp4.conveniences`` module.\n\n* Fixed the ``Satrec`` attribute ``.error``, which was previously\n building a nonsense integer from the wrong data in memory.\n\n* Removed ``.whichconst`` from Python ``Satrec``, to help users avoid\n writing code that will break when the C++ extension is available.\n\n2021-07-01 — 2.20\n\n* Taught ``sgp4init()`` to round both ``epochdays`` and ``jdsatepochF``\n to the same 8 decimal places used for the date fraction in a TLE, if\n the user-supplied ``epoch`` itself has 8 or fewer digits behind the\n decimal point. This should make it easier to build satellites that\n round-trip to TLE format with perfect accuracy.\n\n* Fixed how ``export_tle()`` formats the BSTAR field when its value, if\n written in scientific notation, has a positive exponent.\n\n* Fixed the ``epochyr`` assigned by ``sgp4init()`` so years before 2000\n have two digits instead of three (for example, so that 1980 produces\n an ``epochyr`` of 80 instead of 980).\n\n2021-04-22 — 2.19\n\n* Extended the documentation on the Python Package Index and in the\n module docstring so it lists every ``Satrec`` attribute that this\n library exposes; even the more obscure ones might be useful to folks\n working to analyze satellite orbits.\n\n2021-03-08 — 2.18\n\n* If a TLE satellite number lacks the required 5 digits,\n ``twoline2rv()`` now gives the underlying C++ library a little help so\n it can still parse the classification and international designator\n correctly.\n\n* The ``Satrec`` attributes ``jdsatepoch``, ``jdsatepochF``,\n ``epochyr``, and ``epochdays`` are now writeable, so users can adjust\n their values manually — which should make up for the fact that the\n ``sgp4init()`` method can’t set them with full floating point\n precision.\n\n| 2021-02-17 — 2.17 — Fixed where in the output array the ``sgp4_array()`` method writes NaN values when an SGP4 propagation fails.\n| 2021-02-12 — 2.16 — Fixed ``days2mdhms()`` rounding to always match TLE epoch.\n| 2021-01-08 — 2.15 — Fixed parsing of the ``satnum`` TLE field in the Python fallback code, when the field has a leading space; added OMM export routine.\n| 2020-12-16 — 2.14 — New data formats: added OMM message support for both XML and CSV, and added support for the new Alpha-5 extension to TLE files.\n| 2020-10-14 — 2.13 — Enhanced ``sgp4init()`` with custom code that also sets the ``epochdays`` and ``epochyr`` satellite attributes.\n| 2020-05-28 — 2.12 — Moved the decision of whether to set the locale during ``twoline2rv()`` from import time to runtime, for users who change locales after their application is up and running.\n| 2020-05-24 — 2.11 — Fixed a regression in how dates are split into hours, minutes, and seconds that would sometimes produce a time whose second=60, crashing the pure-Python version of the library.\n| 2020-05-22 — 2.10 — Switch the locale temporarily to ``C`` during the C++ accelerated ``twoline2rv()``, since it does not protect its ``sscanf()`` calls from locales that, like German, expect comma decimal points instead of the period decimal points always used in a TLE.\n| 2020-05-21 — 2.9 — Added ``sat_epoch_datetime()``, expanded documentation around converting a satellite epoch to a date and time, and started rounding the epoch to exactly the digits provided in the TLE; and removed the ``Satrec.epoch`` attribute from Python fallback code to better match the C++ version.\n| 2020-05-07 — 2.8 — New function ``jday_datetime()`` is now available in the ``sgp4.conveniences`` module, thanks to Egemen Imre.\n| 2020-04-24 — 2.7 — New method ``sgp4init()`` (thank you, Chris Lewicki!) is available.\n| 2020-04-20 — 2.6 — New routine ``export_tle()`` (thank you, Egemen Imre!) is available. Improved how the accelerated C++ backend parses the ``intldesg`` string and the ``revnum`` integer.\n| 2020-03-22 — 2.5 — Gave the new accelerated ``twoline2rv()`` an optional argument that lets the user choose a non-standard set of gravity constants.\n| 2020-02-25 — 2.4 — Improved the ``jday()`` docstring; made the old legacy Python resilient if the day of the month is out-of-range (past the end of the month) in a TLE; and Mark Rutten fixed the C++ so it compiles on Windows!\n| 2020-02-04 — 2.3 — Removed experimental code that caused performance problems for users with Numba installed.\n| 2020-02-02 — 2.2 — A second release on Palindrome Day: fix the Satrec ``.epochyr`` attribute so it behaves the same way in Python as it does in the official C library, where it is only the last 2 digits of the year; and make ``.no`` available in the Python fallback case as well.\n| 2020-02-02 — 2.1 — Add vectorized array method to Satrec object; add ``.no`` attribute to new Satrec object to support old code that has not migrated to the new name ``.no_kozai``; gave Python wrapper classes ``__slots__`` to avoid the expense of a per-object attribute dictionary.\n| 2020-01-30 — 2.0 — Rewrite API to use genuine Vallado C++ code on those systems where it can be compiled; add accelerated vectorized array interface; make ``gstime()`` a public function; clarify format error message.\n| 2015-01-15 — 1.4 — Display detailed help when TLE input does not match format.\n| 2014-06-26 — 1.3 — Return ``(NaN,NaN,NaN)`` vectors on error and set ``.error_message``\n| 2013-11-29 — 1.2 — Made ``epochyr`` 4 digits; add ``datetime`` for ``.epoch``\n| 2012-11-22 — 1.1 — Python 3 compatibility; more documentation\n| 2012-08-27 — 1.0 — Initial release\n\n","description_content_type":null,"docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":["Author","Author-Email","Classifier","Description","Home-Page","License","Summary"],"home_page":"https://github.com/brandon-rhodes/python-sgp4","keywords":null,"license":"MIT","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"sgp4","package_url":"https://pypi.org/project/sgp4/","platform":null,"project_url":"https://pypi.org/project/sgp4/","project_urls":{"Homepage":"https://github.com/brandon-rhodes/python-sgp4"},"provides_extra":null,"release_url":"https://pypi.org/project/sgp4/2.24/","requires_dist":null,"requires_python":null,"summary":"Track Earth satellites given TLE data, using up-to-date 2020 SGP4 routines.","version":"2.24","yanked":false,"yanked_reason":null}

Package search

sgp4

project_urls

Dependencies

All package metadata

Releases