Evolution methods¤

Evolved mass, power-action L1 error estimate, convergence and status.

The estimate excludes one-generation approximation and representation error. With throw=False, use the distribution only after inspecting convergence.

Fields:

• distribution: Float64 full or interior mass, with the input population shape. Signed inputs are not normalized.
• error_estimate: Scalar absolute L1 power-error estimate in population coordinates; zero for Sequential and identity actions.
• converged: Scalar boolean, true exactly when status is successful.
• status: EvolutionStatus describing the numerical outcome.

Numerical outcomes; successful power checks do not certify backend accuracy.

• successful: Finite output with accepted power-error and inner-solve checks.
• nonfinite: Nonfinite output or error estimate.
• unconverged: Power-error estimate exceeds the configured tolerance.
• linear_solve_failed: A shifted solve failed its status or residual checks.

Compare a result's status with these members. A failed shifted solve takes precedence over nonfiniteness, which takes precedence over power nonconvergence.

Repeat one-generation transitions without an additional power approximation.

Construct as Sequential(). Geometry is supplied separately to advance or through DemographicTransition. The reported power-action error is zero.

Approximate repeated evolution with matrix-free polynomial Arnoldi.

For a prepared operator \(A\), seed \(b\), and \(g\) steps, build an orthonormal basis \(V\) for \(\mathcal K_m(A,b)=\mathrm{span}(b,Ab,\ldots,A^{m-1}b)\). With \(H=V^TAV\), approximate \(A^g b\approx VH^gV^Tb\). Only operator applications are needed; there are no shifted solves. All transition backends are supported, including Dense for small reference calculations.

The basis uses O(n m) storage for working-state size n and dimension m. Larger dimensions can be necessary for long intervals; no restart or automatic Sequential fallback is performed. Convergence checks exclude backend approximation error. First-order derivatives use a coupled Krylov sensitivity action and a two-sided operator pullback, without basis AD. Sensitivity or pullback nonconvergence raises even with throw=False. Higher-order operator sensitivities are not implemented. This method does not provide a matched expectation transpose of its primal approximation.

Approximate a prepared power action using a resolvent Krylov basis.

Each basis vector solves \([I+\tau(I-A)]z=v\), with \(\tau=g/8\) for working exponent \(g\). Jacobi uses a reusable dense LU factorization; other transition backends use unpreconditioned Lineax GMRES. Solver choice is internal. Inner failures are reported as linear_solve_failed.

GMRES uses rtol=1e-11, atol=1e-13, restart=50 (capped by state size), and at most 100 restart cycles per solve, with a recomputed residual check. These inner tolerances are independent of the outer power tolerances. FFT/NUFFT speedups depend on how many operator applications GMRES needs.

First-order derivatives approximate the mathematical power sensitivity with a coupled Krylov action and a two-sided operator pullback. Arnoldi bases are not differentiated. Sensitivity or pullback nonconvergence raises even with throw=False. Higher-order operator sensitivities are not implemented. The input-dependent primal approximation has no matched expectation transpose.