Skip to content

GlobalDiffEq: events and DAEs for GlobalErrorEstimation and GlobalAdjoint - #4984

Open
jClugstor wants to merge 15 commits into
SciML:masterfrom
jClugstor:globaldiffeq_events
Open

jClugstor wants to merge 15 commits into
SciML:masterfrom
jClugstor:globaldiffeq_events

Conversation

@jClugstor

@jClugstor jClugstor commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Depends on #4981 (the global_error toggles of DEVerbosity) and #4982 (the AD trait forwarding, which the DAE test with gtol needs).

Draft: until #4981 and #4982 are merged, the diff also shows their changes: lib/DiffEqBase/ (#4981); and src/richardson.jl, the forwarddiffs_model/forwarddiff_chunksize lines in src/estimation.jl and src/adjoint.jl, test/algorithm_traits_tests.jl and test/basic_functionality_tests.jl (#4982). After their merge, I rebase this branch, and these changes go out of the diff.

This PR adds support for callbacks (events) and semi-explicit mass-matrix DAEs to the two global error estimators that take a general solver: GlobalErrorEstimation with DefectCorrection, and GlobalAdjoint. Before this PR, both methods rejected callbacks, and only ODEs without a mass matrix were possible.

GlobalErrorEstimation (DefectCorrection)

The companion equation is M e' = f(P + e, p̃, t) - M P', with P the dense output of the forward solve and P + e the true solution. The user callbacks act on the true state P + e, at the true event times, which differ from the forward event times. This works in InterpolatingMode and in SimultaneousMode.

  • ContinuousCallback, VectorContinuousCallback and DiscreteCallback. An affect that changes the parameters acts on a companion copy of the parameters and of the callbacks.
  • At each forward step end, the companion applies the jump of the dense output (e -= [P]).
  • A DiscreteCallback is checked at the forward step ends, and at the true time of a continuous event (an event ends a step in every solve).
  • Mass-matrix DAEs of index 1. After an event, the companion applies the forward reinitialization (BrownFullBasicInit, CheckInit, NoInit) to the true state. OverrideInit gives an error.
  • Terminating callbacks: the estimate is the error at the end time of the forward solve. A warning comes if the forward solve and the true solution terminate differently, or if their events differ.
  • Without gtol, solve(prob, GlobalErrorEstimation(alg)) returns the forward solution with the error of each saved state in sol.global_error (has_global_error is true for DefectCorrection). Under gtol, the final solution has it too.

GlobalAdjoint

One backward solve of the dual along the forward solution, with a DiscreteCallback at the step ends and at the events. The default sensealg is GaussKronrodAdjoint(autojacvec = ReverseDiffVJP()): the adjoint state is the dual only, and a Gauss–Kronrod quadrature on each adjoint step gives the error integral. The adjoint steps stop at each forward step end, so the integrand is smooth on each adjoint step and the quadrature is accurate relative to the integral, for any size of the error. Both rules are DiffEqCallbacks' integrating callbacks, with an exact integrand −λᵀ r. GaussAdjoint selects Gauss–Legendre, with (p + 1) ÷ 2 points for an adjoint solver of order p, and no error control, so its accuracy depends on the adjoint solver: use a fixed order of 5 or higher. A lower order is allowed, but it is less accurate: with Rosenbrock23 (the midpoint rule), a DAE estimate was wrong by up to 100 %. A variable-order solver such as FBDF reports order 1. The solve warns about an order below 5 (toggle global_error_companion_order). InterpolatingAdjoint maps to GaussKronrodAdjoint with the same settings: the dual is the same, and its own parameter integral is not used.

  • Knot terms for a dense output that is not continuous at the step ends (for example Rosenbrock32), and the endpoint shift P(T⁻) - u(T).
  • Events: the dual jumps z ← Sᵀz, with S the saltation matrix of the event. The default (autojacvec = ReverseDiffVJP()) gets Sᵀz from AD products through the affect and the condition, so S is not stored and the cost for each event does not grow with the size of the state. For a DAE, the products also go through the algebraic projection after each affect: the projection is a NonlinearProblem solve (SimpleNonlinearSolve, which the DAE initialization of OrdinaryDiffEqNonlinearSolve loads), so AD differentiates it with the implicit function theorem through the rules of NonlinearSolveBase and SciMLSensitivity (SteadyStateAdjoint). autojacvec = false uses a finite-difference S. The source terms of the cut-step mismatch and of the condition offset complete e⁺ = S (e⁻ + m) + c.
  • Several calls at one time act in order. A DiscreteCallback that acts at the step end that a continuous event makes moves with the event time, so it shares one saltation matrix with that event.
  • Affects that change the parameters: the dual uses the parameters of each interval between the events.
  • Semi-explicit mass-matrix DAEs: only the differential components enter, with an algebraic terminal transform.
  • TrajectoryError at an event time: each saved entry at that time gets the error between the calls there.
  • If ReverseDiff cannot run the model, the default sensealg uses a numerical VJP, with a warning, as adjoint_sensitivities does.

