Skip to content

Latest commit

 

History

History
201 lines (144 loc) · 5.49 KB

README.md

File metadata and controls

201 lines (144 loc) · 5.49 KB

@ruvector/math-wasm

npm version crates.io License WASM

High-performance WebAssembly bindings for advanced mathematical algorithms in vector search and AI.

Brings Optimal Transport, Information Geometry, and Product Manifolds to the browser with near-native performance.

Features

  • 🚀 Optimal Transport - Sliced Wasserstein, Sinkhorn, Gromov-Wasserstein distances
  • 📐 Information Geometry - Fisher Information Matrix, Natural Gradient, K-FAC
  • 🌐 Product Manifolds - E^n × H^n × S^n (Euclidean, Hyperbolic, Spherical)
  • ⚡ SIMD Optimized - Vectorized operations where available
  • 🔒 Type-Safe - Full TypeScript definitions included
  • 📦 Zero Dependencies - Pure Rust compiled to WASM

Installation

npm install @ruvector/math-wasm
# or
yarn add ruvector-math-wasm
# or
pnpm add ruvector-math-wasm

Quick Start

Browser (ES Modules)

import init, {
  WasmSlicedWasserstein,
  WasmSinkhorn,
  WasmProductManifold
} from '@ruvector/math-wasm';

// Initialize WASM module
await init();

// Compute Sliced Wasserstein distance
const sw = new WasmSlicedWasserstein(100); // 100 projections
const source = new Float64Array([0, 0, 1, 1, 2, 2]); // 3 points in 2D
const target = new Float64Array([0.5, 0.5, 1.5, 1.5, 2.5, 2.5]);
const distance = sw.distance(source, target, 2);
console.log(`Wasserstein distance: ${distance}`);

Node.js

const { WasmSlicedWasserstein } = require('@ruvector/math-wasm');

const sw = new WasmSlicedWasserstein(100);
const dist = sw.distance(source, target, 2);

Use Cases

1. Distribution Comparison in ML

Compare probability distributions for generative models, anomaly detection, or data drift monitoring.

// Compare embedding distributions
const sw = new WasmSlicedWasserstein(200).withPower(2); // W2 distance

const trainEmbeddings = new Float64Array(/* ... */);
const testEmbeddings = new Float64Array(/* ... */);

const drift = sw.distance(trainEmbeddings, testEmbeddings, 768);
if (drift > threshold) {
  console.warn('Data drift detected!');
}

2. Semantic Vector Search

Use product manifolds for hierarchical and semantic search.

const manifold = new WasmProductManifold({
  euclidean_dim: 256,
  hyperbolic_dim: 128,
  spherical_dim: 128,
  curvature_h: -1.0,
  curvature_s: 1.0
});

// Compute distance in mixed-curvature space
const dist = manifold.distance(queryVector, documentVector);

3. Optimal Transport for Image Comparison

const sinkhorn = new WasmSinkhorn(0.01, 100); // regularization, max_iters

// Compare image histograms
const result = sinkhorn.solveTransport(
  costMatrix,
  sourceWeights,
  targetWeights,
  n, m
);

console.log(`Transport cost: ${result.cost}`);
console.log(`Converged: ${result.converged}`);

4. Natural Gradient Optimization

const fisher = new WasmFisherInformation(512);

// Compute Fisher Information Matrix
const fim = fisher.compute(activations);

// Apply natural gradient
const naturalGrad = fisher.naturalGradientStep(gradient, 0.01);

API Reference

Optimal Transport

Class Description
WasmSlicedWasserstein Fast approximation via random projections
WasmSinkhorn Entropy-regularized optimal transport
WasmGromovWasserstein Cross-space structural comparison

Information Geometry

Class Description
WasmFisherInformation Fisher Information Matrix computation
WasmNaturalGradient Natural gradient descent optimizer

Product Manifolds

Class Description
WasmProductManifold E^n × H^n × S^n mixed-curvature space
WasmSphericalSpace Spherical geometry operations

Performance

Benchmarked on M1 MacBook Pro (WASM in Chrome):

Operation Dimension Time
Sliced Wasserstein (100 proj) 1000 points × 128D 2.3ms
Sinkhorn (100 iter) 500 × 500 8.7ms
Product Manifold distance 512D 0.04ms

TypeScript Support

Full TypeScript definitions are included:

import { WasmSlicedWasserstein, WasmSinkhornConfig } from '@ruvector/math-wasm';

const sw: WasmSlicedWasserstein = new WasmSlicedWasserstein(100);
const distance: number = sw.distance(source, target, dim);

Building from Source

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build
cd crates/ruvector-math-wasm
wasm-pack build --target web --release

# Test
wasm-pack test --headless --chrome

Related Packages

License

MIT OR Apache-2.0

Links