Skip to main content

gmres_affine

Function gmres_affine 

Source
pub fn gmres_affine<T, F>(
    apply_a: F,
    b: &T,
    x0: &T,
    a0: AnyScalar,
    a1: AnyScalar,
    options: &GmresOptions,
) -> Result<GmresResult<T>, KrylovError>
where T: TensorVectorSpace, F: Fn(&T) -> Result<T>,
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.