HMath.Matrix.Decomposition¶

Description

Pure reference decompositions with explicit shape and tolerance contracts. Cholesky uses a symmetric positive-definite matrix; unpivoted LDL^T requires nonzero scalar pivots. Bidiagonalization supports rectangular real matrices.

On this page¶

API	Purpose
gaussianElimination	Given finite nonnegative relative tolerance then finite matrix, return normalized row-echelon form and zero-based pivot columns.
gaussJordan	Given relative tolerance then finite matrix, return reduced row-echelon form and zero-based pivot columns using row pivoting.
cholesky	Factor a finite symmetric positive-definite matrix as L*transpose(L), returning lower-triangular L.
ldlt	Factor a finite symmetric matrix as Ldiag(d)transpose(L), returning unit lower L and diagonal list d.
givensQR	Factor finite m-by-n matrix as Q*R using Givens rotations, returning square m-by-m Q and m-by-n R without column pivoting.
Bidiagonal	Orthogonal factors A=UBtranspose(V), retaining a rectangular bidiagonal B.
Bidiagonal	Declaration and type contract below.
bidiagonalU	Left orthogonal factor in A=UBtranspose(V).
bidiagonalB	Bidiagonal matrix in the factorization, retaining input shape.
bidiagonalV	Right orthogonal factor in A=UBtranspose(V).
bidiagonalize	Reduce a finite rectangular matrix to bidiagonal form with orthogonal factors, returning Bidiagonal fields.
tridiagonalize	Reduce a symmetric finite square matrix to (Q,T), satisfying A = Q * T * transpose Q with tridiagonal T.
Iteration	Accepted eigenpair estimate with residual and iteration count.
Iteration	Declaration and type contract below.
iterationValue	Returned real eigenvalue estimate.
iterationVector	Returned normalized eigenvector estimate.
iterationResidual	Eigenpair residual norm used to assess convergence.
iterationCount	Number of eigen-iteration updates performed.
powerIteration	Given positive finite tolerance,positive budget,square finite matrix,then nonzero starting vector, estimate a dominant eigenpair.
inverseIteration	Given tolerance,budget,shift,square matrix,then starting vector, estimate an eigenpair near shift by repeated shifted solves.
rayleighIteration	Given tolerance,budget,square matrix,then nonzero initial vector, refine an eigenpair with Rayleigh-quotient shifts.
Arnoldi	Krylov basis columns and upper-Hessenberg projection returned by arnoldi; exact breakdown may shorten the basis.
Arnoldi	Declaration and type contract below.
arnoldiBasis	Orthonormal Krylov basis vectors as matrix columns.
arnoldiHessenberg	Hessenberg projection relating the matrix action to the Arnoldi basis.
arnoldi	Given positive finite tolerance,requested basis size,square matrix,then nonzero initial vector, build Arnoldi basis/projection.
lanczos	Symmetric Lanczos with the three-term recurrence and two full reorthogonalization passes.
qrIteration	Given positive finite tolerance,positive budget,then finite square matrix, iterate QR to return (Q,T): accumulated orthogonal vectors and the resulting iterate.
jordanChains	Verify supplied Jordan chains against A and lambda and construct J and P.
jordanForm	Exact Jordan construction over Rational with a caller-provided complete set of distinct rational eigenvalues (multiplicities are inferred).

Documentation

gaussianElimination

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

Given finite nonnegative relative tolerance then finite matrix, return normalized row-echelon form and zero-based pivot columns. Partial row pivoting skips pivots below tolerance times the global entry scale. Invalid tolerance/non-finite arithmetic fails.

gaussJordan

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

Given relative tolerance then finite matrix, return reduced row-echelon form and zero-based pivot columns using row pivoting. Invalid tolerance/non-finite arithmetic fails.

cholesky

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

Factor a finite symmetric positive-definite matrix as L*transpose(L), returning lower-triangular L. Non-squareasymmetricnon-finite input or a nonpositive diagonal pivot returns Left MathError.

ldlt

ldlt :: RealFloat a => Matrix a -> Either MathError (Matrix a, [a]) Source #

Factor a finite symmetric matrix as L*diag(d)*transpose(L), returning unit lower L and diagonal list d. This unpivoted method requires nonzero scalar pivots; it can reject invertible indefinite matrices needing block pivots.

givensQR

givensQR :: RealFloat a => Matrix a -> Either MathError (Matrix a, Matrix a) Source #

Factor finite m-by-n matrix as Q*R using Givens rotations, returning square m-by-m Q and m-by-n R without column pivoting. Non-finite input/intermediate results fail.

Bidiagonal

data Bidiagonal a Source #

Orthogonal factors A=U*B*transpose(V), retaining a rectangular bidiagonal B.

Constructors

Bidiagonal
Fields bidiagonalU :: Matrix a Left orthogonal factor in A=UBtranspose(V). bidiagonalB :: Matrix a Bidiagonal matrix in the factorization, retaining input shape. bidiagonalV :: Matrix a Right orthogonal factor in A=UBtranspose(V).

Instances

Instances details

