@danielsimonjr/mathts-functions 0.17.2 → 0.19.0

package/dist/gpu/elementwise-gpu.d.ts

@@ -2,52 +2,65 @@
  * WebGPU fused element-wise chain.
  *
  * Why a *chain* and not a single op: a lone element-wise op on the GPU is pure
- * transfer tax — upload n floats, do one flop each, read n floats back. The
- * same memory-bound economics retired element-wise ops from the WASM backend.
- * A **fused chain** uploads once, runs every op in the chain on-device by
- * ping-ponging two storage buffers, and reads back once, so the transfer cost
- * is amortized across the whole chain.
+ * transfer tax — upload n floats, do one flop each, read n floats back. A
+ * **fused chain** uploads once, runs every op on-device by ping-ponging two
+ * storage buffers, and reads back once, so the transfer is amortized across the
+ * whole chain.
  *
- * Contract (mirrors the WASM `elementwiseChainDispatch`): this is a
- * **never-throw** best-effort fast path. It returns `null` — never rejects —
- * whenever the GPU is unavailable, not opted in, the input is too small, or the
- * chain contains an op with no GPU kernel. The caller then falls through to the
- * existing WASM/JS tiers.
+ * **Read this before reaching for the GPU:** for element-wise chains the GPU is
+ * the *fastest* tier (3.2–8.3× over WASM — see the table on
+ * `fuseUnaryChainAsync`), but it computes in **f32** where every CPU tier is
+ * f64-exact. That is the whole trade, and `enableGpu()` is how a caller consents
+ * to it. `fuseUnaryChainAsync` therefore tries the GPU first, but only when the
+ * flag is on; with it off (the default) the GPU never runs.
  *
- * Precision: the GPU path computes in **f32** (WGSL has no f64). This is why it
- * is gated behind the explicit `enableGpu()` opt-in.
- */
-import { type GPUContextOptions } from '@danielsimonjr/mathts-gpu';
-/**
- * WGSL expressions for each supported op, as a function of `x`.
+ * An earlier revision of this comment claimed the GPU was ~1.9× *slower* than
+ * WASM. That was an artifact of a `Float32Array.from()` in this very file — the
+ * generic `Array.from` path, which cost 433 ms at n=2²⁰ where the constructor
+ * costs 5.9 ms. Do not re-derive a tier ranking from a single tier's number; see
+ * `gpu-vs-wasm.browser.test.ts`, which measures all three in one run.
  *
- * Deliberately a SUBSET of the WASM op set. `erfc` is absent: WGSL has no
- * `erfc` builtin, and hand-rolling a polynomial approximation would silently
- * change the accuracy contract. A chain containing an unsupported op returns
- * `null` and falls back, rather than quietly computing something else.
+ * Contract (mirrors the WASM `elementwiseChainDispatch`): a **never-throw**
+ * best-effort fast path. It returns `null` — never rejects — whenever the GPU is
+ * unavailable, not opted in, the input is too small, or the chain contains an op
+ * with no GPU kernel. The caller then falls through to the CPU tiers.
  */
+import { type GPUContextOptions } from '@danielsimonjr/mathts-gpu';
 declare const WGSL_OP_BODY: {
     readonly abs: "return abs(x);";
     readonly sin: "return sin(x);";
     readonly cos: "return cos(x);";
     readonly tan: "return tan(x);";
     readonly exp: "return exp(x);";
-    readonly log: "return log(x);";
     readonly atan: "return atan(x);";
     readonly sinh: "return sinh(x);";
     readonly tanh: "return tanh(x);";
-    readonly atanh: "return atanh(x);";
-    readonly log2: "return log2(x);";
-    readonly log10: "return log(x) * 0.4342944819032518;";
-    readonly sec: "return 1.0 / cos(x);";
-    readonly csc: "return 1.0 / sin(x);";
-    readonly cot: "return 1.0 / tan(x);";
+    readonly log: "return safe_log(x);";
+    readonly log2: "return safe_log(x) * 1.4426950408889634;";
+    readonly log10: "return safe_log(x) * 0.4342944819032518;";
+    readonly atanh: "return safe_atanh(x);";
+    readonly sec: "return safe_recip(cos(x));";
+    readonly csc: "return safe_recip(sin(x));";
+    readonly cot: "return safe_recip(tan(x));";
 };
 /** Ops that have a GPU kernel. A chain outside this set falls back. */
 export type GpuElementwiseOp = keyof typeof WGSL_OP_BODY;
 export declare const GPU_ELEMENTWISE_OPS: GpuElementwiseOp[];
 /** Whether every op in the chain has a GPU kernel. */
 export declare function isGpuChainSupported(ops: readonly string[]): ops is readonly GpuElementwiseOp[];
