Module krylov 

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
• hermitian_lanczos_lowest_eigenpair: Matrix-free lowest eigenpair solver for Hermitian operators

Future Extensions

• CG (Conjugate Gradient) for symmetric positive definite systems
• BiCGSTAB for non-symmetric systems with better convergence properties

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

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

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. 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. 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.