diff --git a/CHANGELOG.md b/CHANGELOG.md index 1319f5a..1ba1b30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,12 +17,16 @@ Also see the [GitHub Releases](https://github.com/JuliaQuantumControl/QuantumGra * Changed: The field `G` of `GradGenerator` and `GradgenOperator` is now `H`, and the field `control_deriv_ops` of `GradgenOperator` is now `control_derivs`, the same name as in `GradGenerator`. To adapt, replace `G.G` with `G.H` and `G.control_deriv_ops` with `G.control_derivs` for any gradient generator `G`. The positional arguments of the `GradgenOperator` constructor are unchanged * Changed: The documentation uses a simplified notation that matches the field names: the dynamical generator `H`, the control derivatives `control_derivs` (μ̂ₗ), the gradient generator `G`, and the gradient vector `Ψ` with the state `Ψ.state` and the gradient states `Ψ.grad_states` (Ψ′ₗ) * Changed: `specrange` for a `GradgenOperator` now computes the spectral range of the dynamical generator `G.H`, which is the spectral range of the gradient generator. This is more efficient, and it avoids estimating the spectral range of a non-normal matrix with the `:arnoldi` method. With `method=:auto`, the choice between `:diag` and `:arnoldi` is based on the size of `G.H` +* Changed: `similar(Ψ, S)` for a `GradVector` now returns a `GradVector` with element type `S`, instead of a flat `Vector{S}` * Added: An overview of the gradient generator and the gradient vector in the documentation * Added: A "Background" page in the documentation that proves that propagating a gradient vector under a gradient generator yields the exact derivatives of the propagated state, interprets gradient vectors as dual numbers in forward-mode automatic differentiation, and extends the theory to time-dependent generators and to arbitrary control parameters (the basis for GOAT-type methods) * Added: `eigvals`, `tr`, and `det` for a `GradgenOperator`, evaluated from the dynamical generator `G.H` * Added: A section about the properties of the gradient generator (spectrum, Jordan structure, non-normality, adjoint), and a discussion of the "flat", "frozen", and "full dual" semantics of propagating gradient vectors with different numerical methods, on the "Background" page of the documentation * Added: How-to guides in the documentation for the backward propagation of gradient vectors, for gradient vectors with the Chebychev propagator, and for controlling the time steps of an adaptive ODE solver for gradient vectors +* Added: A `GradVector` can now be propagated with the ODE solvers of [OrdinaryDiffEq](https://github.com/SciML/OrdinaryDiffEq.jl), e.g., with `propagate(Ψ, G, tlist; method = OrdinaryDiffEq)`. Broadcasting over `GradVector`s and scalars operates on the state and the gradient states separately (together with an array, a `GradVector` still acts as a flat vector), and extensions for DiffEqBase and RecursiveArrayTools provide the remaining methods that the solvers require. By default, an adaptive solver estimates its error from the state only (the "frozen" semantics), so the state is the same as in a propagation without gradients, and the result matches forward-mode automatic differentiation with ForwardDiff through OrdinaryDiffEq +* Added: `frozen_internalnorm` and `flat_internalnorm`, to select the error norm of an adaptive ODE solver for a `GradVector` via `internalnorm`. With `flat_internalnorm`, the error estimate includes the gradient states * Fixed: `isreal` for a `GradgenOperator` no longer throws a `MethodError` +* Fixed: The in-place propagation of a `GradVector` with the ExponentialUtilities propagator of QuantumPropagators (`method = ExponentialUtilities`), via an extension for ExponentialUtilities * Fixed: `norm(Ψ)` for a `GradVector` is now the Euclidean norm of the block vector, consistent with `dot`. Previously, it was the sum of the norms of the state and the gradient states. As a consequence, `check_normalization=true` in the Chebychev propagator of QuantumPropagators, which is not valid for gradient vectors, now fails instead of passing by accident diff --git a/Project.toml b/Project.toml index 71c857d..9d3b9d9 100644 --- a/Project.toml +++ b/Project.toml @@ -11,14 +11,23 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf" [weakdeps] ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9" +DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e" +ExponentialUtilities = "d4d017d3-3776-5f7e-afef-a10c40355c18" +RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd" [extensions] QuantumGradientGeneratorsArrayInterfaceExt = "ArrayInterface" +QuantumGradientGeneratorsDiffEqBaseExt = "DiffEqBase" +QuantumGradientGeneratorsExponentialUtilitiesExt = "ExponentialUtilities" +QuantumGradientGeneratorsRecursiveArrayToolsExt = "RecursiveArrayTools" [compat] -ArrayInterface = "7.0" +ArrayInterface = "7.7.1" +DiffEqBase = "6.147, 7" +ExponentialUtilities = "1.17.1" LinearAlgebra = "1" QuantumControl = ">=0.11.4" +RecursiveArrayTools = "3.12, 4" Random = "1" SparseArrays = "1" julia = "1.10" diff --git a/docs/Project.toml b/docs/Project.toml index d163a5e..87675d8 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,4 @@ [deps] -DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656" @@ -15,7 +14,6 @@ QuantumPropagators = "7bf12567-5742-4b91-a078-644e72a65fc1" QuantumGradientGenerators = {path = ".."} [compat] -DiffEqBase = "6, 7" Documenter = "1.18" DocumenterCitations = "1.5" DocumenterInterLinks = "1.1" diff --git a/docs/src/background.md b/docs/src/background.md index e42e42b..c87c706 100644 --- a/docs/src/background.md +++ b/docs/src/background.md @@ -367,7 +367,7 @@ In the *flat* semantics, ``G`` and ``Ψ`` are an ordinary matrix and vector of d In the *frozen* semantics, every quantity that a method derives from the data, such as a spectral range, interpolation points, expansion coefficients, the number of terms, or a time step, is computed from ``\hat{H}`` and the state ``|Ψ⟩`` alone, exactly as in the propagation of ``|Ψ⟩`` without gradients, and then held fixed. The state component of the result is then the same as the propagation of ``|Ψ⟩`` under ``\hat{H}`` (up to floating-point rounding). With the frozen quantities, the remaining computation consists only of linear combinations, products, and linear solves with ``ϵ``-independent coefficients, so by [Proposition 6](@ref Background-prop-linear-algebra), the gradient states are the exact derivative of the computed state, except for the dependence of the frozen quantities on ``ϵ``. The computed state depends on these quantities only through the error of the propagation, so the missing contribution is of the order of that error. For ODE solvers, this approach is known as internal numerical differentiation [BockMOCRS1981; Sec. 8.3.3](@cite). -In the *full dual* semantics, the quantities that a method derives from the data are themselves dual numbers, computed in dual arithmetic. For example, the inner product of two dual vectors is ``⟨Ψ|Φ⟩ + η (⟨Ψ^\prime|Φ⟩ + ⟨Ψ|Φ^\prime⟩)``. Thus, their dependence on ``ϵ`` is differentiated as well, and only discrete decisions, such as the number of terms or the acceptance of a time step, remain frozen. The gradient states are then the exact derivative of the computed state, wherever the discrete decisions do not change. This is forward-mode automatic differentiation with a dual-number type like that of [ForwardDiff](https://github.com/JuliaDiff/ForwardDiff.jl). Gradient vectors cannot represent it, since an inner product of gradient vectors is an ordinary complex number; it requires dual numbers as the scalar type throughout the propagation method. Whether the error control of an adaptive method is itself frozen is a choice of the method: [DifferentialEquations](https://github.com/SciML/DifferentialEquations.jl), e.g., includes the dual parts of ForwardDiff dual numbers in its default error norm, as in the flat semantics. +In the *full dual* semantics, the quantities that a method derives from the data are themselves dual numbers, computed in dual arithmetic. For example, the inner product of two dual vectors is ``⟨Ψ|Φ⟩ + η (⟨Ψ^\prime|Φ⟩ + ⟨Ψ|Φ^\prime⟩)``. Thus, their dependence on ``ϵ`` is differentiated as well, and only discrete decisions, such as the number of terms or the acceptance of a time step, remain frozen. The gradient states are then the exact derivative of the computed state, wherever the discrete decisions do not change. This is forward-mode automatic differentiation with a dual-number type like that of [ForwardDiff](https://github.com/JuliaDiff/ForwardDiff.jl). Gradient vectors cannot represent it, since an inner product of gradient vectors is an ordinary complex number; it requires dual numbers as the scalar type throughout the propagation method. Whether the error control of an adaptive method is itself frozen is a choice of the method. In [OrdinaryDiffEq](https://github.com/SciML/OrdinaryDiffEq.jl), the default error norm of a *complex* state of ForwardDiff dual numbers is a dual number whose value is the norm of the values of the state, and the solver chooses its time steps from that value, as in the frozen semantics. For a *real* state of dual numbers, the default error norm also includes the dual parts, as in the flat semantics. The three semantics coincide for methods that make no choices based on the data, or whose choices do not depend on ``ϵ``: the exact exponential ([Proposition 1](@ref Background-prop-gradgen-exp)), polynomial propagators with fixed coefficients ([Corollary 7](@ref Background-cor-polynomial)), and ODE solvers with a fixed time grid ([Proposition 12](@ref Background-prop-ode-solvers)). They differ for Krylov methods and for adaptive time steps. The propagation methods in `QuantumPropagators` behave as follows when propagating a gradient vector: @@ -376,7 +376,7 @@ The three semantics coincide for methods that make no choices based on the data, | `ExpProp` | none | exact (all coincide) | | [Chebychev](@extref QuantumPropagators :label:`method_cheby`) | spectral range of ``\hat{H}`` ([Proposition 8](@ref Background-prop-charpoly)), fixed at initialization | all coincide | | [Newton](@extref QuantumPropagators :label:`method_newton`) | Krylov subspace and interpolation points, from the full gradient vector | flat | -| ODE solvers with adaptive time steps | time steps, from an error norm of the full gradient vector (by default) | flat | +| ODE solvers with adaptive time steps | time steps, from an error norm of the state ([`frozen_internalnorm`](@ref), the default for a [`GradVector`](@ref)) or of the full gradient vector ([`flat_internalnorm`](@ref)), see the [how-to guide](@ref Howto-ODE) | frozen (default) or flat | ### Relation to automatic differentiation @@ -591,7 +591,7 @@ The block form of ``\hat{U}_G``, Eq. \eqref{eq:gradgen-u-prop}, holds for the e *Proof.* Each step of the method uses only linear combinations with coefficients that depend on the method and the time steps, applications of the generator at fixed times, and, for implicit methods, solutions of linear systems with matrices assembled linearly from ``\mathbb{1}`` and the generator at fixed times. These are the operations for which forward-mode differentiation through gradient generators is exact ([Proposition 6](@ref Background-prop-linear-algebra)). ``\square`` -Thus, differentiating the discretized propagation and discretizing the equation of motion for the derivative \eqref{eq:variational} give the same result, and the gradient is consistent with the computed state to machine precision. This requires that the time steps do not depend on ``u``. With an adaptive step size control, the gradient states are not the exact derivative of the computed state, but they still converge to ``\partial_u |Ψ(T)⟩`` as the tolerance decreases, provided the error control includes the gradient states, as in the [flat semantics](@ref Background-Semantics). +Thus, differentiating the discretized propagation and discretizing the equation of motion for the derivative \eqref{eq:variational} give the same result, and the gradient is consistent with the computed state to machine precision. This requires that the time steps do not depend on ``u``. With an adaptive step size control, the time steps depend on ``u`` through the error estimate, and the gradient states are the exact derivative of the computed state only for time steps held fixed. If the time steps are chosen from the state alone, as in the [frozen semantics](@ref Background-Semantics), the gradient states are the solution of the equation of motion for the derivative, Eq. \eqref{eq:variational}, by the same method on the time grid of the state, and they converge to ``\partial_u |Ψ(T)⟩`` as the tolerance decreases and the time grid is refined, but the tolerance does not control their error directly. If the error control includes the gradient states, as in the [flat semantics](@ref Background-Semantics), it does. The second approach is the piecewise-constant approximation that [`QuantumPropagators`](@extref QuantumPropagators :doc:`index`) uses for time-dependent generators. On each interval of the time grid, the generator is evaluated at a fixed time ``\tilde{t}_n``, by default the midpoint of the interval, giving ``\hat{H}_n(u) = \hat{H}(\tilde{t}_n; u)``, the propagators ``\hat{U}_n = e^{-\ii \hat{H}_n dt_n}``, and the approximate final state ``|\bar{Ψ}(T)⟩ = \hat{U}_{N_T} \cdots \hat{U}_1 |Ψ(0)⟩``. diff --git a/docs/src/howto.md b/docs/src/howto.md index 7952af3..c0a2ebf 100644 --- a/docs/src/howto.md +++ b/docs/src/howto.md @@ -168,17 +168,16 @@ Both the state and the gradient deviate from the exact result at the level of th ## [How to control the time steps of an adaptive ODE solver for gradient vectors](@id Howto-ODE) -When a gradient vector is propagated with an adaptive ODE solver, the error estimate that determines the time steps can include the gradient states or ignore them. With the default error norm, it includes them (the *flat* semantics). With an error norm that looks only at the state, the solver takes exactly the time steps it would take for the state alone (the *frozen* semantics). See [Flat, frozen, and dual semantics](@ref Background-Semantics) for the theory. This guide shows how to select either behavior and what the choice does to the cost and the accuracy of the gradient. +When a gradient vector is propagated with an adaptive ODE solver, the error estimate that determines the time steps can ignore the gradient states or include them. By default, it ignores them, and the solver takes exactly the time steps it would take for the state alone (the *frozen* semantics). With [`flat_internalnorm`](@ref) as the error norm, it includes them (the *flat* semantics). See [Flat, frozen, and dual semantics](@ref Background-Semantics) for the theory. This guide shows how to select either behavior and what the choice does to the cost and the accuracy of the gradient. -The ODE solvers in [OrdinaryDiffEq](https://github.com/SciML/OrdinaryDiffEq.jl) require the state to be an array. A [`GradVector`](@ref) is not an array, so represent the gradient vector as a flat vector with the gradient states first and the state last, ``(|Ψ^\prime_1⟩, \dots, |Ψ^\prime_L⟩, |Ψ⟩)``. A [`GradgenOperator`](@ref) applies to such a vector block by block. +A [`GradVector`](@ref) can be propagated with the ODE solvers in [OrdinaryDiffEq](https://github.com/SciML/OrdinaryDiffEq.jl) like any other state: ```@example ode using LinearAlgebra using Printf using OrdinaryDiffEq -using DiffEqBase: ODE_DEFAULT_NORM using QuantumPropagators: hamiltonian, propagate, init_prop, prop_step! -using QuantumGradientGenerators: GradGenerator +using QuantumGradientGenerators: GradGenerator, GradVector, flat_internalnorm Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 2.1] Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] @@ -189,54 +188,36 @@ tlist = [0.0, T] H(u) = hamiltonian(Ĥ₀ + u * Ĥ₁, (Ĥ₁, ϵ)) G = GradGenerator(H(0.0)) - -N = length(Ψ₀) # dimension of the Hilbert space -L = 1 # number of gradient states -Ψ_flat = [zeros(ComplexF64, L * N); Ψ₀] -state_idxs = (L*N+1):((L+1)*N) -grad_idxs = 1:N # first gradient state nothing # hide ``` As in the [Chebychev guide](@ref Howto-Cheby), the derivative is with respect to a static offset ``u`` of the control. -For the flat semantics, propagate with the default error norm. The flat vector does not pass the interface check that [`propagate`](@extref QuantumPropagators.propagate) runs by default (`GradgenOperator` implements `mul!` for a flat vector, but not `*`), so disable the check with `check = false`: +For the frozen semantics, propagate with the default error norm: ```@example ode -Ψ = propagate( - Ψ_flat, - G, - tlist; - method = OrdinaryDiffEq, - check = false, - reltol = 1e-6, - abstol = 1e-6 -) +Ψ = propagate(GradVector(Ψ₀, 1), G, tlist; method = OrdinaryDiffEq, reltol = 1e-6, abstol = 1e-6) nothing # hide ``` -For the frozen semantics, pass an `internalnorm` that evaluates the default norm on the state component only. OrdinaryDiffEq also calls the norm on individual numbers, which requires a second method: +The default error norm for a gradient vector is [`frozen_internalnorm`](@ref), the default norm of OrdinaryDiffEq (the root mean square of all elements) evaluated for `Ψ.state` only. -```@example ode -state_norm(u::AbstractVector, t) = ODE_DEFAULT_NORM(view(u, state_idxs), t) -state_norm(u::Number, t) = ODE_DEFAULT_NORM(u, t) +For the flat semantics, pass `internalnorm = flat_internalnorm`, the root mean square of all elements of the state and the gradient states: +```@example ode Ψ = propagate( - Ψ_flat, + GradVector(Ψ₀, 1), G, tlist; method = OrdinaryDiffEq, - check = false, reltol = 1e-6, abstol = 1e-6, - internalnorm = state_norm + internalnorm = flat_internalnorm ) nothing # hide ``` -In either case, the state is `Ψ[state_idxs]` and the gradient state is `Ψ[grad_idxs]`. - -To decide between the two, compare them over a range of tolerances. The following propagates the state alone, and the gradient vector in both modes, and reports the number of time steps (from the underlying OrdinaryDiffEq integrator), the deviation of the state from the propagation of the state alone, and the error of the gradient relative to a reference propagation with a tight tolerance: +To decide between the two, compare them over a range of tolerances. The following propagates the state alone ("bare"), and the gradient vector with both norms, and reports the number of time steps (from the underlying OrdinaryDiffEq integrator), the deviation of the state from the propagation of the state alone, and the error of the gradient relative to a reference propagation with a tight tolerance: ```@example ode function propagate_ode(Ψ, generator; kwargs...) @@ -245,9 +226,9 @@ function propagate_ode(Ψ, generator; kwargs...) return copy(propagator.state), propagator.integrator.stats.naccept end -Ψ_ref, _ = propagate_ode(Ψ_flat, G; alg = Vern9(), reltol = 1e-14, abstol = 1e-14) +Ψ_ref, _ = propagate_ode(GradVector(Ψ₀, 1), G; alg = Vern9(), reltol = 1e-14, abstol = 1e-14) -@printf("%7s | %5s | %-27s | %-27s\n", "", "bare", "flat", "frozen") +@printf("%7s | %5s | %-27s | %-27s\n", "", "bare", "frozen", "flat") @printf( "%7s | %5s | %5s %10s %10s | %5s %10s %10s\n", "tol", @@ -262,22 +243,24 @@ end for tol in (1e-4, 1e-6, 1e-8, 1e-10) kw = (; reltol = tol, abstol = tol) Ψ_bare, n_bare = propagate_ode(Ψ₀, H(0.0); kw...) - Ψ_flat_T, n_flat = propagate_ode(Ψ_flat, G; kw...) - Ψ_frozen_T, n_frozen = propagate_ode(Ψ_flat, G; internalnorm = state_norm, kw...) + Ψ_frozen, n_frozen = propagate_ode(GradVector(Ψ₀, 1), G; kw...) + Ψ_flat, n_flat = propagate_ode(GradVector(Ψ₀, 1), G; internalnorm = flat_internalnorm, kw...) @printf( "%7.0e | %5d | %5d %10.2e %10.2e | %5d %10.2e %10.2e\n", tol, n_bare, - n_flat, - norm(Ψ_flat_T[state_idxs] - Ψ_bare), - norm(Ψ_flat_T[grad_idxs] - Ψ_ref[grad_idxs]), n_frozen, - norm(Ψ_frozen_T[state_idxs] - Ψ_bare), - norm(Ψ_frozen_T[grad_idxs] - Ψ_ref[grad_idxs]), + norm(Ψ_frozen.state - Ψ_bare), + norm(Ψ_frozen.grad_states[1] - Ψ_ref.grad_states[1]), + n_flat, + norm(Ψ_flat.state - Ψ_bare), + norm(Ψ_flat.grad_states[1] - Ψ_ref.grad_states[1]), ) end ``` -With the frozen norm, the solver takes the same time steps as for the state alone, and the state component is identical to the propagation of the state without gradients. The gradient is the derivative of the computed state, except for the dependence of the time steps on ``u``, and its error is of the order of the propagation error. With the default (flat) norm, the gradient states contribute to the error estimate. The solver then takes more time steps, the state deviates from the propagation of the state alone within the tolerance, and the gradient is more accurate at the same tolerance. +With the default (frozen) norm, the solver takes the same time steps as for the state alone, and the state component is identical to the propagation of the state without gradients. The gradient is the derivative of the computed state, except for the dependence of the time steps on ``u``. Its error is a few times the tolerance. With the flat norm, the gradient states contribute to the error estimate. The solver then takes more time steps, the state deviates from the propagation of the state alone within the tolerance, and the error of the gradient is about the tolerance. The flat norm is not more efficient per time step, though: in this example, tightening the tolerance of the frozen propagation by a factor of about 3 gives a gradient about as accurate as the flat one, at about the same number of time steps. + +Keep the default when the state must agree exactly with a propagation without gradients, e.g., when a functional is evaluated from separately propagated states and its gradient from gradient vectors. Use the flat norm when the tolerance should bound the error of the gradient directly, without calibrating it. -Use the frozen norm when the state must agree exactly with a propagation without gradients, e.g., when a functional is evaluated from separately propagated states and its gradient from gradient vectors, or when the cost of each time step matters more than the accuracy of the gradient at a given tolerance. Use the default norm when the accuracy of the gradient should be controlled directly by the tolerance. The default norm of DifferentialEquations for the dual numbers of [ForwardDiff](https://github.com/JuliaDiff/ForwardDiff.jl) also includes the dual parts, so forward-mode automatic differentiation through the solver follows the flat semantics as well. +The default is also what forward-mode automatic differentiation with the dual numbers of [ForwardDiff](https://github.com/JuliaDiff/ForwardDiff.jl) does: for a complex state of dual numbers, the default error norm of OrdinaryDiffEq is itself a dual number, whose value is the norm of the values of the state, and the solver chooses its time steps from that value. The result is the same as for a gradient vector with the default norm, except that rounding errors in the error estimate can occasionally change the acceptance of a time step at the threshold of the tolerance, and with it the subsequent time steps. diff --git a/ext/QuantumGradientGeneratorsDiffEqBaseExt.jl b/ext/QuantumGradientGeneratorsDiffEqBaseExt.jl new file mode 100644 index 0000000..f74b523 --- /dev/null +++ b/ext/QuantumGradientGeneratorsDiffEqBaseExt.jl @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +module QuantumGradientGeneratorsDiffEqBaseExt + +import DiffEqBase: ODE_DEFAULT_NORM +import QuantumGradientGenerators: GradVector, frozen_internalnorm, flat_internalnorm + + +frozen_internalnorm(Ψ::GradVector, t) = ODE_DEFAULT_NORM(Ψ.state, t) +frozen_internalnorm(u::Number, t) = ODE_DEFAULT_NORM(u, t) + + +function flat_internalnorm(Ψ::GradVector, t) + # The root mean square of all elements, from the root mean square of each + # block: (Σ_blocks n_b · rms_b²) / (Σ_blocks n_b) + n = length(Ψ.state) + sum_abs2 = n * ODE_DEFAULT_NORM(Ψ.state, t)^2 + for Ψ′ in Ψ.grad_states + n′ = length(Ψ′) + sum_abs2 += n′ * ODE_DEFAULT_NORM(Ψ′, t)^2 + n += n′ + end + return sqrt(sum_abs2 / max(n, 1)) +end + +flat_internalnorm(u::Number, t) = ODE_DEFAULT_NORM(u, t) + + +# Default: frozen semantics. Without this method, OrdinaryDiffEq would fall +# back to `norm(Ψ)`, the Euclidean norm, which unlike the root mean square +# scales with the dimension. +ODE_DEFAULT_NORM(Ψ::GradVector, t) = frozen_internalnorm(Ψ, t) + +end diff --git a/ext/QuantumGradientGeneratorsExponentialUtilitiesExt.jl b/ext/QuantumGradientGeneratorsExponentialUtilitiesExt.jl new file mode 100644 index 0000000..33b4ed9 --- /dev/null +++ b/ext/QuantumGradientGeneratorsExponentialUtilitiesExt.jl @@ -0,0 +1,31 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +module QuantumGradientGeneratorsExponentialUtilitiesExt + +# The Krylov propagation of ExponentialUtilities builds its Krylov subspace from +# a `GradVector` via the vector interface (`eachindex`, `getindex`) and the +# flat `mul!` of a `GradgenOperator`, but `expv!` only accepts an +# `AbstractVector` as its output `w`. A `GradVector` is not an `AbstractVector`, +# and `similar(Ψ, T)` returns a `GradVector` (which ODE solvers rely on), so +# `expv(t, A, Ψ)` passes a `GradVector` as `w`. We compute the result in a flat +# `Vector`, with the gradient states first and the state last (the layout of +# `getindex` for a `GradVector`), and copy it into `w` block by block. + +import ExponentialUtilities: expv!, KrylovSubspace +import QuantumGradientGenerators: GradVector, _copy_flat! + + +# This allocates the flat buffer in every call. The out-of-place `expv` +# allocates its result anyway. For in-place propagation, a propagator should +# keep a flat buffer as a workspace, call `expv!` for that buffer, and copy it +# into the gradient vector (`Ψ .= buffer`), which avoids this method. +function expv!(w::GradVector, t::Number, Ks::KrylovSubspace; kwargs...) + w_flat = Vector{eltype(w)}(undef, length(w)) + expv!(w_flat, t, Ks; kwargs...) + return _copy_flat!(w, w_flat) +end + + +end diff --git a/ext/QuantumGradientGeneratorsRecursiveArrayToolsExt.jl b/ext/QuantumGradientGeneratorsRecursiveArrayToolsExt.jl new file mode 100644 index 0000000..b6b4c2c --- /dev/null +++ b/ext/QuantumGradientGeneratorsRecursiveArrayToolsExt.jl @@ -0,0 +1,17 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +module QuantumGradientGeneratorsRecursiveArrayToolsExt + +# ODE solvers (OrdinaryDiffEq) copy and fill their state with the "recursive" +# functions of RecursiveArrayTools + +import RecursiveArrayTools: recursivecopy, recursivecopy!, recursivefill! +import QuantumGradientGenerators: GradVector + +recursivecopy(Ψ::GradVector) = copy(Ψ) +recursivecopy!(dest::GradVector, src::GradVector) = copyto!(dest, src) +recursivefill!(Ψ::GradVector, v) = fill!(Ψ, v) + +end diff --git a/src/QuantumGradientGenerators.jl b/src/QuantumGradientGenerators.jl index 9727859..5591888 100644 --- a/src/QuantumGradientGenerators.jl +++ b/src/QuantumGradientGenerators.jl @@ -5,12 +5,15 @@ module QuantumGradientGenerators export GradGenerator, GradgenOperator, GradVector, resetgradvec! +export frozen_internalnorm, flat_internalnorm include("grad_generator.jl") include("gradgen_operator.jl") include("grad_vector.jl") include("evaluate.jl") include("linalg.jl") +include("broadcast.jl") include("spectral.jl") +include("internalnorm.jl") end diff --git a/src/broadcast.jl b/src/broadcast.jl new file mode 100644 index 0000000..eb50d3d --- /dev/null +++ b/src/broadcast.jl @@ -0,0 +1,106 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +# Broadcasting over gradient vectors and scalars operates block by block: +# `Ψ .+ c .* Φ` is evaluated as `Ψ.state .+ c .* Φ.state` and +# `Ψ.grad_states[l] .+ c .* Φ.grad_states[l]` for each `l`. This is how ODE +# solvers (OrdinaryDiffEq) update their state, and it avoids indexing into the +# gradient vector element by element. All `GradVector` arguments must have the +# same number of gradient states. +# +# Broadcasting a gradient vector together with an array treats the gradient +# vector as a flat vector with the gradient states first and the state last +# (the layout of `getindex`), e.g., `V[:, 1] .= Ψ ./ β` in the Krylov methods of +# ExponentialUtilities. This requires the vector interface +# (`supports_vector_interface`) and indexes the gradient vector element by +# element. + +using Base.Broadcast: Broadcasted, BroadcastStyle, AbstractArrayStyle, DefaultArrayStyle + + +struct GradVectorStyle <: BroadcastStyle end + +Base.BroadcastStyle(::Type{<:GradVector}) = GradVectorStyle() + +# With scalars (and `Ref`): block by block +Base.BroadcastStyle(s::GradVectorStyle, ::AbstractArrayStyle{0}) = s + +# With arrays: flat +Base.BroadcastStyle(::GradVectorStyle, s::AbstractArrayStyle) = s + +Base.broadcastable(Ψ::GradVector) = Ψ + +Base.ndims(::Type{<:GradVector}) = 1 + +# The blocks are only known when the broadcast is materialized +Base.Broadcast.instantiate(bc::Broadcasted{GradVectorStyle}) = bc + +# Element access for flat broadcasting +Base.getindex(Ψ::GradVector, I::CartesianIndex{1}) = Ψ[I[1]] + + +# The block `l` of a broadcast argument: the state for `l = 0`, the gradient +# state `l` otherwise +_block(Ψ::GradVector, l) = (l == 0) ? Ψ.state : Ψ.grad_states[l] +_block(bc::Broadcasted, l) = Broadcasted(bc.f, map(arg -> _block(arg, l), bc.args)) +_block(x, l) = x + +_num_grad_states(bc::Broadcasted) = _num_grad_states(bc.args...) +_num_grad_states(Ψ::GradVector, args...) = length(Ψ.grad_states) +_num_grad_states(bc::Broadcasted, args...) = + something(_num_grad_states(bc), _num_grad_states(args...)) +_num_grad_states(x, args...) = _num_grad_states(args...) +_num_grad_states() = nothing + +_materialize_block(bc, l) = Base.Broadcast.materialize(_block(bc, l)) + + +function Base.copy(bc::Broadcasted{GradVectorStyle}) + L = _num_grad_states(bc) + state = _materialize_block(bc, 0) + grad_states = [_materialize_block(bc, l) for l = 1:L] + return GradVector{L,typeof(state)}(state, grad_states) +end + + +function Base.copyto!(dest::GradVector, bc::Broadcasted{GradVectorStyle}) + Base.Broadcast.materialize!(dest.state, _block(bc, 0)) + for l in eachindex(dest.grad_states) + Base.Broadcast.materialize!(dest.grad_states[l], _block(bc, l)) + end + return dest +end + + +# Only scalars on the right-hand side, e.g., `Ψ .= 0` +function Base.copyto!(dest::GradVector, bc::Broadcasted{<:AbstractArrayStyle{0}}) + copyto!(dest.state, bc) + for l in eachindex(dest.grad_states) + copyto!(dest.grad_states[l], bc) + end + return dest +end + + +# Arrays on the right-hand side: flat +function Base.copyto!(dest::GradVector, bc::Broadcasted{<:AbstractArrayStyle}) + return _copy_flat!(dest, Base.Broadcast.materialize(bc)) +end + + +# Copy a flat vector (gradient states first, state last) into a gradient vector +function _copy_flat!(Ψ::GradVector, v::AbstractVector) + N = length(Ψ.state) + L = length(Ψ.grad_states) + (length(v) == (L + 1) * N) || throw( + DimensionMismatch( + "A flat vector of length $(length(v)) does not match a GradVector of length $((L + 1) * N)" + ) + ) + for l = 1:L + copyto!(Ψ.grad_states[l], view(v, ((l-1)*N+1):(l*N))) + end + copyto!(Ψ.state, view(v, (L*N+1):((L+1)*N))) + return Ψ +end diff --git a/src/internalnorm.jl b/src/internalnorm.jl new file mode 100644 index 0000000..fd3e629 --- /dev/null +++ b/src/internalnorm.jl @@ -0,0 +1,85 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +# The methods are defined in the `QuantumGradientGeneratorsDiffEqBaseExt` +# extension, since they build on the default norm of DiffEqBase + + +@doc raw"""Error norm of an ODE solver for the frozen semantics. + +```julia +nrm = frozen_internalnorm(Ψ::GradVector, t) +``` + +returns the default norm of OrdinaryDiffEq (`DiffEqBase.ODE_DEFAULT_NORM`, the +root mean square of all elements) of the state `Ψ.state`, ignoring the +gradient states. It is meant to be passed as the `internalnorm` of an ODE +solver: + +```julia +using OrdinaryDiffEq +Ψ = propagate(GradVector(Ψ₀, L), G, tlist; method = OrdinaryDiffEq, internalnorm = frozen_internalnorm) +``` + +The adaptive ODE solver then evaluates its error estimate from the state +component of the gradient vector only, and its time steps are the same as in the propagation of `Ψ.state` without gradients, so `Ψ.state` is the +result of that propagation (up to floating-point rounding), and the gradient +states are the derivative of that result with the time steps held fixed. This +is the ["frozen" semantics](@ref Background-Semantics) of propagating a +gradient vector. It is also what ForwardDiff dual numbers in a complex state +produce in OrdinaryDiffEq. + +This is the default for a [`GradVector`](@ref): passing +`internalnorm = frozen_internalnorm` gives the same result as passing no +`internalnorm`. For the alternative, see [`flat_internalnorm`](@ref). + +The methods of this function are only defined when DiffEqBase (a dependency +of OrdinaryDiffEq) is loaded. + +```julia +frozen_internalnorm(u::Number, t) +``` + +is the default norm of OrdinaryDiffEq, which ODE solvers use for scalars. +""" +function frozen_internalnorm end + + +@doc raw"""Error norm of an ODE solver for the flat semantics. + +```julia +nrm = flat_internalnorm(Ψ::GradVector, t) +``` + +returns the root mean square of all elements of the state `Ψ.state` and the +gradient states `Ψ.grad_states`. It is meant to be passed as the +`internalnorm` of an ODE solver: + +```julia +using OrdinaryDiffEq +Ψ = propagate(GradVector(Ψ₀, L), G, tlist; method = OrdinaryDiffEq, internalnorm = flat_internalnorm) +``` + +The adaptive ODE solver then evaluates its error estimate from all components +of the gradient vector, as with the default norm of OrdinaryDiffEq for a +`Vector` of all the elements of the gradient vector. The time steps then depend +on the gradient states, so `Ψ.state` deviates from the propagation of the +state without gradients, within the tolerance of the solver. The gradient +states approximate the exact derivative of the propagated state, to the same +tolerance. This is the ["flat" semantics](@ref Background-Semantics) of +propagating a gradient vector. + +Without `internalnorm`, an ODE solver uses [`frozen_internalnorm`](@ref) for +a [`GradVector`](@ref). + +The methods of this function are only defined when DiffEqBase (a dependency +of OrdinaryDiffEq) is loaded. + +```julia +flat_internalnorm(u::Number, t) +``` + +is the default norm of OrdinaryDiffEq, which ODE solvers use for scalars. +""" +function flat_internalnorm end diff --git a/src/linalg.jl b/src/linalg.jl index 398d850..338c8b4 100644 --- a/src/linalg.jl +++ b/src/linalg.jl @@ -237,8 +237,14 @@ function Base.similar(Ψ::GradVector{num_controls,T}) where {num_controls,T} return GradVector{num_controls,typeof(state_sim)}(state_sim, grad_states_sim) end -# similar(Ψ, S) calls length(Ψ), which will error if !supports_vector_interface -Base.similar(Ψ::GradVector, ::Type{S}) where {S} = Vector{S}(undef, length(Ψ)) +# A gradient vector with element type S. ODE solvers (OrdinaryDiffEq) use this +# for the buffer of their error estimate, so it must have the block structure +# of `Ψ` for the error norm to distinguish the state from the gradient states. +function Base.similar(Ψ::GradVector{num_controls,T}, ::Type{S}) where {num_controls,T,S} + state_sim = similar(Ψ.state, S) + grad_states_sim = [similar(Ψ′, S) for Ψ′ ∈ Ψ.grad_states] + return GradVector{num_controls,typeof(state_sim)}(state_sim, grad_states_sim) +end # similar(Ψ, dims) calls eltype(Ψ) but not length/size, so no vector interface needed Base.similar(Ψ::GradVector, dims::Tuple{Vararg{Int}}) = Array{eltype(Ψ)}(undef, dims) diff --git a/test/Project.toml b/test/Project.toml index 6633bc6..15b5ca4 100644 --- a/test/Project.toml +++ b/test/Project.toml @@ -1,5 +1,9 @@ [deps] +DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e" +ExponentialUtilities = "d4d017d3-3776-5f7e-afef-a10c40355c18" +ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" +OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" QuantumControl = "8a270532-f23f-47a8-83a9-b33d10cad486" QuantumControlTestUtils = "d3fd27c9-1dfb-4e67-b0c0-90d0d87a1e48" QuantumGradientGenerators = "a563f35e-61db-434d-8c01-8b9e3ccdfd85" @@ -14,5 +18,9 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f" QuantumGradientGenerators = {path = ".."} [compat] +DiffEqBase = "6.147, 7" +ExponentialUtilities = "1.17.1" +ForwardDiff = "0.10, 1" +OrdinaryDiffEq = "6.62, 7" QuantumPropagators = "0.9" julia = "1.10" diff --git a/test/runtests.jl b/test/runtests.jl index 7297338..ed2c4da 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -23,6 +23,16 @@ using SafeTestsets include("test_properties.jl") end + print("\n* OrdinaryDiffEq (test_ode.jl):") + @time @safetestset "OrdinaryDiffEq" begin + include("test_ode.jl") + end + + print("\n* ExponentialUtilities (test_expv.jl):") + @time @safetestset "ExponentialUtilities" begin + include("test_expv.jl") + end + print("\n* Interface (test_interface.jl):") @time @safetestset "Interface" begin include("test_interface.jl") diff --git a/test/test_expv.jl b/test/test_expv.jl new file mode 100644 index 0000000..4ca1d76 --- /dev/null +++ b/test/test_expv.jl @@ -0,0 +1,29 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +using Test +using LinearAlgebra: norm +using QuantumPropagators: hamiltonian, propagate, ExpProp +using QuantumGradientGenerators: GradGenerator, GradVector +import ExponentialUtilities + + +@testset "ExponentialUtilities (inplace=$inplace)" for inplace in (true, false) + + # The Krylov propagation of ExponentialUtilities allocates its result with + # `similar(Ψ, T)`, which is a `GradVector`, and passes it to `expv!` + Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 2.1] + Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] + ϵ(t) = 0.3 * sin(π * t / 5)^2 + G = GradGenerator(hamiltonian(Ĥ₀, (Ĥ₁, ϵ))) + tlist = collect(range(0, 5; length = 51)) + Ψ₀ = ComplexF64[1, 0, 0] + + Ψ_exact = propagate(GradVector(Ψ₀, 1), G, tlist; method = ExpProp) + Ψ = propagate(GradVector(Ψ₀, 1), G, tlist; method = ExponentialUtilities, inplace) + @test Ψ isa GradVector{1,Vector{ComplexF64}} + @test norm(Ψ.state - Ψ_exact.state) < 1e-12 + @test norm(Ψ.grad_states[1] - Ψ_exact.grad_states[1]) < 1e-12 + +end diff --git a/test/test_interface.jl b/test/test_interface.jl index b2420dd..4d3de5a 100644 --- a/test/test_interface.jl +++ b/test/test_interface.jl @@ -203,7 +203,7 @@ end Φ3 = rand(rng, ComplexF64, N * (L + 1)) Φ3_init = copy(Φ3) mul!(Φ3, G, Ψ_flat, α, β) - @test norm(Φ3 - (α * Φ_ref + β * Φ3_init)) < 1e-14 + @test norm(Φ3 - (α * Φ_ref + β * Φ3_init)) < 1e-13 # works with views (the actual ExponentialUtilities use case) V = rand(rng, ComplexF64, N * (L + 1), 4) @@ -256,8 +256,10 @@ end end @test all(gradvec2[k] == gradvec[k] for k = 1:length(gradvec)) - # similar(gradvec, S) returns a mutable Vector{S} with same length - @test similar(gradvec, ComplexF32) isa Vector{ComplexF32} + # similar(gradvec, S) returns a gradient vector with element type S and the + # same block structure + @test similar(gradvec, ComplexF32) isa GradVector{L,Vector{ComplexF32}} + @test eltype(similar(gradvec, ComplexF32)) == ComplexF32 @test length(similar(gradvec, ComplexF32)) == length(gradvec) # similar(gradvec, dims) returns a plain Array with same eltype and given dims diff --git a/test/test_ode.jl b/test/test_ode.jl new file mode 100644 index 0000000..6c8b754 --- /dev/null +++ b/test/test_ode.jl @@ -0,0 +1,248 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +using Test +using LinearAlgebra: norm, mul!, lmul! +using QuantumPropagators: hamiltonian, propagate, init_prop, prop_step!, ExpProp, evaluate +using QuantumGradientGenerators: + GradGenerator, GradVector, frozen_internalnorm, flat_internalnorm +import OrdinaryDiffEq +# Only algorithms that OrdinaryDiffEq 6 and 7 both export +using OrdinaryDiffEq: ODEProblem, solve, Tsit5, Vern7, Vern9 +import DiffEqBase +using ForwardDiff: Dual, Tag, value, partials + + +const Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 2.1] +const Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] +const T = 5.0 +ϵ(t) = 0.3 * sin(π * t / T)^2 +const Ψ₀ = ComplexF64[1, 0, 0] +const tlist = [0.0, T] + +const H = hamiltonian(Ĥ₀, (Ĥ₁, ϵ)) +const G = GradGenerator(H) + +# The exact derivative of the propagated state with respect to a static +# offset of the control, from the block exponential on a fine time grid +const Ψ_exact = + propagate(GradVector(Ψ₀, 1), G, collect(range(0, T; length = 2001)); method = ExpProp) + + +# Propagate with OrdinaryDiffEq via QuantumPropagators; return the result and +# the number of accepted time steps +function propagate_ode(Ψ, generator; kwargs...) + propagator = init_prop(Ψ, generator, tlist; method = OrdinaryDiffEq, kwargs...) + prop_step!(propagator) + return copy(propagator.state), propagator.integrator.stats.naccept +end + + +# Propagate a gradient vector directly with OrdinaryDiffEq; return the result +# and the time grid +function propagate_gradvec(alg; kwargs...) + function f!(du, u, p, t) + mul!(du, evaluate(G, t), u) + lmul!(-1im, du) + end + sol = solve(ODEProblem(f!, GradVector(Ψ₀, 1), (0.0, T)), alg; kwargs...) + return sol.u[end], sol.t +end + + +# Propagate a state of ForwardDiff dual numbers for the Hamiltonian at the +# control ϵ(t) + δ, directly with OrdinaryDiffEq. Return the value and the +# derivative with respect to δ, and the number of accepted time steps. +function propagate_dual(alg; kwargs...) + # A proper tag (not `Nothing`), so that the dual numbers can be ordered + # with the tags of the automatic differentiation in DiffEqBase + δ = Dual{typeof(Tag(propagate_dual, Float64))}(0.0, 1.0) + f!(du, u, p, t) = (du .= -1im .* ((Ĥ₀ .+ (ϵ(t) + p) .* Ĥ₁) * u)) + u₀ = Complex{typeof(δ)}.(Ψ₀) + sol = solve(ODEProblem(f!, u₀, (0.0, T), δ), alg; save_everystep = false, kwargs...) + u = sol.u[end] + Ψ = value.(real.(u)) .+ 1im .* value.(imag.(u)) + ∂Ψ = partials.(real.(u), 1) .+ 1im .* partials.(imag.(u), 1) + return Ψ, ∂Ψ, sol.stats.naccept +end + + +@testset "Blockwise broadcasting" begin + + Ψ = GradVector(ComplexF64[1, 2, 3], 2) + Ψ.grad_states[1] .= ComplexF64[4, 5, 6] + Ψ.grad_states[2] .= ComplexF64[7, 8, 9] + Φ = GradVector(ComplexF64[1im, 0, 0], 2) + Φ.grad_states[2] .= 1.0 + + Θ = Ψ .+ 2 .* Φ + @test Θ isa GradVector{2,Vector{ComplexF64}} + @test Θ.state == Ψ.state .+ 2 .* Φ.state + @test Θ.grad_states[1] == Ψ.grad_states[1] .+ 2 .* Φ.grad_states[1] + @test Θ.grad_states[2] == Ψ.grad_states[2] .+ 2 .* Φ.grad_states[2] + + Θ = similar(Ψ) + Θ .= Ψ .* Φ .- 1im + @test Θ.state == Ψ.state .* Φ.state .- 1im + @test Θ.grad_states[2] == Ψ.grad_states[2] .* Φ.grad_states[2] .- 1im + + Θ .= 0 + @test norm(Θ) == 0.0 + + A = abs2.(Ψ) + @test A isa GradVector{2,Vector{Float64}} + @test A.grad_states[1] == [16.0, 25.0, 36.0] + + # Together with an array, a gradient vector is a flat vector with the + # gradient states first and the state last (the layout of `getindex`) + flat = [Ψ.grad_states[1]; Ψ.grad_states[2]; Ψ.state] + v = collect(ComplexF64, 1:9) + @test (Ψ .+ v) isa Vector{ComplexF64} + @test (Ψ .+ v) == flat .+ v + w = zeros(ComplexF64, 9) + w .= Ψ ./ 2 + @test w == flat ./ 2 + Θ = similar(Ψ) + Θ .= v .* Ψ + @test Θ.grad_states[2] == v[4:6] .* Ψ.grad_states[2] + @test Θ.state == v[7:9] .* Ψ.state + @test_throws DimensionMismatch (Θ .= ones(ComplexF64, 4)) + + # Buffers for the error estimate of ODE solvers keep the block structure + R = similar(Ψ, Float64) + @test R isa GradVector{2,Vector{Float64}} + @test length(R.state) == 3 + +end + + +@testset "ODE error norms" begin + + Ψ = GradVector(ComplexF64[3, 4, 0, 0], 1) + Ψ.grad_states[1] .= ComplexF64[0, 0, 12, 0] + # root mean square of the state: √(25/4) = 2.5 + @test frozen_internalnorm(Ψ, 0.0) ≈ 2.5 + @test DiffEqBase.ODE_DEFAULT_NORM(Ψ, 0.0) ≈ 2.5 + # root mean square of all 8 elements: √(169/8) + @test flat_internalnorm(Ψ, 0.0) ≈ √(169 / 8) + flat_vector = [Ψ.grad_states[1]; Ψ.state] + @test flat_internalnorm(Ψ, 0.0) ≈ DiffEqBase.ODE_DEFAULT_NORM(flat_vector, 0.0) + @test frozen_internalnorm(-2.0 + 0im, 0.0) == 2.0 + @test flat_internalnorm(-2.0, 0.0) == 2.0 + +end + + +@testset "OrdinaryDiffEq: frozen semantics by default" begin + + tol = (; reltol = 1e-6, abstol = 1e-6) + Ψ_bare, n_bare = propagate_ode(Ψ₀, H; tol...) + Ψ, n = propagate_ode(GradVector(Ψ₀, 1), G; tol...) + Ψ_frozen, n_frozen = + propagate_ode(GradVector(Ψ₀, 1), G; tol..., internalnorm = frozen_internalnorm) + + # The time steps, and therefore the state, are those of the propagation + # without gradients + @test n == n_bare + @test norm(Ψ.state - Ψ_bare) < 1e-14 + # The default is `frozen_internalnorm` + @test n_frozen == n + @test norm(Ψ_frozen.state - Ψ.state) == 0.0 + @test norm(Ψ_frozen.grad_states[1] - Ψ.grad_states[1]) == 0.0 + + # The gradient approximates the exact derivative within the tolerance + @test norm(Ψ.grad_states[1] - Ψ_exact.grad_states[1]) < 1e-4 + + # `propagate` passes its interface check for the gradient vector + Ψ = propagate(GradVector(Ψ₀, 1), G, tlist; method = OrdinaryDiffEq, tol...) + @test norm(Ψ.state - Ψ_bare) < 1e-14 + +end + + +@testset "OrdinaryDiffEq: default norm of complex dual numbers" begin + + # 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, so the time steps do not depend on the dual parts + TT = typeof(Tag(propagate_dual, Float64)) + vals = ComplexF64[1+2im, -0.5im, 3.0, 0.1-0.2im] + duals = ComplexF64[10im, 5.0, -3+1im, 2.0] + u = [ + Complex(Dual{TT}(real(v), real(d)), Dual{TT}(imag(v), imag(d))) for + (v, d) in zip(vals, duals) + ] + nrm = DiffEqBase.ODE_DEFAULT_NORM(u, 0.0) + @test value(nrm) ≈ DiffEqBase.ODE_DEFAULT_NORM(vals, 0.0) + @test !(value(nrm) ≈ DiffEqBase.ODE_DEFAULT_NORM([vals; duals], 0.0)) + +end + + +@testset "OrdinaryDiffEq: frozen semantics = ForwardDiff ($(nameof(typeof(alg))), tol=$tol)" for alg in + ( + Tsit5(), + Vern7(), + Vern9() + ), + tol in (1e-4, 1e-8) + + # On the time grid of the gradient vector in the frozen semantics, the + # gradient is the derivative of the computed state (ForwardDiff) + Ψ, ts = propagate_gradvec(alg; reltol = tol, abstol = tol) + Ψ_dual, ∂Ψ_dual, _ = propagate_dual(alg; adaptive = false, dt = T, tstops = ts) + @test norm(Ψ.state - Ψ_dual) < 1e-13 + @test norm(Ψ.grad_states[1] - ∂Ψ_dual) < 1e-13 + + # With adaptive time steps, the dual numbers take the same time steps, but + # the default norm of OrdinaryDiffEq sums with `@fastmath`, so its + # rounding errors differ between `ComplexF64` and dual numbers, and + # between CPUs. This can flip the acceptance of a time step at the + # threshold of the tolerance, after which the time steps and the results + # differ by much less than the tolerance. + Ψ_dual, ∂Ψ_dual, n_dual = propagate_dual(alg; reltol = tol, abstol = tol) + @test abs((length(ts) - 1) - n_dual) <= 1 + @test norm(Ψ.state - Ψ_dual) < tol + @test norm(Ψ.grad_states[1] - ∂Ψ_dual) < tol + +end + + +@testset "OrdinaryDiffEq: flat semantics" begin + + tol = (; reltol = 1e-6, abstol = 1e-6) + Ψ_bare, n_bare = propagate_ode(Ψ₀, H; tol...) + Ψ, n = propagate_ode(GradVector(Ψ₀, 1), G; tol..., internalnorm = flat_internalnorm) + + # Same as the default norm for a flat vector of all elements, up to + # rounding errors in the error estimate (`flat_internalnorm` sums block by + # block), which can flip the acceptance of a time step at the threshold + Ψ_flat = [zeros(ComplexF64, 3); Ψ₀] + Ψ_flat, n_flat = propagate_ode(Ψ_flat, G; tol...) + @test abs(n - n_flat) <= 1 + @test norm(Ψ.state - Ψ_flat[4:6]) < 1e-6 + @test norm(Ψ.grad_states[1] - Ψ_flat[1:3]) < 1e-6 + + # The time steps take into account the gradient state, which changes the + # state within the tolerance + @test n > n_bare + @test 0 < norm(Ψ.state - Ψ_bare) < 1e-5 + @test norm(Ψ.grad_states[1] - Ψ_exact.grad_states[1]) < 1e-4 + +end + + +@testset "OrdinaryDiffEq: fixed time steps" begin + + # With fixed time steps, the frozen and the flat semantics coincide, and + # the gradient is the derivative of the propagated state (ForwardDiff) + kw = (; alg = Tsit5(), adaptive = false, dt = 0.05) + Ψ_dual, ∂Ψ_dual, _ = propagate_dual(kw.alg; adaptive = false, dt = 0.05) + Ψ_frozen, _ = propagate_ode(GradVector(Ψ₀, 1), G; kw...) + Ψ_flat, _ = propagate_ode(GradVector(Ψ₀, 1), G; kw..., internalnorm = flat_internalnorm) + @test norm(Ψ_frozen.grad_states[1] - ∂Ψ_dual) < 1e-13 + @test norm(Ψ_flat.grad_states[1] - ∂Ψ_dual) < 1e-13 + @test norm(Ψ_frozen.state - Ψ_dual) < 1e-13 + +end