Space Situational Awareness Toolkit (SSATK)

SSATK is a Python toolkit for space situational awareness (SSA) and astrodynamics. One package, import ssatk, covers the analysis chain from state vectors to figures:

• propagating orbits and six-degree-of-freedom (6-DoF) spacecraft,
• designing impulsive and continuous-thrust transfers,
• converting between inertial, Earth-fixed, lunar and satellite frames,
• modelling the space environment (Sun and Moon, eclipses, atmosphere, geomagnetic field, radiation belts),
• screening conjunctions and fitting orbits to measurements,
• reading and writing standard orbit-data formats, and
• plotting orbits, ground tracks, eclipses, sensor coverage and the magnetosphere, including an interactive WebGL satellite viewer.

python -m pip install ssatk

Contents

• Installation
• Quick start
• What SSATK covers
• Validation
• Demos
• Documentation
• Development
• Dependencies
• Citing SSATK
• License

Installation

SSATK supports Python 3.10–3.13.

python -m pip install ssatk

The install pulls four data packages automatically, about 210 MB in total: ssa-data-core, ssa-data-gravity, ssa-data-lunar and ssa-data-lunar-gravity. They hold the IERS Earth-orientation and space-weather snapshots, gravity models, planetary and lunar ephemerides, star catalogue, and Earth and Moon textures. SSATK reads them from the installed packages; only explicit download helpers (TLE catalogue updates, OMNI solar-wind records and optional demo datasets) contact the network.

One dependency compiles a C++ extension during installation (about one minute), so a C++ compiler must be available.

Optional extras:

Quick start

Propagate a 51.6° low-Earth orbit for three hours and draw its ground track:

import numpy as np
import ssatk
from ssatk.plots import orbit_plot

orbit = ssatk.Orbit.fromKeplerianElements(
    a=ssatk.EARTH_RADIUS + 420e3, e=0.0005, i=np.radians(51.6),
    pa=0.0, raan=0.0, trueAnomaly=0.0, t=1.4e9,   # t: GPS seconds
)
t = 1.4e9 + np.linspace(0.0, 3 * 3600.0, 541)
r, v = ssatk.rv(orbit, time=t)

orbit_plot(r, t, view="ground track", save_path="quickstart/ground_track.png")

Relative output paths are written under ~/ssatk_output/figures; set SSATK_OUTPUT_DIR to choose another root. Interactive versions of most figures are written as self-contained HTML.

What SSATK covers

Physical constants and the core orbit objects are available at the top level (ssatk.EARTH_MU, ssatk.constants.RGEO, ssatk.Orbit, ssatk.rv); task code imports the module it needs, for example from ssatk.orbital_mechanics import transfer_hohmann.

Validation

SSATK's test policy (docs/testing_policy.md) requires numerical tests to identify their reference and tolerance. The test reference audit distinguishes independent physical references from consistency and compatibility checks, and records remaining validation limits. Representative results:

The first five rows are reproduced by ssatk-benchmark --profile validation --quick; the rest by pytest tests.

Demos

The demos/ directory holds runnable examples in 13 categories, from getting started and orbit visualization to 6-DoF dynamics, eclipses, photometry and sensor coverage and spacecraft mesh views. Build the full gallery as an HTML report:

ssatk-demo-gallery --open

The report is written to ~/ssatk_output/documents/index.html. Use --output PATH to choose another directory, or --demos-dir PATH to run the demos from a source checkout. The selected directory contains the report and all generated assets; the adjacent ZIP can be moved or shared on its own. CI publishes this directory to GitHub Pages after checking local asset links. See the gallery hosting guide for preview and deployment instructions, validation scope, and optional-demo skips.

Documentation

The user guide, API reference, benchmarking study and 6-DoF design notes are built with Sphinx:

• Hosted: https://ssatk.readthedocs.io

• Local build:

  python -m pip install -r docs/requirements.txt
  python -m sphinx -b html -W --keep-going docs /tmp/ssatk-docs
  

Development

git clone https://github.com/LLNL/ssatk.git
cd ssatk
python -m pip install -e ".[dev,geomagnetics,atmosphere,propulsion]"
python -m pip install --no-deps -e packaging/ssapy-toolkit-compat   # tests the legacy import name
pytest tests

CI runs the tests on Python 3.10–3.13, builds the docs with warnings treated as errors, runs the demo gallery, and enforces the repository policy in CONTRIBUTING.md. Its lint gate checks fatal Ruff errors (E9,F63,F7,F82) in changed Python files.

An optional local hook maps the repository with Graphify after each commit:

python -m pip install graphifyy
bash scripts/install_graphify_hook.sh

Disable it for one commit with SSATK_GRAPHIFY_HOOK=0 git commit ....

Dependencies

NumPy, SciPy, pandas, Astropy and PyERFA, h5py, Matplotlib, Plotly, Pillow, imageio, REBOUND, llnl-ssapy (orbit objects, SGP4 and Keplerian propagation, Earth-orientation helpers), and the four ssa-data-* packages above.

Citing SSATK

Citation metadata is in CITATION.cff; GitHub's "Cite this repository" button formats it.

License

SSATK is distributed under the BSD 3-Clause license. All new contributions must be made under the same license; see LICENSE.

SPDX-License-Identifier: BSD-3-Clause

LLNL-CODE-2015996