klu-js

Rust bindings for the KLU sparse matrix factorization library.

JavaScript / WebAssembly API

The crate exports a wasm-bindgen API when built for wasm32-unknown-unknown. The sparse matrix arrays use compressed-column storage. Ap and Ai are Int32Arrays, Ax and B are Float64Arrays, and B is updated in place.

import init, {
  klu_analyze,
  klu_defaults,
  klu_factor,
  klu_free_numeric,
  klu_free_symbolic,
  klu_refactor,
  klu_solve,
  klu_tsolve,
} from "klu-js";

await init();

const common = klu_defaults();
const n = 5;
const ap = new Int32Array([0, 2, 5, 9, 10, 12]);
const ai = new Int32Array([0, 1, 0, 2, 4, 1, 2, 3, 4, 2, 1, 4]);
const ax = new Float64Array([2, 3, 3, -1, 4, 4, -3, 1, 2, 2, 6, 1]);

const symbolic = klu_analyze(n, ap, ai, common);
const numeric = klu_factor(ap, ai, ax, symbolic, common);
const b = new Float64Array([8, 45, -3, 3, 19]);

klu_solve(symbolic, numeric, n, 1, b, common);
// b is now [1, 2, 3, 4, 5].

// Reuse symbolic/numeric handles for changed values of the same matrix:
// klu_refactor(ap, ai, changedAx, symbolic, numeric, common);
// klu_tsolve(symbolic, numeric, n, 1, b, common);

klu_free_numeric(numeric, common);
klu_free_symbolic(symbolic, common);

klu_solve, klu_tsolve, klu_refactor, and the free functions return the underlying KLU status (1 for success). klu_analyze and klu_factor throw a JavaScript exception if KLU cannot create their handle. The latest status and numerical statistics are available on common, for example common.status and common.numerical_rank.

Build with wasm-pack build --target web (or run wasm-bindgen on the generated .wasm file). A C toolchain with a wasm-compatible libc/sysroot is required because KLU is compiled from the bundled C sources.

The CDN package is built with wasm-pack --target no-modules, which exposes the same API through the global wasm_bindgen object for use from a classic <script src="…"> tag.

CDN example

After publishing [email protected], serve the repository and open http://localhost:8000/examples/cdn.html:

python -m http.server 8000

The page loads klu_js.js and its adjacent WebAssembly binary from jsDelivr, then factors and solves the sample sparse system.

Packaging for npm

Build the browser package and create a local npm tarball with:

wasm-pack build --target no-modules --release
wasm-pack pack

The generated package and tarball are written to pkg/. After reviewing the tarball, publish the package with npm publish ./pkg --access public (or use wasm-pack publish).

Building for WASI

Install the Rust target and download the WASI SDK and matching sysroot from the wasi-sdk project. In PowerShell, configure the SDK paths and build with:

rustup target add wasm32-wasip1

$wasiSdk = 'C:/path/to/wasi-sdk'
$wasiSysroot = 'C:/path/to/wasi-sysroot'
$env:CC_wasm32_wasip1 = "$wasiSdk/bin/clang.exe"
$env:WASI_SYSROOT = $wasiSysroot
$env:LIBCLANG_PATH = "$wasiSdk/bin"
$env:BINDGEN_EXTRA_CLANG_ARGS = "--sysroot=$wasiSysroot --target=wasm32-wasip1 -I$wasiSdk/lib/clang/23/include"

cargo build --target wasm32-wasip1

Use forward-slash paths in BINDGEN_EXTRA_CLANG_ARGS on Windows.