@gasm-compiler/math-reference

CPU-side reference implementations of Gasm math extension functions

When compiling WebAssembly to WGSL with @gasm-compiler/core, math functions like sin, cos, sqrt, etc. are compiled to native WGSL built-ins for GPU execution. This package provides matching CPU-side implementations so you can:

• Test your Wasm modules on the CPU before running on the GPU
• Validate numerical results between CPU and GPU execution
• Run Gasm-compatible WebAssembly in Node.js/Deno without a GPU

Installation

npm install @gasm-compiler/math-reference

Quick Start

Run Gasm WebAssembly on the CPU

import { createMathImports, instantiateWithMath } from "@gasm-compiler/math-reference";

// Instantiate a Gasm-compatible Wasm module with math imports provided
const instance = await instantiateWithMath(wasmBytes);

// Or with additional imports (e.g., memory)
const instance = await instantiateWithMath(wasmBytes, {
  env: { memory: new WebAssembly.Memory({ initial: 1 }) }
});

Use math functions directly

import { sin, cos, sqrt, clamp, smoothstep } from "@gasm-compiler/math-reference";

sin(Math.PI / 2);      // 1.0
sqrt(4);                // 2.0
clamp(5, 0, 1);         // 1.0
smoothstep(0, 1, 0.5);  // 0.5

Vector operations

import { vec3, dot, cross, normalize } from "@gasm-compiler/math-reference";

const a = vec3(1, 0, 0);
const b = vec3(0, 1, 0);

dot(a, b);        // 0.0
cross(a, b);      // vec3(0, 0, 1)
normalize(a);     // vec3(1, 0, 0)

WebAssembly Integration

Use createMathImports() to get a Wasm import object that satisfies all (import "gasm" ...) math function imports:

import { createMathImports } from "@gasm-compiler/math-reference";

const imports = createMathImports();
const module = new WebAssembly.Module(wasmBytes);
const instance = new WebAssembly.Instance(module, imports);

This lets you execute Gasm-compatible WebAssembly modules on the CPU with the same math functions that compile to WGSL built-ins on the GPU.

Comparison Utilities

import { approximatelyEqual, setConfig } from "@gasm-compiler/math-reference";

// Set tolerance for floating-point comparisons
setConfig({ tolerance: 1e-6 });

// Compare CPU vs GPU results
approximatelyEqual(0.1 + 0.2, 0.3); // true

Function Reference

M0: Core Scalar Functions

| Function | Signature | Description | |----------|-----------|-------------| | sin | (x: number) => number | Sine of angle in radians | | cos | (x: number) => number | Cosine of angle in radians | | tan | (x: number) => number | Tangent of angle in radians | | asin | (x: number) => number | Arc sine | | acos | (x: number) => number | Arc cosine | | atan | (x: number) => number | Arc tangent | | atan2 | (y, x) => number | Arc tangent of y/x | | sinh | (x: number) => number | Hyperbolic sine | | cosh | (x: number) => number | Hyperbolic cosine | | tanh | (x: number) => number | Hyperbolic tangent | | asinh | (x: number) => number | Inverse hyperbolic sine | | acosh | (x: number) => number | Inverse hyperbolic cosine | | atanh | (x: number) => number | Inverse hyperbolic tangent | | exp | (x: number) => number | e^x | | exp2 | (x: number) => number | 2^x | | log | (x: number) => number | Natural logarithm | | log2 | (x: number) => number | Base-2 logarithm | | pow | (x, y) => number | x^y | | sqrt | (x: number) => number | Square root | | inverseSqrt | (x: number) => number | 1/sqrt(x) | | abs | (x: number) => number | Absolute value | | sign | (x: number) => number | Sign (-1, 0, or 1) | | floor | (x: number) => number | Floor | | ceil | (x: number) => number | Ceiling | | trunc | (x: number) => number | Truncate toward zero | | round | (x: number) => number | Round to nearest | | fract | (x: number) => number | Fractional part | | min | (x, y) => number | Minimum | | max | (x, y) => number | Maximum | | clamp | (x, min, max) => number | Clamp to range | | saturate | (x: number) => number | Clamp to [0, 1] | | mix | (x, y, a) => number | Linear interpolation | | step | (edge, x) => number | Step function | | smoothstep | (e0, e1, x) => number | Smooth Hermite step | | fma | (a, b, c) => number | Fused multiply-add |

M1: Vector Functions

| Function | Signature | Description | |----------|-----------|-------------| | length | (v: Vector) => number | Vector magnitude | | distance | (a, b) => number | Distance between points | | dot | (a, b) => number | Dot product | | cross | (a, b) => Vec3 | Cross product (vec3 only) | | normalize | (v: Vector) => Vector | Unit vector | | reflect | (i, n) => Vector | Reflect off surface | | refract | (i, n, eta) => Vector | Refract through surface | | faceForward | (n, i, nRef) => Vector | Face forward |

M2: Advanced Functions

| Function | Signature | Description | |----------|-----------|-------------| | modf | (x) => { fract, whole } | Split into fractional and whole parts | | frexp | (x) => { significand, exponent } | Extract mantissa and exponent | | ldexp | (sig, exp) => number | Construct from mantissa and exponent | | degrees | (rad) => number | Radians to degrees | | radians | (deg) => number | Degrees to radians | | countOneBits | (x) => number | Population count | | countLeadingZeros | (x) => number | Count leading zeros | | countTrailingZeros | (x) => number | Count trailing zeros | | firstLeadingBit | (x) => number | First leading 1 bit | | firstTrailingBit | (x) => number | First trailing 1 bit | | reverseBits | (x) => number | Reverse bit order | | extractBits | (val, off, cnt) => number | Extract bit field | | insertBits | (orig, ins, off, cnt) => number | Insert bit field |

Related Packages

• @gasm-compiler/core — Compile WebAssembly to WGSL for GPU execution
• @gasm-compiler/cli — Command-line compiler

License

See LICENSE for details.