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

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.

1. Features
2. Architecture
3. Requirements
4. Installation
   • User Installation
   • Developer Installation
5. Tutorials
6. Testing
7. Contributing
8. Citing Scarabaeus
9. License

• Spacecraft, CelestialBody, GroundStation body hierarchy
• nPlateModel — N-plate geometry with static and CK-frame (rotating) panels
• Camera, Antenna instrument classes
• MissionSequence — chained propagation / manoeuvre / OD arcs
• Trajectory — post-processing and visualisation of propagated states
• Propagator — configurable propagator wrapping any force model

• ArrayWUnits / Units — dimension-safe arithmetic with full unit tracking
• ArrayWFrame — arrays with attached reference frames
• EpochArray — time object supporting UTC, TDB, TT, SCLK conversions
• SpiceManager — unified SPICE wrapper (kernels, frames, ephemeris queries)
• OrbitalElements — Cartesian ↔ Keplerian conversions
• Bplane — B-plane targeting utilities
• Plotting — styled matplotlib helpers
• DatabaseManager — local / MongoDB data back-end

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

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.

git clone https://github.com/ccar-orcca/scarabaeus.git
cd scarabaeus

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

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).

See DEVELOPMENT.md for the full guide. The summary is below.

pip install -e . --group dev

Follow the rustup installer instructions, then verify:

rustc --version

maturin develop

This compiles the Rust code and binds it to the Python package. Re-run whenever Rust source files change.

pre-commit install

This installs nbstripout and other hooks that run before each commit.

A tiered tutorial suite lives in tutorials/ as Jupyter Notebooks (.ipynb).

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/.

Contributions are welcome. Please read CONTRIBUTING.md and the developer guide before opening a pull request.

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.

1. Set up the developer environment.
2. Branch from develop with a descriptive name, e.g. feature/add-xyz or fix/filter-bug.
3. Follow the NumPy docstring convention for all public API.
4. Run the test suite and ensure all tests pass: pytest.
5. 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.

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.

Scarabaeus is distributed under the ISC License.

Copyright (c) 2026 CCAR-ORCCA, University of Colorado Boulder.