HMath.Sparse¶

Description

Sparse matrices use canonical sorted coordinates, coalesced duplicates and no explicit zeros. Formats carry public metadata and are validated on import. CSR/CSC indices within each segment must be strictly increasing. DIA stores one value per row of a diagonal, with zero padding. BSR allows edge blocks only with zero padding. ELLPACK uses -1 and zero for unused row-major slots.

On this page¶

API	Purpose
Sparse	Canonical immutable sparse matrix with summed duplicate coordinates and explicit zeros removed.
SparseFormat	Interchange representation selector carrying COO,CSR,CSC,DIA,BSR,or ELLPACK arrays; validate through fromFormat.
COO	Declaration and type contract below.
CSR	Declaration and type contract below.
CSC	Declaration and type contract below.
DIA	Declaration and type contract below.
BSR	Declaration and type contract below.
ELLPACK	Declaration and type contract below.
sparse	Given rows,columns,then (row,column,value) entries, validate coordinates, sum duplicates and remove explicit zeros.
sparseShape	Return declared (row count,column count), including empty dimensions.
nonzeros	Return stored nonzero count after duplicate coalescing and zero removal.
sparseEntries	Return canonical nonzero (row,column,value) triples in ascending coordinate order.
fromFormat	Validate COOCSRCSCDIABSRELLPACK dimensions, pointersindices and values, then construct canonical sparse storage.
toCOO	Return coordinate-list SparseFormat with explicit rowcolumnvalue arrays, preserving canonical nonzeros.
toCSR	Return compressed sparse row format with row offsets, column indices and nonzero values.
toCSC	Return compressed sparse column format with column offsets, row indices and values.
toDIA	Return diagonal sparse format; absent positions in represented diagonals are padded with zero.
toBSR	Given positive block rows,block columns,then sparse matrix, build block-sparse-row format with zero padding within edge blocks.
toELLPACK	Return ELLPACK padded row storage, using row width equal to maximum nonzeros per row.
sparseToDense	Return a dense Matrix with the same dimensions and zeros for missing entries.
denseToSparse	Convert a dense matrix to canonical sparse storage, discarding exact zeros and preserving dimensions.
sparseTranspose	Exchange row/column coordinates and dimensions without changing values, returning canonical sparse order.
sparseAdd	Add equal-shaped sparse matrices, coalescing entries and dropping resulting zeros.
sparseSubtract	Subtract right sparse values from left for equal shapes; coalesce and remove zeros.
spmv	Given sparse matrix then dense vector, return matrix-vector product.
spmm	Multiply compatible sparse matrices using sparse row contributions.
sparseKronecker	Return sparse Kronecker product, multiplying row/column dimensions and nonzero pairs.
sparseTriangularSolve	Given lower Bool,square finite sparse matrix,then RHS list, solve by forward/back substitution.
sparseDiagonalSolve	Given diagonal square sparse matrix then RHS, divide by each diagonal pivot.
SparseLU	Opaque sparse row-pivoted LU factors with reconstruction permutation; solve through sparseSolveLU.
sparseLU	Given finite nonnegative relative pivot tolerance then square finite sparse matrix, compute sparse LU with row pivoting.
sparseLULower	Extract unit lower-triangular sparse factor from a SparseLU result.
sparseLUUpper	Extract upper-triangular sparse factor from a SparseLU result.
sparseLUPermutation	Return LU row permutation in pivoted order, for reconstructing PA=LU.
sparseSolveLU	Given sparse LU factors then RHS list, apply row permutation and triangular solves.
sparseCholesky	Factor a symmetric positive-definite finite sparse matrix into a lower sparse factor.
SparseQR	Opaque sparse QR factors with implicit orthogonal transform; use sparseQRUpper and sparseQRApplyQT.
sparseQR	Sparse Householder QR retains only the R nonzeros and compact reflectors; fill is retained, never silently dropped.
sparseQRUpper	Extract upper-triangular/trapezoidal sparse R from a sparse QR factorization.
sparseQRApplyQT	Given sparse QR factors then compatible RHS list, apply transpose(Q) without constructing dense Q.
sparseGraph	For a square sparse matrix, return one adjacency row per vertex with stored (column,value) neighbors.
sparseStorageBytes	Logical payload bytes: two machine-width indices and caller-provided scalar width per nonzero.
SparseTensor	Canonical sparse multidimensional entries, constructed by sparseTensor with checked coordinates and duplicate coalescing.
sparseTensor	Given dimensions then (coordinate-list,value) entries, validate rank/bounds, sum duplicate coordinates and remove zeros.
sparseTensorEntries	Return canonical nonzero (coordinate list,value) pairs in lexicographic coordinate order.
sparseTensorShape	Return axis dimensions of a sparse tensor; [] denotes a scalar.
sparseTensorLookup	Given sparse tensor then full zero-based coordinates, return stored value or zero.
sparseEigenReference	Small-problem spectral reference backend.
sparseSVDReference	Given explicit dense-byte budget then sparse Double matrix, densify only if within budget and run checked dense SVD.