Show a => Show (Bidiagonal a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods showsPrec :: Int -> Bidiagonal a -> ShowS # show :: Bidiagonal a -> String # showList :: [Bidiagonal a] -> ShowS #
Eq a => Eq (Bidiagonal a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods (==) :: Bidiagonal a -> Bidiagonal a -> Bool # (/=) :: Bidiagonal a -> Bidiagonal a -> Bool #

bidiagonalize

bidiagonalize :: RealFloat a => Matrix a -> Either MathError (Bidiagonal a) Source #

Reduce a finite rectangular matrix to bidiagonal form with orthogonal factors, returning Bidiagonal fields. Input/numeric validation errors propagate; inspect the factor types and module reconstruction example.

tridiagonalize

tridiagonalize :: Matrix Double -> Either MathError (Matrix Double, Matrix Double) Source #

Reduce a symmetric finite square matrix to (Q,T), satisfying A = Q * T * transpose Q with tridiagonal T. Non-square/asymmetric input or numerical failure returns Left MathError.

Iteration

data Iteration a Source #

Accepted eigenpair estimate with residual and iteration count. See the iterative solver's tolerance and failure contract.

Constructors

Iteration
Fields iterationValue :: a Returned real eigenvalue estimate. iterationVector :: [a] Returned normalized eigenvector estimate. iterationResidual :: a Eigenpair residual norm used to assess convergence. iterationCount :: Int Number of eigen-iteration updates performed.

Instances

Instances details

Show a => Show (Iteration a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods showsPrec :: Int -> Iteration a -> ShowS # show :: Iteration a -> String # showList :: [Iteration a] -> ShowS #
Eq a => Eq (Iteration a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods (==) :: Iteration a -> Iteration a -> Bool # (/=) :: Iteration a -> Iteration a -> Bool #

powerIteration

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

Given positive finite tolerance,positive budget,square finite matrix,then nonzero starting vector, estimate a dominant eigenpair. Return Iteration with valuevectorresidualcount; invalid dimensionsoptions, non-finite arithmetic or exhausted budget fails.

inverseIteration

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

Given tolerance,budget,shift,square matrix,then starting vector, estimate an eigenpair near shift by repeated shifted solves. Require valid finite inputs and nonzero start; singular shifted systems or convergence/numerical failures return Left MathError.

rayleighIteration

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

Given tolerance,budget,square matrix,then nonzero initial vector, refine an eigenpair with Rayleigh-quotient shifts. Shape/options, singular shifted solves or convergence/numerical failures return Left MathError.

Arnoldi

data Arnoldi a Source #

Krylov basis columns and upper-Hessenberg projection returned by arnoldi; exact breakdown may shorten the basis.

Constructors

Arnoldi
Fields arnoldiBasis :: Matrix a Orthonormal Krylov basis vectors as matrix columns. arnoldiHessenberg :: Matrix a Hessenberg projection relating the matrix action to the Arnoldi basis.

Instances

Instances details

Show a => Show (Arnoldi a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods showsPrec :: Int -> Arnoldi a -> ShowS # show :: Arnoldi a -> String # showList :: [Arnoldi a] -> ShowS #
Eq a => Eq (Arnoldi a) Source #
Instance details Defined in HMath.Matrix.Decomposition Methods (==) :: Arnoldi a -> Arnoldi a -> Bool # (/=) :: Arnoldi a -> Arnoldi a -> Bool #

arnoldi

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

Given positive finite tolerance,requested basis size,square matrix,then nonzero initial vector, build Arnoldi basis/projection. Require 1<=requested<=matrix order. Invalid input or numerical failures return Left MathError; exact Krylov breakdown terminates the basis.

lanczos

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

Symmetric Lanczos with the three-term recurrence and two full reorthogonalization passes. Small correction coefficients are retained in H so the projection residual remains meaningful after floating-point rounding.

qrIteration

qrIteration :: RealFloat a => a -> Int -> Matrix a -> Either MathError (Matrix a, Matrix a) Source #

Given positive finite tolerance,positive budget,then finite square matrix, iterate QR to return (Q,T): accumulated orthogonal vectors and the resulting iterate. Invalid options/shape or failure to converge within budget returns Left MathError.

jordanChains

jordanChains :: RealFloat a => a -> Matrix a -> [(a, [[a]])] -> Either MathError (Matrix a, Matrix a) Source #

Verify supplied Jordan chains against A and lambda and construct J and P. Computing a Jordan structure from floating input is ill posed; the caller supplies chain vectors ordered eigenvector first. A P = P J is checked. This API never pretends a Schur form is a Jordan form.

jordanForm

jordanForm :: Matrix Rational -> [Rational] -> Either MathError (Matrix Rational, Matrix Rational) Source #

Exact Jordan construction over Rational with a caller-provided complete set of distinct rational eigenvalues (multiplicities are inferred). Unlike floating Jordan algorithms this never uses a tolerance to decide structure. Nullspaces of successive (A-lambda I) powers construct generalized chains. An incomplete/nonrational spectrum is rejected rather than approximated.