SparseMatrixCSC

SparseMatrixCSC

Compressed Sparse Column (CSC) Matrix. Exclusively optimized for BigFloat arithmetic.

In CSC format, the matrix is specified by three arrays:

  • values: Non-zero elements of the matrix.
  • rowIndices: The row indices corresponding to the values.
  • colPointers: The start and end indices in values and rowIndices for each column.

Constructor

new SparseMatrixCSC(rows, cols, values, rowIndices, colPointers)

Source:
Parameters:
Name Type Description
rows number

Number of rows.
cols number

Number of columns.
values Array.<BigFloat>

Array of non-zero BigFloat values.
rowIndices Uint32Array | Array.<number>

Row indices for each non-zero value.
colPointers Uint32Array | Array.<number>

Column pointers of length (cols + 1).

Classes

SparseMatrixCSC

Members

nnz

Description:

  • Number of non-zero elements.

Source:

Number of non-zero elements.

Methods

add(other) → {SparseMatrixCSC}

Description:

  • Adds another SparseMatrixCSC to this matrix (C = A + B).

Source:
Parameters:
Name Type Description
other SparseMatrixCSC
Returns:
Type
SparseMatrixCSC

cholesky() → {SparseMatrixCSC}

Description:

  • Sparse Cholesky Factorization. Computes A = L * L^T for Symmetric Positive Definite (SPD) matrices. Extracts factor from the LU Decomposition by scaling L with sqrt(diag(U)).

Source:
Returns:

L - The lower triangular Cholesky factor.

Type
SparseMatrixCSC

clone() → {SparseMatrixCSC}

Description:

  • Creates a deep copy of the matrix.

Source:
Returns:
Type
SparseMatrixCSC

det() → {BigFloat}

Description:

  • Computes the Determinant of the sparse matrix using LU factorization. det(A) = Product of the diagonals of U.

Source:
Returns:
Type
BigFloat

eig(tolopt, maxIteropt) → {Array.<{eigenvalue: Complex, eigenvector: Array.<Complex>}>}

Description:

  • Computes ALL eigenvalues and eigenvectors using the globally convergent QR Algorithm. Uses $O(n^3)$ Hessenberg Reduction followed by $O(n^2)$ Implicit Double-Shift Francis QR.

Source:
Parameters:
Name Type Attributes Default Description
tol number | string | BigFloat <optional>
 "1e-15"

Convergence tolerance.
maxIter number <optional>
 null

Maximum iterations (Defaults to dynamic bound based on size).
Returns:
  • List of complex eigenpairs sorted by magnitude descending.
Type
Array.<{eigenvalue: Complex, eigenvector: Array.<Complex>}>

eigen(tolopt, maxIteropt) → {Object}

Description:

  • Computes the Dominant Eigenpair using Power Iteration. Eigenvalue solvers extract top-K values iteratively.

Source:
Parameters:
Name Type Attributes Default Description
tol number | string | BigFloat <optional>
 "1e-20"

Convergence tolerance.
maxIter number <optional>
 1000

Maximum iterations.
Returns:
Type
Object

ger(x, y) → {SparseMatrixCSC}

Description:

  • General Rank-1 Update (GER). Computes A + x * y^T. Note: Rank-1 updates on sparse matrices usually introduce significant fill-in (dense data).

Source:
Parameters:
Name Type Description
x Vector | Array.<(number|string|BigFloat)>
y Vector | Array.<(number|string|BigFloat)>
Returns:
Type
SparseMatrixCSC

get(row, col) → {BigFloat}

Description:

  • Retrieves the value at the specified row and column. Uses binary search within the specific column for O(log(nnz_in_col)) performance.

Source:
Parameters:
Name Type Description
row number
col number
Returns:
Type
BigFloat

getDiagonal() → {Vector}

Description:

  • Extracts the diagonal elements of the matrix.

Source:
Returns:
  • A vector containing the diagonal elements.
Type
Vector

getJacobiPreconditioner() → {Vector}

Description:

  • Extracts the Jacobi Preconditioner (Inverse of the Diagonal). This is the most memory-efficient and widely used preconditioner for diagonally dominant matrices.

Source:
Returns:
  • A vector representing the diagonal inverse M^{-1}.
Type
Vector

inv() → {SparseMatrixCSC}

Description:

  • Computes the Inverse of the sparse matrix. Warning: The inverse of a sparse matrix is typically dense. This uses column-by-column LU solves to construct the inverse dynamically.

