SSAPy - Space Situational Awareness for Python

ci_badge container_badge docs_badge codecov_badge

SSAPy is a fast, flexible, high-fidelity orbital modeling and analysis tool for orbits spanning from low-Earth orbit into the cislunar regime, and includes the following:

  • Ability to define satellite parameters (area, mass, radiation and drag coefficients, etc.)

  • Support for multiple data types (e.g., read in orbit from TLE file, define a set of Keplerian, Equinoctial, or Kozai Mean Keplerian elements, etc.)

  • Define a fully customizable analytic force propagation model including the following:

    • Earth gravity models (WGS84, EGM84, EGM96, EGM2008)

    • Lunar gravity model (point source & harmonic)

    • Radiation pressure (Earth & solar)

    • Forces for all planets out to Neptune

    • Atmospheric drag models

    • Maneuvering (takes a user defined burn profile)

  • Various community used integrators: SGP4, Runge-Kutta (4, 8, and 7/8), SciPy, Keplerian, Taylor Series

  • User definable timesteps with the ability to return various parameters for any orbit and at any desired timestep (e.g., magnitude, state vector, TLE, Keplerian elements, periapsis, apoapsis, specific angular momentum, and many more.)

  • Ground and space-based observer models

  • Location and time of various lighting conditions of interest

  • Multiple-hypothesis tracking (MHT) UCT linker

  • Vectorized computations (use of array broadcasting for fast computation, easily parallelizable and deployable on HPC machines)

  • Short arc probabilistic orbit determination methods

  • Conjunction probability estimation

  • Built-in uncertainty quantification

  • Support for Monte Carlo runs and data fusion

  • Support for multiple coordinate frames and coordinate frame conversions (GCRF, IERS, GCRS Cartesian, TEME Cartesian, ra/dec, NTW, zenith/azimuth, apparent positions, orthoginal tangent plane, and many more.)

  • Various plotting capabilities (ground tracks, 3D orbit plotting, cislunar trajectory visualization, etc.)

  • User definable timesteps and orbit information retrieval times, in which the user can query parameters of interest for that orbit and time.

Installation

For installation details, see the Installing SSAPy section of the documentation.

Strict dependencies

The following are installed automatically when you install SSAPy:

  • numpy;

  • scipy for many statistical functions;

  • astropy for astronomy related functions;

  • pyerfa a Python wrapper for the ERFA library;

  • emcee an affine-invariant ensemble sampler for Markov chain Monte Carlo;

  • lmfit a package for non-linear least-squares minimization and curve fitting;

  • sgp4 contains functions to compute the positions of satellites in Earth orbit;

  • matplotlib as a plotting backend;

  • and other utility packages, as enumerated in setup.py.

Documentation

All documentation is hosted at https://LLNL.github.io/SSAPy/.

The API documentation may also be seen by doing:

python3
>>> import ssapy
>>> help(ssapy)

Contributing

Contributing to SSAPy is relatively easy. Just send us a pull request. When you send your request, make main the destination branch on the SSAPy repository.

Your PR must pass SSAPy’s unit tests and documentation tests, and must be PEP 8 compliant. We enforce these guidelines with our CI process. To run these tests locally, and for helpful tips on git, see our Contribution Guide.

SSAPy’s main branch has the latest contributions. Pull requests should target main, and users who want the latest package versions, features, etc. can use main.

Releases

For multi-user site deployments or other use cases that need very stable software installations, we recommend using SSAPy’s stable releases.

Each SSAPy release series also has a corresponding branch, e.g. releases/v0.14 has 0.14.x versions of SSAPy, and releases/v0.13 has 0.13.x versions. We backport important bug fixes to these branches but we do not advance the package versions or make other changes that would change the way SSAPy concretizes dependencies within a release branch. So, you can base your SSAPy deployment on a release branch and git pull to get fixes, without the package churn that comes with main.

The latest release is always available with the releases/latest tag.

See the docs on releases for more details.

Code of Conduct

Please note that SSAPy has a Code of Conduct. By participating in the SSAPy community, you agree to abide by its rules.

Authors

SSAPy was developed with support from Lawrence Livermore National Laboratory’s (LLNL) Laboratory Directed Research and Development (LDRD) Program under projects 19-SI-004 and 22-ERD-054, by the following individuals (in alphabetical order):

Many thanks go to SSAPy’s other contributors.

Citing SSAPy

On GitHub, you can copy this citation in APA or BibTeX format via the “Cite this repository” button. If you prefer MLA or Chicago style citations, see the comments in CITATION.cff.

You may also cite the following publications (click here for list of BibTeX citations):

  • Yeager, T., Pruett, K., & Schneider, M. (2022). Unaided Dynamical Orbit Stability in the Cislunar Regime. [Poster presentation]. Cislunar Security Conference, USA.

  • Yeager, T., Pruett, K., & Schneider, M. (2023). Long-term N-body Stability in Cislunar Space. [Poster presentation]. Advanced Maui Optical and Space Surveillance (AMOS) Technologies Conference, USA.

  • Yeager, T., Pruett, K., & Schneider, M. (2023, September). Long-term N-body Stability in Cislunar Space. In S. Ryan (Ed.), Proceedings of the Advanced Maui Optical and Space Surveillance (AMOS) Technologies Conference (p. 208). Retrieved from https://amostech.com/TechnicalPapers/2023/Poster/Yeager.pdf

License

SSAPy is distributed under the terms of the MIT license. All new contributions must be made under the MIT license.

See Link to license and NOTICE for details.

SPDX-License-Identifier: MIT

LLNL-CODE-862420

Basics

API DOCS

Indices and tables