Project 4: SGP4 Orbit Propagator (Finding Your Place)

Implement a deterministic SGP4-based orbit propagator that reads TLEs, produces position/velocity in ECI, and validates against reference ephemerides.

Quick Reference

Attribute Value
Difficulty Level 3: Advanced
Time Estimate 1-2 weeks
Main Programming Language Python
Alternative Programming Languages C, Rust
Coolness Level Level 4: Orbit Whisperer
Business Potential Level 3: Space Ops Tooling
Prerequisites Orbital mechanics basics, numerical methods, coordinate frames
Key Topics TLE parsing, SGP4 propagation, ECI frames

1. Learning Objectives

By completing this project, you will:

  1. Parse TLEs into orbital elements with correct units.
  2. Implement SGP4 propagation with deterministic time steps.
  3. Convert outputs to ECI position and velocity vectors.
  4. Validate results against reference ephemerides.
  5. Build tooling that supports pass prediction and mission planning.

2. All Theory Needed (Per-Concept Breakdown)

Two-Line Elements (TLE) and Mean Orbital Elements

Fundamentals A TLE is a compact text format that encodes a satellite’s mean orbital elements at a specific epoch. It is not a state vector; it is a parameter set for the SGP4 model. You must parse it correctly, including implied decimal points and exponent fields. The TLE’s mean motion and drag terms define how the orbit evolves. If you misinterpret these fields, your propagated position will be wrong by kilometers. Understanding what each line represents is the first step to trustworthy orbit prediction.

Deep Dive into the concept The two-line element format is a historical artifact of early tracking systems. It compresses the orbital parameters into fixed-width columns, including checksum digits. Line 1 includes the satellite number, epoch (year and day-of-year with fractional days), and drag terms (B*). Line 2 includes inclination, right ascension of ascending node (RAAN), eccentricity (with implied decimal), argument of perigee, mean anomaly, and mean motion. These are mean elements, not osculating elements; they average out short-period perturbations. That is why you must use SGP4 to translate them into position and velocity.

Parsing details matter. The epoch uses a two-digit year; you must map it to a full year with a cutoff (e.g., 57-99 -> 1900s, 00-56 -> 2000s) as per standard practice. The eccentricity field lacks a decimal point; you must insert it at the correct place. The mean motion is in revolutions per day and must be converted to radians per minute for SGP4. The B* drag term uses a special exponent notation (e.g., 34123-4), which must be parsed into a floating point value. If you mishandle B*, you will mis-estimate drag and the orbit will drift.

TLEs also include a checksum at the end of each line. A robust parser validates the checksum and rejects corrupted lines. This is especially important if you ingest TLEs from a network or scraped source. For deterministic testing, you should store known-good TLEs and verify your parser against them.

Another subtlety is the epoch: a TLE is only valid around its epoch. Propagating too far away in time increases error. Your simulator should warn if propagation exceeds a reasonable window (e.g., 7-14 days), or at least include that in output metadata. This prevents misinterpretation of large errors as algorithmic bugs.

In summary, the TLE format is a parameterization of the orbit, not a direct state vector. If you treat it as a state vector, your results will be wrong. Your parser must be precise and must transform elements into the units SGP4 expects.

How this fit on projects This concept drives Section 3.2 parsing requirements and Section 6.2 validation tests; it feeds into P12 pass prediction and P13 mission simulation.

Definitions & key terms

  • Epoch -> Time at which the TLE elements are valid.
  • Mean motion -> Revolutions per day; related to semi-major axis.
  • B* drag -> Simplified atmospheric drag coefficient in TLE.
  • Mean anomaly -> Angle of orbiting body in its idealized ellipse.

Mental model diagram (ASCII)

TLE Lines -> Parse -> Mean Elements -> SGP4 -> State Vector

How it works (step-by-step, with invariants and failure modes)

  1. Read line 1 and line 2, validate checksum.
  2. Parse epoch and elements with correct decimal placement.
  3. Convert units into SGP4 expected units.
  4. Feed elements into propagator.

Invariants: checksum matches; eccentricity in [0,1); mean motion positive.

Failure modes: wrong epoch year, misplaced decimal, incorrect unit conversions.

Minimal concrete example

ecc = float("0." + line2[26:33].strip())
mm_rev_day = float(line2[52:63])
mm_rad_min = mm_rev_day * 2*math.pi / 1440.0

Common misconceptions

  • “TLE gives position directly” -> It only gives mean elements.
  • “Epoch is always 20xx” -> Must apply the two-digit year rule.

