Skip to content

v2.0.0

Latest

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 / ArrayWFrame. Read the numbers with .values or .quantity.values.
  • Camera.camera_frame always returns the frame name. Use camera_frame_object when you need a Frame.
  • MeasurementScheduler.elevation_mask returns an ArrayWUnits in degrees. A bare mask that could be either degrees or radians (such as 0.17) is refused, so pass it as an ArrayWUnits instead.
  • FilterSettings.measurement_sigmas is applied once, when the filter is built. To change sigmas after that, call FilterOD.set_measurement_sigmas().
  • FilterOD.fit() writes each iteration as <name>_it{n}.bsp in the filter's folder, instead of a timestamped file in data/kernels/scenario/.
  • Frame objects compare equal by SPICE frame ID, not by identity.
  • A CelestialBody with a non-constant mass raises CelestialBody.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. Pass n_densifier=1 for the 1.0.0 behaviour.
  • SNC process noise: the noise mapping was one power of Δt too high. Retune any SNC Q you 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 CentroidingIdeal and AngularIdeal had the wrong sign, and the Camera calibration 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_bias is 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 SphericalHarmonicsGravity was wrong whenever pole parameters were estimated. It now matches SPICE pxform to 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 nPlateSRP plates was applied untransposed, then rotated a second time.

Orbit determination

  • SolutionOD.map_state_deviation_to_epoch used the STM at the wrong epoch, so iterated estimators diverged from the second iteration whenever the reference ran past the last measurement (#6).
  • MultiFilterOD mapped 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 MeasurementEditing was ill-conditioned.

Measurements

  • DopplerReal count 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=True on 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, and MissionSequence collapsed 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 MissionSequence period / dt given 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=True with integrator="IAS15" raises Propagator.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


Developed at the ORCCA Lab, University of Colorado Boulder.