Scarabaeus
Open-source spacecraft navigation & orbit determination framework
Developed by the Orbital Research Cluster for Celestial Applications (ORCCA)
Colorado Center for Astrodynamics Research (CCAR) · University of Colorado Boulder
Overview
Scarabaeus (SCB) is a Python framework for spacecraft navigation and orbit determination (OD). It provides a unified, mission-agnostic environment for:
- Building and propagating spacecraft trajectories with multiple force models
- Simulating or ingesting radiometric and optical measurements
- Running sequential and batch OD filters (SRIF, LKF, LSB, …)
- Estimating dynamical, measurement, and consider parameters
- Performing maneuver planning and finite/impulsive burn modelling
SCB interfaces with NASA SPICE for time, frame, and kernel management and ships a compiled Rust back-end for performance-critical integrators.
Table of Contents
- Features
- Architecture
- Requirements
- Installation
- Tutorials
- Testing
- Contributing
- Citing Scarabaeus
- License
Features
Dynamics & Force Models
| Class |
Description |
PointMassGravity |
Two-body (Keplerian) gravitational acceleration |
ThreeBodyGravity |
Third-body perturbation via SPICE ephemeris |
SphericalHarmonicsGravity |
Gravity field up to arbitrary degree/order |
CannonballSRP |
Solar radiation pressure (cannonball model) |
nPlateSRP |
Solar radiation pressure (N-plate model with CK-frame solar arrays) |
YarkovskyEffect |
Yarkovsky non-gravitational force |
FirstOrderGaussMarkov |
First-order Gauss–Markov stochastic accelerations |
PiecewiseFirstOrderGaussMarkov |
Piecewise Gauss–Markov accelerations |
ImpulsiveBurn |
Instantaneous delta-v manoeuvres |
FiniteBurn |
Continuous thrust finite burn arcs |
Integrators
| Class |
Description |
IAS15 (Rust) |
Implicit adaptive 15th-order integrator (Rein & Spiegel 2015) |
DOP853 |
Dormand–Prince 8(5,3) via SciPy |
Measurement Models
| Class |
Type |
RangeIdeal |
Two-way range (ideal/simulated) |
RangeRateIdeal |
Two-way range rate (ideal/simulated) |
DopplerIdeal |
Doppler range rate (ideal/simulated) |
DopplerReal |
Doppler from real DSN tracking data |
SequentialRangingReal |
Sequential ranging from real DSN tracking data |
DiffOneWayRangeIdeal |
Differential one-way range (DDOR) |
AngularIdeal |
Right ascension / declination optical measurements |
CentroidingIdeal |
Pixel-plane centroiding measurements |
Orbit Determination
| Class |
Description |
SRIF |
Square Root Information Filter (forward pass) |
SRIFB |
Square Root Information Filter (smoother / backward pass) |
LKF |
Linearised Kalman Filter |
LSB |
Least-squares batch estimator |
MultiFilterOD |
Multi-arc OD over disjoint data windows |
MeasurementEditing |
Outlier detection and data editing |
StateNoiseCompensation |
SNC process noise formulation |
DynamicalModelCompensation |
DMC process noise formulation |
Spacecraft & Environment
Spacecraft, CelestialBody, GroundStation body hierarchynPlateModel — N-plate geometry with static and CK-frame (rotating) panelsCamera, Antenna instrument classesMissionSequence — chained propagation / manoeuvre / OD arcsTrajectory — post-processing and visualisation of propagated statesPropagator — configurable propagator wrapping any force model
Utilities
ArrayWUnits / Units — dimension-safe arithmetic with full unit trackingArrayWFrame — arrays with attached reference framesEpochArray — time object supporting UTC, TDB, TT, SCLK conversionsSpiceManager — unified SPICE wrapper (kernels, frames, ephemeris queries)OrbitalElements — Cartesian ↔ Keplerian conversionsBplane — B-plane targeting utilitiesPlotting — styled matplotlib helpersDatabaseManager — local / MongoDB data back-end
Architecture
scarabaeus/
├── src/
│ ├── scarabaeus/ # Python front-end
│ │ ├── body/ # Body, CelestialBody, GroundStation
│ │ ├── dynamics/ # Force models and burn models
│ │ ├── environment/ # Propagator, StateArray, Trajectory, MissionSequence
│ │ ├── finiteBurn/ # Maneuver, ManeuverParser
│ │ ├── guidance/ # B-plane targeting
│ │ ├── measurements/ # Measurement model classes
│ │ ├── orbitDetermination/ # Filter classes (SRIF, LKF, LSB, …)
│ │ ├── spacecraft/ # Spacecraft, Instrument, Camera, Antenna, nPlateModel
│ │ ├── timeAndFrame/ # EpochArray, Frame, ArrayWFrame, SpiceManager
│ │ ├── uncertaintyQuantification/
│ │ ├── units/ # Units, Dimensions, ArrayWUnits
│ │ └── utils/ # Plotting, OrbitalElements, DatabaseManager, Utils
│ └── scarabaeus_rust/ # Rust back-end (compiled via maturin / PyO3)
│ └── src/
│ ├── ias15.rs # IAS15 integrator
│ ├── integration_event.rs
│ └── lib.rs
├── tutorials/ # Worked examples (basics → advanced)
├── tests/ # pytest test suite
├── docs/ # Sphinx documentation source
├── pyproject.toml
├── DEVELOPMENT.md
└── LICENSE
Requirements
| Dependency |
Version |
Notes |
| Python |
3.11+ |
|
| Rust / Cargo |
1.75+ |
developer build only |
| NumPy |
latest |
|
| SciPy |
latest |
|
| SpiceyPy |
latest |
SPICE toolkit Python bindings |
| matplotlib |
latest |
|
| pandas |
latest |
|
| scikit-learn |
latest |
|
| trimesh |
latest |
mesh geometry (N-plate model) |
| autograd |
latest |
automatic differentiation |
| tqdm |
latest |
progress bars |
| pymongo / ssh_pymongo |
latest |
optional MongoDB data back-end |
| ipykernel / ipympl |
latest |
Jupyter notebook support |
pip version — the developer install uses --group dev syntax, which requires pip ≥ 25. Run pip install --upgrade pip if you encounter an error.
Full dependency list is in pyproject.toml.
Installation
User Installation
1. Clone the repository
git clone https://github.com/ccar-orcca/scarabaeus.git
cd scarabaeus
2. Create a virtual environment
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
3. Install Scarabaeus
pip install .
Or, once the package is published on PyPI:
pip install scarabaeus
SPICE kernels — SCB relies on SPICE kernels for ephemeris, frame, and spacecraft clock data. These are not distributed with the package. Load them in your script using scb.SpiceManager.load_kernel_from_mkfile(path_to_metakernel).
Developer Installation
See DEVELOPMENT.md for the full guide. The summary is below.
1. Follow the user installation steps above
pip install -e . --group dev
3. Install Rust
Follow the rustup installer instructions, then verify:
rustc --version
4. Build the Rust back-end
maturin develop
This compiles the Rust code and binds it to the Python package. Re-run whenever Rust source files change.
5. Install commit hooks
pre-commit install
This installs nbstripout and other hooks that run before each commit.
Tutorials
A tiered tutorial suite lives in tutorials/ as Jupyter Notebooks (.ipynb).
Basics
Advanced
Testing
Scarabaeus ships a multi-tier pytest suite under tests/:
pytest tests/unit_testing/ # fast, isolated unit tests
pytest tests/integration_testing/ # end-to-end scenarios
pytest # full suite with coverage report
Coverage and JUnit XML reports are written to tests/reports/.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md and the developer guide before opening a pull request.
Reporting issues
Open a GitHub Issue and include: a short title, steps to reproduce (minimal working example preferred), expected vs. actual behaviour, and your Scarabaeus version, Python version, and OS. For security vulnerabilities, contact the maintainers directly.
Submitting code
- Set up the developer environment.
- Branch from
develop with a descriptive name, e.g. feature/add-xyz or fix/filter-bug.
- Follow the NumPy docstring convention for all public API.
- Run the test suite and ensure all tests pass:
pytest.
- Open a PR against the
develop branch with a clear description of what changed and why. Reference related Issues (e.g. Closes #42).
Jupyter notebook outputs are stripped automatically by the nbstripout pre-commit hook — do not commit notebooks with cell outputs.
Citing Scarabaeus
If you use Scarabaeus in academic work, please cite the following conference paper:
McMahon J., Fereoli G., Wolf T., Ellis Z., Aldhanhani B., Kuleib M., Frank W., Pugliatti M., Almashjari M., Knittel J. (2026).
Scarabaeus: An Open-Source Tool for Interplanetary Spacecraft Navigation.
30th International Symposium on Space Flight Dynamics (ISSFD), Toulouse, France, June 1–5, 2026. Organized by CNES.
@inproceedings{mcmahon2026scarabaeus,
author = {McMahon, J. and Fereoli, G. and Wolf, T. and Ellis, Z. and
Aldhanhani, B. and Kuleib, M. and Frank, W. and Pugliatti, M. and
Almashjari, M. and Knittel, J.},
title = {Scarabaeus: An Open-Source Tool for Interplanetary Spacecraft Navigation},
booktitle = {30th International Symposium on Space Flight Dynamics (ISSFD)},
year = {2026},
address = {Toulouse, France},
note = {Organized by CNES. A formal DOI (Zenodo or JOSS) is forthcoming.},
url = {https://www.researchgate.net/publication/404941039_Scarabaeus_An_Open-Source_Tool_for_Interplanetary_Spacecraft_Navigation},
}
Note: A formal DOI (Zenodo or JOSS) is forthcoming. When available, add a doi: field to CITATION.cff and update the note field in the BibTeX entry above.
License
Scarabaeus is distributed under the ISC License.
Copyright © 2026 CCAR-ORCCA, University of Colorado Boulder.
评论