Repository navigation
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/ArrayWFrame. Read the numbers with.valuesor.quantity.values.Camera.camera_framealways returns the frame name. Usecamera_frame_objectwhen you need aFrame.MeasurementScheduler.elevation_maskreturns anArrayWUnitsin degrees. A bare mask that could be either degrees or radians (such as0.17) is refused, so pass it as anArrayWUnitsinstead.FilterSettings.measurement_sigmasis applied once, when the filter is built. To change sigmas after that, callFilterOD.set_measurement_sigmas().FilterOD.fit()writes each iteration as<name>_it{n}.bspin the filter's folder, instead of a timestamped file indata/kernels/scenario/.Frameobjects compare equal by SPICE frame ID, not by identity.- A
CelestialBodywith a non-constant mass raisesCelestialBody.InvalidMassError.
Changes that move numerical results
Expect these to change answers relative to 1.0.0:
Propagator(n_densifier=10)is the new default. A(t0, tf)tuple time span therefore returns about ten times as many epochs as before. Passn_densifier=1for the 1.0.0 behaviour.- SNC process noise: the noise mapping was one power of Δt too high. Retune any SNC
Qyou tuned against 1.0.0. - LKF with consider parameters now gives the same estimate and consider covariance as the SRIF, so its consider sigmas change.
- Spherical harmonics with a separate central body or third bodies: the central body's point mass is no longer dropped, and a body is no longer attracted twice.
- Optical measurements: the position partials of
CentroidingIdealandAngularIdealhad the wrong sign, and theCameracalibration matrix had an extra pixel-pitch factor. - Real DSN models:
- Mars, Jupiter and Saturn enter the relativistic light time at their system barycentres. For Mars this moves the path by at most 0.63 mm.
- The solar corona delay is evaluated at the ramped transmit frequency.
- A light-time solution that fails now raises an error.
- Measurements before the first ramp record are flagged as outliers.
- Ideal models:
meas_biasis kept until the reference state carries a bias for that station.
Notable fixes
Click to expand
Dynamics
- The central body's point mass was dropped whenever any spherical-harmonics model was configured.
- A body configured both as a harmonic field and as a third body was attracted twice.
- The IAU body-to-J2000 rotation in
SphericalHarmonicsGravitywas wrong whenever pole parameters were estimated. It now matches SPICEpxformto 3e-12, and the partial signs are fixed. - The unnormalized spherical-harmonics recursion and the body-fixed frame lookup on the partials path failed, which blocked estimation of gravity coefficients through
CelestialBody(#6). - The CK attitude of
nPlateSRPplates was applied untransposed, then rotated a second time.
Orbit determination
SolutionOD.map_state_deviation_to_epochused the STM at the wrong epoch, so iterated estimators diverged from the second iteration whenever the reference ran past the last measurement (#6).MultiFilterODmapped each arc's deviation and covariance forward instead of back to the arc epoch, and SRIF arcs handed over the information matrix instead of the covariance.- The SRIF covariance-analysis update crashed when there were no consider parameters.
- LKF consider sensitivity was initialised incorrectly, and the Joseph-form covariance was not symmetrized.
- Parameters owned by a body that is not propagated (for example a station range bias) were missing from the sidecars. In multi-body states, parameters were also misaligned.
- The Huber detrending in
MeasurementEditingwas ill-conditioned.
Measurements
DopplerRealcount interval: the two ends were converted separately, which could shift the count by about 17 Hz on 60 s X-band data.- Doppler ramp windows: window ends are now carried as (high, low) time pairs. The old floats moved the count in steps of about 0.5–1 mHz.
- Midnight and new-year crossings in ramp integration now integrate correctly.
noisy=Trueon the real models added no noise. It now adds white Gaussian noise of the model's sigma.- Estimated biases on the real models raised a
TypeError. - Units of measurement sigmas were ignored in the dataset weights and in refitted sigmas.
- Stacked per-pass and per-image biases without a mapping put partials in the wrong columns. They now raise an error.
Propagation and I/O
- DOP853 with a
(t0, tf)tuple time span: the propagator raised an error, andMissionSequencecollapsed such legs to two epochs. Propagator.reinitialize()failed on a tuple time span.- Sidecar lookups could return the wrong payload, or fail on settings written by
Trajectory.write_to_spk(). - Units of
MissionSequenceperiod/dtgiven in days or hours were not converted. - Supplementary-data download: the DSN station kernels now come from NAIF's new location, because the old links returned 404.
Resolved from the 1.0.0 known issues
- Spacecraft near the Earth: the real radiometric models can now solve the light time in the geocentric frame (
light_time_frame="geocentric"). - Media corrections: tropospheric and ionospheric zenith delays are now estimable, with analytical partials.
- Station and bias partials for real radiometric data are analytical and are now the default.
Known Issues
- IAS15 does not propagate the STM.
propagate_STM=Truewithintegrator="IAS15"raisesPropagator.IAS15STMError, so use DOP853 for orbit determination. - LKF precision: on very precise data (Doppler), the LKF covariance form can differ from the SRIF by a few percent. Prefer SRIF or SRIFB when precision matters.
- Jupiter and Saturn orbiters should pass the planet centres through
rlt_bodies, because the default relativistic bodies use system barycentres. - As with any actively developed project, more bugs and edge cases may surface as new capabilities are exercised.
Full Changelog
- The complete itemised list is in
CHANGELOG.mdand the 2.0.0 release notes. - Compare: v1.0.0...v2.0.0
Developed at the ORCCA Lab, University of Colorado Boulder.