Source:
Returns:
Type
SparseMatrixCSC

logDet() → {BigFloat}

Description:

  • Computes the Log-Determinant of the matrix (useful for Gaussians and PDFs). logDet(A) = Sum of the logs of the absolute diagonals of U.

Source:
Returns:
Type
BigFloat

lu() → {Object}

Description:

  • Sparse LU Factorization (Left-Looking / Gilbert-Peierls Algorithm). Computes A = L * U where L is lower triangular with unit diagonal, and U is upper triangular.

Source:
Returns:
Type
Object

mul(B) → {SparseMatrixCSC}

Description:

  • Matrix-Matrix Multiplication (C = A * B). Implements Gustavson's Algorithm (Sparse Accumulator variant). Computes the product in O(flops + nnz(C)) time footprint with zero inner-loop allocation.

Source:
Parameters:
Name Type Description
B SparseMatrixCSC

The right-hand side matrix.
Returns:
Type
SparseMatrixCSC

mulScalar(scalar) → {SparseMatrixCSC}

Description:

  • Scalar Multiplication (B = s * A). Executes in O(nnz) time.

Source:
Parameters:
Name Type Description
scalar number | string | BigFloat

The scalar value to multiply with.
Returns:
  • The resulting sparse matrix.
Type
SparseMatrixCSC

mulVec(vec) → {Vector}

Description:

  • Matrix-Vector Multiplication (y = A * x). Linear time execution: O(nnz(A)).

Source:
Parameters:
Name Type Description
vec Vector | Array.<(number|string|BigFloat)>

The input vector.
Returns:
  • The result vector.
Type
Vector

norm1() → {BigFloat}

Description:

  • Computes the L1 Norm (Maximum absolute column sum). Executes in O(nnz) time.

Source:
Returns:
Type
BigFloat

normF() → {BigFloat}

Description:

  • Computes the Frobenius Norm (Square root of the sum of the squares of elements).

Source:
Returns:
Type
BigFloat

normInf() → {BigFloat}

Description:

  • Computes the Infinity Norm (Maximum absolute row sum). Executes in O(nnz) time footprint.

Source:
Returns:
Type
BigFloat

pinv() → {SparseMatrixCSC}

Description:

  • Computes the Moore-Penrose Pseudoinverse (A^+). Uses Normal Equations approach for sparse matrices to avoid full SVD overhead.

Source:
Returns:
Type
SparseMatrixCSC

prune()

Description:

  • Eliminates explicit structural zeros from the matrix. Sparse operations might leave explicit zeros to avoid shifting arrays. Call this method to compact the matrix memory.

Source:

qr() → {Object}

Description:

  • Sparse QR Factorization using Left-Looking Modified Gram-Schmidt (MGS). Computes A = Q * R, where Q is orthogonal and R is upper triangular.

Source:
Returns:
Type
Object

set(row, col, val)

Description:

  • Sets the value at the specified row and column. Warning: Modifying the structure of a CSC matrix is O(nnz). If you are building a matrix, it is highly recommended to use fromCOO instead.

Source:
Parameters:
Name Type Description
row number
col number
val number | string | BigFloat

solve(b) → {Vector}

Description:

  • General Direct Solver for A * x = b. Uses the exact Sparse LU Factorization to compute the solution.

Source:
Parameters:
Name Type Description
b Vector | Array.<(number|string|BigFloat)>
Returns:

x

Type
Vector

solveBiCGSTAB(b, tolopt, maxIteropt, precondopt) → {Vector}

Description:

  • Bi-Conjugate Gradient Stabilized (BiCGSTAB) Method. Solves the linear system A * x = b for non-symmetric square matrices.

    • Fixed memory footprint (O(N) aux vectors, completely avoids GMRES memory explosion).
    • GC-Pause Elimination: Completely pre-allocated functional closures for array vectors.
Source:
Parameters:
Name Type Attributes Default Description
b Vector | Array.<(number|string|BigFloat)>

The right-hand side vector.
tol number | string | BigFloat <optional>
 "1e-20"

Convergence tolerance.
maxIter number <optional>

Maximum number of iterations. Defaults to 2 * matrix dimension.
precond Vector <optional>
 null

Optional Jacobi preconditioner vector (M^{-1}).
Returns:

x - The estimated solution vector.

Type
Vector

solveCG(b, tolopt, maxIteropt) → {Vector}

