Time integration and events
Learn how HPR Sim steps a flight through time, stops exactly at set times such as burnout, and finds events such as apogee and landing.
In short
- What it models: stepping a flight through time, by Dormand-Prince 5(4), which adapts its steps to an error tolerance, or fixed-step Runge-Kutta (RK4). It lands exactly on set times such as burnout, and finds events such as apogee.
- Sources: Dormand and Prince (1980); Hairer, Nørsett and Wanner’s Solving Ordinary
Differential Equations I (1993), whose
DOPRI5code the port follows. Brent (1973) gives the root finding that locates events. - How well it is validated: by analytic and unit tests, and in part, together with the
rigid-body equations, against the codes of one of NASA’s check cases; not yet against a real
flight. Its
step counts match an independent transcription of
DOPRI5, and its error shrinks as theory predicts. In an exactly solvable flight with drag, apogee, deployment and landing times are right to 1.5e-8 s at default tolerances. On NASA’s tumbling brick, with the one named model difference taken off, the default tolerances leave the body rates within 0.0000009229 deg/s of the code nearest them over the 30 s. That is one of two codes that agree with each other; the other two kept codes are further off (a free body against NASA’s check cases). - What it leaves out: it can’t detect a stiff problem, where very fast, heavily damped motion forces tiny steps. The run then stops with an error. Fixed 10 ms RK4 steps can diverge for a light body under a big canopy. An event that crosses zero and back within one step goes unseen.
Code and sources
Code: hpr_sim::integrator and hpr_sim::events. Decisions: ADR-010 (Dormand-Prince
with dense output, RK4, stop times and events).
Sources:
- [DP80] J. R. Dormand and P. J. Prince, “A family of embedded Runge-Kutta formulae”, J. Comput. Appl. Math. 6 (1980) 19–26, doi:10.1016/0771-050X(80)90013-3. Cited, not fetched (the publisher refuses scripted downloads).
- [HNW] E. Hairer, S. P. Nørsett and G. Wanner, Solving Ordinary Differential Equations I, 2nd ed., Springer, 1993. §II.1 (RK4, table 1.2), §II.2 (order conditions, table 2.2), §II.4 (error norm, step control, starting step), §II.5 (DOPRI5, table 5.2), §II.6 (dense output). The PI controller is §IV.2 of volume II. Cited, not fetched.
- [D5] E. Hairer and G. Wanner,
DOPRI5(Fortran, version of 2004), BSD-2-Clause, pinned ashairer-dopri5invalidation/refs.lock.toml. It is the book’s code. The port follows it: coefficients (CDOPRI), the error norm and controller (DOPCOR), the starting step (HINIT) and the dense output (CONTD5). - [B73] R. P. Brent, Algorithms for Minimization without Derivatives, Prentice-Hall, 1973, ch. 4 (the zero finder). Cited, not fetched; implemented from the algorithm’s description.
Stepping and events
Methods
-
Dormand-Prince 5(4) ([DP80]; [HNW] table 5.2) has seven stages, first-same-as-last, so six new evaluations per step. The step advances with the fifth-order solution (local extrapolation), and the embedded fourth-order solution estimates the error: .
-
The error norm ([HNW] eq. 4.11; [D5]) is:
The weights come from
OdeSystem::absolute_tolerance_weights, so components in different units share one . A step is accepted when . -
The step control ([HNW] II, §IV.2; [D5] defaults) is the PI controller, with :
After a rejection, , and the step after a rejection can’t grow.
-
Departures from
DOPRI5:- A non-finite error estimate, or a derivative that fails in stages 2–7, counts as a rejection that shrinks five times. A long step’s stages can probe states off the trajectory (negative mass, a Mach number past a table’s end). The failure is reported only once the step can’t shrink further. A failure at the step’s first stage is reported at once, and so is any failure under RK4.
- A final interval within the rounding of , where is at most , counts as reached, instead of failing as too small.
- A step can be shortened to land on a stop time. After that, the next call starts from the larger of the controller’s proposal and the step the controller wanted before shortening.
- The step size overflowing to infinity (a problem with zero error and no stop) is an error.
- There is no stiffness detection.
-
For the starting step ([HNW] §II.4;
HINIT), , then one Euler step estimates the second derivative and -
With and , the dense output ([HNW] §II.6;
CONTD5) is:It is a continuous extension of order 4, so its error inside a step is .
-
RK4 ([HNW] table 1.2) has weights 1/6, 2/6, 2/6, 1/6 at 0, ½, ½, 1, with a fixed step. Its dense output is the cubic Hermite interpolant of , , , in the same nested form without (error inside a step). is the next step’s , so it costs nothing extra.
Stop times and discontinuities
Integrator::advance(system, t_stop)never steps pastt_stop. LikeDOPRI5, it stretches the last step up to 1% to land on it exactly (never pastmax_step_s). Thentime_s()equalst_stopbit for bit.- The system is one
OdeSystem<N>: the derivative, optional tolerance weights, optional events (event_count,event_direction,event_value), andaccept_step.accept_stepsees every accepted step with its dense output and can stop the run (Advance::Stopped). So a flight phase can record from, and stop on, its own state. - A discontinuity in the right-hand side (burnout, a staging, a phase change) must be a stop time. An RK step across a jump drops to first order (Loft lesson L23).
- The last stage of the step ending at
t_stopis evaluated att_stopand belongs to the phase before it. The first stage of the next call belongs to the phase after it. A system that picks its phase from alone gets one of the two wrong, so the caller sets the phase between calls (integrator::tests::a_discontinuity_inside_a_step_...). - Each call evaluates afresh, so the system can change between calls. The step-size estimate carries over.
Events
- An event is a scalar with a direction: rising (), falling () or either. The start value must be strictly on one side.
- After each accepted step,
advanceevaluates every at the step’s end. For each sign change it finds the zero of on the step with Brent’s method ([B73]) toEVENT_TIME_RESOLUTION_S = 1e-12 s(plus ). The earliest zero sets the stop. - The integrator stops at the end of Brent’s final bracket on the far side of
the zero, with the dense output’s state there. It returns
Advance::Events, andfired_events()lists every event past its zero at that state, ascending. Coincident events, such as two devices set to deploy at apogee, fire together. is already past zero (or exactly zero) for all of them when the next call starts, so none is reported twice. The system’saccept_stepsees the shortened step. - The event time is as accurate as the solution. The root finder adds at most about
2e-12 s. The state at the event is the dense output’s, which is fourth order for Dormand-Prince and third for RK4. - Limits:
- A function that crosses zero and returns inside one step goes unseen. Bound the step with
Adaptive::max_step_swhere that can happen. - A function that crosses and comes back to exactly zero at the step’s end is reported at the end.
- Events are checked only on accepted steps, never on stage values.
Integrator::resetbetween calls can move an event function back to its near side, by as little as renormalizing a quaternion. The event then fires again moments later. So normalize inside the system’s functions rather than resetting at an event.
- A function that crosses zero and returns inside one step goes unseen. Bound the step with
Defaults and limits
rtol = atol = 1e-8, no maximum step, and a limit of 10⁶ attempted steps.- The flight keeps these defaults with unit weights. On Valetudo’s flight on a K400C motor they took 1.13 ms to run, in a release build. The apogee came within 1.1e-6 m of a run at 1e-11 (Rigid-body flight).
- A stiff flight phase shows up as
StepTooSmallor the step limit. - A fixed step has to respect the drag’s own time scale. Quadratic drag , with , linearizes to . RK4 is stable only for . A light body under a big canopy is the worst case in HPR Sim. A 0.55 kg sustainer arriving at 168 m/s (551 ft/s) under 2 m² gives . So RK4 needs and diverges at 10 ms. The divergence surfaces as a geodesy error from an absurd position, not as a stability message. The adaptive method has no such limit. Recovery descents are the place this bites, because a separated body can be a tenth of the stack’s mass under a canopy sized for it.
- Integration runs forward only.
t_stopcan be infinite, to run until an event or a stop fromaccept_step. After any error, the integrator stays at its last accepted step and can resume.set_step_limitraises a spent limit.
Verification
Unit tests in hpr_sim::integrator::tests and hpr_sim::events::tests. The numbers quoted were
measured on September 17, 2026.
- In the tableau, rows sum to . The fifth-order weights satisfy all 17 order conditions to
order 5 ([HNW] table 2.2) to 1e-14. The embedded weights satisfy orders 1–4 and miss at least one
fifth-order condition by more than 1e-4. The dense output’s weights satisfy the conditions
to order 4 at = 0.1 to 0.9, which pins
D1–D7. - The port matches
DOPRI5on Hairer’s driver problem, the Arenstorf orbit, atrtol = atol= 1e-4, 1e-7 and 1e-10. The evaluations (494, 1,442 and 5,060) and attempted steps (82, 240 and 843) equal those of an independent line-by-line transcription ofDOPCORandHINIT. So do the accepted steps (64, 216, 841), and the end positions to 1e-9. This pins the controller, the starting step and the error norm. - Step-halving convergence on the nonlinear, non-autonomous , on
, driven through
advance:- Dormand-Prince runs at a fixed step , its first and largest, with tolerances too loose to reject. Over 10 to 160 steps its orders are 5.88, 5.53, 5.31, 5.17, falling toward 5. At 320 steps the error, 6e-15, reaches rounding. The dense output at = ¼, ½, ¾ gives 4.81, 4.97, 4.99, 4.99.
- RK4, 20 to 160 steps: orders 4.04, 4.02, 4.01. Its Hermite dense output gives 3.96, 3.99, 4.00.
- Over with
rtol = atolfrom 1e-4 to 1e-9, the error falls from 2.7e-5 to 2.2e-10. It is 0.22 to 0.28 of the tolerance throughout (asserted within 0.07 to 0.85). - A vertical flight with quadratic drag, , has a closed-form apogee
(
testing::closed_form_quadratic_drag, Loft lesson L21). As the tolerance halves from 1e-5 to 2e-8, the apogee time error falls from 5.7e-4 s to 1.2e-8 s. The height error falls from 3.4e-4 m to 8.3e-8 m. The fall is not monotone step by step: has a kink at apogee. The log-log slope of the height error against the tolerance is 1.36. The worst errors are 117·tol (time) and 91·tol (height). - In a vacuum with constant thrust, burnout is a stop time (Loft lesson L23). At burnout the state matches Tsiolkovsky’s equation with gravity loss to 1e-9 relative, for both methods. The coast apogee is within 6.3e-9 s and 5.2e-6 m of 48.8 km (30 mi) with Dormand-Prince (20 steps). RK4 (0.01 s) comes within 4e-11 s and 1.6e-8 m. Integrated straight through the jump, RK4 misses the velocity by 0.56 m/s (1.8 ft/s). With the stop time the miss is 1e-12 m/s.
cargo xtask check-cases, held by the gate where the codes’ files are fetched: NASA’s check case 2, a brick of three unequal moments tumbling for 30 s (a free body against NASA’s check cases). With the named model difference taken off, the flight at the default tolerances (1e-8) sits 0.0000005866, 0.0000009229 and 0.0000002790 deg/s from the code nearest it in roll, pitch and yaw rate. That code is SIM 1 or SIM 4, which agree with each other; the other two kept codes are up to 0.00004975 and 0.001242 deg/s away. At tolerances of 1e-12 the first three fall to 0.000000002126, 0.000000003051 and 0.000000001089 deg/s. So they are the default tolerances’ step error, read from HPR Sim’s own two flights and not from the codes. The steps are not checked on their own here: the gravity and rigid-body equations are in the same flight.- Events are located within 1e-6 s (Loft lesson L22):
- For the quadratic-drag flight, the apogee, a 300 m (984 ft) descending deploy and landing are all located against the closed forms. Errors: 1.2e-8, 1.5e-8 and 1.4e-8 s at the default tolerances, and 3e-12 to 1.3e-11 s with RK4 at 0.01 s. at the stop is below 1e-13.
- For , falling zeros and extrema over 20 s are located to 3e-8 s (Dormand-Prince) and 1.6e-9 s (RK4).
- Restarting on an event doesn’t report it again.
- Three coincident events fire together, once per crossing.
- Three crossings inside one RK4 step come out in time order, to 1e-12 s.
- Where the dense output is exact (), nonlinear event functions stop between 0 and 2.5e-12 s past their roots, on the far side.
- Brent’s method is checked on:
- a smooth root, to 1e-14;
- a triple root;
- a step discontinuity (under 60 evaluations, far side returned);
- exact zeros at the ends, a bracket that doesn’t bracket and a NaN.
- These failures are reported as errors, never as a quiet stop:
- a failing derivative (the adaptive method closes to within 1e-9 s of where it fails);
- a blow-up ( stops near );
- a step overflowing to infinity;
- the step limit (and resuming after raising it);
- bad settings, a backward stop and zero weights.
- Stops 1 to 40 ulps ahead of = 0, 3, 100 and 1,000 s are reached. Steps respect
max_step_s.accept_stepcan stop a run. Repeated runs are bit-identical. Unknown fields and the old tag names are refused in settings files.