Documentation

Sparse

data Sparse a Source #

Canonical immutable sparse matrix with summed duplicate coordinates and explicit zeros removed. Construct using sparse or checked format conversions.

Instances

Instances details

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

SparseFormat

data SparseFormat a Source #

Interchange representation selector carrying COO,CSR,CSC,DIA,BSR,or ELLPACK arrays; validate through fromFormat.

Constructors

COO Int Int [(Int, Int, a)]
CSR Int Int [Int] [Int] [a]
CSC Int Int [Int] [Int] [a]
DIA Int Int [(Int, [a])]
BSR Int Int Int Int [Int] [Int] [[a]]
ELLPACK Int Int Int [Int] [a]

Instances

Instances details

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

sparse

sparse :: (Eq a, Num a) => Int -> Int -> [(Int, Int, a)] -> Either MathError (Sparse a) Source #

Given rows,columns,then (row,column,value) entries, validate coordinates, sum duplicates and remove explicit zeros. Return canonical ordered sparse storage; invalid shape/indices or size overflow fail.

sparseShape

sparseShape :: Sparse a -> (Int, Int) Source #

Return declared (row count,column count), including empty dimensions.

nonzeros

nonzeros :: Sparse a -> Int Source #

Return stored nonzero count after duplicate coalescing and zero removal.

sparseEntries

sparseEntries :: Sparse a -> [(Int, Int, a)] Source #

Return canonical nonzero (row,column,value) triples in ascending coordinate order.

fromFormat

fromFormat :: (Eq a, Num a) => SparseFormat a -> Either MathError (Sparse a) Source #

Validate COOCSRCSCDIABSRELLPACK dimensions, pointersindices and values, then construct canonical sparse storage. Invalid layout or coordinates return Left MathError.

toCOO

toCOO :: Sparse a -> SparseFormat a Source #

Return coordinate-list SparseFormat with explicit rowcolumnvalue arrays, preserving canonical nonzeros.

toCSR

toCSR :: Sparse a -> SparseFormat a Source #

Return compressed sparse row format with row offsets, column indices and nonzero values.

toCSC

toCSC :: Sparse a -> SparseFormat a Source #

Return compressed sparse column format with column offsets, row indices and values.

toDIA

toDIA :: Num a => Sparse a -> SparseFormat a Source #

Return diagonal sparse format; absent positions in represented diagonals are padded with zero.

toBSR

toBSR :: Num a => Int -> Int -> Sparse a -> Either MathError (SparseFormat a) Source #

Given positive block rows,block columns,then sparse matrix, build block-sparse-row format with zero padding within edge blocks. Invalid block dimensions or size overflow fails.

toELLPACK

toELLPACK :: Num a => Sparse a -> Either MathError (SparseFormat a) Source #

Return ELLPACK padded row storage, using row width equal to maximum nonzeros per row. Invalid/overflowing storage dimensions fail.

sparseToDense

sparseToDense :: Num a => Sparse a -> Either MathError (Matrix a) Source #

Return a dense Matrix with the same dimensions and zeros for missing entries. Checked dense element-count overflow can fail.

denseToSparse

denseToSparse :: (Eq a, Num a) => Matrix a -> Sparse a Source #

Convert a dense matrix to canonical sparse storage, discarding exact zeros and preserving dimensions.

sparseTranspose

sparseTranspose :: Sparse a -> Sparse a Source #

Exchange row/column coordinates and dimensions without changing values, returning canonical sparse order.

sparseAdd

sparseAdd :: (Eq a, Num a) => Sparse a -> Sparse a -> Either MathError (Sparse a) Source #

Add equal-shaped sparse matrices, coalescing entries and dropping resulting zeros. Shape mismatch or checked construction errors fail.

sparseSubtract

sparseSubtract :: (Eq a, Num a) => Sparse a -> Sparse a -> Either MathError (Sparse a) Source #

Subtract right sparse values from left for equal shapes; coalesce and remove zeros. Shape mismatch fails.

spmv

spmv :: Num a => Sparse a -> [a] -> Either MathError [a] Source #

Given sparse matrix then dense vector, return matrix-vector product. Vector length must equal column count; mismatch returns Left MathError.

spmm

spmm :: (Eq a, Num a) => Sparse a -> Sparse a -> Either MathError (Sparse a) Source #

Multiply compatible sparse matrices using sparse row contributions. Inner-dimension mismatch or output construction errors return Left MathError.

sparseKronecker

sparseKronecker :: (Eq a, Num a) => Sparse a -> Sparse a -> Either MathError (Sparse a) Source #

Return sparse Kronecker product, multiplying row/column dimensions and nonzero pairs. Dimension/product overflow fails.

sparseTriangularSolve

sparseTriangularSolve :: RealFloat a => Bool -> Sparse a -> [a] -> Either MathError [a] Source #

Given lower Bool,square finite sparse matrix,then RHS list, solve by forward/back substitution. Require correct triangular structure and matching RHS length; zero diagonal pivots or non-finite arithmetic fail.

