@danielsimonjr/mathts-matrix

High-performance matrix operations with multi-backend support (JS/WASM/GPU).

Installation

npm install @danielsimonjr/mathts-matrix

Usage

import {
  DenseMatrix,
  matMul,
  transposeNestedArray,
  svd,
  eig,
  lu,
  qr,
  cholesky,
} from '@danielsimonjr/mathts-matrix';

// Create a matrix from a 2D array
const A = DenseMatrix.fromArray([
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
]);

// DenseMatrix methods use the JS backend (add, multiply, transpose, …)
const sum = A.add(A);
const product = A.multiply(A);
const transposed = A.transpose();

// `eig` / `svd` take number[][]; `lu` / `qr` / `cholesky` take DenseMatrix
const { U, S, V, rank } = svd(A.toArray());
const { values, vectors } = eig(A.toArray());
const { L, U: Ulu, P } = lu(A);

// Nested-array multiply / transpose (same kernels as decomposition internals)
const C = matMul(A.toArray(), A.toArray());
const At = transposeNestedArray(A.toArray());

WASM matrix multiply (not DenseMatrix.multiply)

After await backendManager.initialize(), backendManager.multiply(a, b) and wasmBackend.multiply(a, b) can run the AssemblyScript GEMM kernel when size gates pass. Tensor.matMul in @danielsimonjr/mathts-tensor routes through the same manager. Public lu / qr / cholesky / eig / svd stay on JS; eigWasm and svdWasm are async wrappers that still call those JS solvers.

import { backendManager, DenseMatrix } from '@danielsimonjr/mathts-matrix';

await backendManager.initialize();
const a = DenseMatrix.random(32, 32);
const c = backendManager.multiply(a, a);

Backends

| Backend | How you reach it | Role | | -------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | JS | DenseMatrix methods; lu/qr/cholesky/eig/svd | Default | | WASM | backendManager.multiply, wasmBackend.multiply, Tensor.matMul | SIMD GEMM (+ unused-by-public decomp methods on WASMBackend) | | GPU | gpuMatrixBackend.multiplyAsync; @danielsimonjr/mathts-functions with enableGpu() | f32 opt-in; not registered on BackendManager |

Live defaults come from one table: matrix/src/config.ts DEFAULT_CONFIG (multiply WASM 256 flop count; gpu.enabled false). DEFAULT_EXTENDED_HINTS on BackendManager is derived from that table at load time. GPU hint 65536 is dormant until a GPU backend registers. Element-wise WASM paths were retired as slower than JS (2026-07).

Matrix Types

• DenseMatrix - Standard dense storage (row-major)
• SparseMatrix - CSR format for sparse data

Status

This package is under active development. Currently implemented:

• [x] Type definitions
• [x] Backend infrastructure
• [x] Dense matrix structure
• [x] Sparse matrix (CSR) structure
• [x] Matrix operations (add, multiply, transpose, etc.)
• [x] WASM backend (AssemblyScript) for manager-driven GEMM
• [x] GPU backend (WebGPU) via GPUMatrixBackend
• [x] SVD decomposition (JS)
• [x] Eigenvalue solvers (JS)
• [x] LU / QR / Cholesky and related exports (see API reference)

License

MIT