@danielsimonjr/mathts-functions 0.18.0 → 0.19.0

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

@@ -7,11 +7,18 @@
  * storage buffers, and reads back once, so the transfer is amortized across the
  * whole chain.
  *
- * **Read this before reaching for the GPU:** for element-wise work the GPU is
- * *slower* than WASM (~1.9×, measured) *and* less precise (f32 vs f64). It earns
- * its place only where WASM cannot load. `fuseUnaryChainAsync` therefore tries
- * WASM first. The GPU wins decisively on **compute-bound** work — see
- * `gpuMatmul`, where O(n³) arithmetic amortizes the O(n²) transfer.
+ * **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.
+ *
+ * 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.
  *
  * Contract (mirrors the WASM `elementwiseChainDispatch`): a **never-throw**
  * best-effort fast path. It returns `null` — never rejects — whenever the GPU is

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;;;;;;;;;;;;;;;;;;;GAmBG;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,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

@@ -7480,7 +7480,7 @@ async function elementwiseChainGpuDispatch(ops, xs, options) {
     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 = pool.acquireStorageBuffer(bytes, "chain-a", true, true);
     bufB = pool.acquireStorageBuffer(bytes, "chain-b", true, true);
@@ -7562,7 +7562,7 @@ 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]);
@@ -7570,10 +7570,10 @@ function jsChain(ops, xs) {
   return out;
 }
 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, options);
-  if (gpu) return Float64Array.from(gpu);
   return jsChain(ops, xs);
 }
 

package/dist/typed/fused.d.ts

@@ -26,31 +26,49 @@ 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:
+ *
+ *  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

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;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;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,iBAAiB,EAAE,EACxB,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,YAAY,CAAC,CAUvB"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-functions",
-  "version": "0.18.0",
+  "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",