sparseDiagonalSolve

sparseDiagonalSolve :: RealFloat a => Sparse a -> [a] -> Either MathError [a] Source #

Given diagonal square sparse matrix then RHS, divide by each diagonal pivot. Off-diagonal entries, shape mismatch, zero pivots or non-finite data fail.

SparseLU

data SparseLU a Source #

Opaque sparse row-pivoted LU factors with reconstruction permutation; solve through sparseSolveLU.

Instances

Instances details

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

sparseLU

sparseLU :: RealFloat a => a -> Sparse a -> Either MathError (SparseLU a) Source #

Given finite nonnegative relative pivot tolerance then square finite sparse matrix, compute sparse LU with row pivoting. Invalid toleranceinput, zeronear-singular pivots or numerical failure returns Left MathError.

sparseLULower

sparseLULower :: SparseLU a -> Sparse a Source #

Extract unit lower-triangular sparse factor from a SparseLU result.

sparseLUUpper

sparseLUUpper :: SparseLU a -> Sparse a Source #

Extract upper-triangular sparse factor from a SparseLU result.

sparseLUPermutation

sparseLUPermutation :: SparseLU a -> [Int] Source #

Return LU row permutation in pivoted order, for reconstructing P*A=L*U.

sparseSolveLU

sparseSolveLU :: RealFloat a => SparseLU a -> [a] -> Either MathError [a] Source #

Given sparse LU factors then RHS list, apply row permutation and triangular solves. Dimension mismatch, singularity or non-finite input/result fails.

sparseCholesky

sparseCholesky :: RealFloat a => Sparse a -> Either MathError (Sparse a) Source #

Factor a symmetric positive-definite finite sparse matrix into a lower sparse factor. Invalid shape/symmetry, nonpositive pivots or numerical failure returns Left MathError.

SparseQR

data SparseQR a Source #

Opaque sparse QR factors with implicit orthogonal transform; use sparseQRUpper and sparseQRApplyQT.

Instances

Instances details

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

sparseQR

sparseQR :: RealFloat a => Sparse a -> Either MathError (SparseQR a) Source #

Sparse Householder QR retains only the R nonzeros and compact reflectors; fill is retained, never silently dropped. Reflection vectors are dense tails.

Given finite nonnegative tolerance then sparse matrix, compute its checked sparse QR factors. Invalid tolerance, input or numerical failure returns Left MathError.

sparseQRUpper

sparseQRUpper :: SparseQR a -> Sparse a Source #

Extract upper-triangular/trapezoidal sparse R from a sparse QR factorization.

sparseQRApplyQT

sparseQRApplyQT :: RealFloat a => SparseQR a -> [a] -> Either MathError [a] Source #

Given sparse QR factors then compatible RHS list, apply transpose(Q) without constructing dense Q. Invalid length or non-finite arithmetic fails.

sparseGraph

sparseGraph :: Sparse a -> Either MathError [(Int, [(Int, a)])] Source #

For a square sparse matrix, return one adjacency row per vertex with stored (column,value) neighbors. Non-square matrix returns Left MathError.

sparseStorageBytes

sparseStorageBytes :: Int -> Sparse a -> Either MathError Integer Source #

Logical payload bytes: two machine-width indices and caller-provided scalar width per nonzero. Runtime Map node overhead is implementation dependent.

SparseTensor

data SparseTensor a Source #

Canonical sparse multidimensional entries, constructed by sparseTensor with checked coordinates and duplicate coalescing.

Instances

Instances details

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

sparseTensor

sparseTensor :: (Eq a, Num a) => [Int] -> [([Int], a)] -> Either MathError (SparseTensor a) Source #

Given dimensions then (coordinate-list,value) entries, validate rank/bounds, sum duplicate coordinates and remove zeros. Invalid shape/indices return Left MathError.

sparseTensorEntries

sparseTensorEntries :: SparseTensor a -> [([Int], a)] Source #

Return canonical nonzero (coordinate list,value) pairs in lexicographic coordinate order.

sparseTensorShape

sparseTensorShape :: SparseTensor a -> [Int] Source #

Return axis dimensions of a sparse tensor; [] denotes a scalar.

sparseTensorLookup

sparseTensorLookup :: Num a => SparseTensor a -> [Int] -> Either MathError a Source #

Given sparse tensor then full zero-based coordinates, return stored value or zero. Wrong rank or out-of-range indices fail.

sparseEigenReference

sparseEigenReference :: Integer -> Sparse Double -> Either MathError Eigen Source #

Small-problem spectral reference backend. The caller explicitly authorizes a dense element budget; oversized matrices fail before generating zeros. This is not a scalable sparse eigensolver/SVD and never silently densifies.

sparseSVDReference

sparseSVDReference :: Integer -> Sparse Double -> Either MathError SVD Source #

Given explicit dense-byte budget then sparse Double matrix, densify only if within budget and run checked dense SVD. This is a reference fallback, not a sparse iterative SVD; budgetbackendnumeric errors fail.