+/** Drop the cached shaders/buffers (device loss, or between tests). */
+export declare function resetGpuElementwise(): void;
+/** Options for a GPU element-wise dispatch. */
+export interface GpuChainOptions extends GPUContextOptions {
+    /**
+     * Per-call override of the global `enableGpu()` flag.
+     *
+     * The global flag is process-wide mutable state: any dependency that calls
+     * `enableGpu()` would otherwise change *your* call's behaviour. Passing `gpu`
+     * explicitly makes a call self-describing and immune to that.
+     */
+    gpu?: boolean;
+}
 /**
  * Run a fused element-wise chain on the GPU.
  *
@@ -55,6 +68,6 @@ export declare function isGpuChainSupported(ops: readonly string[]): ops is read
  * @param xs  - input samples
  * @returns the f32 results, or `null` to signal "fall back to another tier"
  */
-export declare function elementwiseChainGpuDispatch(ops: readonly string[], xs: Float64Array | Float32Array, options?: GPUContextOptions): Promise<Float32Array | null>;
+export declare function elementwiseChainGpuDispatch(ops: readonly string[], xs: Float64Array | Float32Array, options?: GpuChainOptions): Promise<Float32Array | null>;
 export {};
 //# sourceMappingURL=elementwise-gpu.d.ts.map

