HMath.Matrix.Advanced¶
Module index · Numerical conventions
Description
Matrix constructors, products, spaces, and matrix functions. Spectral functions are Double precision. The simple log/sqrt entries use symmetric spectral algorithms; General variants accept nonsymmetric invertible real matrices off the nonpositive-real spectral branch cut, with finite budgets. Exponential uses scaling and squaring.
On this page¶
| API | Purpose |
|---|---|
| generateMatrix | Given row count, column count, then zero-based (row,column) generator, construct a row-major matrix. |
| triangularMatrix | Given lower flag then matrix, preserve entries onbelow the diagonal if True, onabove if False, and zero the rest. |
| symmetricMatrix | Return (A+transpose(A))/2 for a square matrix. |
| hermitianMatrix | Return (A+conjugateTranspose(A))/2 for a square complex matrix. |
| permutationMatrix | Given a permutation p of [0..n-1], construct n-by-n P with P[i,p[i]]=1. |
| blockMatrix | Assemble a rectangular grid of matrix blocks. |
| bandedMatrix | Given rows, columns, then (diagonal offset,values) pairs, construct a matrix with zeros elsewhere. |
| conjugateTranspose | Transpose a complex matrix and conjugate every entry, exchanging its row/column dimensions. |
| zipMatrixWith | Given elementwise function and two identically shaped matrices, apply it to corresponding entries and return a new matrix. |
| batchedMultiply | Multiply pairs of matrices from equally long lists, preserving batch order. |
| kronecker | Return the block Kronecker product of matrices A and B, of shape (ArowsBrows,AcolsBcols). |
| khatriRao | Return columnwise Kronecker product, requiring equal column counts. |
| matrixPower | Given Integer exponent then square real matrix, compute power by squaring. |
| trace | Return sum of main diagonal of a square matrix; non-square input returns NonSquareMatrix. |
| matrixNorm1 | Return maximum absolute column sum (induced one norm). |
| matrixNormInfinity | Return maximum absolute row sum (induced infinity norm). |
| frobeniusNorm | Return scaled Euclidean norm of all entries, reducing intermediate overflow; empty matrix norm is zero. |
| spectralNorm | Return largest singular value via SVD, or zero for an empty singular spectrum. |
| pseudoinverse | Given relative singular-value tolerance then m-by-n matrix, return n-by-m Moore-Penrose pseudoinverse via thresholded SVD. |
| complexPseudoinverse | Complex128 Moore-Penrose pseudoinverse, thresholded relative to the largest singular value. |
| matrixRank | Given finite nonnegative relative tolerance then matrix, count positive singular values whose ratio to the largest exceeds tolerance. |
| conditionNumber | Return largest/smallest singular-value ratio; singular matrices yield positive infinity, empty spectrum yields 1. |
| nullSpace | Given relative singular-value tolerance then m-by-n matrix, return an n-by-(n-rank) basis for its numerical right null space using full SVD. |
| columnSpace | Given relative SVD rank tolerance then matrix, return columns of left singular vectors spanning its numerical column space. |
| rowSpace | Given relative rank tolerance then matrix, return a column basis for its row space by applying columnSpace to its transpose. |
| changeCoordinates | Given source basis matrix, target square basis matrix, then source coordinate list, map to physical coordinates and solve in target basis. |
| matrixExp | Given positive finite tolerance, positive iteration budget, then square finite matrix, approximate exp(A) by scaling, Taylor series and squaring. |
| matrixLog | Compute principal real matrix logarithm of a symmetric positive-definite Double matrix using symmetric eigendecomposition. |
| matrixSqrt | Compute symmetric positive-semidefinite matrix square root by spectral decomposition; tolerate eigenvalues down to -1e-12 and clamp them to zero. |
| matrixLogGeneral | Real principal matrix logarithm on the same spectral domain as matrixSqrtGeneral. |
| matrixSqrtGeneral | Principal square root for invertible real matrices whose spectra avoid the nonpositive real axis. |
| polar | Return (U,P) from SVD so A=U*P, with P positive semidefinite; rectangular input uses the thin polar factors. |
Documentation
generateMatrix
generateMatrix :: Int -> Int -> (Int -> Int -> a) -> Either MathError (Matrix a) Source #
Given row count, column count, then zero-based (row,column) generator, construct a row-major matrix. Negative dimensions or Int-size element product overflow return Left MathError.
triangularMatrix
triangularMatrix :: Num a => Bool -> Matrix a -> Either MathError (Matrix a) Source #
Given lower flag then matrix, preserve entries onbelow the diagonal if True, onabove if False, and zero the rest. Rectangular matrices are allowed; return checked construction result.
symmetricMatrix
symmetricMatrix :: Fractional a => Matrix a -> Either MathError (Matrix a) Source #
Return (A+transpose(A))/2 for a square matrix. Non-square input returns NonSquareMatrix; arithmetic follows Fractional.
hermitianMatrix
hermitianMatrix :: RealFloat a => Matrix (Complex a) -> Either MathError (Matrix (Complex a)) Source #
Return (A+conjugateTranspose(A))/2 for a square complex matrix. Non-square input fails; this symmetrizes rather than merely asserting the original is Hermitian.
permutationMatrix
permutationMatrix :: Num a => [Int] -> Either MathError (Matrix a) Source #
Given a permutation p of [0..n-1], construct n-by-n P with P[i,p[i]]=1. Duplicate, missing, or out-of-range indices return Left InvalidArgument.
blockMatrix
blockMatrix :: [[Matrix a]] -> Either MathError (Matrix a) Source #
Assemble a rectangular grid of matrix blocks. Require equal heights within each block row and equal widths within each block column. Ragged grids or total-size overflow fail; empty grids yield a 0-by-0 matrix.
bandedMatrix
bandedMatrix :: Num a => Int -> Int -> [(Int, [a])] -> Either MathError (Matrix a) Source #
Given rows, columns, then (diagonal offset,values) pairs, construct a matrix with zeros elsewhere. Offset k means column-row=k. Each list must match that diagonal's length; duplicates add. Invalid dimensions/counts fail.
conjugateTranspose
conjugateTranspose :: RealFloat a => Matrix (Complex a) -> Matrix (Complex a) Source #
Transpose a complex matrix and conjugate every entry, exchanging its row/column dimensions.
zipMatrixWith
zipMatrixWith :: (a -> b -> c) -> Matrix a -> Matrix b -> Either MathError (Matrix c) Source #
Given elementwise function and two identically shaped matrices, apply it to corresponding entries and return a new matrix. Mismatched shapes return ShapeMismatch.
batchedMultiply
batchedMultiply :: Num a => [Matrix a] -> [Matrix a] -> Either MathError [Matrix a] Source #
Multiply pairs of matrices from equally long lists, preserving batch order. Different batch lengths or any checked multiplication failure return Left MathError.
kronecker
kronecker :: Num a => Matrix a -> Matrix a -> Either MathError (Matrix a) Source #
Return the block Kronecker product of matrices A and B, of shape (Arows*Brows,Acols*Bcols). Reject dimension/element-count overflow.
khatriRao
khatriRao :: Num a => Matrix a -> Matrix a -> Either MathError (Matrix a) Source #
Return columnwise Kronecker product, requiring equal column counts. Shape is (Arows*Brows,columns); mismatched columns or dimension overflow fail.
matrixPower
matrixPower :: RealFloat a => Integer -> Matrix a -> Either MathError (Matrix a) Source #
Given Integer exponent then square real matrix, compute power by squaring. Zero yields identity; negative exponent inverts first. Non-square/singular input or multiplication errors propagate.
trace
trace :: Num a => Matrix a -> Either MathError a Source #
Return sum of main diagonal of a square matrix; non-square input returns NonSquareMatrix. A 0-by-0 matrix has trace zero.
matrixNorm1
matrixNorm1 :: (Ord a, Num a) => Matrix a -> a Source #
Return maximum absolute column sum (induced one norm). Empty dimensions give zero; no finiteness check is added.
matrixNormInfinity
matrixNormInfinity :: (Ord a, Num a) => Matrix a -> a Source #
Return maximum absolute row sum (induced infinity norm). A matrix with no elements gives zero.
frobeniusNorm
frobeniusNorm :: RealFloat a => Matrix a -> a Source #
Return scaled Euclidean norm of all entries, reducing intermediate overflow; empty matrix norm is zero. No Either result is added.
spectralNorm
spectralNorm :: Matrix Double -> Either MathError Double Source #
Return largest singular value via SVD, or zero for an empty singular spectrum. Invalid input/backend decomposition failures return Left MathError.
pseudoinverse
pseudoinverse :: Double -> Matrix Double -> Either MathError (Matrix Double) Source #
Given relative singular-value tolerance then m-by-n matrix, return n-by-m Moore-Penrose pseudoinverse via thresholded SVD. Rectangular/rank-deficient inputs are supported; invalid tolerance or numeric/decomposition failures propagate.
complexPseudoinverse
complexPseudoinverse :: Double -> Matrix (Complex Double) -> Either MathError (Matrix (Complex Double)) Source #
Complex128 Moore-Penrose pseudoinverse, thresholded relative to the largest singular value. Both rectangular and rank-deficient inputs are supported.
matrixRank
matrixRank :: Double -> Matrix Double -> Either MathError Int Source #
Given finite nonnegative relative tolerance then matrix, count positive singular values whose ratio to the largest exceeds tolerance. Zero tolerance counts all positive singular values. Invalid tolerance or SVD failure propagates.
conditionNumber
conditionNumber :: Matrix Double -> Either MathError Double Source #
Return largest/smallest singular-value ratio; singular matrices yield positive infinity, empty spectrum yields 1. Input/SVD failures return Left MathError.
nullSpace
nullSpace :: Double -> Matrix Double -> Either MathError (Matrix Double) Source #
Given relative singular-value tolerance then m-by-n matrix, return an n-by-(n-rank) basis for its numerical right null space using full SVD. Invalid tolerance/decomposition failures propagate.
columnSpace
columnSpace :: Double -> Matrix Double -> Either MathError (Matrix Double) Source #
Given relative SVD rank tolerance then matrix, return columns of left singular vectors spanning its numerical column space. Invalid tolerance/decomposition errors propagate.
rowSpace
rowSpace :: Double -> Matrix Double -> Either MathError (Matrix Double) Source #
Given relative rank tolerance then matrix, return a column basis for its row space by applying columnSpace to its transpose.
changeCoordinates
changeCoordinates :: RealFloat a => Matrix a -> Matrix a -> [a] -> Either MathError [a] Source #
Given source basis matrix, target square basis matrix, then source coordinate list, map to physical coordinates and solve in target basis. Shape mismatch, singular target, and checked solve errors propagate.
matrixExp
matrixExp :: RealFloat a => a -> Int -> Matrix a -> Either MathError (Matrix a) Source #
Given positive finite tolerance, positive iteration budget, then square finite matrix, approximate exp(A) by scaling, Taylor series and squaring. Return NonConvergence on exhausted series budget; inputshapenumerical failures propagate.
matrixLog
matrixLog :: Matrix Double -> Either MathError (Matrix Double) Source #
Compute principal real matrix logarithm of a symmetric positive-definite Double matrix using symmetric eigendecomposition. Reject non-square/asymmetric matrices, nonpositive spectrum, non-real decomposition, or numeric failure.
matrixSqrt
matrixSqrt :: Matrix Double -> Either MathError (Matrix Double) Source #
Compute symmetric positive-semidefinite matrix square root by spectral decomposition; tolerate eigenvalues down to -1e-12 and clamp them to zero. Invalid shapesymmetryspectrum or decomposition failure returns Left MathError.
matrixLogGeneral
matrixLogGeneral :: Double -> Int -> Matrix Double -> Either MathError (Matrix Double) Source #
Real principal matrix logarithm on the same spectral domain as matrixSqrtGeneral. Inverse scaling by successive principal square roots makes the Mercator series converge in matrix 1-norm. The budget bounds each phase: root reductions, each inner Denman-Beavers solve, series terms, and the final exponential reconstruction check. There is no unbounded convergence loop.
matrixSqrtGeneral
matrixSqrtGeneral :: Double -> Int -> Matrix Double -> Either MathError (Matrix Double) Source #
Principal square root for invertible real matrices whose spectra avoid the nonpositive real axis. This nonsymmetric reference method uses scaled Denman-Beavers iteration with private inverse solves. The budget bounds the number of coupled iterations; failure to meet the reconstruction tolerance returns NonConvergence. Ill-conditioned inverse steps may report a LU error. The existing matrixSqrt additionally handles symmetric singular PSD inputs.