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 systemscg: Conjugate gradients for Hermitian positive-definite systemsbicgstab: BiCGSTAB for real nonsymmetric and complex non-Hermitian systemshermitian_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§
- BiCg
Stab Options - Convergence controls for
bicgstab, which retains a fixed number of vectors. Start with the defaults for double precision and usertol = 1e-5for single precision. - BiCg
Stab Result - Solution and true-residual diagnostics returned by
bicgstab. Likesuper::CgResult, the residual is absolute;super::GmresResultreports a relative residual by default. - CgOptions
- Convergence and iteration controls for
cg. Unlikesuper::GmresOptions, CG needs no restart dimension: it keeps a fixed number of vectors. Start with the defaults for double precision; use looser tolerances (for examplertol = hermitian_tol = 1e-5) for single precision. - CgResult
- Solution and true-residual diagnostics returned by
cg. As withsuper::HermitianLanczosResult,residual_normis an absolute norm;super::GmresResultinstead reports a relative norm by default. - Gmres
Options - Options for GMRES solver.
- Gmres
Result - Result of GMRES solver. Contains the solution, iteration count, final residual norm, and convergence status.
- Hermitian
Krylov Expm Options - 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. - Hermitian
Krylov Expm Result - Result of
hermitian_krylov_expm_multiply. - Hermitian
Lanczos Options - 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, useDefault::default. - Hermitian
Lanczos Result - Result of
hermitian_lanczos_lowest_eigenpair. Contains the lowest Ritz eigenpair, the final true residual norm, iteration count, and convergence status. - Restart
Gmres Options - Options for restarted GMRES with truncation.
This is used by
restart_gmres_with_truncationwhich wraps the standard GMRES with an outer loop that recomputes the true residual at each restart. - Restart
Gmres Result - Result of restarted GMRES solver.
Enums§
- Krylov
Error - Error returned by the matrix-free Krylov solvers.
Functions§
- bicgstab
- Solve
A x = bwith matrix-free BiCGSTAB. - cg
- Solve
A x = bwith matrix-free conjugate gradients. - gmres
- Solve
A x = busing GMRES (Generalized Minimal Residual Method). This implements the restarted GMRES algorithm that works with abstract tensor types through theTensorVectorSpacetrait’s vector space operations. - gmres_
affine - Solve
(a0 I + a1 A) x = busing GMRES with relative residual tolerance. A zero-norm RHS returns the zero vector after validating the affine coefficients.a1 = 0givesx = b / a0in closed form, with the residual of thatxreported; a subnormal quotient component can round to zero, so the closed form is not always converged. A gradient-trackeda1 = 0adds-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 toapply_a. WhenA(b / a0)has a NaN or infinite component,Ais applied again tob / a0 2^-sfor the smalleststhat keeps it finite, found in about2 log2(s)further calls; components ofb / a0that this scaling rounds away are applied as separate exact parts until none is left. The search covers everysfor whichb / a0 2^-skeeps its largest component nonzero. For single-precisionbthe closed form requires every factor ofAnyScalar::reciprocal_factorsto be in thef32range. A zero initial residual, also that of the closed form, is converged for everyrtol, including0. The Arnoldi basis is built from the unshiftedAcallback, 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 = busing GMRES with an absolute residual tolerance. The Arnoldi basis is built from the unshiftedAcallback, while the affine coefficients are applied to the small Hessenberg problem. This mirrors KrylovKit’slinsolve(operator, b, a0, a1)algorithm and avoids changing the Krylov basis when affine coefficients are present. - gmres_
with_ absolute_ tolerance - Solve
A x = busing 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 defaultgmresAPI uses relative residual tolerance and is preferred for scale-independent solves. - gmres_
with_ total_ iteration_ limit - Solve
A x = busing GMRES while enforcing a total iteration limit.GmresOptions::max_iterremains the restart cycle length andGmresOptions::max_restartsremains the maximum number of restart cycles.max_total_itercaps the total number of Arnoldi steps across all restart cycles; the final cycle is shortened when necessary. - gmres_
with_ truncation - Solve
A x = busing GMRES with optional truncation after each iteration. This is an extension ofgmresthat 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 forA, 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 toA * vector. The algorithm builds an orthonormal Krylov basis using modified Gram-Schmidt with a second reorthogonalization pass, forms the small projected matrixV^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 = busing restarted GMRES with truncation. This wrapsgmres_with_truncationwith 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.