Skip to content

Properties of gradient generators, propagation semantics, and how-to guides - #37

Merged
goerz merged 4 commits into
masterfrom
gradgen-properties
Nov 22, 2026
Merged

goerz merged 4 commits into
masterfrom
gradgen-properties

Conversation

@goerz

@goerz goerz commented Nov 22, 2026

Copy link
Copy Markdown
Member

This builds on the "Background" page from #36. It establishes which properties of a gradient generator G follow from those of the dynamical generator Ĥ, uses them in the implementation, and documents what the gradient states of a numerical propagation mean for different propagation methods.

Code

  • specrange, eigvals, tr, and det of a GradgenOperator are evaluated from G.H alone. G is block upper-triangular with Ĥ in all L+1 diagonal blocks, so det(G - λ) = det(Ĥ - λ)^(L+1): G has the eigenvalues, spectral range, and spectral radius of Ĥ. This reduces an exact diagonalization from dimension N(L+1) to N, and it avoids an Arnoldi estimate for the non-normal G, whose Ritz values can lie outside the spectral range. With method=:auto, the choice between :diag and :arnoldi is now based on the size of G.H.
  • norm(::GradVector) is now the Euclidean norm of the block vector, consistent with dot, as the Arnoldi iteration requires. It used to be the sum of the norms of the state and the gradient states.
  • Tests for all proven properties (test/test_properties.jl). Two Arnoldi tests in test/test_specrad.jl passed only because of the (L+1)-fold eigenvalues of G (and one of them was flaky); they now use a seeded RNG and test the estimate for Ĥ. The check_state tests now use gradient vectors with non-zero gradient states: with zero gradient states, they could not detect the inconsistent norm.

Documentation

  • A section "Properties of the gradient generator" on the Background page, organized by practical consequence: the spectrum comes from Ĥ; a gradient generator cannot be propagated by diagonalization (it is not diagonalizable, because the derivative of a phase grows linearly in time, and the eigenvector method silently returns wrong results); methods that assume a Hermitian generator (Lanczos, norm conservation, bounds on expectation values) do not apply, since G is never normal; a backward propagation needs G[Ĥ†], not G[Ĥ]†; and norm/dot treat a gradient vector as one long vector.
  • A subsection "Flat, frozen, and dual semantics" that distinguishes how a propagation method can treat inner products, norms, and data-dependent choices (spectral range, interpolation points, time steps) when it propagates a gradient vector, where the three coincide (exact exponential, Chebychev, fixed-step ODE solvers), and a table for the propagators in QuantumPropagators.
  • Propositions, corollaries, and the theorem are typeset as admonitions with individual anchors (Documenter ≥ 1.18), which can be linked with @ref and, via the inventory, with @extref from other packages. References to numbered results throughout the page now state what the result says.
  • New citations: Tal-Ezer & Kosloff (Chebychev), Berman et al. and Ashkenazi et al. (Newton), Arnoldi, Lanczos, Bock (internal numerical differentiation), Feynman (Hellmann–Feynman theorem), Golub & Van Loan, Horn & Johnson, Hartman, and Moler & Van Loan.
  • A "How-to Guides" page: backward propagation of gradient vectors; gradient vectors with the Chebychev propagator (exact derivative of the Chebychev approximation); and controlling the time steps of an adaptive ODE solver for gradient vectors ("flat" vs. "frozen" error control via internalnorm), with numerical comparisons.

Related

  • check_normalization=true in the Chebychev propagator compares expectation values with the spectral range, which is not valid for a gradient generator. With the corrected norm, it now fails for gradient vectors instead of passing by accident. QuantumPropagators will skip the check (with a warning) for non-Hermitian generators; until that is released, the how-to advises against passing it.
  • Planned follow-up: a helper for the "frozen" error norm of ODE solvers, and *(::GradgenOperator, ::AbstractVector), so that the ODE how-to no longer needs check = false.

A gradient generator G is block upper-triangular with the dynamical
generator Ĥ in all L+1 diagonal blocks, so det(G - λ) = det(Ĥ - λ)^(L+1).
Use this to compute `specrange`, `eigvals`, `tr`, and `det` of a
`GradgenOperator` from `G.H` alone: an exact diagonalization has
dimension N instead of N(L+1), and an Arnoldi estimate avoids the Ritz
values of the non-normal matrix G, which can lie outside the spectral
range. With `method=:auto`, the choice between `:diag` and `:arnoldi`
now depends on the size of `G.H`. Two Arnoldi tests in
test_specrad.jl only passed because of the (L+1)-fold eigenvalues of G;
they now compare against the estimate for Ĥ with a seeded RNG.

