跳到主要内容

快速开始

WASMatrix 是由 AssemblyScript WebAssembly core 支撑的 TypeScript 矩阵库。矩阵缓冲区保留在 WASM memory 中，使用 f32 row-major storage，并要求 WebAssembly SIMD。

This guide walks through the first things most users need:

  • install the package
  • create matrices
  • run matrix, elementwise, and linear algebra operations
  • read results back only when you need them
  • understand when cached factorizations and lazy views help

Installation​

npm install wasmatrix

WASMatrix is ESM-only. Importing the package initializes the adjacent WASM asset with top-level await.

import Matrix from "wasmatrix";

The package ships JavaScript and WASM separately. The runtime resolves dist/wasmatrix.wasm with new URL("./wasmatrix.wasm", import.meta.url), so Node, Deno, Bun, browsers, CDNs, and bundlers can handle the asset in their normal way.

Runtime Requirements​

WASMatrix needs ESM, top-level await, and WebAssembly SIMD. If SIMD validation fails, initialization throws instead of silently falling back to a scalar implementation.

import { isSimdSupported } from "wasmatrix";

console.log(isSimdSupported());

Run Your First Program​

Create a file named hello.mjs and solve a small linear system.

import Matrix from "wasmatrix";

const A = Matrix.from(2, 2, [
  4, 7,
  2, 6
]);

const b = Matrix.from(2, 1, [
  1,
  0
]);

const x = A.solve(b);

console.log("det(A)", A.determinant());
console.log("solution", x.toArray());
console.log("check", A.matmul(x).equalsApprox(b));
node hello.mjs
bun hello.mjs
deno run --allow-read hello.mjs

The solve, determinant, and multiplication work runs inside WASM. JavaScript receives values only when toArray(), determinant(), or equalsApprox() reads them back.

Create Matrices​

Matrix.from(rows, cols, values) uses row-major values. Static constructors such as zeros, ones, identity, and diagonal also carry structure tags for later shortcuts.

const A = Matrix.from(2, 3, [
  1, 2, 3,
  4, 5, 6
]);

const Z = Matrix.zeros(3, 3);
const O = Matrix.ones(3, 2);
const I = Matrix.identity(4);
const D = Matrix.diagonal([2, 4, 8]);

Keep Data In WASM​

Most methods return another Matrix, and the result stays in WASM memory. Read back with toArray(), toFloat32Array(), row(), column(), or diagonal() only when JavaScript needs the values.

const result = A
  .scale(2)
  .addScalar(1)
  .sqrt()
  .clamp(0, 4);

const values = result.toArray();

Elementwise pipeline​

Elementwise chains are represented lazily and fused into one WASM pass when materialized. Row and column vectors broadcast without expanding to dense matrices.

const Y = A
  .add(B)
  .subtract(0.25)
  .hadamard(C)
  .clamp(-2, 2)
  .sqrt();

const centered = X.subtract(rowMeans);
const scaled = centered.divide(columnStddev);

Linear Algebra Without Dense Inverses​

Prefer solve() when you want A^-1 B. WASMatrix can reuse versioned LU, Cholesky, and QR caches across compatible determinant, solve, inverse, and rank calls on the same matrix object.

const x = A.solve(b);
const det = A.determinant();
const again = A.solve(otherRightHandSide);

Mutation And Cache Invalidation​

set() increments the matrix version and invalidates cached factorizations, reductions, packed operands, and materialized views. Keep the coefficient matrix object stable when you want cache reuse.

A.set(0, 0, A.at(0, 0) + 1);

設定​

fastMath enables more aggressive algebraic rewrites. cacheLimitBytes controls the WASM heap budget used by reusable caches.

import { configure } from "wasmatrix";

configure({
  fastMath: false,
  cacheLimitBytes: 64 * 1024 * 1024
});

Dispose Long-Lived Temporaries​

Long-running services, apps, and benchmarks should call dispose() for large temporaries when they are no longer needed.

const tmp = A.matmul(B);
try {
  console.log(tmp.frobeniusNorm());
} finally {
  tmp.dispose();
}

Development Build​

npm run build compiles the AssemblyScript kernel, the TypeScript runtime, and the distributable WASM file. The benchmark suite prints JSON timings, speedups, and checksums.

npm install
npm run build
npm test
npm run test:e2e
npm run benchmark

Where To Go Next​

Read the API Guide for the full method list, structural shortcuts, cache behavior, and memory-management details.