Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
11 changes: 10 additions & 1 deletion Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
2 changes: 0 additions & 2 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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"
Expand Down
6 changes: 3 additions & 3 deletions docs/src/background.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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)⟩``.

Expand Down
Loading