Skip to content

Releases

v2.0.0

Choose a tag to compare

@giovannifereoli giovannifereoli released this 20 Oct 20:47

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 like eta_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 a SolutionOD.

Dynamics

  • Polyhedral gravity (PolyhedralGravity, Werner & Scheeres): the gravity of a constant-density shape model, valid down to the surface, evaluated in Rust. ShapeHarmonics converts 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:
    • ThermalRadiation follows the OSIRIS-REx small-force approach, with temperature tables per surface.
    • AntennaRadiationPressure covers 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) and PiecewisePolynomialAcceleration.
    • FOGM, PFOGM, piecewise-polynomial and Fourier accelerations can all be expressed in inertial, RTN or body-fixed frames.
  • SmoothedImpulsiveBurn models 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

  • MeasurementScheduler builds synthetic tracking from requests. Each request has its own observer, measurement type and window, with support for recurring passes and elevation masks.
  • MeasurementRegistry, MeasurementStream, MeasurementConfig and ObsData describe 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=...) and MultiFilterOD.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_interval cap 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.
  • MCMC samples the posterior of a converged filter with emcee. Plotting.plot_corner() draws corner plots with optional covariance ellipses.
  • SolutionCloseness gives 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, tspan included, can be changed after load().
    • A (t0, tf) tuple time span now works with DOP853.
    • Dense output (n_densifier) resamples each integration step.
  • MissionSequence legs 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.
  • EphemerisCache evaluates third-body ephemerides from cached Chebyshev polynomials inside the integrator.
  • import scarabaeus loads 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.IAS15STMError and Measurement.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 install compiles the extension and the crate uses the 2024 edition.
  • New dependencies are pyerfa, emcee and corner. pip installs them automatically.
  • Reinstall the package (pip install . or pip 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

  • GroundStation and the station displacement models (SolidTide, PoleTide, OceanLoading, BodyOrientation) now return ArrayWUnits / `ArrayWFra...
Read more

v1.0.0

Choose a tag to compare

@giovannifereoli giovannifereoli released this 30 May 06:17

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.