SGP4PROP

When NORAD tracks a satellite or a piece of debris, they disseminate TLEs that describe the orbit. These TLEs were generated for use with the SGP-4 model only. Using other techniques to interact with the TLEs will likely result in large errors.

Fortunately, Air Force Space Command (AFSPC) distributes an official SGP-4 propagation program. Officially, this program is called the "Standardized Astrodynamic Algorithms (SAA) Library", but in industry it is generally referred to as SGP4PROP. You can download it here.

The package comes with more than just an executable. It also comes with source code, a validation test kit, and example drivers that you can use to guide yourself towards system integration with your other products.

First Steps

After downloading the appropriate package for your system, extract it to a local folder. The docs explicitly state that network drives and other types of storage can cause problems with how it runs.

I downloaded the 64 bit Linux packages, so my instructions and source code may vary slightly from yours if you are on Windows.

Next, read the docs. The top level folder provides 5 different versions of the README document. These documents explain what is in the package and how to use it.

Validation

Switch to the SGP4_small_V7.9_LINUX64/Verify/Execution folder. To validate the test package, all you have to do is run ./Run_Test_Cases.bat.

You should open and read ./Run_Test_Cases.bat. This is what it does:

1) It adds the SAA library to the path. For Windows, that looks like this:

SET PATH=../../Lib;%PATH%

For Linux, that looks like this:

export LD_LIBRARY_PATH=../../Lib:$LD_LIBRARY_PATH

2) It cleans up the folders around itself, deleting prior validation run outputs and making sure the Diff, TestResults, and Reports folder exists.

3) It runs the test cases using the input files in the Execution folder.

Windows:

C_Sgp4Prop  sgp4_val.inp ..\TestResults\sgp4_val  -I..\..\Lib\
C_Sgp4Prop  rel14.inp    ..\TestResults\rel14     -I..\..\Lib\

Linux:

./C_Sgp4Prop  sgp4_val.inp ../TestResults/sgp4_val   -I../../Lib/
./C_Sgp4Prop  rel14.inp    ../TestResults/rel14      -I../../Lib/

These lines are especially important because they break out the syntax of C_Sgp4Prop, which is the C Driver provided in the Examples folder.

4) It does a ton of diff / file comparison operations and stores the output in the Diff folder. The Linux command for this is simply diff, and the Windows command is fc.

Go ahead and run the script. Make sure you are running it from within that folder, the path matters and is hard coded into ./Run_Test_Cases.bat. If your run was successful, it should look something like this:

It works! Go ahead and look in the SGP4_small_V7.9_LINUX64/Verify/TestResults folder for sgp4_val_C_MeanElem.txt. You'll see more familiar Keplerian elements arranged in a table with a step size of 2700 minutes.

Finally, go look in SGP4_small_V7.9_LINUX64/Verify/Diff and make sure all the files are empty. If there is anything written there, a difference was found and your copy of the code failed validation against the baseline results.

General Usage

Based on the Run_Test_Cases.bat, it is entirely possible to use the C_Sgp4Prop executable to do your work. I placed the whole extracted package in my ~/bin/ folder, then added the following bash script there as well. Now if I ever want to interact with one of those *.inp files, I can just use my sgp4prop script to compute the data.

#! /bin/bash
# ~/bin/sgp4prop <sgp4_file.inp>
# all output will be placed on current path at ./output/sgp4_val*

# set environment variable
export LD_LIBRARY_PATH=~/bin/SGP4_small_V7.9_LINUX64/Lib 

# make the output folder if it doesn't exist
mkdir ./output 

# If it does exist, clean it out
rm ./output/sgp4_val*.txt #clean up the output folder

# run the program
LIB=~/bin/SGP4_small_V7.9_LINUX64/Lib/
~/bin/SGP4_small_V7.9_LINUX64/Verify/Execution/C_Sgp4Prop  $1 ./output/sgp4_val -I$LIB

I wouldn't recommend this, however. The step size of 2700 minutes is huge, and the process of writing to an output file just so you can read it back in is time consuming.

Fortunately, there are several driver examples provided in the Driver_Examples folder. In particular, you can look at the source code for C_Sgp4Prop at SGP4_small_V7.9_LINUX64/Driver_Examples/C/C_Sgp4Prop/C_Sgp4Prop.c. Copying this code and changing the output is fairly straightforward.

Heads-up for the Linux users out there: The Windows package has many more examples, including a more complete set of Python 2 drivers. My next project on this front is writing a Python 3 driver that makes some sense.