Skip to content

HMath.Matrix.Iterative

Module index · Numerical conventions

Description

Bounded reference iterative solvers for dense real matrices. Every returned result is checked against the original residual. Square methods stop when ||b-Ax|| <= atol + rtol*||b||. Least-squares methods may also stop when ||A^T(b-Ax)|| <= atol + rtol*||A^T b||. Full Krylov bases are retained in GMRES, MINRES and LSMR; these emphasize transparent mathematics over storage. Nonfinite arithmetic, breakdown and exhausted budgets return structured errors.

On this page

API Purpose
IterativeOptions Absolute and relative residual tolerances and maximum iterations.
IterativeOptions Declaration and type contract below.
absoluteTolerance Finite nonnegative absolute residual tolerance.
relativeTolerance Finite nonnegative relative residual tolerance.
maximumIterations Nonnegative maximum iteration count.
defaultIterativeOptions 1000 iterations, zero absolute tolerance and relative tolerance 1e-10.
IterativeResult Converged state with norms evaluated from the original matrix and rhs.
IterativeResult Declaration and type contract below.
iterativeSolution Solution in original variable order.
iterativeIterations Number of completed updates.
iterativeResidualNorm Euclidean norm of b-Ax.
iterativeNormalResidualNorm Euclidean norm of A^T(b-Ax), useful for inconsistent least squares.
Preconditioner A checked inverse action M^-1; constructors retain their input dimension.
applyPreconditioner Apply an inverse action; wrong vector lengths and nonfinite values fail.
identityPreconditioner Identity inverse action in a nonnegative dimension.
jacobiPreconditioner Inverse diagonal preconditioner.
blockJacobiPreconditioner Block Jacobi from contiguous positive block sizes summing to the dimension.
ilu0Preconditioner Incomplete LU with zero fill and no pivoting.
ic0Preconditioner Incomplete Cholesky with zero fill for a symmetric positive-definite input.
conjugateGradient Conjugate gradient for symmetric positive-definite matrices.
preconditionedCG Preconditioned conjugate gradient.
gmres Restarted GMRES with modified Gram--Schmidt Arnoldi and a second orthogonalization pass.
minres Minimum residual on the symmetric Lanczos Krylov space, including indefinite systems.
bicg Bi-conjugate gradient for nonsymmetric square matrices; the initial shadow residual equals the initial residual.
bicgstab Stabilized BiCG with a fixed initial shadow residual and a minimal-residual omega step.
lsqr LSQR by Golub--Kahan bidiagonalization and plane-rotation recurrences.
lsmr LSMR's minimum-normal-residual Krylov objective using explicit Golub--Kahan bases and QR on the projected tridiagonal normal operator.
jacobiSolve Simultaneous Jacobi stationary iteration.
gaussSeidelSolve Forward Gauss--Seidel stationary iteration.
sorSolve Successive over-relaxation, requiring a finite relaxation 0<omega<2.
iterativeRefinement Residual-correction refinement using a reusable partial-pivoted LU.

Documentation

IterativeOptions

data IterativeOptions a Source #

Absolute and relative residual tolerances and maximum iterations. A zero budget succeeds only when the supplied initial guess already meets tolerance.

Constructors

IterativeOptions 

Fields

Instances

Instances details
Show a => Show (IterativeOptions a) Source # 
Instance details

Defined in HMath.Matrix.Iterative

Methods

showsPrec :: Int -> IterativeOptions a -> ShowS #

show :: IterativeOptions a -> String #

showList :: [IterativeOptions a] -> ShowS #

Eq a => Eq (IterativeOptions a) Source # 
Instance details

Defined in HMath.Matrix.Iterative

Methods

(==) :: IterativeOptions a -> IterativeOptions a -> Bool #

(/=) :: IterativeOptions a -> IterativeOptions a -> Bool #

defaultIterativeOptions

defaultIterativeOptions :: Fractional a => IterativeOptions a Source #

1000 iterations, zero absolute tolerance and relative tolerance 1e-10.

IterativeResult

data IterativeResult a Source #

Converged state with norms evaluated from the original matrix and rhs.

Constructors

IterativeResult 

Fields

Instances

Instances details
Show a => Show (IterativeResult a) Source # 
Instance details

Defined in HMath.Matrix.Iterative

Methods

showsPrec :: Int -> IterativeResult a -> ShowS #

show :: IterativeResult a -> String #

showList :: [IterativeResult a] -> ShowS #

