diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fea790..1319f5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,9 +16,14 @@ 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` * 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 * Fixed: `isreal` for a `GradgenOperator` no longer throws a `MethodError` +* 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 ## [v0.1.10] — 2026-09-16 diff --git a/docs/Project.toml b/docs/Project.toml index f6f6849..d163a5e 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,8 +1,12 @@ [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" +LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" +OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f" +Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" QuantumControl = "8a270532-f23f-47a8-83a9-b33d10cad486" QuantumGradientGenerators = "a563f35e-61db-434d-8c01-8b9e3ccdfd85" QuantumPropagators = "7bf12567-5742-4b91-a078-644e72a65fc1" @@ -11,7 +15,11 @@ QuantumPropagators = "7bf12567-5742-4b91-a078-644e72a65fc1" QuantumGradientGenerators = {path = ".."} [compat] -Documenter = "1.4" +DiffEqBase = "6, 7" +Documenter = "1.18" DocumenterCitations = "1.5" DocumenterInterLinks = "1.1" +LinearAlgebra = "1" +OrdinaryDiffEq = "6.59, 7" +Printf = "1" julia = "1.10" diff --git a/docs/make.jl b/docs/make.jl index b84041f..426a85f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -38,6 +38,7 @@ bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style = :numer PAGES = [ "Home" => "index.md", + "How-to Guides" => "howto.md", "Background" => "background.md", "API" => "api.md", "References" => "references.md", @@ -58,6 +59,7 @@ makedocs(; asset( "https://juliaquantumcontrol.github.io/QuantumControl.jl/dev/assets/topbar/topbar.js" ), + "assets/admonitions.css", ], mathengine = MathJax3( Dict( diff --git a/docs/src/assets/admonitions.css b/docs/src/assets/admonitions.css new file mode 100644 index 0000000..4eaa2db --- /dev/null +++ b/docs/src/assets/admonitions.css @@ -0,0 +1,13 @@ +/* + * SPDX-FileCopyrightText: © 2026 Michael Goerz + * + * SPDX-License-Identifier: MIT OR CC0-1.0 + */ + +/* A link to an anchor `[](@id ...)` at the start of an admonition body (e.g., + * a proposition) should show the admonition's title, not scroll it under the + * top bar. The top bar's own height is already accounted for by its + * `scroll-padding-top`. */ +.admonition-body span[id] { + scroll-margin-top: 3rem; +} diff --git a/docs/src/background.md b/docs/src/background.md index 828f601..e42e42b 100644 --- a/docs/src/background.md +++ b/docs/src/background.md @@ -96,13 +96,15 @@ From here on, we consider a single control ``ϵ``, with ``G = \left(\begin{small Let ``\hat{H}(ϵ)`` be constant in time and continuously differentiable in the real control value ``ϵ``, with ``\hat{μ} = \partial \hat{H} / \partial ϵ``. We write ``\hat{U}(t) = e^{-\ii \hat{H}(ϵ) t}``, leaving the dependence on ``ϵ`` implicit, and ``\partial_ϵ \hat{U} \equiv \partial \hat{U} / \partial ϵ``. Note that ``\hat{H}`` and ``\hat{μ}`` generally do not commute. -**Proposition 1.** For every real ``t``, +!!! proposition "Proposition 1" -```math -\begin{equation}\label{eq:gradgen-exp} -e^{-\ii G t} = \begin{pmatrix} \hat{U}(t) & \partial_ϵ \hat{U}(t) \\ 0 & \hat{U}(t) \end{pmatrix}\,. -\end{equation} -``` + [](@id Background-prop-gradgen-exp)For every real ``t``, + + ```math + \begin{equation}\label{eq:gradgen-exp} + e^{-\ii G t} = \begin{pmatrix} \hat{U}(t) & \partial_ϵ \hat{U}(t) \\ 0 & \hat{U}(t) \end{pmatrix}\,. + \end{equation} + ``` In particular, for ``t = dt``, ``e^{-\ii G dt} (0, |Ψ⟩) = (\partial_ϵ \hat{U} |Ψ⟩, \hat{U} |Ψ⟩)``, which together with the [reduction to a single control](@ref Background-Reduction) proves Eq. \eqref{eq:main}. @@ -128,7 +130,7 @@ Let ``W(t)`` be the right-hand side of Eq. \eqref{eq:gradgen-exp}. Since ``\hat The matrix ``e^{-\ii G t}`` solves the same linear differential equation with the same initial value, so ``W(t) = e^{-\ii G t}`` by uniqueness of the solution. ``\square`` -Since ``t`` may be negative, Proposition 1 also covers the backward propagation in GRAPE, with ``\hat{H}`` replaced by ``\hat{H}^\dagger`` and ``dt`` by ``dt^{(-)} < 0``: as ``\partial \hat{H}^\dagger / \partial ϵ = \hat{μ}^\dagger`` for a real ``ϵ``, the gradient generator ``G[\hat{H}^\dagger]`` has ``\hat{μ}^\dagger`` in its upper right block. +Since the block form of ``e^{-\ii G t}`` in Eq. \eqref{eq:gradgen-exp} holds for negative ``t`` as well, it also covers the backward propagation in GRAPE, with ``\hat{H}`` replaced by ``\hat{H}^\dagger`` and ``dt`` by ``dt^{(-)} < 0``: as ``\partial \hat{H}^\dagger / \partial ϵ = \hat{μ}^\dagger`` for a real ``ϵ``, the gradient generator ``G[\hat{H}^\dagger]`` has ``\hat{μ}^\dagger`` in its upper right block. Eq. \eqref{eq:ode-dU} is an inhomogeneous linear equation with zero initial value. Its solution by variation of constants is @@ -153,20 +155,22 @@ which for ``t = dt`` is the [expansion used by `GRAPE.jl` with `gradient_method= ### Non-zero gradient states and multiple time steps -Applying Eq. \eqref{eq:gradgen-exp} to a gradient vector with an arbitrary gradient state gives the following result. +Applying the block form of ``e^{-\ii G t}``, Eq. \eqref{eq:gradgen-exp}, to a gradient vector with an arbitrary gradient state gives the following result. -**Corollary 2.** For any ``|Ψ^\prime⟩`` and ``|Ψ⟩``, +!!! corollary "Corollary 2" -```math -\begin{equation}\label{eq:chain} -e^{-\ii G dt} \begin{pmatrix} |Ψ^\prime⟩ \\ |Ψ⟩ \end{pmatrix} -= \begin{pmatrix} \hat{U} |Ψ^\prime⟩ + \partial_ϵ \hat{U} |Ψ⟩ \\ \hat{U} |Ψ⟩ \end{pmatrix}\,. -\end{equation} -``` + [](@id Background-cor-gradient-state)For any ``|Ψ^\prime⟩`` and ``|Ψ⟩``, + + ```math + \begin{equation}\label{eq:chain} + e^{-\ii G dt} \begin{pmatrix} |Ψ^\prime⟩ \\ |Ψ⟩ \end{pmatrix} + = \begin{pmatrix} \hat{U} |Ψ^\prime⟩ + \partial_ϵ \hat{U} |Ψ⟩ \\ \hat{U} |Ψ⟩ \end{pmatrix}\,. + \end{equation} + ``` If the state ``|Ψ⟩ = |Ψ(ϵ)⟩`` itself depends on ``ϵ`` and ``|Ψ^\prime⟩ = \partial_ϵ |Ψ⟩``, the upper component is ``\partial_ϵ (\hat{U} |Ψ⟩)``, by the product rule. That is, a gradient vector of the form ``(\partial_ϵ |Ψ⟩, |Ψ⟩)`` is propagated to a gradient vector of the same form. -Now consider a piecewise-constant propagation in which the generators ``\hat{H}_n(ϵ)`` of *all* time steps depend on the same parameter ``ϵ``. With ``G_n = G[\hat{H}_n]``, applying Eq. \eqref{eq:chain} once per time step gives +Now consider a piecewise-constant propagation in which the generators ``\hat{H}_n(ϵ)`` of *all* time steps depend on the same parameter ``ϵ``. With ``G_n = G[\hat{H}_n]``, applying the single-step product rule, Eq. \eqref{eq:chain}, once per time step gives ```math \begin{equation}\label{eq:multistep} @@ -191,7 +195,7 @@ one time step at a time. GRAPE is the opposite case: each control value ``ϵ_{nl ## [Dual numbers and forward-mode differentiation](@id Background-Dual) -Proposition 1 has a second interpretation: the gradient vector is the state together with its "dual part", and propagation under the gradient generator is forward-mode automatic differentiation [GriewankWalther2008](@cite). This section makes this statement precise, which yields an independent proof of Proposition 1 and, more importantly, a statement about the numerical methods that are used in practice to propagate gradient vectors. +The block form of ``e^{-\ii G t}``, with ``\hat{U}`` on the diagonal and ``\partial_ϵ \hat{U}`` in the upper right block ([Proposition 1](@ref Background-prop-gradgen-exp)), has a second interpretation: the gradient vector is the state together with its "dual part", and propagation under the gradient generator is forward-mode automatic differentiation [GriewankWalther2008](@cite). This section makes this statement precise, which yields an independent proof of that block form and, more importantly, a statement about the numerical methods that are used in practice to propagate gradient vectors. ### Dual numbers @@ -215,7 +219,7 @@ For example, ``f(x) = x^3 - 2x`` at ``x = 2`` gives ``(2 + η)^3 - 2(2 + η) = ( ### Gradient vectors as dual states -Operators and vectors may have dual-number entries. Since ``η`` is a scalar, it commutes with all operators, and a dual operator can be written uniquely as ``\hat{A} + η \hat{B}`` with ordinary complex matrices ``\hat{A}`` and ``\hat{B}``. Likewise, a dual vector is ``|Ψ⟩ + η |Ψ^\prime⟩``. Multiplication follows Eq. \eqref{eq:dual-mult}, keeping the order of the operators: +Operators and vectors may have dual-number entries. Since ``η`` is a scalar, it commutes with all operators, and a dual operator can be written uniquely as ``\hat{A} + η \hat{B}`` with ordinary complex matrices ``\hat{A}`` and ``\hat{B}``. Likewise, a dual vector is ``|Ψ⟩ + η |Ψ^\prime⟩``. Multiplication follows the multiplication rule of dual numbers, Eq. \eqref{eq:dual-mult}, keeping the order of the operators: ```math \begin{equation}\label{eq:dual-op-mult} @@ -238,19 +242,21 @@ To compare dual operators and dual vectors with gradient generators and gradient Applied to a scalar dual number instead of an operator, Eq. \eqref{eq:iota} gives ``ι(a + bη) = \left(\begin{smallmatrix} a & b \\ 0 & a \end{smallmatrix}\right)``, the standard [matrix representation of dual numbers](https://en.wikipedia.org/wiki/Dual_number#Matrix_representation). In particular, ``ι(η) = \left(\begin{smallmatrix} 0 & 1 \\ 0 & 0 \end{smallmatrix}\right)`` squares to zero, like ``η``. -**Proposition 3.** The map ``ι`` is linear and injective, and for all dual operators ``X``, ``Y`` and dual vectors ``v``, +!!! proposition "Proposition 3" -```math -\begin{equation}\label{eq:iota-homomorphism} -ι(X Y) = ι(X) ι(Y)\,, -\qquad -ι(X v) = ι(X) ι(v)\,, -\qquad -ι(\mathbb{1}) = \mathbb{1}\,. -\end{equation} -``` + [](@id Background-prop-iota)The map ``ι`` is linear and injective, and for all dual operators ``X``, ``Y`` and dual vectors ``v``, + + ```math + \begin{equation}\label{eq:iota-homomorphism} + ι(X Y) = ι(X) ι(Y)\,, + \qquad + ι(X v) = ι(X) ι(v)\,, + \qquad + ι(\mathbb{1}) = \mathbb{1}\,. + \end{equation} + ``` -If ``X = \hat{A} + η \hat{B}`` with an invertible ``\hat{A}``, then ``X^{-1} = \hat{A}^{-1} - η \hat{A}^{-1} \hat{B} \hat{A}^{-1}`` and ``ι(X^{-1}) = ι(X)^{-1}``. + If ``X = \hat{A} + η \hat{B}`` with an invertible ``\hat{A}``, then ``X^{-1} = \hat{A}^{-1} - η \hat{A}^{-1} \hat{B} \hat{A}^{-1}`` and ``ι(X^{-1}) = ι(X)^{-1}``. *Proof.* Linearity and injectivity are evident from Eq. \eqref{eq:iota}. Block multiplication gives @@ -278,23 +284,25 @@ For a generator ``\hat{H}(ϵ)`` that is differentiable in the real control ``ϵ` \end{equation} ``` -For a linear control, or any polynomial dependence on ``ϵ``, this is simply the evaluation of the expression for ``\hat{H}`` in dual arithmetic. Comparing with Eq. \eqref{eq:iota} gives the following identification. +For a linear control, or any polynomial dependence on ``ϵ``, this is simply the evaluation of the expression for ``\hat{H}`` in dual arithmetic. Comparing ``\hat{H} + η \hat{μ}`` with the block representation ``ι`` in Eq. \eqref{eq:iota} gives the following identification. -**Proposition 4.** The gradient generator is the image of the dynamical generator evaluated at the dual control value, and the gradient vector is the image of a dual state: +!!! proposition "Proposition 4" -```math -\begin{equation}\label{eq:gradgen-dual} -G[\hat{H}] = ι\big(\hat{H}(ϵ + η)\big)\,, -\qquad -Ψ = \begin{pmatrix} |Ψ^\prime⟩ \\ |Ψ⟩ \end{pmatrix} = ι\big(|Ψ⟩ + η |Ψ^\prime⟩\big)\,. -\end{equation} -``` + [](@id Background-prop-gradgen-dual)The gradient generator is the image of the dynamical generator evaluated at the dual control value, and the gradient vector is the image of a dual state: + + ```math + \begin{equation}\label{eq:gradgen-dual} + G[\hat{H}] = ι\big(\hat{H}(ϵ + η)\big)\,, + \qquad + Ψ = \begin{pmatrix} |Ψ^\prime⟩ \\ |Ψ⟩ \end{pmatrix} = ι\big(|Ψ⟩ + η |Ψ^\prime⟩\big)\,. + \end{equation} + ``` A gradient vector with a zero gradient state is the image of a state that does not depend on ``ϵ``. For ``L`` controls, ``G[\hat{H}]`` and ``(|Ψ^\prime_1⟩, \dots, |Ψ^\prime_L⟩, |Ψ⟩)`` are the images of ``\hat{H} + \sum_l η_l \hat{μ}_l`` and ``|Ψ⟩ + \sum_l η_l |Ψ^\prime_l⟩`` in the same way, with ``L`` dual units satisfying ``η_l η_{l^\prime} = 0``. This is the dual-number form of the [reduction to a single control](@ref Background-Reduction). For the backward propagation, ``(\hat{A} + η \hat{B})^\dagger = \hat{A}^\dagger + η \hat{B}^\dagger``, so ``G[\hat{H}^\dagger] = ι(\hat{H}^\dagger(ϵ + η))``. ### Functions of dual operators -Eq. \eqref{eq:dual-f} carries over to operators, with one subtlety: ``\hat{A}`` and ``\hat{B}`` generally do not commute, so ``(\hat{A} + η \hat{B})^m \neq \hat{A}^m + m \hat{A}^{m-1} \hat{B} η``. The correct generalization of ``f^\prime(x)`` is the directional derivative +The rule ``f(x + η) = f(x) + f^\prime(x) η`` for polynomials, Eq. \eqref{eq:dual-f}, carries over to operators, with one subtlety: ``\hat{A}`` and ``\hat{B}`` generally do not commute, so ``(\hat{A} + η \hat{B})^m \neq \hat{A}^m + m \hat{A}^{m-1} \hat{B} η``. The correct generalization of ``f^\prime(x)`` is the directional derivative ```math \begin{equation}\label{eq:frechet} @@ -302,20 +310,22 @@ Df(\hat{A})[\hat{B}] \equiv \frac{d}{ds} f(\hat{A} + s \hat{B}) \Big\vert_{s=0}\ \end{equation} ``` -**Theorem 5.** Let ``f(z) = \sum_{m=0}^{\infty} c_m z^m`` be a power series with complex coefficients and radius of convergence ``R``, and let ``\hat{A}`` and ``\hat{B}`` be complex ``N \times N`` matrices with ``\Vert \hat{A} \Vert < R`` in a submultiplicative norm. Then +!!! theorem "Theorem 5" -```math -\begin{equation}\label{eq:analytic} -\begin{split} -f(\hat{A} + η \hat{B}) &= f(\hat{A}) + η Df(\hat{A})[\hat{B}]\,, \\ -Df(\hat{A})[\hat{B}] &= \sum_{m=1}^{\infty} c_m \sum_{k=0}^{m-1} \hat{A}^k \hat{B} \hat{A}^{m-1-k}\,. -\end{split} -\end{equation} -``` + [](@id Background-theorem-dual-functions)Let ``f(z) = \sum_{m=0}^{\infty} c_m z^m`` be a power series with complex coefficients and radius of convergence ``R``, and let ``\hat{A}`` and ``\hat{B}`` be complex ``N \times N`` matrices with ``\Vert \hat{A} \Vert < R`` in a submultiplicative norm. Then + + ```math + \begin{equation}\label{eq:analytic} + \begin{split} + f(\hat{A} + η \hat{B}) &= f(\hat{A}) + η Df(\hat{A})[\hat{B}]\,, \\ + Df(\hat{A})[\hat{B}] &= \sum_{m=1}^{\infty} c_m \sum_{k=0}^{m-1} \hat{A}^k \hat{B} \hat{A}^{m-1-k}\,. + \end{split} + \end{equation} + ``` *Proof.* Let ``D_m = \sum_{k=0}^{m-1} \hat{A}^k \hat{B} \hat{A}^{m-1-k}``. By induction with Eq. \eqref{eq:dual-op-mult}, ``(\hat{A} + η \hat{B})^m = \hat{A}^m + η D_m``, since ``(\hat{A}^m + η D_m)(\hat{A} + η \hat{B}) = \hat{A}^{m+1} + η (\hat{A}^m \hat{B} + D_m \hat{A})``. Only ``η^2 = 0`` and the fact that ``η`` commutes with everything enter; the order of ``\hat{A}`` and ``\hat{B}`` is preserved. Expanding ``(\hat{A} + s \hat{B})^m`` into ordered products, the terms of first order in ``s`` are exactly those of ``s D_m``. As ``\Vert D_m \Vert \le m \Vert \hat{A} \Vert^{m-1} \Vert \hat{B} \Vert``, all series converge absolutely for small ``|s|``, and may be rearranged into ``f(\hat{A} + s \hat{B}) = f(\hat{A}) + s \sum_m c_m D_m + \mathcal{O}(s^2)``. ``\square`` -For the exponential, ``R = \infty``. With ``f(z) = e^{-\ii z dt}``, ``\hat{A} = \hat{H}``, and ``\hat{B} = \hat{μ}``, the dual part in Eq. \eqref{eq:analytic} is the Taylor series \eqref{eq:taylor} for ``t = dt``, and it is the derivative of ``e^{-\ii \hat{H}(ϵ) dt}`` with respect to ``ϵ`` by the chain rule. With Propositions 3 and 4, +For the exponential, ``R = \infty``. With ``f(z) = e^{-\ii z dt}``, ``\hat{A} = \hat{H}``, and ``\hat{B} = \hat{μ}``, the dual part in Eq. \eqref{eq:analytic} is the Taylor series \eqref{eq:taylor} for ``t = dt``, and it is the derivative of ``e^{-\ii \hat{H}(ϵ) dt}`` with respect to ``ϵ`` by the chain rule. Since ``ι`` preserves products and convergent series ([Proposition 3](@ref Background-prop-iota)), and ``G = ι(\hat{H}(ϵ + η))`` ([Proposition 4](@ref Background-prop-gradgen-dual)), ```math \begin{equation}\label{eq:expG-dual} @@ -323,35 +333,152 @@ e^{-\ii G dt} = ι\Big(e^{-\ii \hat{H}(ϵ + η) dt}\Big) = ι\big(\hat{U} + η \ \end{equation} ``` -which is an independent proof of Proposition 1. Applied to a gradient vector, ``(\hat{U} + η \partial_ϵ \hat{U})(|Ψ⟩ + η |Ψ^\prime⟩)`` is the product rule of Corollary 2, and over several time steps, the dual part of the product of the dual propagators ``\hat{U}_n + η \partial_ϵ \hat{U}_n`` is Eq. \eqref{eq:multistep-sum}. +which is an independent proof of the block form of ``e^{-\ii G dt}`` in Eq. \eqref{eq:gradgen-exp}. Applied to a gradient vector, ``(\hat{U} + η \partial_ϵ \hat{U})(|Ψ⟩ + η |Ψ^\prime⟩)`` is the product rule for a non-zero gradient state, Eq. \eqref{eq:chain}, and over several time steps, the dual part of the product of the dual propagators ``\hat{U}_n + η \partial_ϵ \hat{U}_n`` is Eq. \eqref{eq:multistep-sum}. ### [Forward-mode differentiation of numerical methods](@id Background-Numerical-Methods) The dual-number picture extends beyond the exact exponential, to the numerical methods that are actually used to propagate gradient vectors. -**Proposition 6.** Consider a finite computation that produces a vector or an operator from one or more generators ``\hat{H}(t_i; ϵ)``, a state ``|Ψ(ϵ)⟩``, and any number of ``ϵ``-independent operators and vectors, using only linear combinations with ``ϵ``-independent coefficients, products of operators, application of operators to vectors, and the solution of linear systems. Run the same computation with each ``\hat{H}(t_i)`` replaced by ``G[\hat{H}(t_i)]``, ``|Ψ⟩`` by ``(\partial_ϵ |Ψ⟩, |Ψ⟩)``, every ``ϵ``-independent operator ``\hat{O}`` by ``\mathrm{diag}(\hat{O}, \hat{O})``, and every ``ϵ``-independent vector ``|Φ⟩`` by ``(0, |Φ⟩)``. Then, in exact arithmetic, a resulting vector ``|Φ(ϵ)⟩`` is replaced by ``(\partial_ϵ |Φ⟩, |Φ⟩)``, and a resulting operator ``\hat{X}(ϵ)`` by ``\left(\begin{smallmatrix} \hat{X} & \partial_ϵ \hat{X} \\ 0 & \hat{X} \end{smallmatrix}\right)``. +!!! proposition "Proposition 6" + + [](@id Background-prop-linear-algebra)Consider a finite computation that produces a vector or an operator from one or more generators ``\hat{H}(t_i; ϵ)``, a state ``|Ψ(ϵ)⟩``, and any number of ``ϵ``-independent operators and vectors, using only linear combinations with ``ϵ``-independent coefficients, products of operators, application of operators to vectors, and the solution of linear systems. Run the same computation with each ``\hat{H}(t_i)`` replaced by ``G[\hat{H}(t_i)]``, ``|Ψ⟩`` by ``(\partial_ϵ |Ψ⟩, |Ψ⟩)``, every ``ϵ``-independent operator ``\hat{O}`` by ``\mathrm{diag}(\hat{O}, \hat{O})``, and every ``ϵ``-independent vector ``|Φ⟩`` by ``(0, |Φ⟩)``. Then, in exact arithmetic, a resulting vector ``|Φ(ϵ)⟩`` is replaced by ``(\partial_ϵ |Φ⟩, |Φ⟩)``, and a resulting operator ``\hat{X}(ϵ)`` by ``\left(\begin{smallmatrix} \hat{X} & \partial_ϵ \hat{X} \\ 0 & \hat{X} \end{smallmatrix}\right)``. -*Proof.* By Proposition 4, the replacements are ``ι`` of the inputs evaluated at ``ϵ + η``, each of the form "value ``+ η`` derivative". By Proposition 3, running the computation on the block objects is the same as running it in dual arithmetic. Each allowed operation preserves the form "value ``+ η`` derivative": linear combinations because ``\partial_ϵ`` is linear, products because Eq. \eqref{eq:dual-op-mult} is the product rule, and inverses because the dual part of ``X^{-1}`` in Proposition 3 is ``\partial_ϵ (X^{-1})``. ``\square`` +*Proof.* By the identification of gradient generators and gradient vectors with dual objects ([Proposition 4](@ref Background-prop-gradgen-dual)), the replacements are ``ι`` of the inputs evaluated at ``ϵ + η``, each of the form "value ``+ η`` derivative". Since ``ι`` preserves sums, products, and inverses ([Proposition 3](@ref Background-prop-iota)), running the computation on the block objects is the same as running it in dual arithmetic. Each allowed operation preserves the form "value ``+ η`` derivative": linear combinations because ``\partial_ϵ`` is linear, products because Eq. \eqref{eq:dual-op-mult} is the product rule, and inverses because the dual part of ``X^{-1} = \hat{A}^{-1} - η \hat{A}^{-1} \hat{B} \hat{A}^{-1}`` is ``\partial_ϵ (X^{-1})``. ``\square`` -Two kinds of operations fall outside Proposition 6. First, operations that are not complex-linear in the state, such as inner products and norms (e.g., in an orthogonalization or an error estimate), act on the gradient vector as a whole, not as dual arithmetic would. Second, choices that a method makes based on the data, such as the number of terms of an expansion, a spectral range, or an adaptive time step, are made for ``G`` rather than for ``\hat{H}``. If such choices are fixed before the computation, Proposition 6 applies with these choices frozen. +[Proposition 6](@ref Background-prop-linear-algebra) allows only linear combinations with ``ϵ``-independent coefficients, products of operators, applications of operators to vectors, and solutions of linear systems. Two kinds of operations fall outside of it. First, operations that are not complex-linear in the state, such as inner products and norms (e.g., in an orthogonalization or an error estimate), act on the gradient vector as a whole, not as dual arithmetic would. Second, choices that a method makes based on the data, such as the number of terms of an expansion, a spectral range, or an adaptive time step, are made for ``G`` rather than for ``\hat{H}``. If such choices are fixed before the computation, the remaining computation is linear algebra of the allowed kind, and its result is the exact derivative for these fixed choices. The [flat, frozen, and dual semantics](@ref Background-Semantics) below distinguish how a method can treat inner products, norms, and data-dependent choices. -Most propagation methods for a piecewise-constant generator approximate ``\hat{U} = e^{-\ii \hat{H} dt}`` by a polynomial in ``\hat{H}``. For these, Proposition 6 gives a strong statement. +Most propagation methods for a piecewise-constant generator approximate ``\hat{U} = e^{-\ii \hat{H} dt}`` by a polynomial in ``\hat{H}``. Evaluating a polynomial requires only linear combinations and products of ``\hat{H}``, which are operations allowed in [Proposition 6](@ref Background-prop-linear-algebra). This gives a strong statement. -**Corollary 7.** Let ``p(z) = \sum_{k=0}^{K} c_k z^k`` be a polynomial whose coefficients do not depend on ``ϵ``. Then ``p(G)`` maps ``(\partial_ϵ |Ψ⟩, |Ψ⟩)`` to ``(\partial_ϵ [p(\hat{H}(ϵ)) |Ψ⟩], p(\hat{H}(ϵ)) |Ψ⟩)``. +!!! corollary "Corollary 7" + + [](@id Background-cor-polynomial)Let ``p(z) = \sum_{k=0}^{K} c_k z^k`` be a polynomial whose coefficients do not depend on ``ϵ``. Then ``p(G)`` maps ``(\partial_ϵ |Ψ⟩, |Ψ⟩)`` to ``(\partial_ϵ [p(\hat{H}(ϵ)) |Ψ⟩], p(\hat{H}(ϵ)) |Ψ⟩)``. The gradient state is thus the exact derivative of the *approximate* propagated state, not an approximation of the derivative of the exact propagated state. The error of the propagation enters the state and the gradient consistently: up to floating-point rounding, the gradient is the derivative of the function of ``ϵ`` that the propagation actually evaluates, no matter how few terms the polynomial has. How well it approximates ``\partial_ϵ \hat{U} |Ψ⟩`` depends on how well ``p^\prime`` approximates the derivative of ``z \mapsto e^{-\ii z dt}`` on the spectrum of ``\hat{H}``. -The [Chebychev propagator](@extref QuantumPropagators :label:`method_cheby`) in `QuantumPropagators` is of this form. It shifts and scales ``\hat{H}`` with a spectral range ``[E_{\min}, E_{\min} + Δ]``, sums Chebychev polynomials with Bessel-function coefficients that depend only on ``Δ dt``, and multiplies with a phase factor. The spectral range is determined when the propagator is initialized, from the minimum and maximum values of the controls, and it does not change with the control values in a particular time step. Thus, Corollary 7 applies to every time step. For a gradient generator, the spectral range is estimated for ``G`` itself. Since ``G`` is block upper-triangular with ``\hat{H}`` in all diagonal blocks, ``\det(G - λ \mathbb{1}) = \det(\hat{H} - λ \mathbb{1})^{L+1}``, so ``G`` has the same eigenvalues as ``\hat{H}``, and the same Chebychev coefficients apply. In particular, the eigenvalues of ``G`` are real for a Hermitian ``\hat{H}``, even though ``G`` is not Hermitian. (In general, ``G`` is not diagonalizable: by Proposition 4, its eigenvalues are the dual numbers ``λ_j + η \partial_ϵ λ_j``, and each one with a non-zero dual part corresponds to a ``2 \times 2`` Jordan block. This is irrelevant for polynomials.) +The [Chebychev propagator](@extref QuantumPropagators :label:`method_cheby`) in `QuantumPropagators` [Tal-EzerJCP1984](@cite) is of this form. It shifts and scales ``\hat{H}`` with a spectral range ``[E_{\min}, E_{\min} + Δ]``, sums Chebychev polynomials with Bessel-function coefficients that depend only on ``Δ dt``, and multiplies with a phase factor. The spectral range is determined when the propagator is initialized, from the minimum and maximum values of the controls, and it does not change with the control values in a particular time step. Thus, the polynomial of each time step has ``ϵ``-independent coefficients, and the gradient state after each time step is the exact derivative of the Chebychev approximation ([Corollary 7](@ref Background-cor-polynomial)). For a gradient generator, the spectral range of ``G`` is that of ``\hat{H}`` ([Proposition 8](@ref Background-prop-charpoly)), and `specrange` computes it from ``\hat{H}``, so the same Chebychev coefficients apply. + +This exactness does not hold for methods whose polynomial depends on the propagated vector. The [Newton propagator](@extref QuantumPropagators :label:`method_newton`) [BermanJPA1992, AshkenaziJCP1995](@cite) builds a Krylov subspace with an Arnoldi iteration [ArnoldiQAM1951](@cite), which uses inner products of the full gradient vector, and chooses its interpolation points from the resulting Ritz values. The propagation of ``Ψ`` under ``G`` is then not the derivative of the Newton propagation of ``|Ψ⟩`` under ``\hat{H}``. Instead, it is an approximation of ``e^{-\ii G dt} Ψ`` that converges together with the propagation, so the gradient states are accurate to the precision of the propagation. The same holds for Krylov methods in general. + +### [Flat, frozen, and dual semantics](@id Background-Semantics) + +Operations beyond linear combinations of vectors and operators with ``ϵ``-independent coefficients, products of operators, applications of operators to vectors, and solutions of linear systems ([Proposition 6](@ref Background-prop-linear-algebra)), such as inner products, norms, and the choices that a method makes based on the data (a spectral range, interpolation points, the number of terms, or a time step), determine the interpretation and role of the gradient states in a numerical propagation. A propagation method that is applied to a gradient vector can treat these operations in three ways. + +In the *flat* semantics, ``G`` and ``Ψ`` are an ordinary matrix and vector of dimension ``N(L+1)``. Inner products and norms include the gradient states, and every choice that depends on the data is made for ``G`` and ``Ψ`` as a whole. The state component of the result then differs from the propagation of ``|Ψ⟩`` under ``\hat{H}`` alone within the precision of the propagation, and the gradient states approximate the exact derivative ``\partial_ϵ |Ψ(T)⟩`` of the propagated state to that same precision. The gradient converges together with the propagation. + +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. + +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: + +| Method | Choices based on the data | Semantics | +|:------------------------------------------------------------------- |:--------------------------------------------------------------------------------- |:------------------------- | +| `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 | -Corollary 7 does not apply to methods whose polynomial depends on the propagated vector. The [Newton propagator](@extref QuantumPropagators :label:`method_newton`) builds a Krylov subspace with an Arnoldi iteration, which uses inner products of the full gradient vector, and chooses its interpolation points from the resulting Ritz values. The propagation of ``Ψ`` under ``G`` is then not the derivative of the Newton propagation of ``|Ψ⟩`` under ``\hat{H}``. Instead, it is an approximation of ``e^{-\ii G dt} Ψ`` that converges together with the propagation, so the gradient states are accurate to the precision of the propagation. The same holds for Krylov methods in general. ### Relation to automatic differentiation -The preceding results confirm that a gradient vector ``(|Ψ^\prime⟩, |Ψ⟩)`` is the faithful matrix representation of the dual state ``|Ψ⟩ + η |Ψ^\prime⟩``, and the gradient generator is the representation of the dynamical generator at the dual control value ``ϵ + η`` (Proposition 4). Propagating a gradient vector under a gradient generator is forward-mode automatic differentiation of the propagation with respect to ``ϵ``. For the exact propagator, this gives ``(\partial_ϵ (\hat{U} |Ψ⟩), \hat{U} |Ψ⟩)``. For a numerical method built from linear algebra with ``ϵ``-independent coefficients, such as a Chebychev propagator, it gives the exact derivative of the approximate result. For methods whose internal choices depend on the propagated vector, such as Krylov methods, it gives an approximation of the exact derivative that converges together with the propagation. +A gradient vector ``(|Ψ^\prime⟩, |Ψ⟩)`` is the faithful matrix representation of the dual state ``|Ψ⟩ + η |Ψ^\prime⟩``, and the gradient generator is the representation of the dynamical generator at the dual control value ``ϵ + η`` (Propositions [3](@ref Background-prop-iota) and [4](@ref Background-prop-gradgen-dual)). Propagating a gradient vector under a gradient generator is forward-mode automatic differentiation of the propagation with respect to ``ϵ``. For the exact propagator, this gives ``(\partial_ϵ (\hat{U} |Ψ⟩), \hat{U} |Ψ⟩)``. For a numerical method built from linear algebra with ``ϵ``-independent coefficients, such as a Chebychev propagator, it gives the exact derivative of the approximate result. For methods whose internal choices depend on the propagated vector, such as Krylov methods, a gradient vector follows the flat semantics, and the gradient is an approximation of the exact derivative that converges together with the propagation. GRAPE combines this forward mode with the reverse mode. The gradient with respect to all ``ϵ_{nl}`` is obtained from one forward propagation of ``|Ψ⟩`` and one backward propagation of ``|χ⟩``, independent of the number ``N_T`` of time steps. That backward propagation is reverse-mode (adjoint) differentiation across the time steps. Within each time step, the gradient generator ``G[\hat{H}_n^\dagger]`` provides the derivative of the single-step propagator in forward mode, for all ``L`` controls at once, with the gradient states reset before each step [GoerzQ2022](@cite). +## [Properties of the gradient generator](@id Background-Properties) + +Propagation methods use more than the product of the generator with a vector. They estimate spectral ranges, diagonalize, compute inner products and norms, and may rely on Hermiticity or use the adjoint of the generator. Each subsection below starts with a practical consequence for the propagation of gradient vectors and then derives it from a property of the gradient generator ``G = G[\hat{H}]`` for ``L`` controls, Eq. \eqref{eq:gradgen}. Throughout, ``G`` is block upper-triangular, with ``\hat{H}`` in all ``L+1`` diagonal blocks. + +### [Spectrum](@id Background-Spectrum) + +The spectral range of a gradient generator, which methods like the Chebychev propagator require, is the spectral range of ``\hat{H}`` and does not have to be estimated separately. Accordingly, `QuantumGradientGenerators` evaluates `eigvals`, `tr`, and `det` of a [`GradgenOperator`](@ref), as well as its spectral range ([`specrange`](@extref QuantumPropagators.SpectralRange.specrange)), from ``\hat{H}`` alone. For an exact diagonalization, this reduces the dimension from ``N(L+1)`` to ``N``. For an Arnoldi estimate, it avoids the Ritz values of ``G``, which can lie outside of the spectral range, as shown [below](@ref Background-Non-Normality). + +!!! proposition "Proposition 8" + + [](@id Background-prop-charpoly)The characteristic polynomial of the gradient generator ``G`` for ``L`` controls is + + ```math + \begin{equation}\label{eq:charpoly} + \det(G - λ \mathbb{1}) = \det(\hat{H} - λ \mathbb{1})^{L+1}\,. + \end{equation} + ``` + + Thus, ``G`` has the same eigenvalues as ``\hat{H}``, each with ``L+1`` times its algebraic multiplicity, and ``\operatorname{tr} G = (L+1) \operatorname{tr} \hat{H}`` and ``\det G = (\det \hat{H})^{L+1}``. In particular, ``G`` has the same spectral range and spectral radius as ``\hat{H}``, and its eigenvalues are real if ``\hat{H}`` is Hermitian, even though ``G`` is not Hermitian. + +*Proof.* The matrix ``G - λ \mathbb{1}`` is block upper-triangular with diagonal blocks ``\hat{H} - λ \mathbb{1}``, and the determinant of a block-triangular matrix is the product of the determinants of its diagonal blocks. The trace of ``G`` is the sum of the traces of its diagonal blocks, and ``\det G`` is Eq. \eqref{eq:charpoly} at ``λ = 0``. ``\square`` + +### [Diagonalizability](@id Background-Diagonalization) + +A gradient generator cannot be propagated by diagonalizing it once and evaluating ``V e^{-\ii D t} V^{-1}`` for any number of time steps, as is common for a constant generator ``\hat{H} = V D V^{-1}``. The gradient generator ``G`` does not have a complete set of eigenvectors, so no such ``V`` exists. A numerical eigensolver does not report this as an error. Instead, it returns a matrix ``V`` with nearly parallel columns, and ``V e^{-\ii D t} V^{-1}`` is then wrong in all digits [MolerSIREV2003; Method 14](@cite). For example, for random Hermitian ``20 \times 20`` matrices ``\hat{H}`` and ``\hat{μ}``, the relative error of the resulting gradient block is larger than one. A method that relies on diagonalization must therefore diagonalize ``\hat{H}``, not ``G``. Methods that evaluate the exponential of ``G`` without diagonalizing it, such as the Chebychev propagator (a polynomial in ``G``) or `ExpProp` (a Padé approximation), are not affected. + +The reason is that the derivative of a phase grows linearly in time. Let ``L = 1`` ([a single control](@ref Background-Reduction)), let ``\hat{H}`` be Hermitian, and let ``\hat{H} |r⟩ = λ |r⟩`` for a non-degenerate eigenvalue ``λ``. Propagating the gradient vector ``(0, |r⟩)`` yields ``(\partial_ϵ \hat{U}(t) |r⟩, e^{-\ii λ t} |r⟩)`` by [Proposition 1](@ref Background-prop-gradgen-exp): the state only acquires a phase. Inserting ``\hat{U}(s) |r⟩ = e^{-\ii λ s} |r⟩`` and ``⟨r| \hat{U}(t - s) = e^{-\ii λ (t - s)} ⟨r|`` into the integral for ``\partial_ϵ \hat{U}(t)``, Eq. \eqref{eq:duhamel}, gives the component of the gradient state along ``|r⟩``, + +```math +\begin{equation}\label{eq:phase-derivative} +⟨r| \partial_ϵ \hat{U}(t) |r⟩ += -\ii t ⟨r| \hat{μ} |r⟩ e^{-\ii λ t} += \frac{\partial}{\partial ϵ} e^{-\ii λ(ϵ) t}\,, +\end{equation} +``` + +where ``⟨r| \hat{μ} |r⟩ = \partial_ϵ λ`` is the derivative of the eigenvalue (the Hellmann–Feynman theorem [FeynmanPR1939](@cite)). If ``G`` had a complete set of eigenvectors, every component of ``e^{-\ii G t} Ψ`` would be a linear combination of the pure exponentials ``e^{-\ii λ_j t}``, which cannot produce the term ``t e^{-\ii λ t}``. Thus, whenever an eigenvalue of ``\hat{H}`` depends on the control, ``G`` lacks an eigenvector. + +!!! proposition "Proposition 9" + + [](@id Background-prop-jordan)Let ``L = 1`` ([a single control](@ref Background-Reduction)), and let ``λ`` be a non-degenerate eigenvalue of ``\hat{H}`` with right and left eigenvectors, ``\hat{H} |r⟩ = λ |r⟩`` and ``⟨\tilde{r}| \hat{H} = λ ⟨\tilde{r}|``. If ``⟨\tilde{r}| \hat{μ} |r⟩ \neq 0``, the only eigenvectors of ``G`` for the eigenvalue ``λ`` are the multiples of ``(|r⟩, 0)``, although ``λ`` is a double eigenvalue of ``G``. Hence, ``G`` is not diagonalizable. + +*Proof.* The equation ``(G - λ \mathbb{1}) (|x⟩, |y⟩) = 0`` means ``(\hat{H} - λ \mathbb{1}) |y⟩ = 0`` and ``(\hat{H} - λ \mathbb{1}) |x⟩ = -\hat{μ} |y⟩``. The first equation gives ``|y⟩ = c |r⟩``. Applying ``⟨\tilde{r}|`` to the second gives ``0 = -c ⟨\tilde{r}| \hat{μ} |r⟩``, so ``c = 0``, and ``|x⟩`` is a multiple of ``|r⟩``. By the characteristic polynomial, Eq. \eqref{eq:charpoly}, ``λ`` is a double eigenvalue of ``G``. ``\square`` + +In the language of linear algebra, ``λ`` belongs to a ``2 \times 2`` Jordan block of ``G``. In the dual-number picture, the eigenvalue of ``\hat{H}(ϵ + η)`` is ``λ + η \partial_ϵ λ``, and its block representation ``ι(λ + η \partial_ϵ λ) = \left(\begin{smallmatrix} λ & \partial_ϵ λ \\ 0 & λ \end{smallmatrix}\right)`` is that Jordan block. Its exponential, ``e^{-\ii λ t} \left(\begin{smallmatrix} 1 & -\ii t \partial_ϵ λ \\ 0 & 1 \end{smallmatrix}\right)``, contains the derivative of the phase in Eq. \eqref{eq:phase-derivative}. The Jordan structure is thus not a defect of the construction, but the way in which ``G`` encodes the derivative. By the [reduction to a single control](@ref Background-Reduction), the ``l``'th gradient state evolves exactly as under the single-control gradient generator ``G_l``, so for ``L`` controls, ``G`` is not diagonalizable as soon as ``⟨\tilde{r}| \hat{μ}_l |r⟩ \neq 0`` for any of the controls. + +### [Non-normality](@id Background-Non-Normality) + +Methods that assume a Hermitian generator, such as the Lanczos iteration, norm conservation, or bounds on expectation values, do not apply to a gradient generator, even if ``\hat{H}`` is Hermitian. + +The norm of a gradient vector is not conserved, since ``e^{-\ii G t}`` is not unitary. By Eq. \eqref{eq:gradgen-exp}, the gradient states grow from zero, and by Eq. \eqref{eq:phase-derivative}, they may grow linearly in time. A propagation method must not renormalize gradient vectors or test them for norm conservation. + +Krylov methods must use the Arnoldi iteration [ArnoldiQAM1951](@cite) rather than the Lanczos iteration [LanczosJRNBS1950](@cite), which assumes a Hermitian generator [GolubVanLoan2013; Chapter 10](@cite). Accordingly, `ishermitian` is `false` for a `GradgenOperator`. + +Expectation values ``⟨v| G |v⟩`` in normalized vectors ``v`` (also called Rayleigh quotients) can lie outside the spectral range of ``\hat{H}``, which is also the spectral range of ``G``. For example, let ``L = 1`` ([a single control](@ref Background-Reduction)), let ``\hat{H}`` be Hermitian, and let ``|e⟩`` be the eigenvector for its largest eigenvalue ``E_{\max}``. For ``v = (s |e⟩, |e⟩) / \sqrt{2}`` with ``s = \pm 1``, + +```math +\begin{equation}\label{eq:rayleigh} +⟨v| G |v⟩ = E_{\max} + \frac{s}{2} ⟨e| \hat{μ} |e⟩\,, +\end{equation} +``` + +which exceeds ``E_{\max}`` for one choice of ``s`` whenever ``⟨e| \hat{μ} |e⟩ \neq 0``. The Ritz values of an Arnoldi iteration are expectation values of this kind, so an Arnoldi estimate of the spectral range of ``G`` can be too large, which is why `specrange` uses ``\hat{H}`` [instead](@ref Background-Spectrum). Likewise, a check that bounds expectation values by the spectral range is not valid for a gradient generator. For example, the optional `check_normalization` of the Chebychev propagator can fail for a gradient vector, even though the spectral range is correct. + +All of these shortcuts rely on the generator being Hermitian, or at least *normal*. A matrix ``A`` is normal if it commutes with its adjoint, ``A A^\dagger = A^\dagger A``. Equivalently, it has a complete set of orthonormal eigenvectors, that is, it can be diagonalized by a unitary transformation. Hermitian and unitary matrices are normal. In the orthonormal eigenbasis of a normal matrix, an expectation value ``⟨v| A |v⟩ = \sum_j |⟨j|v⟩|^2 λ_j`` is a weighted average of the eigenvalues ``λ_j``, and thus lies within the spectral range. For a non-normal matrix, there is no orthonormal eigenbasis, and expectation values can lie outside of it [HornJohnson1991; Chapter 1](@cite). A gradient generator is never normal. + +!!! proposition "Proposition 10" + + [](@id Background-prop-non-normal)If ``G`` is normal, ``G G^\dagger = G^\dagger G``, then all ``\hat{μ}_l = 0``. In particular, a gradient generator with a non-zero control derivative is neither Hermitian nor unitary. + +*Proof.* For ``l \le L``, the ``l``'th diagonal block of ``G G^\dagger`` is ``\hat{H} \hat{H}^\dagger + \hat{μ}_l \hat{μ}_l^\dagger``, and that of ``G^\dagger G`` is ``\hat{H}^\dagger \hat{H}``. If the two are equal, taking the trace and using ``\operatorname{tr}(\hat{H} \hat{H}^\dagger) = \operatorname{tr}(\hat{H}^\dagger \hat{H})`` gives ``\operatorname{tr}(\hat{μ}_l \hat{μ}_l^\dagger) = 0``, so ``\hat{μ}_l = 0``. ``\square`` + +### [Adjoint](@id Background-Adjoint) + +For a backward propagation, as in GRAPE, the gradient generator must be constructed from the adjoint dynamical generator. This is ``G[\hat{H}^\dagger]``, with ``\hat{μ}^\dagger`` in its upper right block, as discussed for the [exponential of the gradient generator](@ref Background-Exponential). The adjoint of the gradient generator, ``G[\hat{H}]^\dagger``, is a different matrix, and propagating under it does not yield any gradient. It is block lower-triangular. For ``L = 1`` ([a single control](@ref Background-Reduction)), + +```math +\begin{equation}\label{eq:gradgen-adjoint} +G[\hat{H}]^\dagger += \begin{pmatrix} \hat{H}^\dagger & 0 \\ \hat{μ}^\dagger & \hat{H}^\dagger \end{pmatrix} += P \, G[\hat{H}^\dagger] \, P\,, +\qquad +P = \begin{pmatrix} 0 & \mathbb{1} \\ \mathbb{1} & 0 \end{pmatrix}\,, +\end{equation} +``` + +so a gradient vector ``(0, |χ⟩)`` propagated under ``G[\hat{H}]^\dagger`` keeps a zero gradient state. The two matrices are similar, but ``G[\hat{H}]^\dagger \neq G[\hat{H}^\dagger]`` unless ``\hat{μ} = 0``. To prevent this mistake, `QuantumGradientGenerators` does not define `adjoint` for a gradient generator. See the [how-to guide on backward propagation](@ref Howto-Backward) for an example. + +### [Inner products and norms](@id Background-Norm) + +Inner products and norms treat a gradient vector as one long vector of dimension ``N(L+1)``: for two gradient vectors ``Ψ`` and ``Φ``, `dot(Ψ, Φ)` is the inner product of the block vectors, ``⟨Ψ|Φ⟩ + \sum_l ⟨Ψ^\prime_l|Φ^\prime_l⟩`` in terms of their states and gradient states, and `norm(Ψ)` is the corresponding Euclidean norm, ``\big(⟨Ψ|Ψ⟩ + \sum_l ⟨Ψ^\prime_l|Ψ^\prime_l⟩\big)^{1/2}``. These are the inner product and norm of the [flat semantics](@ref Background-Semantics), not the dual-valued inner product of the full dual semantics. That `norm` and `dot` are consistent is essential for the Arnoldi iteration, which normalizes its basis vectors with the norm and orthogonalizes them with the inner product. + + ## [Time-dependent generators and parameters](@id Background-Time-Dependent) So far, the generator was constant within a time step, and we differentiated with respect to the value of a control. Both restrictions can be lifted. Let ``\hat{H}(t; u)`` depend on time ``t \in [0, T]`` and on a real parameter ``u``. Typically, ``u`` is one of the [control parameters](@extref QuantumControl :label:`Control-Parameters`) ``\{u_n\}`` that the control functions depend on, ``ϵ_l(t) = ϵ_l(\{u_n\}, t)``: the value of a [pulse](@extref QuantumControl :label:`Pulse`) on one interval of the time grid, as in GRAPE, or, e.g., the amplitude or width of an analytic pulse shape. It may also be a parameter of the drift term or of the dissipators of a Liouvillian. We assume that both ``\hat{H}`` and ``\partial_u \hat{H} \equiv \partial \hat{H} / \partial u`` are continuous in ``(t, u)`` on each interval of a fixed (``u``-independent) partition of ``[0, T]``, which covers smooth control functions as well as controls that are piecewise constant on a fixed time grid. The time evolution operator is the solution of @@ -373,15 +500,17 @@ G_u(t) = \begin{pmatrix} \hat{H}(t; u) & \partial_u \hat{H}(t; u) \\ 0 & \hat{H} and ``\hat{U}_G(t, t_0)`` is the time evolution operator for ``\ii \frac{d}{dt} Ψ(t) = G_u(t) Ψ(t)``. -**Proposition 8.** ``\hat{U}(t, t_0; u)`` is continuously differentiable in ``u``, and +!!! proposition "Proposition 11" -```math -\begin{equation}\label{eq:gradgen-u-prop} -\hat{U}_G(t, t_0) = \begin{pmatrix} \hat{U}(t, t_0) & \partial_u \hat{U}(t, t_0) \\ 0 & \hat{U}(t, t_0) \end{pmatrix}\,. -\end{equation} -``` + [](@id Background-prop-time-dependent)``\hat{U}(t, t_0; u)`` is continuously differentiable in ``u``, and + + ```math + \begin{equation}\label{eq:gradgen-u-prop} + \hat{U}_G(t, t_0) = \begin{pmatrix} \hat{U}(t, t_0) & \partial_u \hat{U}(t, t_0) \\ 0 & \hat{U}(t, t_0) \end{pmatrix}\,. + \end{equation} + ``` -*Proof.* By the standard theorem on the differentiable dependence of solutions of ordinary differential equations on parameters (applied to one interval of the partition after the other), ``\hat{U}`` is continuously differentiable in ``u``, and ``\partial_u \hat{U}`` solves the equation obtained by differentiating Eq. \eqref{eq:tdse-U}, +*Proof.* By the standard theorem on the differentiable dependence of solutions of ordinary differential equations on parameters [Hartman2002; Chapter V](@cite) (applied to one interval of the partition after the other), ``\hat{U}`` is continuously differentiable in ``u``, and ``\partial_u \hat{U}`` solves the equation obtained by differentiating Eq. \eqref{eq:tdse-U}, ```math \begin{equation}\label{eq:variational} @@ -390,9 +519,9 @@ and ``\hat{U}_G(t, t_0)`` is the time evolution operator for ``\ii \frac{d}{dt} \end{equation} ``` -The rest of the proof is identical to that of Proposition 1: the right-hand side ``W(t)`` of Eq. \eqref{eq:gradgen-u-prop} satisfies ``W(t_0) = \mathbb{1}`` and ``\ii \frac{d}{dt} W = G_u(t) W``, as does ``\hat{U}_G(t, t_0)``. ``\square`` +The rest of the proof is identical to that of the block form of ``e^{-\ii G t}`` ([Proposition 1](@ref Background-prop-gradgen-exp)): the right-hand side ``W(t)`` of Eq. \eqref{eq:gradgen-u-prop} satisfies ``W(t_0) = \mathbb{1}`` and ``\ii \frac{d}{dt} W = G_u(t) W``, as does ``\hat{U}_G(t, t_0)``. ``\square`` -For a generator that is constant in time, Proposition 8 reduces to Proposition 1. As in Corollary 2, applying Eq. \eqref{eq:gradgen-u-prop} to a gradient vector gives +For a generator that is constant in time, Eq. \eqref{eq:gradgen-u-prop} reduces to the block form of ``e^{-\ii G t}``, Eq. \eqref{eq:gradgen-exp}. As for a single time step, Eq. \eqref{eq:chain}, applying Eq. \eqref{eq:gradgen-u-prop} to a gradient vector gives ```math \begin{equation}\label{eq:gradvec-u-prop} @@ -427,9 +556,9 @@ plus any explicit dependence of ``\hat{H}`` on ``u_n``. The blocks of the gradie This is the setting of optimal control methods for analytic or otherwise parameterized control functions. GOAT [MachnesPRL2018](@cite) optimizes analytic control functions with few parameters by integrating the coupled equations of motion for ``\hat{U}`` and ``\partial_u \hat{U}`` forward in time with an ODE solver, [MachnesPRL2018; Eq. (7)](@cite), which is Eq. \eqref{eq:gradgen-u} with the order of the blocks reversed. GROUP [SorensenPRA2018](@cite) expands the control in a chopped basis, ``ϵ(t) = ϵ_0(t) + S(t) \sum_n u_n f_n(t)``, and GRAFS [LucarelliPRA2018](@cite) expands piecewise-constant controls in band-limited Slepian sequences. Both obtain the gradient with respect to the expansion coefficients from a GRAPE-type adjoint gradient via the chain rule, [SorensenPRA2018; Eq. (16)](@cite) and [LucarelliPRA2018; Eqs. (18, 19)](@cite). The gradient generator for the parameters ``u_n`` is the mathematical basis for implementing GOAT-type methods with `QuantumGradientGenerators`. -GRAPE is the special case where the control parameters are the pulse values themselves, ``\{u_n\} = \{ϵ_{nl}\}``. Then ``\partial ϵ_l(t) / \partial ϵ_{n^\prime l^\prime}`` is ``δ_{l l^\prime}`` on the interval ``n^\prime`` and zero elsewhere. A forward propagation would carry ``N_T L`` gradient states, each driven only during its own time interval and evolving freely under ``\hat{H}`` afterwards. In the gradient of a functional (below), the free evolution can be moved onto the backward-propagated state ``|χ⟩``. This is why GRAPE needs only ``L`` gradient states for one time step at a time. For parameters that affect the controls at all times, as in GOAT, the forward propagation carries all ``M`` gradient states over the entire time interval, but requires no backward propagation and no storage of states at intermediate times. +GRAPE is the special case where the control parameters are the pulse values themselves, ``\{u_n\} = \{ϵ_{nl}\}``. Then ``\partial ϵ_l(t) / \partial ϵ_{n^\prime l^\prime}`` is ``δ_{l l^\prime}`` on the interval ``n^\prime`` and zero elsewhere. A forward propagation would carry ``N_T L`` gradient states, each driven only during its own time interval and evolving freely under ``\hat{H}`` afterwards. In the [gradient of a functional](@ref Background-Functionals), the free evolution can be moved onto the backward-propagated state ``|χ⟩``. This is why GRAPE needs only ``L`` gradient states for one time step at a time. For parameters that affect the controls at all times, as in GOAT, the forward propagation carries all ``M`` gradient states over the entire time interval, but requires no backward propagation and no storage of states at intermediate times. -### Gradients of functionals +### [Gradients of functionals](@id Background-Functionals) For a final-time functional ``J_T(\{|Ψ_k(T)⟩\})`` of the states of several trajectories ``k``, we follow the conventions of the GRAPE documentation, with [Wirtinger derivatives](@extref GRAPE :label:`Wirtinger-Vectors`) and ``|χ_k(T)⟩ \equiv - \partial J_T / \partial ⟨Ψ_k(T)|``. With the gradient states ``|Ψ^\prime_{kn}(T)⟩ = \partial_{u_n} |Ψ_k(T)⟩`` from the forward propagation of the ``k``'th trajectory, the chain rule gives @@ -454,34 +583,38 @@ with the backward-propagated states ``|χ_k(t)⟩ = \hat{U}^\dagger(T, t) |χ_k( ### Numerical propagation -Proposition 8 concerns the exact time evolution. In practice, the propagation under ``G_u(t)`` is numerical, either with a general ODE solver or with a piecewise-constant approximation. As before, it suffices to consider a single parameter ``u``. +The block form of ``\hat{U}_G``, Eq. \eqref{eq:gradgen-u-prop}, holds for the exact time evolution. In practice, the propagation under ``G_u(t)`` is numerical, either with a general ODE solver or with a piecewise-constant approximation. As in the [reduction to a single control](@ref Background-Reduction), it suffices to consider a single parameter ``u``. + +!!! proposition "Proposition 12" -**Proposition 9.** Consider a Runge–Kutta or linear multistep method (explicit or implicit, with exact solution of the linear systems for implicit methods) on a time grid that does not depend on ``u``. Applying the method to ``\ii \frac{d}{dt} Ψ = G_u(t) Ψ`` with the initial gradient vector ``(\partial_u |Ψ(0)⟩, |Ψ(0)⟩)`` yields gradient vectors ``(\partial_u |Ψ_n⟩, |Ψ_n⟩)``, where ``|Ψ_n⟩`` is the numerical solution of Eq. \eqref{eq:tdse} with ``\hat{H}(t; u)`` by the same method. + [](@id Background-prop-ode-solvers)Consider a Runge–Kutta or linear multistep method (explicit or implicit, with exact solution of the linear systems for implicit methods) on a time grid that does not depend on ``u``. Applying the method to ``\ii \frac{d}{dt} Ψ = G_u(t) Ψ`` with the initial gradient vector ``(\partial_u |Ψ(0)⟩, |Ψ(0)⟩)`` yields gradient vectors ``(\partial_u |Ψ_n⟩, |Ψ_n⟩)``, where ``|Ψ_n⟩`` is the numerical solution of Eq. \eqref{eq:tdse} with ``\hat{H}(t; u)`` by the same method. -*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. Proposition 6 applies. ``\square`` +*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. +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). 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)⟩``. -**Proposition 10.** Let ``G_n = G_u(\tilde{t}_n)`` be the gradient generator evaluated at the same times ``\tilde{t}_n`` as the generator. Then +!!! proposition "Proposition 13" -```math -\begin{equation}\label{eq:pwc} -e^{-\ii G_{N_T} dt_{N_T}} \cdots e^{-\ii G_1 dt_1} -\begin{pmatrix} \partial_u |Ψ(0)⟩ \\ |Ψ(0)⟩ \end{pmatrix} -= \begin{pmatrix} \partial_u |\bar{Ψ}(T)⟩ \\ |\bar{Ψ}(T)⟩ \end{pmatrix}\,, -\end{equation} -``` + [](@id Background-prop-pwc)Let ``G_n = G_u(\tilde{t}_n)`` be the gradient generator evaluated at the same times ``\tilde{t}_n`` as the generator. Then + + ```math + \begin{equation}\label{eq:pwc} + e^{-\ii G_{N_T} dt_{N_T}} \cdots e^{-\ii G_1 dt_1} + \begin{pmatrix} \partial_u |Ψ(0)⟩ \\ |Ψ(0)⟩ \end{pmatrix} + = \begin{pmatrix} \partial_u |\bar{Ψ}(T)⟩ \\ |\bar{Ψ}(T)⟩ \end{pmatrix}\,, + \end{equation} + ``` -and as ``\max_n dt_n \rightarrow 0``, the right-hand side converges to ``(\partial_u |Ψ(T)⟩, |Ψ(T)⟩)``. + and as ``\max_n dt_n \rightarrow 0``, the right-hand side converges to ``(\partial_u |Ψ(T)⟩, |Ψ(T)⟩)``. -*Proof.* Since ``\tilde{t}_n`` does not depend on ``u``, ``G_n = G[\hat{H}_n]``, and Eq. \eqref{eq:pwc} is Eq. \eqref{eq:multistep}. The left-hand side is the time evolution under the piecewise-constant ``\bar{G}(t) = G_n`` for ``t \in (t_{n-1}, t_n]``. By variation of constants, ``\hat{U}_{\bar{G}}(T, 0) - \hat{U}_G(T, 0) = -\ii \int_0^T \hat{U}_{\bar{G}}(T, t) (\bar{G}(t) - G_u(t)) \hat{U}_G(t, 0) dt``, which vanishes as ``\max_n dt_n \rightarrow 0`` because ``G_u(t)`` is uniformly continuous on each interval of the partition. The convergence then follows from Proposition 8. ``\square`` +*Proof.* Since ``\tilde{t}_n`` does not depend on ``u``, ``G_n = G[\hat{H}_n]``, and Eq. \eqref{eq:pwc} is the product rule over multiple time steps, Eq. \eqref{eq:multistep}. The left-hand side is the time evolution under the piecewise-constant ``\bar{G}(t) = G_n`` for ``t \in (t_{n-1}, t_n]``. By variation of constants, ``\hat{U}_{\bar{G}}(T, 0) - \hat{U}_G(T, 0) = -\ii \int_0^T \hat{U}_{\bar{G}}(T, t) (\bar{G}(t) - G_u(t)) \hat{U}_G(t, 0) dt``, which vanishes as ``\max_n dt_n \rightarrow 0`` because ``G_u(t)`` is uniformly continuous on each interval of the partition. The convergence then follows from the block form of ``\hat{U}_G(T, 0)``, Eq. \eqref{eq:gradgen-u-prop}. ``\square`` -The gradient states are thus the exact derivative of the piecewise-constant approximation, and they converge to the exact derivative together with it (to second order in ``dt`` for smooth controls and midpoint evaluation). Each step ``e^{-\ii G_n dt_n}`` is evaluated with one of the propagators in `QuantumPropagators`, so Eq. \eqref{eq:pwc} holds to the precision of that propagator, and exactly for a polynomial propagator with ``u``-independent coefficients, by Corollary 7. It is essential that ``\partial_u \hat{H}`` is evaluated at the same times ``\tilde{t}_n`` as ``\hat{H}``. Otherwise, the gradient states still converge to the exact derivative, but they are not the derivative of the computed state ``|\bar{Ψ}(T)⟩``, and the mismatch between the computed functional and its gradient, of the order of the time discretization error, can stall a gradient-based optimization close to convergence. +The gradient states are thus the exact derivative of the piecewise-constant approximation, and they converge to the exact derivative together with it (to second order in ``dt`` for smooth controls and midpoint evaluation). Each step ``e^{-\ii G_n dt_n}`` is evaluated with one of the propagators in `QuantumPropagators`, so Eq. \eqref{eq:pwc} holds to the precision of that propagator, and exactly for a polynomial propagator with ``u``-independent coefficients, whose gradient states are the exact derivative of its approximation ([Corollary 7](@ref Background-cor-polynomial)). It is essential that ``\partial_u \hat{H}`` is evaluated at the same times ``\tilde{t}_n`` as ``\hat{H}``. Otherwise, the gradient states still converge to the exact derivative, but they are not the derivative of the computed state ``|\bar{Ψ}(T)⟩``, and the mismatch between the computed functional and its gradient, of the order of the time discretization error, can stall a gradient-based optimization close to convergence. ### Remarks Nothing in this section relies on Hermiticity of ``\hat{H}``. All results apply to non-Hermitian Hamiltonians and to Liouvillians, where ``u`` may also parameterize the dissipators, and to a backward propagation under ``\hat{H}^\dagger(t)`` with the gradient generator ``G[\hat{H}^\dagger]``. -Second derivatives can be obtained by nesting: if ``\hat{H}`` is twice continuously differentiable, applying Proposition 8 to ``G_{u_1}(t)`` with respect to a second parameter ``u_2`` gives a generator of dimension ``4N`` whose time evolution operator contains ``\partial_{u_1} \partial_{u_2} \hat{U}`` in its upper right block. This is the matrix representation of numbers with two dual units, ``η_1^2 = η_2^2 = 0``. [GoodwinJCP2015](@citet) obtain second derivatives of single-step propagators from a larger block-triangular matrix in the same spirit, and [MachnesPRL2018](@citet) note that GOAT extends to second derivatives. +Second derivatives can be obtained by nesting: if ``\hat{H}`` is twice continuously differentiable, applying the time-dependent block form, Eq. \eqref{eq:gradgen-u-prop}, to ``G_{u_1}(t)`` with respect to a second parameter ``u_2`` gives a generator of dimension ``4N`` whose time evolution operator contains ``\partial_{u_1} \partial_{u_2} \hat{U}`` in its upper right block. This is the matrix representation of numbers with two dual units, ``η_1^2 = η_2^2 = 0``. [GoodwinJCP2015](@citet) obtain second derivatives of single-step propagators from a larger block-triangular matrix in the same spirit, and [MachnesPRL2018](@citet) note that GOAT extends to second derivatives. diff --git a/docs/src/howto.md b/docs/src/howto.md new file mode 100644 index 0000000..7952af3 --- /dev/null +++ b/docs/src/howto.md @@ -0,0 +1,283 @@ +```@meta +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# SPDX-License-Identifier: MIT OR CC-BY-4.0 +CurrentModule = QuantumGradientGenerators +``` + +# [How-to Guides](@id QGG-Howto) + +**Contents** + +```@contents +Pages = ["howto.md"] +Depth = 2:2 +``` + + +## [How to propagate a gradient vector backward in time](@id Howto-Backward) + +A backward propagation, as in GRAPE, propagates a state ``|χ⟩`` from ``t = T`` to ``t = 0`` under the adjoint generator ``\hat{H}^\dagger(t)``. To get the derivative of each backward time step with respect to the control value on that time step, propagate a gradient vector under the gradient generator ``G[\hat{H}^\dagger]`` of the adjoint generator. + +Start from the dynamical generator, here a non-Hermitian three-level system with a decaying upper level: + +```@example backward +using LinearAlgebra +using QuantumPropagators: hamiltonian, init_prop, prop_step!, ExpProp +using QuantumGradientGenerators: GradGenerator, GradVector, resetgradvec! + +Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 (2.1-0.05im)] +Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] +T = 5.0 +tlist = collect(range(0, T; length = 51)) +ϵ(t) = 0.2 + 0.1 * sin(2π * t / T) +H = hamiltonian(Ĥ₀, (Ĥ₁, ϵ)) +nothing # hide +``` + +Construct the adjoint generator by taking the adjoint of each operator. The control is real, so the control function stays the same: + +```@example backward +H_adj = hamiltonian(copy(Ĥ₀'), (copy(Ĥ₁'), ϵ)) +nothing # hide +``` + +With [QuantumControl](@extref QuantumControl :doc:`index`), `adjoint(traj)` of a `Trajectory` `traj` returns a trajectory with the adjoint generator in the same way. + +Build the gradient generator from the adjoint generator. Its control derivative is ``\hat{μ}^\dagger = \hat{H}_1^\dagger``: + +```@example backward +G = GradGenerator(H_adj) +nothing # hide +``` + +Initialize a backward propagator for a gradient vector that holds the boundary condition ``|χ(T)⟩`` as its state: + +```@example backward +χ_T = ComplexF64[0, 0, 1] +propagator = init_prop(GradVector(χ_T, 1), G, tlist; method = ExpProp, backward = true) +nothing # hide +``` + +Propagate one time step at a time, resetting the gradient states with [`resetgradvec!`](@ref) before each step. After the step for the interval ``n``, the gradient state is the derivative of that backward step with respect to the control value ``ϵ_n`` on the interval, applied to ``|χ(t_n)⟩``: + +```@example backward +N_T = length(tlist) - 1 +χ_states = Vector{Vector{ComplexF64}}(undef, N_T + 1) # |χ(tₙ)⟩ at tlist[n] +dχ = Vector{Vector{ComplexF64}}(undef, N_T) # derivative of backward step n +χ_states[N_T+1] = χ_T +for n = N_T:-1:1 + resetgradvec!(propagator.state) # keeps the state, zeroes the gradient + χ = prop_step!(propagator) + χ_states[n] = copy(χ.state) + dχ[n] = copy(χ.grad_states[1]) +end +``` + +This is how GRAPE evaluates its gradient with `gradient_method = :gradgen`. Without the call to `resetgradvec!`, the gradient state instead accumulates the derivative with respect to a parameter that all time steps depend on, see [Non-zero gradient states and multiple time steps](@ref Background-cor-gradient-state). + +To check the result, compare with a finite-difference derivative of a single backward step, ``e^{-\ii \hat{H}^\dagger(ϵ_n) (-dt)}``, applied to ``|χ(t_{n+1})⟩``: + +```@example backward +n = 20 +ϵₙ = propagator.parameters[ϵ][n] +dt = tlist[n+1] - tlist[n] +Û_bw(e) = exp(1im * (Ĥ₀ + e * Ĥ₁)' * dt) +h = 1e-5 +dχ_fd = (Û_bw(ϵₙ + h) - Û_bw(ϵₙ - h)) * χ_states[n+1] / 2h +norm(dχ[n] - dχ_fd) +``` + +!!! warning "Not the adjoint of the gradient generator" + + The gradient generator for the backward propagation is ``G[\hat{H}^\dagger]``, with ``\hat{μ}^\dagger`` in its upper right block. This is not the adjoint ``G[\hat{H}]^\dagger`` of the forward gradient generator, which is block *lower*-triangular. Propagating ``(0, |χ⟩)`` under ``G[\hat{H}]^\dagger`` leaves the gradient state at zero. For this reason, `QuantumGradientGenerators` does not define `adjoint` for a gradient generator. See [Adjoint](@ref Background-Adjoint) on the Background page for details. + + +## [How to propagate gradient vectors with the Chebychev propagator](@id Howto-Cheby) + +The [Chebychev propagator](@extref QuantumPropagators :label:`method_cheby`) works for gradient vectors without any extra configuration. The gradient states it produces are the exact derivative of the Chebychev propagation of the state, even when that propagation is inaccurate: a polynomial in the gradient generator with coefficients that do not depend on the control maps a gradient vector to the derivative of the same polynomial applied to the state ([Corollary 7](@ref Background-cor-polynomial)). This guide shows how to propagate a gradient vector and how to verify the gradient against finite differences. + +Define a Hermitian generator. Here, the parameter ``u`` with respect to which we take the derivative is a static offset of the control, ``ϵ(t) + u``, so that ``\partial \hat{H} / \partial u = \hat{H}_1``: + +```@example cheby +using LinearAlgebra +using QuantumPropagators: hamiltonian, propagate, Cheby, ExpProp +using QuantumGradientGenerators: GradGenerator, GradVector + +Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 2.1] +Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] +T = 5.0 +tlist = collect(range(0, T; length = 51)) +ϵ(t) = 0.3 * sin(π * t / T)^2 +Ψ₀ = ComplexF64[1, 0, 0] + +H(u) = hamiltonian(Ĥ₀ + u * Ĥ₁, (Ĥ₁, ϵ)) +G = GradGenerator(H(0.0)) +nothing # hide +``` + +Propagate a gradient vector with `method = Cheby`: + +```@example cheby +Ψ = propagate(GradVector(Ψ₀, 1), G, tlist; method = Cheby) +nothing # hide +``` + +The gradient generator has the same eigenvalues as ``\hat{H}``, each with multiplicity ``L+1`` ([Proposition 8](@ref Background-prop-charpoly)), so the propagator obtains its spectral range from ``\hat{H}``. It uses the same Chebychev coefficients as a propagation of the state alone, so the state component is identical: + +```@example cheby +Ψ.state == propagate(Ψ₀, H(0.0), tlist; method = Cheby) +``` + +The gradient vector is propagated without resetting the gradient state, so `Ψ.grad_states[1]` is the derivative ``\partial_u |Ψ(T)⟩`` of the final state with respect to the offset ``u``. + +Do not pass `check_normalization = true` when propagating a gradient vector. That check compares expectation values ``⟨v|G|v⟩`` with the spectral range, and for a gradient generator, these can lie outside the spectral range of ``\hat{H}`` ([Non-normality](@ref Background-Non-Normality)), so the check fails even when the spectral range is correct. + +To verify the gradient with finite differences, the Chebychev propagations for ``u`` and ``u \pm h`` must use the same coefficients. By default, the spectral range, and thus the coefficients, are determined from the generator, and so they change with ``u``. Fix the spectral range with `specrange_method = :manual` and `E_min`, `E_max` (a range that contains the spectrum of ``\hat{H}`` for all values of ``u`` and of the control). To demonstrate that the gradient is the derivative of the Chebychev propagation even when the propagation is inaccurate, also truncate the Chebychev series early with `cheby_coeffs_limit = 1e-2`: + +```@example cheby +cheby_kwargs = (; + method = Cheby, + specrange_method = :manual, + E_min = -0.5, + E_max = 2.5, + cheby_coeffs_limit = 1e-2, +) +Ψ = propagate(GradVector(Ψ₀, 1), G, tlist; cheby_kwargs...) + +h = 1e-6 +dΨ_fd = + ( + propagate(Ψ₀, H(h), tlist; cheby_kwargs...) - + propagate(Ψ₀, H(-h), tlist; cheby_kwargs...) + ) / 2h +norm(Ψ.grad_states[1] - dΨ_fd) +``` + +The gradient matches the finite-difference derivative of the same Chebychev propagation to the precision of the finite differences. For comparison, the exact derivative of the piecewise-constant time evolution follows from propagating the gradient vector with `ExpProp`: + +```@example cheby +Ψ_exact = propagate(GradVector(Ψ₀, 1), G, tlist; method = ExpProp) +( + state_error = norm(Ψ.state - Ψ_exact.state), + gradient_error = norm(Ψ.grad_states[1] - Ψ_exact.grad_states[1]), +) +``` + +Both the state and the gradient deviate from the exact result at the level of the truncation error of the Chebychev series. With the default `cheby_coeffs_limit = 1e-12`, both are accurate to near machine precision. + + +## [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. + +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. + +```@example ode +using LinearAlgebra +using Printf +using OrdinaryDiffEq +using DiffEqBase: ODE_DEFAULT_NORM +using QuantumPropagators: hamiltonian, propagate, init_prop, prop_step! +using QuantumGradientGenerators: GradGenerator + +Ĥ₀ = ComplexF64[0 0 0; 0 1.0 0; 0 0 2.1] +Ĥ₁ = ComplexF64[0 1 0; 1 0 √2; 0 √2 0] +T = 5.0 +tlist = [0.0, T] +ϵ(t) = 0.3 * sin(π * t / T)^2 +Ψ₀ = ComplexF64[1, 0, 0] + +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`: + +```@example ode +Ψ = propagate( + Ψ_flat, + G, + tlist; + method = OrdinaryDiffEq, + check = false, + 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: + +```@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) + +Ψ = propagate( + Ψ_flat, + G, + tlist; + method = OrdinaryDiffEq, + check = false, + reltol = 1e-6, + abstol = 1e-6, + internalnorm = state_norm +) +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: + +```@example ode +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 + +Ψ_ref, _ = propagate_ode(Ψ_flat, G; alg = Vern9(), reltol = 1e-14, abstol = 1e-14) + +@printf("%7s | %5s | %-27s | %-27s\n", "", "bare", "flat", "frozen") +@printf( + "%7s | %5s | %5s %10s %10s | %5s %10s %10s\n", + "tol", + "steps", + "steps", + "Δ state", + "grad err", + "steps", + "Δ state", + "grad err" +) +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...) + @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]), + ) +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. + +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. diff --git a/docs/src/index.md b/docs/src/index.md index aaf3ca9..800492a 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -52,7 +52,7 @@ In the code, a gradient generator `G` holds ``\hat{H}`` in `G.H` and ``\hat{μ}_ ## Contents ```@contents -Pages = ["background.md", "api.md", "references.md"] +Pages = ["howto.md", "background.md", "api.md", "references.md"] Depth = 2 ``` diff --git a/docs/src/refs.bib b/docs/src/refs.bib index db9bdfb..2bb96d3 100644 --- a/docs/src/refs.bib +++ b/docs/src/refs.bib @@ -1,9 +1,14 @@ @string{itac = "IEEE Trans. Automat. Contr."} @string{jcp = "J. Chem. Phys."} @string{jmr = "J. Magnet. Res."} +@string{jpa = "J. Phys. A"} +@string{jrnbs = "J. Res. Natl. Bur. Stand."} +@string{pr = "Phys. Rev."} @string{pra = "Phys. Rev. A"} @string{prl = "Phys. Rev. Lett."} +@string{qam = "Q. Appl. Math."} @string{quant = "Quantum"} +@string{siamrev = "SIAM Rev."} % https://github.com/Humans-of-Julia/BibParser.jl/issues/32 @string{XXXclearparser = ""} @@ -113,3 +118,124 @@ @book{GriewankWalther2008 Edition = {Second}, Address = {Philadelphia}, } + +@article{Tal-EzerJCP1984, + Author = {Tal-Ezer, Hillel and Kosloff, Ronnie}, + Title = {An Accurate and Efficient Scheme for Propagating the Time Dependent {Schrödinger} Equation}, + Journal = jcp, + Year = {1984}, + Doi = {10.1063/1.448136}, + Pages = {3967}, + Volume = {81}, + Number = {9}, +} + +@article{BermanJPA1992, + Author = {Berman, Michael and Kosloff, Ronnie and Tal-Ezer, Hillel}, + Title = {Solution of the time-dependent Liouville-von Neumann equation: dissipative evolution}, + Journal = jpa, + Year = {1992}, + Doi = {10.1088/0305-4470/25/5/031}, + Pages = {1283}, + Volume = {25}, + Number = {5}, +} + +@article{AshkenaziJCP1995, + Author = {Ashkenazi, Guy and Kosloff, Ronnie and Ruhman, Sanford and Tal-Ezer, Hillel}, + Title = {Newtonian propagation methods applied to the photodissociation dynamics of {I}$_3^{-}$}, + Journal = jcp, + Year = {1995}, + Doi = {10.1063/1.469904}, + Pages = {10005-10014}, + Volume = {103}, + Number = {23}, +} + +@article{ArnoldiQAM1951, + Author = {Arnoldi, W. E.}, + Title = {{The principle of minimized iterations in the solution of the matrix eigenvalue problem}}, + Journal = qam, + Year = {1951}, + Doi = {10.1090/qam/42792}, + Pages = {17--29}, + Volume = {9}, + Number = {1}, +} + +@incollection{BockMOCRS1981, + Author = {Bock, H. G.}, + Title = {Numerical Treatment of Inverse Problems in Chemical Reaction Kinetics}, + Booktitle = {Modelling of Chemical Reaction Systems}, + Year = {1981}, + Doi = {10.1007/978-3-642-68220-9_8}, + Pages = {102--125}, + Editor = {Ebert, K. H. and Deuflhard, P. and Jäger, W.}, + Publisher = {Springer}, + Volume = {18}, +} + +@article{FeynmanPR1939, + Author = {Feynman, R. P.}, + Title = {Forces in {Molecules}}, + Journal = pr, + Year = {1939}, + Doi = {10.1103/PhysRev.56.340}, + Pages = {340--343}, + Volume = {56}, + Number = {4}, +} + +@book{GolubVanLoan2013, + Author = {Golub, Gene H. and Van Loan, Charles F.}, + Title = {Matrix {Computations}}, + Publisher = {Johns Hopkins University Press}, + Year = {2013}, + Doi = {10.56021/9781421407944}, + Series = {Johns Hopkins Studies in the Mathematical Sciences}, + Edition = {Fourth}, + Address = {Baltimore}, +} + +@book{HornJohnson1991, + Author = {Horn, Roger A. and Johnson, Charles R.}, + Title = {Topics in {Matrix} {Analysis}}, + Publisher = {Cambridge University Press}, + Year = {1991}, + Doi = {10.1017/cbo9780511840371}, + Address = {Cambridge}, +} + +@book{Hartman2002, + Author = {Hartman, Philip}, + Title = {Ordinary {Differential} {Equations}}, + Publisher = {Society for Industrial and Applied Mathematics}, + Year = {2002}, + Doi = {10.1137/1.9780898719222}, + Series = {Classics in Applied Mathematics}, + Volume = {38}, + Edition = {Second}, + Address = {Philadelphia}, +} + +@article{LanczosJRNBS1950, + Author = {Lanczos, Cornelius}, + Title = {An iteration method for the solution of the eigenvalue problem of linear differential and integral operators}, + Journal = jrnbs, + Year = {1950}, + Doi = {10.6028/jres.045.026}, + Pages = {255--282}, + Volume = {45}, + Number = {4}, +} + +@article{MolerSIREV2003, + Author = {Moler, Cleve and Van Loan, Charles}, + Title = {Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later}, + Journal = siamrev, + Year = {2003}, + Doi = {10.1137/S00361445024180}, + Pages = {3--49}, + Volume = {45}, + Number = {1}, +} diff --git a/src/QuantumGradientGenerators.jl b/src/QuantumGradientGenerators.jl index ed3d056..9727859 100644 --- a/src/QuantumGradientGenerators.jl +++ b/src/QuantumGradientGenerators.jl @@ -11,5 +11,6 @@ include("gradgen_operator.jl") include("grad_vector.jl") include("evaluate.jl") include("linalg.jl") +include("spectral.jl") end diff --git a/src/gradgen_operator.jl b/src/gradgen_operator.jl index 36ca335..7abecce 100644 --- a/src/gradgen_operator.jl +++ b/src/gradgen_operator.jl @@ -29,6 +29,12 @@ available as `G.H` and `G.control_derivs`. The resulting object can be multiplied directly with a gradient vector [`GradVector`](@ref), e.g., in the process of evaluating a piecewise-constant time propagation. + +Since ``G`` is block upper-triangular with ``\hat{H}`` in all diagonal blocks, +its eigenvalues are those of ``\hat{H}``. Accordingly, `eigvals`, `tr`, `det`, +and `specrange` (and thus the spectral range used by the Chebychev propagator) +are evaluated from `G.H`, see the +[Properties of the gradient generator](@ref Background-Properties). """ struct GradgenOperator{num_controls,HT,CDT} H::HT diff --git a/src/linalg.jl b/src/linalg.jl index 4e3d2bc..398d850 100644 --- a/src/linalg.jl +++ b/src/linalg.jl @@ -70,12 +70,13 @@ function LinearAlgebra.axpy!(a, X::GradVector, Y::GradVector) end +# The Euclidean norm of the block vector, consistent with `dot` function LinearAlgebra.norm(Ψ::GradVector) - nrm = LinearAlgebra.norm(Ψ.state) + nrm_sq = LinearAlgebra.norm(Ψ.state)^2 for l ∈ eachindex(Ψ.grad_states) - nrm += LinearAlgebra.norm(Ψ.grad_states[l]) + nrm_sq += LinearAlgebra.norm(Ψ.grad_states[l])^2 end - return nrm + return sqrt(nrm_sq) end @@ -93,6 +94,7 @@ function LinearAlgebra.dot(Ψ::GradVector, G::GradgenOperator, Φ::GradVector) end +# A gradient generator is not normal unless all control derivatives are zero LinearAlgebra.ishermitian(G::GradgenOperator) = false diff --git a/src/spectral.jl b/src/spectral.jl new file mode 100644 index 0000000..b3edaf3 --- /dev/null +++ b/src/spectral.jl @@ -0,0 +1,48 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +# Spectral properties of a gradient generator, evaluated from the dynamical +# generator `G.H` alone. The gradient generator is block upper-triangular with +# `G.H` in all diagonal blocks, so its characteristic polynomial is that of +# `G.H` to the power `L+1`, see the "Properties of the gradient generator" +# section of the Background page in the documentation. + +import LinearAlgebra +import QuantumControl.QuantumPropagators.SpectralRange: specrange + + +_num_blocks(::GradgenOperator{num_controls}) where {num_controls} = num_controls + 1 + + +function specrange(G::GradgenOperator, method::Val{:auto}; kwargs...) + return specrange(G.H, method; _specrange_kwargs(kwargs)...) +end + +function specrange(G::GradgenOperator, method::Val{:diag}; kwargs...) + return specrange(G.H, method; _specrange_kwargs(kwargs)...) +end + +function specrange(G::GradgenOperator, method::Val{:arnoldi}; kwargs...) + return specrange(G.H, method; _specrange_kwargs(kwargs)...) +end + +# A `GradVector` given as the starting vector for the Arnoldi iteration +# contributes its state +function _specrange_kwargs(kwargs) + if haskey(kwargs, :state) && (kwargs[:state] isa GradVector) + return (; kwargs..., state = kwargs[:state].state) + end + return kwargs +end + + +function LinearAlgebra.eigvals(G::GradgenOperator) + return repeat(LinearAlgebra.eigvals(Array(G.H)); inner = _num_blocks(G)) +end + + +LinearAlgebra.tr(G::GradgenOperator) = _num_blocks(G) * LinearAlgebra.tr(G.H) + + +LinearAlgebra.det(G::GradgenOperator) = LinearAlgebra.det(G.H)^_num_blocks(G) diff --git a/test/runtests.jl b/test/runtests.jl index 5691566..7297338 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -18,6 +18,11 @@ using SafeTestsets include("test_specrad.jl") end + print("\n* Properties (test_properties.jl):") + @time @safetestset "Properties" begin + include("test_properties.jl") + end + print("\n* Interface (test_interface.jl):") @time @safetestset "Interface" begin include("test_interface.jl") diff --git a/test/test_interface.jl b/test/test_interface.jl index 15e19ff..b2420dd 100644 --- a/test/test_interface.jl +++ b/test/test_interface.jl @@ -21,6 +21,12 @@ using StableRNGs: StableRNG N = 10 Ψ₀ = random_state_vector(N; rng) Ψ = GradVector(Ψ₀, 2) + # Non-zero gradient states: with zero gradient states, any norm of a + # GradVector equals the norm of its state, so `check_state` could not + # detect a `norm` that is inconsistent with `dot` + for l in eachindex(Ψ.grad_states) + Ψ.grad_states[l] .= random_state_vector(N; rng) + end @test check_state(Ψ) @test norm(2.2 * Ψ - Ψ * 2.2) < 1e-14 @@ -34,6 +40,12 @@ end N = 10 Ψ₀ = SVector{N,ComplexF64}(random_state_vector(N; rng)) Ψ = GradVector(Ψ₀, 2) + # Non-zero gradient states: with zero gradient states, any norm of a + # GradVector equals the norm of its state, so `check_state` could not + # detect a `norm` that is inconsistent with `dot` + for l in eachindex(Ψ.grad_states) + Ψ.grad_states[l] = SVector{N,ComplexF64}(random_state_vector(N; rng)) + end @test check_state(Ψ) @test norm(2.2 * Ψ - Ψ * 2.2) < 1e-14 @@ -208,6 +220,12 @@ end L = 2 Ψ₀ = rand(rng, ComplexF64, N) gradvec = GradVector(Ψ₀, L) + # Non-zero gradient states: with zero gradient states, any norm of a + # GradVector equals the norm of its state, so `check_state` could not + # detect a `norm` that is inconsistent with `dot` + for l in eachindex(gradvec.grad_states) + gradvec.grad_states[l] .= rand(rng, ComplexF64, N) + end # supports_vector_interface is true for Vector-backed GradVector @test supports_vector_interface(typeof(gradvec)) @@ -256,6 +274,12 @@ end L = 2 Ψ₀ = SVector{N,ComplexF64}(rand(rng, ComplexF64, N)) gradvec = GradVector(Ψ₀, L) + # Non-zero gradient states: with zero gradient states, any norm of a + # GradVector equals the norm of its state, so `check_state` could not + # detect a `norm` that is inconsistent with `dot` + for l in eachindex(gradvec.grad_states) + gradvec.grad_states[l] = SVector{N,ComplexF64}(rand(rng, ComplexF64, N)) + end # SVector-backed GradVector: supports_vector_interface follows the component type @test supports_vector_interface(typeof(gradvec)) diff --git a/test/test_properties.jl b/test/test_properties.jl new file mode 100644 index 0000000..192f101 --- /dev/null +++ b/test/test_properties.jl @@ -0,0 +1,140 @@ +# SPDX-FileCopyrightText: © 2026 Michael Goerz +# +# SPDX-License-Identifier: MIT + +# Properties of the gradient generator, as proven in the "Properties of the +# gradient generator" section of the Background page in the documentation + +using Test +using LinearAlgebra +using StableRNGs: StableRNG +using QuantumPropagators.SpectralRange: specrange +using QuantumGradientGenerators: GradgenOperator, GradVector +using QuantumControlTestUtils.RandomObjects: random_matrix, random_state_vector + + +@testset "Spectrum, trace, determinant" begin + rng = StableRNG(2026) + N = 8 + Ĥ = random_matrix(N; hermitian = true, rng) + μ̂₁ = random_matrix(N; hermitian = true, rng) + μ̂₂ = random_matrix(N; hermitian = true, rng) + G = GradgenOperator(Ĥ, [μ̂₁, μ̂₂]) + G_full = Array(G) + + evals = eigvals(G) + @test evals isa Vector{Float64} # real, for a Hermitian Ĥ + @test length(evals) == 3N + @test evals ≈ repeat(eigvals(Hermitian(Ĥ)); inner = 3) + evals_full = sort(eigvals(G_full); by = real) + @test maximum(abs.(imag.(evals_full))) < 1e-12 + @test norm(real.(evals_full) - evals) < 1e-10 + + @test tr(G) ≈ tr(G_full) + @test tr(G) ≈ 3 * tr(Ĥ) + @test det(G) ≈ det(G_full) + @test det(G) ≈ det(Ĥ)^3 + + Ĥ_nh = random_matrix(N; rng) # non-Hermitian + G_nh = GradgenOperator(Ĥ_nh, [μ̂₁]) + @test eigvals(G_nh) isa Vector{ComplexF64} + @test tr(G_nh) ≈ tr(Array(G_nh)) + @test det(G_nh) ≈ det(Array(G_nh)) +end + + +@testset "Spectral range" begin + rng = StableRNG(2027) + N = 40 + Ĥ = random_matrix(N; hermitian = true, rng) + μ̂ = random_matrix(N; hermitian = true, rng) + G = GradgenOperator(Ĥ, [μ̂]) + + E_min, E_max = extrema(eigvals(Hermitian(Ĥ))) + @test all(specrange(G, :diag) .≈ (E_min, E_max)) + @test specrange(G, :diag) == specrange(Ĥ, :diag) + @test specrange(G; rng = StableRNG(1)) == specrange(Ĥ; rng = StableRNG(1)) # :auto + G_small = GradgenOperator(Ĥ[1:20, 1:20], [μ̂[1:20, 1:20]]) # size 40 > 32 + @test specrange(G_small) == specrange(Ĥ[1:20, 1:20], :diag) # :auto → :diag + @test specrange(G; E_min = -1, E_max = 1) == (-1.0, 1.0) + + # :arnoldi uses only the state of a `GradVector` as the starting vector + Ψ = GradVector(random_state_vector(N; rng), 1) + Ψ.grad_states[1] .= random_state_vector(N; rng) + @test specrange(G, :arnoldi; state = Ψ) == specrange(Ĥ, :arnoldi; state = Ψ.state) + @test specrange(G; method = :arnoldi, state = Ψ) == + specrange(Ĥ; method = :arnoldi, state = Ψ.state) + E_min_a, E_max_a = specrange(G, :arnoldi; rng) + @test E_min_a < E_min + 0.1 * (E_max - E_min) + @test E_max_a > E_max - 0.1 * (E_max - E_min) +end + + +@testset "Jordan structure" begin + rng = StableRNG(2028) + N = 6 + Ĥ = random_matrix(N; hermitian = true, rng) + μ̂ = random_matrix(N; hermitian = true, rng) + G_full = Array(GradgenOperator(Ĥ, [μ̂])) + F = eigen(Hermitian(Ĥ)) + for j = 1:N + r = F.vectors[:, j] + @test abs(dot(r, μ̂, r)) > 1e-3 # generic: Hellmann–Feynman derivative ≠ 0 + # algebraic multiplicity 2, but a one-dimensional eigenspace + σ = svdvals(G_full - F.values[j] * I) + @test σ[end] < 1e-12 + @test σ[end-1] > 1e-6 + end +end + + +@testset "Non-normality" begin + rng = StableRNG(2029) + N = 6 + Ĥ = random_matrix(N; hermitian = true, rng) + μ̂ = random_matrix(N; hermitian = true, rng) + Zero = zeros(ComplexF64, N, N) + + G_full = Array(GradgenOperator(Ĥ, [μ̂])) + @test norm(G_full * G_full' - G_full' * G_full) > 1e-3 + @test !ishermitian(GradgenOperator(Ĥ, [μ̂])) + G₀_full = Array(GradgenOperator(Ĥ, [Zero])) + @test norm(G₀_full * G₀_full' - G₀_full' * G₀_full) < 1e-12 + + # Rayleigh quotient outside the spectral range + F = eigen(Hermitian(Ĥ)) + E_max = F.values[end] + e = F.vectors[:, end] + μ_ee = real(dot(e, μ̂, e)) + v = [sign(μ_ee) * e; e] / √2 + rq = real(dot(v, G_full, v)) + @test rq ≈ E_max + abs(μ_ee) / 2 + @test rq > E_max +end + + +@testset "Adjoint" begin + rng = StableRNG(2030) + N = 6 + Ĥ = random_matrix(N; rng) + μ̂ = random_matrix(N; rng) + Zero = zeros(ComplexF64, N, N) + One = Matrix{ComplexF64}(I, N, N) + P = [Zero One; One Zero] + G_full = Array(GradgenOperator(Ĥ, [μ̂])) + G_adj_full = Array(GradgenOperator(copy(Ĥ'), [copy(μ̂')])) + @test norm(G_full' - G_adj_full) > 1e-3 # G[Ĥ]† ≠ G[Ĥ†] + @test norm(G_full' - P * G_adj_full * P) < 1e-14 +end + + +@testset "Gradient vector norm" begin + rng = StableRNG(2031) + N = 10 + Ψ = GradVector(random_state_vector(N; rng), 2) + Ψ.grad_states[1] .= random_state_vector(N; rng) + Ψ.grad_states[2] .= 2 * random_state_vector(N; rng) + @test norm(Ψ) ≈ sqrt(real(dot(Ψ, Ψ))) + @test norm(Ψ) ≈ norm(convert(Vector{ComplexF64}, Ψ)) + @test norm(Ψ) ≈ √6 +end diff --git a/test/test_specrad.jl b/test/test_specrad.jl index d858992..b41c2b3 100644 --- a/test/test_specrad.jl +++ b/test/test_specrad.jl @@ -4,6 +4,7 @@ using Test using LinearAlgebra +using StableRNGs: StableRNG using QuantumPropagators.SpectralRange: specrange using QuantumGradientGenerators: GradGenerator using QuantumControlTestUtils.RandomObjects: random_matrix @@ -54,11 +55,16 @@ using QuantumPropagators.Controls: evaluate H_range_diag = collect(specrange(Ĥ, method = :diag)) @test norm(H_range_diag - G_range_diag) < 1e-12 - G_range_arnoldi = collect(specrange(G, method = :arnoldi, m_max = 100)) + # The spectral range of G is computed from Ĥ + G_range_arnoldi = + collect(specrange(G, method = :arnoldi, m_max = 100, rng = StableRNG(1))) @test eltype(G_range_arnoldi) ≡ Float64 - @test norm(G_range_arnoldi - [H_E_min, H_E_max]) < 1e-2 - # `specrange(Ĥ, method=:arnoldi)` isn't very exact, so we don't - # compare against that. + H_range_arnoldi = + collect(specrange(Ĥ, method = :arnoldi, m_max = 100, rng = StableRNG(1))) + @test G_range_arnoldi == H_range_arnoldi + # The Arnoldi estimate is enlarged to enclose the exact spectral range + @test G_range_arnoldi[1] <= H_E_min + @test G_range_arnoldi[2] >= H_E_max end @@ -105,8 +111,11 @@ end @test eltype(G_range_diag) ≡ Float64 @test norm(G_range_diag - [G_E_min, G_E_max]) < 1e-12 - G_range_arnoldi = collect(specrange(G, method = :arnoldi, m_max = 100)) + G_range_arnoldi = + collect(specrange(G, method = :arnoldi, m_max = 100, rng = StableRNG(1))) @test eltype(G_range_arnoldi) ≡ Float64 - @test norm(G_range_arnoldi - [G_E_min, G_E_max]) < 0.2 + @test G_range_arnoldi[1] <= G_E_min + @test G_range_arnoldi[2] >= G_E_max + @test norm(G_range_arnoldi - [G_E_min, G_E_max]) < 0.5 end