Skip to main content

Module krylov

Module krylov 

Source
Expand description

Krylov subspace methods for solving linear equations with abstract tensors.

This module provides iterative solvers that work with any type implementing TensorVectorSpace, enabling their use in tensor network algorithms without requiring dense vector representations.

§Solvers

  • gmres: Generalized Minimal Residual Method (GMRES) for non-symmetric systems
  • cg: Conjugate gradients for Hermitian positive-definite systems
  • bicgstab: BiCGSTAB for real nonsymmetric and complex non-Hermitian systems
  • hermitian_lanczos_lowest_eigenpair: Matrix-free lowest eigenpair solver for Hermitian operators

§Example

use tensor4all_core::{
    krylov::{gmres, GmresOptions},
    DynIndex, IdxTensor, TensorVectorSpace,
};

let i = DynIndex::new_dyn(2);
let rhs = IdxTensor::from_dense(vec![i.clone()], vec![1.0, -1.0])?;
let initial_guess = IdxTensor::from_dense(vec![i.clone()], vec![0.0, 0.0])?;

let apply_operator = |x: &IdxTensor| Ok(x.clone());
let result = gmres(apply_operator, &rhs, &initial_guess, &GmresOptions::default())?;

assert!(result.converged);
assert!(result.solution.sub(&rhs)?.maxabs()? < 1e-12);

Structs§

BiCgStabOptions
Convergence controls for bicgstab, which retains a fixed number of vectors. Start with the defaults for double precision and use rtol = 1e-5 for single precision.
BiCgStabResult
Solution and true-residual diagnostics returned by bicgstab. Like super::CgResult, the residual is absolute; super::GmresResult reports a relative residual by default.
CgOptions
Convergence and iteration controls for cg. Unlike super::GmresOptions, CG needs no restart dimension: it keeps a fixed number of vectors. Start with the defaults for double precision; use looser tolerances (for example rtol = hermitian_tol = 1e-5) for single precision.
CgResult
Solution and true-residual diagnostics returned by cg. As with super::HermitianLanczosResult, residual_norm is an absolute norm; super::GmresResult instead reports a relative norm by default.
GmresOptions
Options for GMRES solver.
GmresResult
Result of GMRES solver. Contains the solution, iteration count, final residual norm, and convergence status.
HermitianKrylovExpmOptions
Options for hermitian_krylov_expm_multiply. The routine builds a Hermitian Lanczos basis for a matrix-free operator, exponentiates the small projected Hermitian matrix, and combines the basis vectors without materializing the full operator. Scalar convergence checks and projected eigendecompositions are explicit non-differentiable boundaries; vector-space tensor operations preserve backend metadata when the underlying tensor implementation supports it.
HermitianKrylovExpmResult
Result of hermitian_krylov_expm_multiply.
HermitianLanczosOptions
Options for hermitian_lanczos_lowest_eigenpair. These options control the maximum Krylov subspace dimension, convergence tolerance, and validation tolerance for the small projected Hermitian matrix. When in doubt, use Default::default.
HermitianLanczosResult
Result of hermitian_lanczos_lowest_eigenpair. Contains the lowest Ritz eigenpair, the final true residual norm, iteration count, and convergence status.
RestartGmresOptions
Options for restarted GMRES with truncation. This is used by restart_gmres_with_truncation which wraps the standard GMRES with an outer loop that recomputes the true residual at each restart.
RestartGmresResult
Result of restarted GMRES solver.

Enums§

KrylovError
Error returned by the matrix-free Krylov solvers.

Functions§

bicgstab
Solve A x = b with matrix-free BiCGSTAB.
cg
Solve A x = b with matrix-free conjugate gradients.
gmres
Solve A x = b using GMRES (Generalized Minimal Residual Method). This implements the restarted GMRES algorithm that works with abstract tensor types through the TensorVectorSpace trait’s vector space operations.
gmres_affine
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.
gmres_affine_with_absolute_tolerance
Solve (a0 I + a1 A) x = b using GMRES with an absolute residual tolerance. The Arnoldi basis is built from the unshifted A callback, while the affine coefficients are applied to the small Hessenberg problem. This mirrors KrylovKit’s linsolve(operator, b, a0, a1) algorithm and avoids changing the Krylov basis when affine coefficients are present.
gmres_with_absolute_tolerance
Solve A x = b using GMRES with an absolute residual tolerance. A zero-norm RHS returns the zero vector rather than the initial guess. This variant stops when ||b - A*x|| < atol. The default gmres API uses relative residual tolerance and is preferred for scale-independent solves.
gmres_with_total_iteration_limit
Solve A x = b using GMRES while enforcing a total iteration limit. GmresOptions::max_iter remains the restart cycle length and GmresOptions::max_restarts remains the maximum number of restart cycles. max_total_iter caps the total number of Arnoldi steps across all restart cycles; the final cycle is shortened when necessary.
gmres_with_truncation
Solve A x = b using GMRES with optional truncation after each iteration. This is an extension of gmres that allows truncating Krylov basis vectors to control bond dimension growth in tensor network representations.
hermitian_krylov_expm_multiply
Apply exp(exponent * A) to a vector using a matrix-free Hermitian Krylov method. This routine only materializes small projected Krylov matrices. It never forms the full matrix for A, so it can be used by tensor-network local solvers whose operator application is available as a closure.
hermitian_lanczos_lowest_eigenpair
Compute the lowest eigenpair of a Hermitian matrix-free operator. The operator is supplied as apply_a, which maps a vector to A * vector. The algorithm builds an orthonormal Krylov basis using modified Gram-Schmidt with a second reorthogonalization pass, forms the small projected matrix V^dagger A V, and solves that small Hermitian problem via tensorbackend. The full operator matrix is never materialized.
restart_gmres_with_truncation
Solve A x = b using restarted GMRES with truncation. This wraps gmres_with_truncation with an outer loop that recomputes the true residual at each restart. This is particularly useful for MPS/MPO computations where truncation can cause the inner GMRES residual to be inaccurate.