HMath.Sparse.Spectral¶
Module index · Numerical conventions
Description
Matrix-free sparse power algorithms. Neither a dense matrix nor A^T A is formed. Sparse multiplication, explicit vector workspaces and orthogonal deflation determine storage. Power convergence requires a starting component in the desired singular/eigen direction and a separated dominant magnitude; an exact residual certifies an eigen/singular pair, not spectral dominance. Every returned pair has residuals checked against the original sparse input. See the power-method SVD derivation in Stanford EE263, exercise 15.10.
On this page¶
| API | Purpose |
|---|---|
| SparseSpectralOptions | Residual tolerances, per-pair iteration budget and an explicit workspace limit measured in scalar elements. |
| SparseSpectralOptions | Declaration and type contract below. |
| sparseAbsoluteTolerance | Absolute norm tolerance, finite and nonnegative. |
| sparseRelativeTolerance | Relative tolerance against max(abs eigen/singular value,maxAbs input). |
| sparseIterationLimit | Nonnegative number of power updates per pair. |
| sparseWorkspaceLimit | Maximum estimated simultaneous vector elements, nonnegative. |
| defaultSparseSpectralOptions | Absolute tolerance 1e-12, relative tolerance 1e-10, 1000 iterations per pair and a workspace limit of ten million scalar elements. |
| SparseEigenResult | A normalized real symmetric eigenpair and its independently checked residual. |
| SparseEigenResult | Declaration and type contract below. |
| sparseEigenvalue | Rayleigh quotient; negative dominant eigenvalues retain their sign. |
| sparseEigenvector | Unit Euclidean norm eigenvector. |
| sparseEigenResidual | Original norm ||A v-lambda v||_2. |
| sparseEigenIterations | Number of completed power updates. |
| sparseDominantEigen | Symmetric power iteration targeting the eigenvalue of largest magnitude. |
| SparseSVD | Compact singular triplets. |
| SparseSVD | Declaration and type contract below. |
| sparseSingularValues | Nonnegative singular estimates in extraction order. |
| sparseLeftVectors | Left unit vectors, one list per singular triplet. |
| sparseRightVectors | Right unit vectors (columns of V, rather than rows of V^T). |
| sparseSingularResiduals | Original (||A v-s u||_2,||A^T u-s v||_2) residuals. |
| sparseSingularIterations | Power updates used by each triplet. |
| sparseTruncatedSVD | Truncated SVD by two-sided power iteration and two-pass orthogonal deflation. |
Documentation
SparseSpectralOptions
data SparseSpectralOptions a Source #
Residual tolerances, per-pair iteration budget and an explicit workspace limit measured in scalar elements. Tolerances are finite and nonnegative.
Constructors
| SparseSpectralOptions | |
Fields
| |
Instances
| Show a => Show (SparseSpectralOptions a) Source # | |
Defined in HMath.Sparse.Spectral Methods showsPrec :: Int -> SparseSpectralOptions a -> ShowS # show :: SparseSpectralOptions a -> String # showList :: [SparseSpectralOptions a] -> ShowS # | |
| Eq a => Eq (SparseSpectralOptions a) Source # | |
Defined in HMath.Sparse.Spectral Methods (==) :: SparseSpectralOptions a -> SparseSpectralOptions a -> Bool # (/=) :: SparseSpectralOptions a -> SparseSpectralOptions a -> Bool # | |
defaultSparseSpectralOptions
defaultSparseSpectralOptions :: Fractional a => SparseSpectralOptions a Source #
Absolute tolerance 1e-12, relative tolerance 1e-10, 1000 iterations per pair and a workspace limit of ten million scalar elements.
SparseEigenResult
data SparseEigenResult a Source #
A normalized real symmetric eigenpair and its independently checked residual.
Constructors
| SparseEigenResult | |
Fields
| |
Instances
| Show a => Show (SparseEigenResult a) Source # | |
Defined in HMath.Sparse.Spectral Methods showsPrec :: Int -> SparseEigenResult a -> ShowS # show :: SparseEigenResult a -> String # showList :: [SparseEigenResult a] -> ShowS # | |
| Eq a => Eq (SparseEigenResult a) Source # | |
Defined in HMath.Sparse.Spectral Methods (==) :: SparseEigenResult a -> SparseEigenResult a -> Bool # (/=) :: SparseEigenResult a -> SparseEigenResult a -> Bool # | |
sparseDominantEigen
sparseDominantEigen :: RealFloat a => SparseSpectralOptions a -> Sparse a -> [a] -> Either MathError (SparseEigenResult a) Source #
Symmetric power iteration targeting the eigenvalue of largest magnitude. Exact symmetry and finite input are required. The caller supplies a nonzero finite initial vector; its projection onto the desired eigenspace must be nonzero. An initial eigenvector can converge with a zero budget. Equal opposite dominant eigenvalues may cause non-convergence. Returned residuals do not prove that the converged eigenvalue is the largest when the initial projection is zero.
SparseSVD
Compact singular triplets. Left and right vectors are stored as lists of columns, requiring O(k*(rows+columns)) storage instead of a dense matrix.
Constructors
| SparseSVD | |
Fields
| |
sparseTruncatedSVD
sparseTruncatedSVD :: RealFloat a => SparseSpectralOptions a -> Int -> Integer -> Sparse a -> Either MathError (SparseSVD a) Source #
Truncated SVD by two-sided power iteration and two-pass orthogonal deflation. The seed initializes a local deterministic stream, with no global RNG state. Both original singular residuals must meet the configured tolerance. The algorithm targets descending singular values if starting vectors have nonzero projection and the successive singular values are separated; it does not claim a certified rank or ordering when these power-method assumptions fail. Exact null images report RankDeficient, rather than inventing zero singular vectors. Small positive singular values may be returned within tolerance; requesting more vectors than the numerical rank can also exhaust the budget. k=0 returns empty factors, including for empty/zero inputs.