Eq a => Eq (IterativeResult a) Source # 
Instance details

Defined in HMath.Matrix.Iterative

Methods

(==) :: IterativeResult a -> IterativeResult a -> Bool #

(/=) :: IterativeResult a -> IterativeResult a -> Bool #

Preconditioner

data Preconditioner a Source #

A checked inverse action M^-1; constructors retain their input dimension.

applyPreconditioner

applyPreconditioner :: Preconditioner a -> [a] -> Either MathError [a] Source #

Apply an inverse action; wrong vector lengths and nonfinite values fail.

identityPreconditioner

identityPreconditioner :: RealFloat a => Int -> Either MathError (Preconditioner a) Source #

Identity inverse action in a nonnegative dimension.

jacobiPreconditioner

jacobiPreconditioner :: RealFloat a => Matrix a -> Either MathError (Preconditioner a) Source #

Inverse diagonal preconditioner. Every diagonal entry must be nonzero.

blockJacobiPreconditioner

blockJacobiPreconditioner :: RealFloat a => [Int] -> Matrix a -> Either MathError (Preconditioner a) Source #

Block Jacobi from contiguous positive block sizes summing to the dimension. Each diagonal block is factored with pivoted LU; off-block entries are ignored.

ilu0Preconditioner

ilu0Preconditioner :: RealFloat a => Matrix a -> Either MathError (Preconditioner a) Source #

Incomplete LU with zero fill and no pivoting. The exact nonzero pattern of A is retained, diagonal pivots are mandatory, and zero pivots fail explicitly.

ic0Preconditioner

ic0Preconditioner :: RealFloat a => Matrix a -> Either MathError (Preconditioner a) Source #

Incomplete Cholesky with zero fill for a symmetric positive-definite input. Dropping can itself cause a nonpositive pivot; that reports NotPositiveDefinite.

conjugateGradient

conjugateGradient :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Conjugate gradient for symmetric positive-definite matrices. Symmetry is checked; nonpositive Krylov curvature rejects indefinite matrices encountered.

preconditionedCG

preconditionedCG :: RealFloat a => IterativeOptions a -> Preconditioner a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Preconditioned conjugate gradient. The inverse action must be SPD; a nonpositive r^T M^-1 r or search curvature is reported as a domain error.

gmres

gmres :: RealFloat a => IterativeOptions a -> Int -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Restarted GMRES with modified Gram--Schmidt Arnoldi and a second orthogonalization pass. Restart length must be positive; total iterations are bounded by options. Each projected least-squares problem is solved by QR.

minres

minres :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Minimum residual on the symmetric Lanczos Krylov space, including indefinite systems. A full tridiagonal projected least-squares problem is solved by QR each iteration (the mathematical MINRES objective, without short recurrences).

bicg

bicg :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Bi-conjugate gradient for nonsymmetric square matrices; the initial shadow residual equals the initial residual. Biorthogonality breakdown fails explicitly.

bicgstab

bicgstab :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Stabilized BiCG with a fixed initial shadow residual and a minimal-residual omega step. Zero projection/omega denominators return explicit breakdown errors.

lsqr

lsqr :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

LSQR by Golub--Kahan bidiagonalization and plane-rotation recurrences. Rectangular and rank-deficient systems are supported. The least-squares stopping test uses the original normal residual as well as the true residual.

lsmr

lsmr :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

LSMR's minimum-normal-residual Krylov objective using explicit Golub--Kahan bases and QR on the projected tridiagonal normal operator. A^T A is never formed. This full-basis reference version uses more storage than short-recurrence implementations; it minimizes ||A^T(b-Ax)|| over the generated Krylov space.

jacobiSolve

jacobiSolve :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Simultaneous Jacobi stationary iteration. Convergence requires an appropriate splitting (for example strict diagonal dominance); it is not assumed.

gaussSeidelSolve

gaussSeidelSolve :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Forward Gauss--Seidel stationary iteration.

sorSolve

sorSolve :: RealFloat a => IterativeOptions a -> a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Successive over-relaxation, requiring a finite relaxation 0<omega<2.

iterativeRefinement

iterativeRefinement :: RealFloat a => IterativeOptions a -> Matrix a -> [a] -> [a] -> Either MathError (IterativeResult a) Source #

Residual-correction refinement using a reusable partial-pivoted LU. Residuals and corrections use the scalar type's precision. This does not claim mixed-precision accuracy; callers may provide an initial guess from any solver.