Check-your-understanding questions

  1. Why is mean motion given in rev/day and not rad/s?
  2. What does the B* term represent?
  3. How far from the epoch is a TLE reliable?

Check-your-understanding answers

  1. Historical tracking formats; must convert for SGP4.
  2. A simplified drag term used by SGP4.
  3. Typically days to weeks; error grows with time.

Real-world applications

  • Ground pass prediction and tracking.
  • Mission planning and collision avoidance.

Where you’ll apply it

References

  • Vallado, Fundamentals of Astrodynamics and Applications (SGP4 chapters)
  • Space Mission Engineering (orbit determination overview)

Key insights A TLE is a compact model input, not an orbit state.

Summary Correct TLE parsing is the foundation of reliable propagation.

Homework/Exercises to practice the concept

  • Decode one TLE by hand and verify each field.

Solutions to the homework/exercises

  • Use the published column definitions and verify checksum.

SGP4 Propagation and Coordinate Frames

Fundamentals SGP4 (Simplified General Perturbations 4) is the standard algorithm that turns TLE mean elements into position and velocity. It accounts for perturbations like Earth’s oblateness and atmospheric drag. The output state vector is typically in the TEME or ECI frame. To use the results for pointing or pass prediction, you must understand which frame you are in and how to convert it if necessary. Mistaking TEME for ECI yields errors that can be tens of kilometers.

Deep Dive into the concept SGP4 is a semi-analytic propagator designed for efficiency and compatibility with TLEs. It models the secular and periodic effects of Earth’s J2 oblateness, atmospheric drag (via B*), and simplified gravitational perturbations. The algorithm produces position and velocity in the True Equator Mean Equinox (TEME) frame. TEME is close to ECI but not identical; it ignores nutation corrections. Many modern systems accept TEME as a practical approximation, but you must document the frame explicitly.

Propagation starts with mean elements at epoch and advances them by a time offset (minutes since epoch). The algorithm updates the mean motion, mean anomaly, and argument of perigee based on perturbation rates. It then computes the eccentric anomaly and true anomaly to obtain the orbital plane position. Finally, it rotates the position into the inertial frame using inclination and RAAN. The output is a 3D position and velocity vector, typically in kilometers and kilometers per second.

Numerical precision matters. SGP4 has known sensitivity to time offsets and floating-point precision; using double precision is recommended. The algorithm also has regimes where it is less accurate (e.g., very low perigee orbits). You should implement sanity checks: verify that the semi-major axis is reasonable, that eccentricity stays within bounds, and that the resulting altitude is positive.

Coordinate frames can be confusing. If your downstream system expects ECI (J2000), you may need to convert from TEME. This requires accounting for Earth rotation and precession/nutation. For this project, you can output TEME and explicitly label it, or implement a simple conversion if you already have Earth rotation models. The important part is that you do not silently mix frames.

Validation is essential. Use a known TLE and compare your propagated state vector to a reference implementation (e.g., Vallado’s test cases). Accept small differences due to numerical precision, but ensure the error stays within a reasonable tolerance (e.g., < 1 km for short time offsets). For deterministic testing, use fixed time offsets and record golden vectors.

How this fit on projects This concept drives Section 3.2 propagation requirements and Section 6 validation, and it feeds into pass prediction and mission simulation.

Definitions & key terms

  • SGP4 -> Standard orbit propagation algorithm for TLEs.
  • TEME -> True Equator Mean Equinox frame (SGP4 output).
  • ECI -> Earth-Centered Inertial frame.
  • Time offset -> Minutes since epoch.

Mental model diagram (ASCII)

TLE -> Mean Elements -> SGP4 -> TEME State Vector -> (optional) ECI

How it works (step-by-step, with invariants and failure modes)

  1. Compute time since epoch in minutes.
  2. Update mean motion and anomaly with perturbation rates.
  3. Solve for eccentric anomaly and true anomaly.
  4. Compute orbital plane position and rotate into TEME.

Invariants: eccentricity remains < 1; altitude stays above Earth radius; frame is labeled.

Failure modes: time units wrong, using single precision, frame mismatch.

Minimal concrete example

state = sgp4_propagate(tle, minutes_since_epoch)
print(state.r_km, state.v_km_s)

Common misconceptions

  • “TEME is the same as ECI” -> It is close but not identical.
  • “SGP4 is exact” -> It is an approximation with known limits.