Fix `norm(::GradVector)` to be the Euclidean norm of the block vector,
consistent with `dot`, as the Arnoldi iteration requires. It was the
sum of the norms of the state and the gradient states.

Add a "Properties of the gradient generator" section to the Background
page (spectrum, Jordan structure, non-normality and its consequences for
Rayleigh quotients and Ritz values, the adjoint, and the inner product
and norm of gradient vectors), and a subsection that defines the
"flat", "frozen", and "full dual" semantics of propagating gradient
vectors with numerical methods, with a table for the propagators in
QuantumPropagators. Throughout the page, references to numbered results
now state what the result says. Cite the Chebychev and Newton
propagators, Arnoldi and Lanczos iteration, internal numerical
differentiation, the Hellmann-Feynman theorem, and standard texts for
matrix analysis and ODE theory.
Add a "How-to Guides" page with three guides that illustrate practical
consequences of the properties on the Background page:

* Backward propagation: build the gradient generator from the adjoint
  dynamical generator, G[Ĥ†], not the adjoint of the gradient generator,
  and reset the gradient states before each step, as in GRAPE.
* Chebychev propagation: the spectral range comes from Ĥ, and the
  gradient is the exact derivative of the Chebychev approximation, even
  for a deliberately inaccurate propagation. The optional
  `check_normalization` must not be used for gradient vectors.
* Adaptive ODE solvers: an `internalnorm` that only includes the state
  gives the "frozen" semantics (the same time steps as for the bare
  state), the default norm the "flat" semantics, compared numerically
  over a range of tolerances.

The docs environment gains OrdinaryDiffEq, DiffEqBase, LinearAlgebra,
and Printf for the examples.
The interface tests called `check_state` only on gradient vectors
created with `GradVector(Ψ₀, L)`, whose gradient states are zero. For
such a vector, any norm equals the norm of the state, so `check_state`
could not detect that `norm(::GradVector)` was inconsistent with `dot`
(it summed the norms of the components). Fill the gradient states with
random values before calling `check_state`; with the old `norm`, the
check now fails.
Put the statement of every proposition, corollary, and theorem on the
Background page into an admonition, so that it is clear where the
statement ends and the proof or the discussion begins. Each statement
starts with an inline anchor (Documenter >= 1.18), e.g.,
`Background-prop-charpoly`, which can be targeted with `@ref`, and with
`@extref` from other packages, since these anchors are written to the
`objects.inv` inventory. All references to numbered results now link to
them. A small CSS asset keeps the admonition title visible when
following such a link.

Restructure the "Properties of the gradient generator" section so that
each subsection (Spectrum, Diagonalizability, Non-normality, Adjoint,
Inner products and norms) starts with the practical consequence for
propagating gradient vectors: e.g., a gradient generator cannot be
propagated by diagonalizing it (the eigenvector method silently returns
wrong results, as Moler and Van Loan describe), because the derivative
of a phase grows linearly in time. Define "normal" informally, speak of
expectation values instead of Rayleigh quotients, remind the reader
what L is, and link back to the reduction to a single control. Rename
the left eigenvector in Proposition 9 to avoid a clash with the control
index l.

Also: cite Moler and Van Loan (2003), give the section of Bock (1981)
for internal numerical differentiation, update the links and wording in
the how-to guides accordingly, and note in the changelog that
`check_normalization` in the Chebychev propagator now fails for gradient
vectors instead of passing by accident.
@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.9%. Comparing base (38bd2be) to head (943e345).

Additional details and impacted files
@@           Coverage Diff            @@
##           master     #37     +/-   ##
========================================
- Coverage    86.9%   85.9%   -1.0%     
========================================
  Files           6       7      +1     
  Lines         297     311     +14     
========================================
+ Hits          258     267      +9     
- Misses         39      44      +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@goerz
goerz merged commit 3c61e68 into master Nov 22, 2026
9 checks passed
@goerz
goerz deleted the gradgen-properties branch November 22, 2026 16:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant