Skip to main content

spacelab_propagation/
lib.rs

1//! Numerical ODE integration.
2//!
3//! SGP4 is analytic and needs no integrator; this crate is for what SGP4 cannot do — high-fidelity
4//! force models, deep space, manoeuvres, orbit determination, attitude.
5//!
6//! Two rules govern everything here, and they come before any method:
7//!
8//! * **Coefficients are verified, never transcribed from memory.** Every Butcher tableau is checked
9//!   against its order conditions in a computer algebra system (`derivations/dopri5_order.mac`) and
10//!   against analytic-solution and convergence-order tests. A method claiming order 5 that is
11//!   secretly order 4 is caught by reading the measured order off the numbers, not by hoping.
12//! * **Dense output is the interface.** A propagator without a continuous interpolant forces the
13//!   caller into the ring-buffer spline hack GMAT is stuck with. Every adaptive method carries its
14//!   [`DenseOutput`], so [`spacelab_coverage::find_events`] can evaluate `g(t)` at any `t` inside a
15//!   step without re-integrating.
16//!
17//! The state is a fixed-size `[f64; N]`: `[rx, ry, rz, vx, vy, vz]` for an orbit, a quaternion plus
18//! body rate for attitude, `6·M` for `M` bodies. Const-generic `N` keeps it on the stack, `no_std`,
19//! and friendly to the autovectoriser.
20
21#![cfg_attr(not(test), no_std)]
22
23// The degree-120 geopotential coefficient tables are heap-allocated (a ~0.8 MB `GeoPotential` on the
24// stack overflows a thread stack once a few nest); `alloc` provides the `Box` for that. A no_std
25// consumer must therefore supply a global allocator.
26extern crate alloc;
27
28pub mod attitude;
29pub mod attitude_law;
30pub mod density_calibration;
31pub mod density_data;
32pub mod density_rom;
33pub mod dop853;
34pub(crate) mod dop853_consts;
35pub mod dopri5;
36pub mod drag_coefficient;
37pub mod earth_radiation;
38pub mod ephemeris;
39pub mod forces;
40pub mod geopotential;
41pub mod geopotential_coeffs;
42pub mod harris_priester;
43pub mod lifetime;
44pub mod lightcurve;
45pub mod linalg;
46pub mod lunar;
47pub mod lunar_coeffs;
48pub mod maneuver;
49pub mod netcdf_classic;
50pub mod nrlmsise00;
51pub mod ocean_tide;
52pub mod ocean_tide_admittance;
53pub mod ocean_tide_eot20;
54pub mod ocean_tide_fes2004;
55pub mod ocean_tide_fes2014;
56pub mod ocean_tide_got;
57pub mod relativity;
58pub mod rk4;
59pub mod rkn1210;
60pub(crate) mod rkn1210_consts;
61pub mod sdtm;
62pub mod shadow;
63pub mod solid_tide;
64pub mod space_weather;
65pub mod spacecraft;
66pub mod stt;
67pub mod symplectic;
68mod tide_step2_tables;
69pub mod time_variable_gravity;
70pub mod tolerance;
71pub mod torque;
72pub mod variational;
73pub mod wam_ipe;
74pub mod wind_data;
75pub mod wind_model;
76
77#[cfg(feature = "std")]
78extern crate std;
79#[cfg(feature = "std")]
80pub mod abm;
81#[cfg(feature = "std")]
82pub mod adams_nordsieck;
83#[cfg(feature = "std")]
84pub mod ark;
85#[cfg(feature = "std")]
86pub mod driver;
87#[cfg(feature = "std")]
88pub mod dsst;
89#[cfg(feature = "std")]
90pub mod gbs;
91#[cfg(feature = "std")]
92pub mod gj;
93#[cfg(feature = "std")]
94pub mod ias15;
95#[cfg(feature = "std")]
96pub mod ks;
97#[cfg(feature = "std")]
98pub mod mercurius;
99#[cfg(feature = "std")]
100pub mod mri;
101#[cfg(feature = "std")]
102pub mod radau;
103#[cfg(feature = "std")]
104pub mod rosenbrock;
105#[cfg(feature = "std")]
106pub mod saba;
107#[cfg(feature = "std")]
108pub mod taylor;
109#[cfg(feature = "std")]
110pub mod whfast;
111
112pub use attitude_law::{
113    AttitudeProvider, LocalOrbitalFrame, LofType, SpinStabilized, SunPointing, YawSteering,
114};
115// The reduced-order density model's own POD needs a symmetric eigensolver, and so does anything
116// that has to read a spectrum — a graph Laplacian's, for one. Re-exported at the root rather than
117// left behind `density_rom`, whose name says nothing about linear algebra, and rather than copied.
118pub use density_rom::jacobi_symmetric;
119pub use dop853::Dop853;
120pub use dopri5::Dopri5;
121pub use drag_coefficient::{
122    FreeMolecularConditions, SentmanCoefficients, sentman_panel, speed_ratio,
123};
124#[cfg(feature = "std")]
125pub use dsst::{
126    DsstAuxiliary, DsstMeanPropagator, DsstSolarRadiationPressure, DsstTesseral, DsstThirdBody,
127    DsstZonal,
128};
129pub use earth_radiation::{AngularResolution, KnockeEarthRadiation};
130pub use geopotential::GeoPotential;
131pub use harris_priester::{HarrisPriester, HarrisPriesterAtmosphere, harris_priester};
132pub use maneuver::{
133    AccelerationSignal, ConstantThrust, EmpiricalAcceleration, Frame, HarmonicSignal,
134    ImpulsiveManeuver, PolynomialSignal,
135};
136pub use nrlmsise00::{
137    Nrlmsise00Atmosphere, Nrlmsise00Flags, Nrlmsise00Input, Nrlmsise00Output, gtd7, gtd7d,
138};
139pub use ocean_tide::OceanTide;
140pub use relativity::{DeSitter, LenseThirring, Schwarzschild};
141pub use solid_tide::{
142    MeanPole, SolidEarthTide, ocean_pole_tide_corrections, pole_tide_corrections, step2_corrections,
143};
144pub use spacecraft::{
145    BoxWing, Cannonball, DragModel, Facet, PanelDrag, PanelNormal, PanelSrp, RadiationModel,
146};
147pub use time_variable_gravity::{conventional_zonal_coefficients, secular_zonal_correction};
148pub use tolerance::Tolerance;
149
150/// The right-hand side of an ODE: writes `dy/dt` at `(t, y)` into `dydt`.
151///
152/// `t` is seconds from a reference epoch the caller tracks; the integrator never handles an
153/// `Epoch<S>` in its hot loop, which keeps `i128` time arithmetic out of the derivative evaluation.
154pub trait DynamicalSystem<const N: usize> {
155    /// Evaluate the derivative. Called once per stage — this is the hot path.
156    fn derivative(&self, t: f64, y: &[f64; N], dydt: &mut [f64; N]);
157}
158
159/// A continuous representation of the solution over one accepted step, so events and output need no
160/// re-integration. Valid on `[t0, t0 + h]`; behaviour outside that is extrapolation and unspecified.
161pub trait DenseOutput<const N: usize> {
162    /// Interpolate the state at time `t`, writing it into `out`.
163    fn eval(&self, t: f64, out: &mut [f64; N]);
164}
165
166/// The outcome of one trial step of an embedded method: the new state, the componentwise error
167/// estimate, and the dense interpolant for the step just taken.
168#[derive(Debug, Clone, Copy)]
169pub struct StepTrial<const N: usize, D> {
170    /// The proposed state at `t + h`.
171    pub y_next: [f64; N],
172    /// The embedded error estimate, componentwise. Its scaled norm decides acceptance.
173    pub y_err: [f64; N],
174    /// The interpolant for `[t, t + h]`.
175    pub dense: D,
176}