Check-your-understanding questions

  1. Why is SGP4 tied to TLEs rather than arbitrary state vectors?
  2. What frame does SGP4 output by default?
  3. Why compare against reference implementations?

Check-your-understanding answers

  1. It models mean elements and perturbations encoded in TLEs.
  2. TEME.
  3. To validate correctness and numerical stability.

Real-world applications

  • Ground station pass predictions.
  • Satellite tracking catalogs.

Where you’ll apply it

References

  • Vallado, Fundamentals of Astrodynamics and Applications
  • Space Mission Engineering (orbit propagation overview)

Key insights SGP4 is a practical, not perfect, orbit model; validation and frame labeling are non-negotiable.

Summary A correct SGP4 implementation turns a TLE into a usable inertial state.

Homework/Exercises to practice the concept

  • Propagate a TLE 10 minutes and compare to a reference output.

Solutions to the homework/exercises

  • Verify position within 1 km and velocity within 1 m/s.

3. Project Specification

3.1 What You Will Build

A command-line SGP4 propagator that reads a TLE, computes position/velocity at requested times, and outputs deterministic state vectors in TEME/ECI with validation against reference data.

3.2 Functional Requirements

  1. TLE parsing: parse lines, validate checksum, convert units.
  2. Propagation: compute position/velocity for given time offsets.
  3. Frame labeling: output state vectors with explicit frame name.
  4. Validation: compare against golden vectors and report error.

3.3 Non-Functional Requirements

  • Determinism: fixed time offsets produce identical outputs.
  • Accuracy: within tolerance of reference for short time spans.
  • Usability: CLI with --tle, --minutes, --format.

3.4 Example Usage / Output

$ python sgp4_tool.py --tle tle.txt --minutes 0,10,20
[0] r=(7022.1, -1401.2, 12.3) km v=(1.23, 7.34, 0.01) km/s

3.5 Data Formats / Schemas / Protocols

Input TLE file: two lines, fixed width with checksum digits.

Output JSON schema:

{"t_min":10,"frame":"TEME","r_km":[...],"v_km_s":[...],"error_km":0.42}

3.6 Edge Cases

  • Invalid checksum.
  • Propagation too far from epoch.
  • Near-circular or highly eccentric orbits.

3.7 Real World Outcome

A tool that produces reliable state vectors for pass prediction and mission simulation.

3.7.1 How to Run (Copy/Paste)

python sgp4_tool.py --tle samples/iss.tle --minutes 0,30,60 --format json

3.7.2 Golden Path Demo (Deterministic)

  • Use a fixed TLE and fixed time offsets.
  • Compare output to golden_state.json with tolerance.

3.7.3 Failure Demo (Deterministic)

python sgp4_tool.py --tle samples/bad_checksum.tle --minutes 0

Expected: exit code 2 and an error message CHECKSUM_FAIL.

3.7.4 If CLI: Exact Terminal Transcript

$ python sgp4_tool.py --tle samples/iss.tle --minutes 0,10
[0] r=(7022.1,-1401.2,12.3) km v=(1.23,7.34,0.01) km/s
[10] r=(6801.5,-2150.4,900.1) km v=(2.10,7.02,-0.12) km/s
ExitCode=0

4. Solution Architecture

4.1 High-Level Design

TLE Parser -> Elements -> SGP4 Propagator -> State Vector -> Output
                                     |
                                     +-> Validation vs Golden

4.2 Key Components

Component Responsibility Key Decisions
Parser Decode TLE fields Checksum validation
Propagator SGP4 algorithm Double precision
Validator Compare to reference Tolerance values
Output Format results JSON/CSV

4.3 Data Structures (No Full Code)

class TLE:
    epoch: float
    inc_rad: float
    raan_rad: float
    ecc: float
    argp_rad: float
    mean_anom_rad: float
    mean_motion_rad_min: float

4.4 Algorithm Overview

Key Algorithm: SGP4 propagation

  1. Convert TLE elements into SGP4 internal units.
  2. Update mean elements for time offset.
  3. Solve for position and velocity.
  4. Output TEME vectors.

Complexity Analysis:

  • Time: O(1) per time point.
  • Space: O(1).

5. Implementation Guide

5.1 Development Environment Setup

python -m venv .venv
source .venv/bin/activate
pip install numpy

5.2 Project Structure

project-root/
+-- sgp4_tool.py
+-- samples/
|   +-- iss.tle
|   +-- bad_checksum.tle
+-- golden_state.json
+-- README.md

