Sparse Matrix Operations

1/**2 * Example 26: Sparse Matrices3 *4 * CSR (Compressed Sparse Row) matrices store only the non-zero entries.5 * This example builds a CSRMatrix from COO triplets and runs the arithmetic,6 * products, transpose and dense conversion.7 */8 9import { CSRMatrix, tensor } from "deepbox/ndarray";10 11const expectFloat64Array = (value: unknown): Float64Array => {12  if (!(value instanceof Float64Array)) {13    throw new Error("Expected Float64Array");14  }15  return value;16};17 18console.log("=== Sparse Matrix Operations ===\n");19 20// Create a sparse matrix using COO (Coordinate) format21console.log("1. Creating sparse matrices");22// Matrix:23// [1, 0, 0, 2]24// [0, 3, 0, 0]25// [0, 0, 4, 0]26// [5, 0, 0, 6]27const sparse = CSRMatrix.fromCOO({28  rows: 4,29  cols: 4,30  rowIndices: new Int32Array([0, 0, 1, 2, 3, 3]),31  colIndices: new Int32Array([0, 3, 1, 2, 0, 3]),32  values: new Float64Array([1, 2, 3, 4, 5, 6]),33});34console.log("  Created 4x4 sparse matrix with 6 non-zero elements");35console.log(`  Sparsity: ${((1 - sparse.nnz / (sparse.rows * sparse.cols)) * 100).toFixed(1)}%`);36 37// Element access38console.log("\n2. Element access");39console.log(`  Element at (0,0): ${sparse.get(0, 0)}`);40console.log(`  Element at (0,3): ${sparse.get(0, 3)}`);41console.log(`  Element at (1,1): ${sparse.get(1, 1)}`);42 43// Arithmetic operations44console.log("\n3. Sparse matrix addition");45// Matrix:46// [0, 1, 0, 0]47// [2, 0, 0, 0]48// [0, 0, 0, 3]49// [0, 4, 0, 0]50const sparse2 = CSRMatrix.fromCOO({51  rows: 4,52  cols: 4,53  rowIndices: new Int32Array([0, 1, 2, 3]),54  colIndices: new Int32Array([1, 0, 3, 1]),55  values: new Float64Array([1, 2, 3, 4]),56});57const sum = sparse.add(sparse2);58console.log(`  Result has ${sum.nnz} non-zero elements`);59 60console.log("\n4. Scalar multiplication");61const scaled = sparse.scale(2);62console.log(`  Scaled matrix has ${scaled.nnz} non-zero elements`);63console.log(`  Element at (0,0): ${scaled.get(0, 0)} (was ${sparse.get(0, 0)})`);64 65console.log("\n5. Element-wise multiplication (Hadamard product)");66const product = sparse.multiply(sparse2);67console.log(`  Product has ${product.nnz} non-zero elements`);68 69// Matrix-vector multiplication70console.log("\n6. Matrix-vector multiplication");71const vec = tensor([1, 2, 3, 4]);72const result = sparse.matvec(vec);73const resultData = expectFloat64Array(result.data);74console.log(`  Result: [${Array.from(resultData).join(", ")}]`);75 76// Matrix-matrix multiplication77console.log("\n7. Matrix-matrix multiplication");78// Dense matrix (4x2):79// [1, 0]80// [0, 1]81// [1, 1]82// [0, 1]83const dense = tensor([84  [1, 0],85  [0, 1],86  [1, 1],87  [0, 1],88]);89const matmul = sparse.matmul(dense);90console.log(`  Result shape: [${matmul.shape.join(", ")}]`);91console.log("  The product of a sparse and a dense matrix is a dense tensor");92 93// Transpose94console.log("\n8. Transpose");95const transposed = sparse.transpose();96console.log(`  Original: ${sparse.rows}x${sparse.cols}`);97console.log(`  Transposed: ${transposed.rows}x${transposed.cols}`);98console.log(`  Non-zero elements preserved: ${transposed.nnz}`);99 100// Convert back to dense101console.log("\n9. Convert to dense");102const densified = sparse.toDense();103console.log("  Converted back to dense tensor");104console.log(`  Shape: [${densified.shape.join(", ")}]`);105 106console.log("\n=== When to use CSRMatrix ===");107console.log("- Memory use grows with the number of non-zeros, not with rows * cols");108console.log(109  "- Products touch only the stored entries, so they are cheaper when most entries are zero"110);111console.log(112  "- Typical uses: graph adjacency matrices, bag-of-words features, finite-difference operators"113);