Skip to content

Support gradient vectors as states of OrdinaryDiffEq solvers - #38

Open
goerz wants to merge 2 commits into
masterfrom
ode-gradvector
Open

goerz wants to merge 2 commits into
masterfrom
ode-gradvector

Conversation

@goerz

@goerz goerz commented Nov 22, 2026 •

Copy link
Copy Markdown
Member

This follows up on #37. A GradVector can now be propagated with the ODE solvers of OrdinaryDiffEq directly (propagate(Ψ, G, tlist; method = OrdinaryDiffEq)), instead of as a flat Vector with check = false. The choice between the "frozen" and "flat" semantics for adaptive time steps is explicit, and the frozen default is tested against forward-mode automatic differentiation with ForwardDiff.

Code

  • Broadcasting over gradient vectors and scalars operates on the state and the gradient states block by block (src/broadcast.jl), which is how OrdinaryDiffEq updates its state. Together with an array, a GradVector still acts as a flat vector (gradient states first, state last, the layout of getindex), as before. ExponentialUtilities relies on this (V[:, 1] .= b ./ β in some versions).
  • similar(Ψ, S) now returns a GradVector with element type S, instead of a flat Vector{S}. OrdinaryDiffEq allocates the buffer for its error estimate with similar(u, T), so the error norm can only tell the state from the gradient states if the block structure is kept. Neither Julia's array interface ("a mutable array with the same shape and the specified element type") nor check_state (ArrayInterface.ismutable, same size, element type S) requires a particular container type. The new method satisfies check_state whenever the state does, provided similar(state, S) supports the vector interface (always true for an AbstractVector). This follows the same rule as StaticArrays: similar without dims keeps the structure, and with explicit dims it returns a plain Array.
  • Extensions for DiffEqBase and RecursiveArrayTools provide the error norm and the copy/fill functions the solvers call. By default, an adaptive solver estimates its error from the state only (frozen semantics): the state is identical to a propagation without gradients. The exported frozen_internalnorm and flat_internalnorm select the norm explicitly via internalnorm.
  • An extension for ExponentialUtilities adds expv!(w::GradVector, t, Ks). ExponentialUtilities' expv allocates its output with similar(b, T) but expv! only accepts an AbstractVector, so without this method the new similar would break the out-of-place method = ExponentialUtilities propagator of QuantumPropagators. The in-place propagator, which failed on master already, now works as well. The method computes into a flat buffer allocated in each call. A preallocated workspace in the QuantumPropagators propagator is planned as a follow-up.

Tests

  • test/test_ode.jl:
    • The frozen default takes the same time steps as the propagation without gradients.
    • For a complex state of ForwardDiff dual numbers, the default error norm of OrdinaryDiffEq is a dual number whose value is the norm of the values only.
    • For Tsit5, Vern7, and Vern9 at tolerances 1e-4 and 1e-8, ForwardDiff dual numbers propagated directly with OrdinaryDiffEq on the time grid of the frozen GradVector propagation give the same state and gradient to within 1e-13. With their own adaptive time steps, they take the same number of steps up to one, and agree to within the tolerance. Exact agreement is not robust: the default norm of OrdinaryDiffEq sums with @fastmath, so its rounding differs between ComplexF64 and dual numbers and between CPUs, which can flip the acceptance of a time step at the threshold of the tolerance (observed on Linux).
    • flat_internalnorm matches a flat Vector with the default norm (up to a flipped step acceptance, for the same reason).
    • Fixed time steps (Tsit5 with adaptive = false) give the ForwardDiff result for both norms.
    • Unit tests for blockwise and mixed broadcasting and for both norms.
  • test/test_expv.jl: in-place and out-of-place ExponentialUtilities propagation of a GradVector, against ExpProp.

Documentation

  • The how-to guide for adaptive ODE solvers propagates a GradVector directly and compares both norms over a range of tolerances.
  • Corrections on the "Background" page:
    • ForwardDiff through OrdinaryDiffEq follows the flat semantics only for a real state. For a complex state, the default error norm of OrdinaryDiffEq is a dual number whose value is the norm of the values only, so the time steps are those of the propagation without gradients (frozen).
    • The semantics table now lists ODE solvers as "frozen (default) or flat".
    • The discussion after the proposition on ODE solvers no longer claims that the gradient converges only if the error control includes the gradient states.