package/dist/gpu/elementwise-gpu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elementwise-gpu.d.ts","sourceRoot":"","sources":["../../src/gpu/elementwise-gpu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;GAOG;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;CAkCR,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,YAAY,CAAC;AAEzD,eAAO,MAAM,mBAAmB,EAAgC,gBAAgB,EAAE,CAAC;AAEnF,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,IAAI,SAAS,gBAAgB,EAAE,CAE9F;AA8CD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,EAAE,EAAE,YAAY,GAAG,YAAY,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAuH9B"}
+{"version":3,"file":"elementwise-gpu.d.ts","sourceRoot":"","sources":["../../src/gpu/elementwise-gpu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AA+CnC,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;CAgCR,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,YAAY,CAAC;AAEzD,eAAO,MAAM,mBAAmB,EAAgC,gBAAgB,EAAE,CAAC;AAEnF,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,IAAI,SAAS,gBAAgB,EAAE,CAE9F;AAsED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,EAAE,EAAE,YAAY,GAAG,YAAY,EAC/B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA6H9B"}

package/dist/index.js

@@ -396,6 +396,7 @@ __export(typed_exports, {
   reduce: () => reduce,
   reflectVector: () => reflectVector,
   resample: () => resample,
+  resetGpuElementwise: () => resetGpuElementwise,
   residue: () => residue,
   resultant: () => resultant,
   rightArithShift: () => rightArithShift,
@@ -7341,41 +7342,76 @@ var typedSpecial = {
 // src/gpu/elementwise-gpu.ts
 import {
   getGpuDevice,
+  getGlobalGPUContext,
   isGpuEnabled,
-  GPU_MIN_ELEMENTS
+  GPU_MIN_ELEMENTS,
+  ShaderManager,
+  BufferPool
 } from "@danielsimonjr/mathts-gpu";
+var WGSL_IEEE = `
+  // NaN / \xB1Inf are supplied through the UNIFORM, not written as literals.
+  //
+  // WGSL const-folds \`bitcast<f32>(0x7fc00000u)\` even inside a function body and
+  // then rejects the result: "value nan cannot be represented as 'f32'" \u2014 a const
+  // expression may not BE NaN or Inf. Reading the bit pattern from \`params\` (a
+  // runtime uniform) is not const-foldable, so the bitcast survives to runtime.
+  // params = (n, nanBits, posInfBits, negInfBits).
+  fn nan_f32() -> f32 { return bitcast<f32>(params.y); }
+  fn pos_inf() -> f32 { return bitcast<f32>(params.z); }
+  fn neg_inf() -> f32 { return bitcast<f32>(params.w); }
+
+  fn safe_log(x: f32) -> f32 {
+    if (x < 0.0) { return nan_f32(); }
+    if (x == 0.0) { return neg_inf(); }
+    return log(x);
+  }
+  fn safe_atanh(x: f32) -> f32 {
+    if (x > 1.0 || x < -1.0) { return nan_f32(); }
+    if (x == 1.0) { return pos_inf(); }
+    if (x == -1.0) { return neg_inf(); }
+    return atanh(x);
+  }
+  // 1/d with IEEE division-by-zero semantics (JS: 1/0 = +Inf, 1/-0 = -Inf).
+  fn safe_recip(d: f32) -> f32 {
+    if (d == 0.0) {
+      // Distinguish +0 from -0 by its sign bit, as IEEE division does.
+      if ((bitcast<u32>(d) & 0x80000000u) != 0u) { return neg_inf(); }
+      return pos_inf();
+    }
+    return 1.0 / d;
+  }
+`;
 var WGSL_OP_BODY = {
   abs: "return abs(x);",
   sin: "return sin(x);",
   cos: "return cos(x);",
   tan: "return tan(x);",
   exp: "return exp(x);",
-  log: "return log(x);",
   atan: "return atan(x);",
   sinh: "return sinh(x);",
   tanh: "return tanh(x);",
-  atanh: "return atanh(x);",
-  log2: "return log2(x);",
-  // WGSL has no log10 builtin; log(x) * 1/ln(10).
-  log10: "return log(x) * 0.4342944819032518;",
-  // NOTE — `expm1` and `log1p` are DELIBERATELY ABSENT, like `erfc`.
-  //
-  // WGSL has no builtin for either. The naive identities (`exp(x)-1`,
-  // `log(1+x)`) are catastrophically wrong near zero in f32: `1.0 + 1e-8`
-  // rounds to exactly 1.0f, so `log(1+x)` returns 0 where the true value is
-  // 1e-8 — a 100% relative error.
+  // Domain-guarded: WGSL says indeterminate outside the domain; JS does not.
+  log: "return safe_log(x);",
+  log2: "return safe_log(x) * 1.4426950408889634;",
+  // ln(x) / ln(2)
+  log10: "return safe_log(x) * 0.4342944819032518;",
+  // ln(x) / ln(10)
+  atanh: "return safe_atanh(x);",
+  sec: "return safe_recip(cos(x));",
+  csc: "return safe_recip(sin(x));",
+  cot: "return safe_recip(tan(x));"
+  // NOTE — `expm1`, `log1p` and `erfc` are DELIBERATELY ABSENT.
   //
-  // The standard Kahan-compensated forms were implemented and MEASURED on real
-  // hardware (NVIDIA Pascal). They still scored 38% (expm1) and 62% (log1p) max
-  // relative error over x in [1e-9, 1e-3], because the compensation relies on
-  // `log()` being accurate for arguments near 1.0, and the GPU's fast-math
-  // `log()` is not.
+  // WGSL has no builtin for any of them. For expm1/log1p the naive identities
+  // (`exp(x)-1`, `log(1+x)`) are catastrophically wrong near zero in f32
+  // (`1.0 + 1e-8` rounds to exactly 1.0f, so `log(1+x)` returns 0 where the true
+  // value is 1e-8 — 100% relative error), and the standard Kahan-compensated
+  // forms were implemented and MEASURED on real hardware: still 38% (expm1) and
+  // 62% (log1p) max relative error, because the compensation needs an accurate
+  // `log()` near 1.0 and the GPU's fast-math `log()` is not.
   //
-  // An f32 fast path is allowed to be less precise. It is not allowed to be
-  // WRONG. Chains containing these fall back to the exact WASM/JS tiers.
-  sec: "return 1.0 / cos(x);",
-  csc: "return 1.0 / sin(x);",
-  cot: "return 1.0 / tan(x);"
+  // An f32 fast path may be less precise. It may not be WRONG. Chains containing
+  // these fall back to the exact WASM/JS tiers.
 };
 var GPU_ELEMENTWISE_OPS = Object.keys(WGSL_OP_BODY);
 function isGpuChainSupported(ops) {
@@ -7386,6 +7422,9 @@ function wgslFor(op) {
   return `
     @group(0) @binding(0) var<storage, read> inp: array<f32>;
     @group(0) @binding(1) var<storage, read_write> outp: array<f32>;
+    @group(0) @binding(2) var<uniform> params: vec4<u32>; // n, nanBits, +infBits, -infBits
+
+    ${WGSL_IEEE}
 
     fn apply(x: f32) -> f32 {
       ${WGSL_OP_BODY[op]}
@@ -7394,80 +7433,72 @@ function wgslFor(op) {
     @compute @workgroup_size(${WORKGROUP_SIZE})
     fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
       let i = gid.x;
-      if (i >= arrayLength(&inp)) { return; }
+      if (i >= params.x) { return; }
       outp[i] = apply(inp[i]);
     }
   `;
 }
-var pipelineCache = /* @__PURE__ */ new WeakMap();
-function getPipeline(device, op) {
-  let byOp = pipelineCache.get(device);
-  if (!byOp) {
-    byOp = /* @__PURE__ */ new Map();
-    pipelineCache.set(device, byOp);
-  }
-  const cached = byOp.get(op);
-  if (cached) return cached;
-  const pipeline = device.createComputePipeline({
-    label: `elementwise:${op}`,
-    layout: "auto",
-    compute: {
-      module: device.createShaderModule({ code: wgslFor(op), label: `elementwise:${op}` }),
-      entryPoint: "main"
-    }
-  });
-  byOp.set(op, pipeline);
-  return pipeline;
+var resources = null;
+async function getResources(options) {
+  const device = await getGpuDevice(options);
+  if (!device) return null;
+  if (resources && resources.device === device) return resources;
+  const ctx = getGlobalGPUContext();
+  const shaders = new ShaderManager(ctx);
+  for (const op of GPU_ELEMENTWISE_OPS) {
+    shaders.registerShader(op, wgslFor(op));
+  }
+  shaders.precompileRegistered();
+  resources = { device, shaders, pool: new BufferPool(ctx) };
+  return resources;
+}
+function resetGpuElementwise() {
+  resources?.pool.destroy();
+  resources = null;
 }
 async function elementwiseChainGpuDispatch(ops, xs, options) {
   const n = xs.length;
-  if (!isGpuEnabled()) return null;
+  const enabled = options?.gpu ?? isGpuEnabled();
+  if (!enabled) return null;
   if (ops.length === 0) return null;
   if (n < GPU_MIN_ELEMENTS) return null;
   if (!isGpuChainSupported(ops)) return null;
   const bytes = n * 4;
   const workgroups = Math.ceil(n / WORKGROUP_SIZE);
+  let res;
   let bufA;
   let bufB;
   let staging;
+  let params;
   let scopePopped = false;
-  let device;
   try {
-    const d = await getGpuDevice(options);
-    if (!d) return null;
-    device = d;
+    const r = await getResources(options);
+    if (!r) return null;
+    res = r;
+    const { device, shaders, pool } = r;
     const limits = device.limits;
     if (workgroups > limits.maxComputeWorkgroupsPerDimension) return null;
     if (bytes > limits.maxStorageBufferBindingSize) return null;
     if (bytes > limits.maxBufferSize) return null;
-    const input = xs instanceof Float32Array ? xs : Float32Array.from(xs);
+    const input = xs instanceof Float32Array ? xs : new Float32Array(xs);
     device.pushErrorScope("validation");
-    bufA = device.createBuffer({
-      size: bytes,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-      label: "chain-a"
-    });
-    bufB = device.createBuffer({
-      size: bytes,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-      label: "chain-b"
-    });
-    staging = device.createBuffer({
-      size: bytes,
-      usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
-      label: "chain-staging"
-    });
+    bufA = pool.acquireStorageBuffer(bytes, "chain-a", true, true);
+    bufB = pool.acquireStorageBuffer(bytes, "chain-b", true, true);
+    staging = pool.acquireStagingBuffer(bytes, "chain-staging");
+    params = pool.acquireUniformBuffer(16, "chain-params");
     device.queue.writeBuffer(bufA, 0, input);
+    device.queue.writeBuffer(params, 0, new Uint32Array([n, 2143289344, 2139095040, 4286578688]));
     const encoder = device.createCommandEncoder({ label: "elementwise-chain" });
     let src = bufA;
     let dst2 = bufB;
     for (const op of ops) {
-      const pipeline = getPipeline(device, op);
+      const pipeline = shaders.getRegisteredPipeline(op);
       const bindGroup = device.createBindGroup({
         layout: pipeline.getBindGroupLayout(0),
         entries: [
           { binding: 0, resource: { buffer: src } },
-          { binding: 1, resource: { buffer: dst2 } }
+          { binding: 1, resource: { buffer: dst2 } },
+          { binding: 2, resource: { buffer: params } }
         ]
       });
       const pass = encoder.beginComputePass({ label: `chain:${op}` });
@@ -7482,22 +7513,25 @@ async function elementwiseChainGpuDispatch(ops, xs, options) {
     const validationError = await device.popErrorScope();
     scopePopped = true;
     if (validationError) return null;
-    await staging.mapAsync(GPUMapMode.READ);
-    const out = new Float32Array(staging.getMappedRange().slice(0));
+    await staging.mapAsync(GPUMapMode.READ, 0, bytes);
+    const out = new Float32Array(staging.getMappedRange(0, bytes).slice(0));
     staging.unmap();
     return out;
   } catch {
     return null;
   } finally {
-    if (device && !scopePopped) {
+    if (res && !scopePopped) {
       try {
-        await device.popErrorScope();
+        await res.device.popErrorScope();
       } catch {
       }
     }
-    bufA?.destroy();
-    bufB?.destroy();
-    staging?.destroy();
+    if (res) {
+      if (bufA) res.pool.release(bufA);
+      if (bufB) res.pool.release(bufB);
+      if (staging) res.pool.release(staging);
+      if (params) res.pool.release(params);
+    }
   }
 }
 
@@ -7528,18 +7562,18 @@ function fuseUnaryChain(ops, xs) {
   return jsChain(ops, xs);
 }
 function jsChain(ops, xs) {
-  const out = Float64Array.from(xs);
+  const out = new Float64Array(xs);
   for (const op of ops) {
     const f = SCALAR[op];
     for (let i = 0; i < out.length; i++) out[i] = f(out[i]);
   }
   return out;
 }
-async function fuseUnaryChainAsync(ops, xs) {
+async function fuseUnaryChainAsync(ops, xs, options) {
+  const gpu = await elementwiseChainGpuDispatch(ops, xs, options);
+  if (gpu) return new Float64Array(gpu);
   const wasm = elementwiseChainDispatch(ops, xs);
   if (wasm) return wasm;
-  const gpu = await elementwiseChainGpuDispatch(ops, xs);
-  if (gpu) return gpu;
   return jsChain(ops, xs);
 }
 
@@ -45593,6 +45627,7 @@ export {
   reflectVector,
   replacer,
   resample,
+  resetGpuElementwise,
   reshape2 as reshape,
   residue,
   resize2 as resize,

package/dist/typed/fused.d.ts

@@ -13,6 +13,7 @@
  * array is below threshold, so the result is always correct.
  */
 import { type WasmElementwiseOp } from '../wasm/elementwise/wasm-bridge.js';
+import { type GpuChainOptions } from '../gpu/elementwise-gpu.js';
 /**
  * Apply `ops` left-to-right over `xs` (i.e. `ops[last](…ops[0](x))`), fused in
  * WASM when possible. Returns a new `Float64Array`; never mutates `xs`.
@@ -25,35 +26,61 @@ export declare function fuseUnaryChain(ops: WasmElementwiseOp[], xs: Float64Arra
  * `fuseUnaryChain`, because a GPU dispatch is inherently asynchronous and
  * `fuseUnaryChain`'s synchronous signature is public API.
  *
- * Tiers, in order: **WASM (f64) → GPU (f32) → JS (f64)**.
+ * Tiers, in order: **GPU (f32, opt-in) → WASM (f64) → JS (f64)**.
  *
- * ### Why WASM is tried BEFORE the GPU
+ * ### Why the GPU is tried first — but ONLY when explicitly enabled
  *
- * Measured in Chrome on an NVIDIA Pascal adapter, chain `sin→exp→tanh→cos`:
+ * Chain `sin→exp→tanh→cos`, 5 reps. ONE run, 2026-07-13, Chrome on an NVIDIA
+ * Pascal adapter — the same run quoted in the CHANGELOG and the reference docs, so
+ * the three tables agree. Pinned by `gpu-vs-wasm.browser.test.ts`:
  *
- * | n         | JS      | WASM    | GPU     | GPU vs WASM |
- * | --------- | ------- | ------- | ------- | ----------- |
- * | 65,536    | 90 ms   | 16 ms   | 28 ms   | **0.57×**   |
- * | 262,144   | 400 ms  | 60 ms   | 103 ms  | **0.59×**   |
- * | 1,048,576 | 1613 ms | 250 ms  | 457 ms  | **0.55×**   |
+ * | n         | JS     | WASM   | GPU        | GPU vs WASM |
+ * | --------- | ------ | ------ | ---------- | ----------- |
+ * | 65,536    | 44 ms  | 17 ms  | **5.2 ms** | **3.2×**    |
+ * | 262,144   | 185 ms | 63 ms  | **7.5 ms** | **8.3×**    |
+ * | 1,048,576 | 711 ms | 256 ms | **35 ms**  | **7.2×**    |
  *
- * **WASM is ~1.8× faster than the GPU — and it is f64-exact while the GPU is
- * f32.** For element-wise chains the GPU is therefore both slower *and* less
- * precise, so it must never pre-empt WASM. (An earlier revision had GPU first;
- * that only looked like a win because a separate bug meant WASM never loaded in
- * browsers, making the baseline pure JS.)
+ * The GPU is the fastest tier by a wide margin. It is nevertheless **last-resort
+ * by default**, because it computes in f32 while every other tier is f64-exact.
+ * `enableGpu()` is how a caller consents to that trade: precision for speed. With
+ * the flag off — the default — this function is exactly WASM → JS and returns
+ * bit-identical f64 results, so opting out costs nothing.
  *
- * The GPU still earns its place where WASM is **unavailable** — there it beats
- * the JS scalar pass ~2–2.5×. It engages only when the caller opted in via
- * `enableGpu()`, WASM declined, a device exists, the array clears
- * `GPU_MIN_ELEMENTS`, and every op has a GPU kernel.
+ * ### Provenance of these numbers (read before changing the order)
  *
- * (The GPU *does* win decisively for compute-bound work like a large matmul —
- * see `gpuMatmul`. This ordering is specific to memory-bound element-wise work.)
+ * This ordering has been wrong twice, both times from a benchmark measuring
+ * something other than what it claimed:
  *
- * **Precision:** the result is a `Float32Array` only when the GPU tier ran
- * (~7 significant digits); otherwise it is an exact-f64 `Float64Array`. The
- * return type tells you which path ran.
+ *  1. GPU-first was first adopted on a "2.3-2.9x faster than JS" result. That
+ *     baseline was pure JS only because a *separate* bug meant WASM never loaded
+ *     in browsers. Fixing WASM revealed it beat the GPU, so the order was flipped
+ *     to WASM-first.
+ *  2. That flip was also wrong. The GPU figure it rested on was inflated by
+ *     `Float32Array.from(f64array)` in the dispatch — the generic `Array.from`
+ *     path, which runs ToNumber per element. Naming the denominators, because they
+ *     differ: the *conversion* alone was 73x slower (433 ms vs 5.9 ms at n=2^20),
+ *     which made the *end-to-end dispatch* 12.2x slower (439.80 ms -> 36.06 ms).
+ *     With that fixed, the GPU wins outright, as above.
+ *
+ * The lesson both times: a tier's number is only as good as the tier it is
+ * compared against. Re-measure ALL THREE tiers in one run before touching this
+ * order — `gpu-vs-wasm.browser.test.ts` does exactly that and fails loudly if the
+ * ranking changes.
+ *
+ * (The GPU also wins decisively for compute-bound work like a large matmul — see
+ * `gpuMatmul`. It is not merely a memory-bound-work story.)
+ *
+ * **Precision.** Always returns a `Float64Array`. When the GPU tier runs, the
+ * *values* carry f32 precision (~7 significant digits) even though the container
+ * is f64 — the GPU cannot compute in f64 at all.
+ *
+ * It previously returned `Float64Array | Float32Array` to encode which path ran.
+ * That union was a footgun: `.map` / `.filter` / `.set` on it are TS2349 errors,
+ * so **every** caller had to narrow with `instanceof` before touching the result,
+ * and `new Float64Array(r.buffer)` silently produced garbage when the f32 branch
+ * hit. A narrowing tax on 100% of callers, for a branch most never take, is a bad
+ * trade. Callers who specifically want the raw f32 buffer can call
+ * `elementwiseChainGpuDispatch` directly — it is exported for exactly that.
  */
-export declare function fuseUnaryChainAsync(ops: WasmElementwiseOp[], xs: Float64Array): Promise<Float64Array | Float32Array>;
+export declare function fuseUnaryChainAsync(ops: WasmElementwiseOp[], xs: Float64Array, options?: GpuChainOptions): Promise<Float64Array>;
 //# sourceMappingURL=fused.d.ts.map

package/dist/typed/fused.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fused.d.ts","sourceRoot":"","sources":["../../src/typed/fused.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AA0B5C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAAE,YAAY,GAAG,YAAY,CAIvF;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,iBAAiB,EAAE,EACxB,EAAE,EAAE,YAAY,GACf,OAAO,CAAC,YAAY,GAAG,YAAY,CAAC,CAUtC"}
+{"version":3,"file":"fused.d.ts","sourceRoot":"","sources":["../../src/typed/fused.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAyB9F;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAAE,YAAY,GAAG,YAAY,CAIvF;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,iBAAiB,EAAE,EACxB,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,YAAY,CAAC,CAgBvB"}

package/dist/typed/index.d.ts

@@ -47,7 +47,7 @@ export * from './matrix-ops.js';
 export { cond } from './matrix-ops.js';
 export * from './gpu.js';
 export { enableGpu, disableGpu, isGpuEnabled, GPU_MIN_ELEMENTS } from '@danielsimonjr/mathts-gpu';
-export { elementwiseChainGpuDispatch, isGpuChainSupported, GPU_ELEMENTWISE_OPS, type GpuElementwiseOp, } from '../gpu/elementwise-gpu.js';
+export { elementwiseChainGpuDispatch, isGpuChainSupported, resetGpuElementwise, GPU_ELEMENTWISE_OPS, type GpuElementwiseOp, type GpuChainOptions, } from '../gpu/elementwise-gpu.js';
 export * from './relational.js';
 export { typedRelational } from './relational.js';
 export * from './string.js';

package/dist/typed/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/typed/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAK5C,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,kBAAkB,CAAC;AAGjC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,YAAY,CAAC;AAG3B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,iBAAiB,CAAC;AAWhC,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAGvC,cAAc,UAAU,CAAC;AAIzB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClG,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AAInC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsCtC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B1B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/typed/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAK5C,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,cAAc,kBAAkB,CAAC;AAGjC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,YAAY,CAAC;AAG3B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,iBAAiB,CAAC;AAWhC,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAGvC,cAAc,UAAU,CAAC;AAIzB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClG,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAInC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsCtC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-functions",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "Mathematical functions for MathTS - arithmetic, algebra, trigonometry, statistics, and more",
   "author": "Daniel Simon Jr.",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "@danielsimonjr/mathts-core": "^0.6.0",
     "@danielsimonjr/mathts-expression": "^0.6.0",
     "@danielsimonjr/mathts-gpu": "^0.1.1",
-    "@danielsimonjr/mathts-matrix": "^0.3.2",
+    "@danielsimonjr/mathts-matrix": "^0.4.0",
     "@danielsimonjr/mathts-parallel": "^0.3.4",
     "bignumber.js": "^9.1.2",
     "complex.js": "^2.2.5",