pub fn gmres_affine<T, F>(
apply_a: F,
b: &T,
x0: &T,
a0: AnyScalar,
a1: AnyScalar,
options: &GmresOptions,
) -> Result<GmresResult<T>, KrylovError>Expand description
Solve (a0 I + a1 A) x = b using GMRES with relative residual tolerance.
A zero-norm RHS returns the zero vector after validating the affine coefficients.
a1 = 0 gives x = b / a0 in closed form, with the residual of that x
reported; a subnormal quotient component can round to zero, so the closed
form is not always converged. A gradient-tracked a1 = 0 adds
-a1 (A(b / a0) / a0), which is zero in value and makes the first
derivatives those of the exact solution, at the cost of one call to
apply_a. When A(b / a0) has a NaN or infinite component, A is
applied again to b / a0 2^-s for the smallest s that keeps it finite,
found in about 2 log2(s) further calls; components of b / a0 that this
scaling rounds away are applied as separate exact parts until none is
left. The search covers every s for which b / a0 2^-s keeps its largest
component nonzero. For
single-precision b the closed form requires every factor of
AnyScalar::reciprocal_factors to be in the f32 range.
A zero initial residual, also that of the closed form, is converged for
every rtol, including 0.
The Arnoldi basis is built from the unshifted A callback, while affine
coefficients are applied in the projected Hessenberg problem, matching
KrylovKit’s affine linear-solve convention.
§Errors
Returns KrylovError::InvalidOptions when an option is invalid
(including a max_iter whose Krylov workspace cannot be allocated),
KrylovError::InvalidOptions also when a0 or a1 has a NaN or
infinite component, checked before the zero-RHS return, when b or x0 is
single precision and a0 or a1 is outside the f32 range, or when an
untracked a1 = 0 and single-precision b need a factor of 1 / a0 outside
the f32 range,
KrylovError::NoAffineCoefficient when both affine coefficients are zero,
and KrylovError::Operation when the operator application, vector-space
arithmetic, or a backend call fails. Non-convergence is reported through the
result’s converged flag and does not produce an error.
A right-hand side whose norm is not finite, which would make every relative
residual zero, is a KrylovError::NumericalBreakdown.
A gradient-tracked a1 = 0 whose derivative -A(b / a0) / a0 has a real
or imaginary component outside the f64 range, or whose A is not finite
on b / a0 2^-s for any s that keeps b / a0 nonzero, is a
KrylovError::OutOfRange naming that quantity: the input is outside the
supported range, and no NaN or partial gradient is returned.