Description:

  • Conjugate Gradient (CG) Method. Solves the linear system A * x = b for Symmetric Positive Definite (SPD) matrices.

Source:
Parameters:
Name Type Attributes Default Description
b Vector | Array.<(number|string|BigFloat)>

The right-hand side vector.
tol number | string | BigFloat <optional>
 "1e-20"

Convergence tolerance.
maxIter number <optional>

Maximum number of iterations. Defaults to matrix dimension.
Returns:

x - The estimated solution vector.

Type
Vector

solveLowerTriangular(b) → {Vector}

Description:

  • Forward Substitution to solve L * x = b. Assumes this matrix is strictly a Lower Triangular matrix. Column-Oriented approach for CSC layout. O(nnz) time.

Source:
Parameters:
Name Type Description
b Vector | Array.<(number|string|BigFloat)>

The right-hand side vector.
Returns:

x - The solution vector.

Type
Vector

solveUpperTriangular(b) → {Vector}

Description:

  • Backward Substitution to solve U * x = b. Assumes this matrix is strictly an Upper Triangular matrix. Column-Oriented approach for CSC layout. O(nnz) time.

Source:
Parameters:
Name Type Description
b Vector | Array.<(number|string|BigFloat)>

The right-hand side vector.
Returns:

x - The solution vector.

Type
Vector

sub(other) → {SparseMatrixCSC}

Description:

  • Subtracts another SparseMatrixCSC from this matrix (C = A - B).

Source:
Parameters:
Name Type Description
other SparseMatrixCSC
Returns:
Type
SparseMatrixCSC

svd(tolopt, maxIteropt) → {Object}

Description:

  • Computes the Dominant Singular Value and Vectors using Golub-Kahan (Power Method on A^T A). Extracts the Top-1 Singular component.

Source:
Parameters:
Name Type Attributes Default Description
tol number | string | BigFloat <optional>
 "1e-20"
maxIter number <optional>
 1000
Returns:
Type
Object

syrk() → {SparseMatrixCSC}

Description:

  • Symmetric Rank-k Update (SYRK). Computes the matrix product A * A^T.

Source:
Returns:
Type
SparseMatrixCSC

toDense() → {Array.<Array.<BigFloat>>}

Description:

  • Converts the CSC Sparse Matrix back to a Dense Matrix (2D Array of BigFloat).

Source:
Returns:
Type
Array.<Array.<BigFloat>>

toString(radix, prec, maxRowItem) → {string}

Description:

  • Returns a string representation of the matrix. Uses the existing get(row, col) method and nnz property.

Source:
Parameters:
Name Type Default Description
radix number 10

The base for number representation (e.g., 10).
prec number 2

The number of decimal places for BigFloat.
maxRowItem number 10

Maximum number of rows/cols to show before truncating with "...".
Returns:
Type
string

trace() → {BigFloat}

Description:

  • Computes the Trace of the matrix (sum of diagonal elements).

Source:
Returns:
Type
BigFloat

transpose() → {SparseMatrixCSC}

Description:

  • Transposes the matrix. Converts an M x N CSC matrix to an N x M CSC matrix. This algorithm executes in O(nnz + max(rows, cols)) time.

Source:
Returns:
Type
SparseMatrixCSC

trsm(B, loweropt) → {SparseMatrixCSC}

Description:

  • Triangular Solve with Multiple Right-Hand Sides (TRSM). Solves A * X = B, where A is this triangular matrix.

Source:
Parameters:
Name Type Attributes Default Description
B SparseMatrixCSC

The right-hand side sparse matrix.
lower boolean <optional>
 true

True if A is lower triangular, False if upper triangular.
Returns:

X - The solution sparse matrix.

Type
SparseMatrixCSC

(static) fromCOO(rows, cols, rowIdx, colIdx, vals) → {SparseMatrixCSC}

Description:

  • Creates a CSC matrix from Coordinate (COO) / Triplet format. This is the recommended way to build a sparse matrix. Duplicates are automatically summed.

Source:
Parameters:
Name Type Description
rows number
cols number
rowIdx Array.<number>

Array of row coordinates.
colIdx Array.<number>

Array of column coordinates.
vals
Returns:
Type
SparseMatrixCSC

(static) fromDense(matrix) → {SparseMatrixCSC}

Description:

  • Converts a Dense Matrix (2D Array) into a Sparse CSC Matrix.

Source:
Parameters:
Name Type Description
matrix
Returns:
Type
SparseMatrixCSC