Changes that users can see

  • GlobalAdjoint needs an affect that is a function of the state, the parameters and the time, as SciMLSensitivity's callback adjoints do. An affect that reads state that the callback keeps (for example a counter) gives an ArgumentError. GlobalErrorEstimation supports such affects.
  • GlobalAdjoint saves the state after each event that changes it, also if no callback saves it. Thus a TrajectoryError solution can have more saved entries than a plain solve.
  • Under gtol, the final solution of GlobalErrorEstimation in InterpolatingMode is one more forward solve on the user's callbacks; the callback objects see only that solve. If that solve does not repeat the accepted one (a callback with state outside of it), a warning comes, and a new estimate gives the solution.
  • New defaults of GlobalErrorEstimation: companion_alg is the forward solver, with a warning for a solver of order 3 or lower; the companion reltol is 1e-8 (with 1e-3, a transient error peak on stiff Van der Pol made the estimate wrong by a factor of 29); the companion abstol is 1e-4 times the forward abstol, at most gtol / 100.
  • The warnings of GlobalDiffEq use SciMLLogging and follow the verbose keyword of solve (and of global_error_estimate and adjoint_error_estimate). DEVerbosity has a new group, global_error, with five toggles: global_error_event_mismatch, global_error_companion_order, global_error_final_solve, global_error_ad_fallback and global_error_grazing_event (a grazing event, where the saltation matrix has no time-shift term). The default preset (Standard) warns as before; Minimal keeps the event mismatch, the final-solve and the grazing messages. The warning about a low-order companion solver now comes from the solve, not from the constructor (the constructor has no verbose).
  • Version 1.7.3 → 1.8.0. GlobalDiffEq needs DiffEqBase 7.22 (the new toggles, from DiffEqBase: add a global_error group to DEVerbosity #4981) and SciMLLogging 2. The SciMLSensitivity extension now also triggers on DiffEqCallbacks (always loaded with SciMLSensitivity), and needs SciMLSensitivity 7.119 and DiffEqCallbacks 4.18.

Not supported (ArgumentError)

  • Callbacks with StepGridRefinement.
  • Events that change the state or the parameters, and DAEs, with a GlobalAdjoint sensealg other than GaussKronrodAdjoint, GaussAdjoint or InterpolatingAdjoint. A callback that changes nothing (a SavingCallback) is accepted.
  • An adjoint with checkpointing = true: the dual must follow the stored dense output.
  • A mass matrix that is not diagonal with ones and zeros (for example 2.0I).
  • Callbacks and mass matrices with ErrorTransport.

Tests

  • Core: 679 tests pass on Julia 1.13 and on Julia 1.10. QA passes on Julia 1.13.
  • New test files: companion_events_tests.jl and adjoint_events_tests.jl. Each case compares the estimate with the error against an exact solution: resets, parameter switches, events at one time, in the first step and at the end time, DiffEqCallbacks callbacks, terminating callbacks, VectorContinuousCallback, DAEs with reinitialization, error trajectories at event times.
  • Validation catalog (outside of the test suite, run on this branch): 16 problems × 2 solvers × 3 tolerances × 3 methods, 288 estimates, no failures. Worst relative errors: GlobalAdjoint 4e-4 (Tsit5), 7e-3 (Rosenbrock32), 4.6e-3 (DAEs); DefectCorrection 1e-3 (Tsit5), 1.5e-2 (DAEs).

Notes for reviewers

  • The shared event code of GlobalAdjoint is in src/adjoint_events.jl; the backward solve with the event bridges is _bridged_adjoint in the SciMLSensitivity extension.
  • The SciMLSensitivity extension works around a SciMLSensitivity bug: InterpolatingAdjoint(autojacvec = false, autodiff = false) on an out-of-place mass-matrix problem fails with default_relstep(::Nothing, ...). For a DAE with autojacvec = false, the extension gives the adjoint an in-place view of the forced right-hand side.
  • The default changes from InterpolatingAdjoint with the integral in the adjoint state to GaussKronrodAdjoint with a quadrature callback. The old path needed a second adjoint solve for small errors (the error control of the adjoint solve is absolute for the integral component); the quadrature on each adjoint step has relative accuracy, so there is one solve. On the comparison cases, the new default agrees with the old path (with its second solve) to 1e-7..5e-5 relative and is 5 to 60 times faster. A DAE now also works with an AD adjoint_alg (the Gauss adjoint problem has the exact Jacobian).
  • New weak dependency SimpleNonlinearSolve (extension GlobalDiffEqSimpleNonlinearSolveExt): the solver of the algebraic projection in the DAE saltation products. Without it, a DAE event uses the finite-difference S.
  • The adjoint events file takes about 11 to 12 minutes in the tests, mostly compilation. The tests share named right-hand sides and problems, so that the solver and the adjoint stack compile less often.

🤖 Generated with Claude Code

jClugstor and others added 15 commits November 9, 2026 09:32
DefectCorrection now integrates the companion M e' = f(P + e, p̃, t) - M P'
with the user callbacks applied to the true state P + e, in both
InterpolatingMode and SimultaneousMode:

- ContinuousCallback, VectorContinuousCallback and DiscreteCallback, with
  parameter changes on a companion copy of the parameters and the callbacks
- knot updates e -= [P] at each forward step end, with P evaluated on the
  curve of the current step
- mass-matrix DAEs of index 1, with the forward reinitialization
  (BrownFullBasicInit, CheckInit, NoInit) applied to the true state after an
  event; OverrideInit gives an error
- a warning when the forward and true event lists differ

Without gtol, solve(prob, GlobalErrorEstimation(alg)) returns the forward
solution with the error of each saved state in sol.global_error; the final
solve under gtol also fills it. has_global_error is true for DefectCorrection.

The default companion reltol is 1e-8 (a transient error peak made 1e-3
wrong by a factor of 29 on stiff Van der Pol), and the default companion
abstol is 1e-4 times the forward abstol, at most gtol / 100.

Also fix: GlobalErrorEstimation and GlobalRichardson forward
forwarddiffs_model and forwarddiff_chunksize, so implicit solvers work
under gtol; the gtol loop no longer merges the problem callback twice.

Bump the version to 1.8.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GlobalAdjoint now runs one backward InterpolatingAdjoint solve of the dual
along the forward solution, with a DiscreteCallback at the knots and the
events (the shared code is in src/adjoint_events.jl and _bridged_adjoint in
the SciMLSensitivity extension):

- jump terms -z(t_j)' M [P]_j for a dense output that is not continuous at
  the step ends (Rosenbrock32), and the endpoint shift P(T-) - u(T)
- events: the dual jumps z <- S' z with the saltation matrix of each event,
  computed by finite differences of trial runs of the user callbacks; the
  sources of the cut-step mismatch and the condition offset complete
  e+ = S (e- + m) + c
- affects that change the parameters: the parameters of each interval
  between events are recorded and used by the dual and by S
- semi-explicit mass-matrix DAEs: only the differential components enter,
  with an algebraic terminal transform; the adjoint solver needs a Jacobian
  that does not differentiate through the ReverseDiff adjoint
- TrajectoryError at an event time: the second saved entry is the error
  after the event
- the integral is solved again with an abstol relative to its value when it
  is small against the adjoint abstol

StepGridRefinement with callbacks, and events or DAEs with a sensealg other
than InterpolatingAdjoint, give an ArgumentError.

DefectCorrection: companion_alg defaults to the forward solver with a
warning for a solver of order 3 or lower; the true-state integrator supports
PeriodicCallback (get_tstops_max, and its own task-local storage in
SimultaneousMode, where the callback keeps its counters), terminating
callbacks (the estimate is the error at the forward end time), and get_du
for ODEs (TerminateSteadyState). A test that relied on a missed simultaneous
event now checks the outcome that occurs (it differs on Julia 1.10).

Tested against exact solutions: events, parameter switches, DAEs, MTK
models (scratch check), and edge cases (events at one time, in the first
step, at T, DiffEqCallbacks callbacks, terminating callbacks). Core and QA
pass on Julia 1.13 and 1.10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Error trajectories at event times (GlobalAdjoint and DefectCorrection):

- The forward solve records the number of saved states before each event
  call, so each saved entry at an event time is placed between the calls
  there. Before, the entries were assigned by the pattern of the saves,
  which failed for two callbacks at one time (four saves) and, in
  DefectCorrection, for save_positions = (true, false).
- GlobalAdjoint crosses only the calls before the entry (per-call windows);
  DefectCorrection uses the true state after the same number of companion
  DiscreteCallback calls (an after_call hook in the companion callbacks).
- When a callback does not save the state after its affect, the dense
  output after the event starts at the state before it; the window of the
  last call at that time gets the offset u+ - P(t+).
- Merged windows of several calls at one time carry S2 c1 + c2.
- Entries at t0 get zero error in GlobalAdjoint, as in DefectCorrection.

GlobalAdjoint events follow the autojacvec of the sensealg, as
SciMLSensitivity's callback adjoints do. By default (ReverseDiffVJP) the
dual crosses an event with S'z = A'z + grad(g) (j . z), from one ReverseDiff
product through the affect per z, ForwardDiff products and the gradient of
the condition, so the cost per event does not grow with the state size and
S is not stored (43x faster per event at n = 1000 in a prototype).
autojacvec = false, and DAEs, use the finite-difference saltation matrix;
an affect that the AD cannot run falls back to it with a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The error identity needs the dual along the stored dense output P. With
checkpointing = true, InterpolatingAdjoint solves the forward problem again
between its checkpoints, which gives another curve, so the estimate would
not be exact. GlobalAdjoint now throws an ArgumentError for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GlobalAdjoint:
- The trial runs of a VectorContinuousCallback affect get the vector of the
  fired components and their signs from the forward call, not a component
  index.
- The trial runs use a snapshot of the callback taken before each call, so
  an affect with internal state (a counter) is differentiated in the state
  it had at that event.
- An affect that changes neither the state nor the parameters (a
  SavingCallback) gets S = I without trial runs.
- The VJP path tests its JVP too, so a failure falls back to the
  finite-difference saltation matrix before the adjoint solve.
- The default sensealg falls back to a numerical VJP (finite differences),
  with a warning, when ReverseDiff cannot run the model, as
  adjoint_sensitivities does.
- The error at t0 (an initialization that changes the state without a save)
  enters as z(t0)' M e(t0).
- The bridge callback uses the SciMLBase tstop functions and handles a stop
  at the time it moves to.

DefectCorrection:
- The error after the callback initializations is the forward state after
  them minus P(t0), in both modes; before, SimultaneousMode applied an
  initialization affect a second time.
- SimultaneousMode swaps only the task-local keys that the companion's
  callbacks use at each step, not the whole task-local storage.
- _LiveInterp has a concrete integrator type.

Also remove dead code (the merge of windows of nonzero width, the paired
field, an unused variable, comments on CompanionAdjoint).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GlobalAdjoint:
- The trial runs of the affects follow the rule of SciMLSensitivity: an
  affect is a function of the state, the parameters and the time. One trial
  copy of the callbacks serves the solve, each trial run gets its own copy
  of it, and a check at each call that changes the state rejects an affect
  with state in the callback (ArgumentError). The difference between the
  trial and the forward affect enters the source term.
- A DiscreteCallback that acts at the step end of a continuous event shares
  the saltation matrix of that event; saved entries between the calls get
  partial bridges, computed only when an estimate ends there.
- After an event that changes the state, the forward solve saves the state
  if no callback does, so that the dense output after the event starts
  there. Calls at one time are linearized after the calls before them.
- Mass matrices: lambda*I with lambda != 1 gives an ArgumentError; 1.0I is
  the identity. A DAE with autojacvec = false uses an in-place forced
  problem (a SciMLSensitivity bug for out-of-place DAEs with finite
  differences). If the numerical VJP fallback fails too, the first error
  is thrown.
- The second adjoint solve for a small projection: the extension returns
  (; value, refine). In the gtol loop, the second solve waits when the error
  floor allows it, and runs for an estimate near gtol and for the reported
  endpoint error.
- Parameters are compared with one recursive _approx_same (structs without
  ==, arrays of them). A SavingCallback is no event for another sensealg.
- forwarddiffs_model and forwarddiff_chunksize are forwarded.

GlobalErrorEstimation (DefectCorrection):
- The companion checks a DiscreteCallback at the true time of a continuous
  event, not at the forward event time.
- Terminating callbacks are recorded; a warning comes if the forward solve
  and the true solution terminate differently.
- SimultaneousMode stops the companion at the forward step end exactly,
  and keeps O(1) memory in the gtol loop.
- Under gtol, InterpolatingMode keeps the error trajectory of the accepted
  estimate: the final solution is one forward solve on the user's
  callbacks; if it does not repeat the accepted one, a warning comes and a
  new estimate on a copy gives the solution.

GlobalRichardson no longer applies the problem callback two times.

Core: 642 tests pass on Julia 1.13 and 1.10. QA passes on Julia 1.13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DiffEqBase 7.22.0: DEVerbosity gets a global_error group with four toggles
for GlobalDiffEq:
- global_error_event_mismatch: the events or the terminations of the
  forward solve and of the true solution differ
- global_error_companion_order: a companion solver of order 3 or lower
- global_error_final_solve: the final forward solve under gtol does not
  repeat the accepted one
- global_error_ad_fallback: finite differences or a numerical VJP take the
  place of ReverseDiff or ForwardDiff in GlobalAdjoint
None silences all; Minimal keeps the event mismatch and the final solve;
Standard (the default), Detailed and All warn for all four.

GlobalDiffEq: the nine warnings use @SciMLMessage with the verbose keyword
of solve, global_error_estimate and adjoint_error_estimate (a preset is
converted to a DEVerbosity). GlobalAdjoint carries the verbosity in its
recorded data to the SciMLSensitivity extension. The warning about a
low-order companion solver comes from the solve, not the constructor,
which has no verbose. New dependency SciMLLogging 2; DiffEqBase compat 7.22.

Core: 652 tests pass on Julia 1.13 and 1.10. QA passes on Julia 1.13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Rebuild the companion and recording callbacks with Accessors.setproperties,
  so that a new or reordered SciMLBase field cannot break them.
- Correct the SimultaneousMode and GlobalAdjoint docstrings, and document
  callbacks, DAEs, the error trajectory and the verbosity toggles on the docs page.
- Give a message at a grazing event, where the saltation matrix has no
  time-shift term (new DEVerbosity toggle global_error_grazing_event).
- Shorten the comments to the reason for the code, and remove history numbers.
- Share named right-hand sides and problem factories in the adjoint events
  tests, so that the solver and the adjoint stack compile less often
  (the file alone: 1213 s to 790 s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The trait forwarding PR defines the helper there, so that both branches
have the same richardson.jl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The algebraic projection of a semi-explicit DAE (z from f_a(x, z) = 0,
before the affects and after each of them) is now a NonlinearProblem
solve with x as its parameters. AD through it uses the implicit function
theorem through the existing rules of NonlinearSolveBase and
SciMLSensitivity (SteadyStateAdjoint with ReverseDiffVJP, because the
residual writes into arrays). Thus, DAE events use the matrix-free
saltation products, as ODE events do, and no longer need O(n_d * n_a)
right-hand-side evaluations per event.

- New weak dependency SimpleNonlinearSolve (the solver of the projection).
  Without it, a DAE event uses the finite-difference saltation matrix.
- New test set: the VJP form agrees with the finite-difference saltation
  matrix on four DAE event problems.
- Runic formatting of adjoint_events.jl and the SciMLSensitivity extension.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The previous formatting came from Runic 1.5.1, which indents a
comprehension differently from the Runic version that CI uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t solve

The error integral was the last component of the InterpolatingAdjoint
state, so the error control of the adjoint solve was absolute for it,
and a small error needed a second adjoint solve with a smaller abstol.
Now the default sensealg is GaussKronrodAdjoint: the adjoint state is the
dual only, and a quadrature callback integrates -λᵀ r on each adjoint
step, with the exact defect r. The adjoint steps stop at each forward
knot, so the integrand is smooth on each step and the quadrature is
accurate relative to the integral.

- The sensealg selects the quadrature: GaussKronrodAdjoint (default),
  GaussAdjoint (needs an adjoint solver of order 5 or higher), or
  InterpolatingAdjoint (the integral in the adjoint state).
- Remove the second adjoint solve, its constants, the refine closure and
  the "near gtol" band of the gtol loop.
- The Gauss adjoint problem has the exact adjoint Jacobian, so a DAE also
  works with an AD adjoint solver.
- The extension imports DiffEqCallbacks directly (a second trigger).

The validation catalog gives the same worst errors in 3.5 times less time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The quadrature callback reads each adjoint step before the terminal
  cost callback and the bridge change the state (the order of
  SciMLSensitivity's Gauss adjoints). Before, the cost callback acted
  first, so a step before an interior terminal time could read the
  terminal value with some interpolants.
- Build the GaussIntegrand that the Gauss adjoint problem needs without a
  ReverseDiff tape of f at u = 0.
- InterpolatingAdjoint maps to GaussKronrodAdjoint with the same
  settings: the dual is the same, and its own parameter integral was not
  used.
- GaussAdjoint with an adjoint solver of alg_order below 5 (also a
  variable-order solver) gives an ArgumentError before the forward
  solve: its Gauss rule has (p + 1) ÷ 2 points.
- Keep the default subdivision tolerance of the Gauss-Kronrod callback.
- Compat: SciMLSensitivity 7.119, DiffEqCallbacks 4.18.
- Tests for InterpolatingAdjoint with events and a DAE, and for the
  ArgumentError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SciMLBase 3.58 deprecates u_modified!. CI runs the tests with
depwarns on, so the warning broke the @test_logs tests of the
companion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ow 5

GaussAdjoint uses (p + 1) ÷ 2 Gauss points for p = alg_order(adjoint_alg)
and has no error control, so a low order gives a less accurate estimate.
That is a choice of the user, not an error: the solve now warns once,
through the global_error_companion_order toggle, and continues.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant