@jtgtools/xsparse

Sparse linear algebra for TypeScript. xsparse is ESM-only, has no runtime dependencies, and uses Float64 CSR/CSC matrices with Int32 indices.

Install

npm install @jtgtools/xsparse

The package works with Bun, Node, TypeScript, and browser bundlers.

Example

import { TripletMatrix, applyDirichlet, backwardError, cg, ichol } from "@jtgtools/xsparse";

const K = new TripletMatrix(5, 5);
const ke = new Float64Array([1, -1, -1, 1]);

for (let e = 0; e < 4; e++) K.element([e, e + 1], ke);

const { A, b } = applyDirichlet(K.csr(), new Float64Array(5), [0, 4], [0, 2]);
const result = cg(A, b, {
  preconditioner: ichol(A),
  rtol: 1e-10,
  maxIterations: 100,
});

if (!result.converged || backwardError(A, result.x, b) > 1e-11) {
  throw new Error("solve failed");
}

API

• Matrices: TripletMatrix, csr, csc, fromTriplets, fromDense, sparse products, scaling, permutations, block assembly, and Matrix Market I/O.
• Direct methods: Cholesky, pivoted LU, sparse Householder QR, triangular solves, least squares, minimum norm, refinement, and automatic solve dispatch.
• Iterative methods: CG, MINRES, GMRES, FGMRES, BiCGSTAB, CGNR, Richardson, Jacobi, Gauss-Seidel, and SOR.
• Preconditioners: Jacobi, Gauss-Seidel, SOR/SSOR, exact, IC(0), ILU(0), ILUT, ILUTP, and block forms.
• Multigrid: Galerkin coarsening, V/W cycles, geometric helpers, and smoothed-aggregation AMG.
• FEM: assembly, Dirichlet constraints, affine reduction, static condensation, Schur complements, and saddle-point systems.
• Eigenproblems: symmetric and generalized symmetric eigenpairs.
• Graphs: components, matching, structural rank, Dulmage-Mendelsohn, RCM, minimum-degree orderings, coloring, and nested dissection.

Contracts

• Stored matrix entries and solver inputs are finite real numbers.
• Matrix dimensions and sparse metadata must fit signed 32-bit indexing.
• Matrix factories copy input storage, combine duplicates, sort indices, and remove exact zeros.
• Iterative solvers set converged: true only after checking the documented residual. Reaching the iteration limit returns converged: false; invalid input or algorithmic breakdown raises RangeError.
• CG requires SPD input, MINRES requires symmetric input, and generalized eigenproblems require an SPD mass matrix.

See QUALIFICATION.md for the full numerical contract. Applications must still check model-level quantities such as equilibrium, energy, conditioning, and mesh convergence.

Development

The release gate requires Bun, Node/npm, Python 3, NumPy, SciPy, and NetworkX.

bun install
bun run verify

See VERIFICATION.md for pinned versions and the checks run before publication.