Repository navigation
Conversation
goerz
force-pushed
the
ode-gradvector
branch
4 times, most recently
from
November 22, 2026 19:51
488422e to
0683d89
Compare
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.
goerz
force-pushed
the
ode-gradvector
branch
from
November 22, 2026 20:11
0683d89 to
0a7ed25
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This follows up on #37. A
GradVectorcan now be propagated with the ODE solvers of OrdinaryDiffEq directly (propagate(Ψ, G, tlist; method = OrdinaryDiffEq)), instead of as a flatVectorwithcheck = 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
src/broadcast.jl), which is how OrdinaryDiffEq updates its state. Together with an array, aGradVectorstill acts as a flat vector (gradient states first, state last, the layout ofgetindex), as before. ExponentialUtilities relies on this (V[:, 1] .= b ./ βin some versions).similar(Ψ, S)now returns aGradVectorwith element typeS, instead of a flatVector{S}. OrdinaryDiffEq allocates the buffer for its error estimate withsimilar(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") norcheck_state(ArrayInterface.ismutable, same size, element typeS) requires a particular container type. The new method satisfiescheck_statewhenever the state does, providedsimilar(state, S)supports the vector interface (always true for anAbstractVector). This follows the same rule as StaticArrays:similarwithoutdimskeeps the structure, and with explicitdimsit returns a plainArray.frozen_internalnormandflat_internalnormselect the norm explicitly viainternalnorm.expv!(w::GradVector, t, Ks). ExponentialUtilities'expvallocates its output withsimilar(b, T)butexpv!only accepts anAbstractVector, so without this method the newsimilarwould break the out-of-placemethod = ExponentialUtilitiespropagator of QuantumPropagators. The in-place propagator, which failed onmasteralready, 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:1e-4and1e-8, ForwardDiff dual numbers propagated directly with OrdinaryDiffEq on the time grid of the frozenGradVectorpropagation give the same state and gradient to within1e-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 betweenComplexF64and dual numbers and between CPUs, which can flip the acceptance of a time step at the threshold of the tolerance (observed on Linux).flat_internalnormmatches a flatVectorwith the default norm (up to a flipped step acceptance, for the same reason).adaptive = false) give the ForwardDiff result for both norms.test/test_expv.jl: in-place and out-of-place ExponentialUtilities propagation of aGradVector, againstExpProp.Documentation
GradVectordirectly and compares both norms over a range of tolerances.Related
AbstractVector, which avoids the per-step buffer.expv!for a complextdoes not reuse the workspace of theExpvCache(about 184 KB per call form = 30), which dominates the allocations of the propagation of a gradient vector. The requirements ofexpv/arnoldion their input and output vectors are underspecified upstream, see Document the interface required ofbandwinexpv/expv!/arnoldiSciML/ExponentialUtilities.jl#313.