5.3 The Core Question You’re Answering

“Given a TLE, where is the satellite right now?”

5.4 Concepts You Must Understand First

  1. TLE format and parsing rules.
  2. SGP4 propagation steps.
  3. Coordinate frames (TEME vs ECI).

5.5 Questions to Guide Your Design

  1. How will you validate TLE checksums?
  2. What tolerance is acceptable for validation?
  3. How will you label coordinate frames in output?

5.6 Thinking Exercise

Parse a real TLE and compute mean motion in rad/min by hand.

5.7 The Interview Questions They’ll Ask

  1. “Why can’t you use TLE elements directly as a state vector?”
  2. “What is the difference between TEME and ECI?”
  3. “How do you validate SGP4 output?”

5.8 Hints in Layers

Hint 1: Start with a parser that only extracts elements.

Hint 2: Use a known TLE and compare outputs at epoch.

Hint 3: Add checksum validation and error reporting.

Hint 4: Implement golden vector comparison for regression tests.

5.9 Books That Will Help

Topic Book Chapter
Orbital mechanics Vallado, Fundamentals of Astrodynamics SGP4 chapters
Space ops Space Mission Engineering Tracking
Numerical methods Numerical Recipes Root solving

5.10 Implementation Phases

Phase 1: TLE Parser (3-4 days)

Goals: parse fields and validate checksums. Tasks:

  1. Implement checksum logic.
  2. Parse all fields with correct units. Checkpoint: parsed elements match known values.

Phase 2: Propagator (4-6 days)

Goals: implement SGP4 algorithm. Tasks:

  1. Convert elements to internal units.
  2. Compute state vectors. Checkpoint: outputs match reference within tolerance.

Phase 3: Validation & Output (2-3 days)

Goals: output results and validate. Tasks:

  1. Add JSON/CSV output.
  2. Add golden comparison. Checkpoint: regression tests pass.

5.11 Key Implementation Decisions

Decision Options Recommendation Rationale
Output frame TEME only / TEME+ECI TEME with label Avoid silent conversion errors
Validation absolute / relative error both Capture scale variance
Time units minutes / seconds minutes Matches SGP4 standard

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit Tests TLE parsing checksum, epoch parsing
Integration Tests Propagation ISS TLE golden vector
Edge Case Tests High eccentricity near-circular orbits

6.2 Critical Test Cases

  1. Checksum failure: invalid checksum returns error.
  2. Epoch zero: propagation at epoch equals reference.
  3. 10-minute offset: error within tolerance.

6.3 Test Data

TLE: ISS (ZARYA) sample

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Wrong units Vectors off by orders Convert rev/day to rad/min
Frame confusion Wrong pass prediction Label frame explicitly
Epoch parsing error Time-shifted orbit Apply year cutoff rule

7.2 Debugging Strategies

  • Compare to Vallado reference vectors.
  • Print intermediate elements and compare to known SGP4 test cases.

7.3 Performance Traps

SGP4 is O(1); focus on accuracy, not speed.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add CLI to output ground track lat/long.

8.2 Intermediate Extensions

  • Implement TEME -> ECI conversion.

8.3 Advanced Extensions

  • Add atmospheric drag sensitivity analysis across TLE updates.

9. Real-World Connections

9.1 Industry Applications

  • Satellite catalog propagation.
  • Ground station pass planning.
  • SGP4 reference implementations by Vallado.
  • Orekit (Java) for orbit propagation.

9.3 Interview Relevance

  • Demonstrates orbital mechanics and numerical modeling.

10. Resources

10.1 Essential Reading

  • Vallado, Fundamentals of Astrodynamics and Applications.
  • Space Mission Engineering.

10.2 Video Resources

  • SGP4 tutorials (AIAA lectures).

10.3 Tools & Documentation

  • numpy for vector math.
  • matplotlib for plotting ground tracks.

11. Self-Assessment Checklist

11.1 Understanding

  • I can parse a TLE and explain each field.
  • I can explain why SGP4 outputs TEME.
  • I can validate errors against reference data.

11.2 Implementation

  • Propagation results match golden vectors.
  • Checksum validation works.
  • Output frames are explicit.

11.3 Growth

  • I can explain limitations of TLE/SGP4.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Parse TLE and output state vector at epoch.
  • Pass checksum validation tests.

Full Completion:

  • Support multiple time offsets with validation.

Excellence (Going Above & Beyond):

  • Add frame conversion and ground track visualization.