Related

  • Planned: a flat output workspace in the ExponentialUtilities propagator of QuantumPropagators for states that are not an AbstractVector, which avoids the per-step buffer.
  • ExponentialUtilities' expv! for a complex t does not reuse the workspace of the ExpvCache (about 184 KB per call for m = 30), which dominates the allocations of the propagation of a gradient vector. The requirements of expv/arnoldi on their input and output vectors are underspecified upstream, see Document the interface required of b and w in expv/expv!/arnoldi SciML/ExponentialUtilities.jl#313.
  • QuantumPropagators#137: general support for ForwardDiff dual numbers in the propagators.
  • The lower compat bound of ArrayInterface is now 7.7.1, as in QuantumPropagators (which is always loaded with QuantumGradientGenerators). With 7.6, the lowest-compat job resolves NonlinearSolve 3.1, which does not precompile on Julia 1.10.
  • Lower compat bounds of the new weak dependencies: DiffEqBase 6.147 (lower versions let the lowest-compat job resolve NonlinearSolve 3.1.0, which does not precompile on Julia 1.10), RecursiveArrayTools 3.12, and ExponentialUtilities 1.17.1 (as in QuantumPropagators).

@goerz
goerz force-pushed the ode-gradvector branch 4 times, most recently from 488422e to 0683d89 Compare November 22, 2026 19:51
A `GradVector` can now be propagated with `method = OrdinaryDiffEq`
directly, instead of as a flat `Vector` with `check = false`.

* Broadcasting over gradient vectors and scalars operates on the state
  and the gradient states block by block (`src/broadcast.jl`). Together
  with an array, a gradient vector still acts as a flat vector with the
  gradient states first and the state last, as ExponentialUtilities
  requires for `V[:, 1] .= b ./ β`.
* `similar(Ψ, S)` returns a `GradVector` with element type `S` instead
  of a flat `Vector{S}`. OrdinaryDiffEq allocates the buffer for its
  error estimate with it, so the error norm must be able to tell the
  state from the gradient states. Like `similar(Ψ)`, this satisfies the
  requirements of `check_state` whenever the state does.
* Extensions for DiffEqBase and RecursiveArrayTools provide the error
  norm and the copy/fill functions the solvers call. By default, an
  adaptive solver estimates its error from the state only (the "frozen"
  semantics), so the state is identical to a propagation without
  gradients. This reproduces ForwardDiff dual numbers in a complex state
  through OrdinaryDiffEq, to within rounding errors.
* `frozen_internalnorm` and `flat_internalnorm` (exported) select the
  error norm explicitly via `internalnorm`.
* An extension for ExponentialUtilities adds `expv!` for a `GradVector`
  output, which `expv` allocates with `similar(b, T)`. This keeps the
  out-of-place ExponentialUtilities propagator of QuantumPropagators
  working, and fixes the in-place one, which failed before.

The tests compare the frozen semantics against ForwardDiff through
OrdinaryDiffEq for Tsit5, Vern7, and Vern9 at two tolerances, the flat
semantics against a flat `Vector`, fixed time steps against ForwardDiff,
and the ExponentialUtilities propagation (in-place and out-of-place)
against `ExpProp`.
The how-to guide for adaptive ODE solvers now propagates a `GradVector`
directly, with the frozen error norm as the default and
`flat_internalnorm` as the alternative. It compares both over a range of
tolerances and states what the table shows: the frozen state is
identical to the propagation without gradients, the frozen gradient
error is a few times the tolerance, the flat one is about the tolerance,
and the flat norm is not more efficient per time step.

On the "Background" page, the semantics table now lists the ODE solvers
as "frozen (default) or flat". The statement that ForwardDiff dual
numbers through OrdinaryDiffEq follow the flat semantics was only true
for real states: for a complex state, the default error norm uses only
the values, as in the frozen semantics. The discussion of adaptive time
steps after the proposition on ODE solvers no longer claims that the
gradient converges only if the error control includes the gradient
states.

DiffEqBase is no longer needed in the documentation environment.

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