Repository navigation
Releases
v2.0.0
This is the first major update since the public 1.0.0 release. Scarabaeus can now be extended from your own scripts with new force models, parameters, measurements and estimators. It adds many dynamics models and station and planet orientation models, rebuilds measurement setup around scheduled and real-data streams, and moves the heaviest force-model kernels into Rust.
Version 2.0.0 also changes several public interfaces. It fixes a number of bugs that affected numerical results, so please read Upgrading from 1.0.0 below before you update existing scripts.
Release Highlights
Extend the library from your own scripts
You can now add the following without changing the library source:
CustomDynamicModel: a force model written as a Python acceleration function. It is summed into the equations of motion, and any partials you do not supply are filled in by central finite differences.CustomParameter: a new solve-for parameter, either static or with its own dynamics, that can be estimated likeeta_srp.CustomMeasurement: a measurement written as an observable function and its Jacobian, with its own biases and calibration terms.CustomFilter: a whole estimator (sequential, batch or sigma-point). The library supplies the reference trajectory, residuals, partials, STMs and process noise, and packages your result as aSolutionOD.
Dynamics
- Polyhedral gravity (
PolyhedralGravity, Werner & Scheeres): the gravity of a constant-density shape model, valid down to the surface, evaluated in Rust.ShapeHarmonicsconverts a shape model into spherical-harmonic coefficients. - Several spherical-harmonic fields per spacecraft (
sph_harm_bodies), for example Jupiter and its moons. Each field has its own degree, order, coefficient file and partials. - Radiation recoil from thermal emission and transmitters:
ThermalRadiationfollows the OSIRIS-REx small-force approach, with temperature tables per surface.AntennaRadiationPressurecovers radio antennas or an active instrument such as a LIDAR.- Each has an estimable scale factor (
eta_thermal,eta_antenna).
- Empirical accelerations:
- New models:
FourierAcceleration(in time, argument of latitude or solar longitude) andPiecewisePolynomialAcceleration. - FOGM, PFOGM, piecewise-polynomial and Fourier accelerations can all be expressed in inertial, RTN or body-fixed frames.
- New models:
SmoothedImpulsiveBurnmodels an impulsive maneuver as a narrow continuous pulse, so a single propagation (and its variational equations) can carry the burn.nPlateSRP:- Double-sided plates.
- Per-plate SPICE frames.
- Correct CK attitude handling.
ForceModelTranslation:save()/load()to JSON or pickle.list_forces().- Third bodies can be given by name, including system barycentres.
Stations, Earth orientation and planetary orientation
- Station displacement models: solid Earth tide (IERS 2010), pole tide and ocean loading (BLQ).
BodyOrientation: Earth orientation parameter corrections, or a small rotation of any body-fixed frame. All radiometric models apply it.- The following solve-for parameters are new, all with analytical partials:
- Station location offsets (cylindrical).
- EOP corrections: polar motion, UT1 and celestial pole offsets.
- Body orientation corrections.
- Love and Shida numbers.
- Tropospheric and ionospheric zenith delays for each station.
- IAU pole parameters (
pole_ra,pole_dec,pole_pm,pole_w0).
Measurements
MeasurementSchedulerbuilds synthetic tracking from requests. Each request has its own observer, measurement type and window, with support for recurring passes and elevation masks.MeasurementRegistry,MeasurementStream,MeasurementConfigandObsDatadescribe real tracking-data streams and their shared settings.- Real DSN Doppler and sequential ranging:
- Analytical (Moyer) partials are now the default.
- The light time can be solved in a barycentric or geocentric frame.
- The relativistic bodies are configurable.
- Solar corona and electronic delays can be switched on or off individually.
- Ramp tables can cross a year boundary.
- Several precision fixes are included (see Notable fixes).
- Real-data forward model is about 6–7× faster. A one-iteration multi-pass OD on real DSN data went from 68 s to 10 s, and the results are bit-identical.
- Two-component streams (angles, centroids) are reported, edited and flagged per component.
Orbit determination
- A cost-function convergence test (weighted least-squares cost J/n) runs alongside the state-deviation test, selected with
convergence_criterion. Use it for weakly observable problems. - Hooks between iterations:
FilterOD.fit(callback=...)andMultiFilterOD.fit(callback=...)call your function after each iteration.FilterOD.set_measurement_sigmas()reweights datasets between iterations.
- Process noise for each body (SNC and DMC), with a
max_intervalcap so that a data gap does not receive unbounded noise. DMC now follows an estimated Gauss–Markov decay rate. - LKF consider analysis now matches SRIF, SRIFB and LSB.
MCMCsamples the posterior of a converged filter with emcee.Plotting.plot_corner()draws corner plots with optional covariance ellipses.SolutionClosenessgives the statistical distance between two OD solutions (Bhaskaran & Rush).SolutionOD:save()writes JSON or pickle with full metadata (frame, units, labels, a-priori, convergence, provenance).state_covariance_to_elements()returns the estimate and covariance in Keplerian elements.
Propagation and trajectories
Propagator:- Returns a
Trajectory. - Every setting,
tspanincluded, can be changed afterload(). - A
(t0, tf)tuple time span now works with DOP853. - Dense output (
n_densifier) resamples each integration step.
- Returns a
MissionSequencelegs can be given only their(t0, tf)bounds and adopt the integrator's own grid.- SPK files are written as type 13 (Hermite). The velocity is the exact derivative of the position, and the position curve no longer jumps between nodes.
- States with several bodies are written to one SPK per body.
- Sidecar files are located by
SpiceManager.sidecar_files()instead of a fixed folder layout.
Performance
- The Rust extension, now imported as
scarabaeus.rust, carries the spherical-harmonics, n-plate SRP and polyhedron gravity kernels. Their partials are checked by dual-number automatic differentiation. EphemerisCacheevaluates third-body ephemerides from cached Chebyshev polynomials inside the integrator.import scarabaeusloads its classes lazily.
Documentation and tutorials
- OSIRIS-REx real-data tutorial rewritten as a multi-pass batch OD on three DSN passes from June 2018 (DSS-65 and DSS-35). It covers:
- SRIFB with PFOGM stochastic accelerations, an estimated SRP scale factor and per-pass range biases.
- Huber and MAD editing.
- A three-day prediction test against the OD044 reconstruction.
- API pages are new for the Rust classes, with the equations each kernel evaluates. Docstrings across all packages were corrected, and every public class now has a page.
- Errors are more descriptive: dedicated exception classes, nested on the class that raises them (for example
Propagator.IAS15STMErrorandMeasurement.LightTimeConvergenceError), replace generic errors and silent failures.
Upgrading from 1.0.0
Installation
- Python ≥ 3.11.9.
- Rust 1.85 or newer is now required for every install, because
pip installcompiles the extension and the crate uses the 2024 edition. - New dependencies are
pyerfa,emceeandcorner. pip installs them automatically. - Reinstall the package (
pip install .orpip install -e .) so the extension is rebuilt under its new module name.
Renamed, moved or removed
| 1.0.0 | 2.0.0 |
|---|---|
scarabaeus.scarabaeus_rust |
scarabaeus.rust (top-level names such as scarabaeus.IAS15 are unchanged) |
scarabaeus.dynamics.EphemerisCaching (build_ephemeris_cache, NoLoadedSPKError) |
scarabaeus.utils.EphemerisCache |
SpiceManager.write_spk_segment_type9() |
SpiceManager.write_spk_segment_type13(); degree_poly must be odd |
Spacecraft.inertial_to_body_DCM_nadir_pointing_to_sun |
Spacecraft.inertial_to_body_DCM_nadirPointingSun (attitude mode "nadirPointingSun") |
MeasurementScheduler keywords start_et, cadence_sec, gap_sec, … |
start, cadence, gap, … (they accept EpochArray / ArrayWUnits or bare seconds) |
DopplerReal / SequentialRangingReal partials_finite_diff |
partials_method="fd" |
partials_method="ideal" on the real models |
removed; use "analytical" (default) or "fd" |
sc_transpoder_delay_RU |
sc_transponder_delay_RU |
Measurement.PARTIALS_METHODS_SUPPORTED |
PARTIALS_METHODS on each model |
OPTIONAL_AUX_KEYS / RECORD_FIELDS on the real models |
AUX_KEYS.optional / AUX_KEYS.record_fields |
RangeIdeal / RangeRateIdeal set_pass_index() |
set_pass_epochs(), or MeasurementScheduler.add(..., per_pass_bias=True) |
MeasurementScheduler.EDGE_TOLERANCE_SEC, MeasurementEditing.DEFAULT_PASS_GAP_SEC, DEFAULT_MIN_PASS_POINTS |
entries in utils/Constants.py |
MeasurementDataSet.remove_outliers() |
removed (outliers are flagged through outlier_flag) |
DatabaseManager |
removed |
StateArray.from_components() |
deprecated |
Behaviour changes
GroundStationand the station displacement models (SolidTide,PoleTide,OceanLoading,BodyOrientation) now returnArrayWUnits/ `ArrayWFra...
v1.0.0
Scarabaeus v1.0.0
Release Highlights
Core Framework
- Comprehensive spacecraft orbit determination framework for interplanetary missions
- Major dynamical models implemented and validated
- Rust backend integrated for performance-critical computations
- Estimation framework includes:
- Batch filtering
- Sequential filtering
- Smoothing
- Multi-arc estimation
- Stochastics and consider parameter estimation
Measurement Models
- Radiometric measurement models
- Optical navigation measurement models
- Measurement editing and data manipulation utilities
Utilities
- Data export and file management tools
- Plotting and visualization utilities
- Orbit determination post-processing tools
Known Issues
General
- As with any actively developed software project, additional bugs and edge cases may still be discovered as new capabilities are introduced and tested.
Performance
- Plotting performance can still be improved in some workflows.
- Visualization utilities are undergoing ongoing standardization and refinement.
Real Measurement Models
- Real radiometric measurement models assume the spacecraft is outside Earth's
sphere of influence. Geocentric-frame corrections required are not yet fully supported. - Partial derivatives of media corrections (tropospheric and ionospheric
parameters) with respect to filter solve-for parameters are not yet implemented. - Ground station and measurement bias partial derivatives for real radiometric data require further refactoring and simplification.
Project History
The Scarabaeus project was originally started on May 10, 2022.
Over the years, it has benefited from contributions from many students, researchers, and collaborators, growing to nearly 4,000 commits on the main development branch.
Most day-to-day development currently takes place within an internal university GitLab repository. Consequently, the public repository represents a curated subset of the full development effort and may not include experimental features, ongoing investigations, or active issue tracking.
Public releases are planned around major development milestones, scientific achievements, and mission-related deliverables.
Developed at the ORCCA Lab, University of Colorado Boulder.