@danielsimonjr/mathts-parallel 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { Transfer } from '@danielsimonjr/mathts-workerpool';
  *   - Special / distribution functions (`erfc`, `besselJ`, `normalCDF`)
  *   - Additional ops exposed via the typed functions layer
  */
-type OpName = 'add' | 'subtract' | 'multiply' | 'divide' | 'pow' | 'scale' | 'abs' | 'negate' | 'sqrt' | 'square' | 'exp' | 'log' | 'sin' | 'cos' | 'tan' | 'sign' | 'tensordot' | 'sum' | 'mean' | 'variance' | 'norm' | 'histogram' | 'dot' | 'distance' | 'parallelStatProd' | 'matmul' | 'outer' | 'matvec' | 'transpose' | 'matrixPower' | 'characteristicPolynomial' | 'parallelFFT' | 'parallelConv' | 'spectrogram' | 'fft2d' | 'distanceMatrix' | 'erfc' | 'besselJ' | 'normalCDF' | 'chiSquareTest' | 'kolmogorovSmirnovTest' | 'mannWhitneyTest' | 'shapiroWilkTest' | 'integrateChunk' | 'sampleChunk';
+type OpName = 'add' | 'subtract' | 'multiply' | 'divide' | 'pow' | 'scale' | 'abs' | 'negate' | 'sqrt' | 'square' | 'bitAnd' | 'bitOr' | 'bitXor' | 'bitNot' | 'leftShift' | 'rightArithShift' | 'rightLogShift' | 'exp' | 'log' | 'sin' | 'cos' | 'tan' | 'sign' | 'tensordot' | 'sum' | 'mean' | 'min' | 'max' | 'minMax' | 'variance' | 'std' | 'norm' | 'histogram' | 'dot' | 'prod' | 'distance' | 'parallelStatProd' | 'matmul' | 'outer' | 'matvec' | 'transpose' | 'matrixPower' | 'characteristicPolynomial' | 'parallelFFT' | 'parallelConv' | 'spectrogram' | 'fft2d' | 'distanceMatrix' | 'erfc' | 'besselJ' | 'normalCDF' | 'chiSquareTest' | 'kolmogorovSmirnovTest' | 'mannWhitneyTest' | 'shapiroWilkTest' | 'integrateChunk' | 'sampleChunk';
 /**
  * Per-op threshold override.  The value is the minimum element count required
  * before parallelizing the named operation.  Special string aliases:
@@ -148,6 +148,15 @@ declare class ComputePool {
      * backward-compatibility with existing callers that don't know the op name).
      */
     shouldParallelize(elementCount: number, op?: OpName): boolean;
+    /**
+     * Wrap a sequentially-computed reduction result in the `ParallelResult`
+     * envelope. Used by the reduction methods below so that ops whose threshold
+     * says "don't parallelize at this size" (notably the memory-bound reductions
+     * pinned to `'never'`) compute inline instead of paying a worker round-trip —
+     * previously every reduction dispatched to the pool unconditionally, ignoring
+     * its threshold.
+     */
+    private seqResult;
     /**
      * Execute a method in the worker pool
      */

package/dist/index.js

@@ -346,6 +346,13 @@ var DEFAULT_THRESHOLD_BY_OP = {
   cos: "never",
   tan: "never",
   sign: "never",
+  // Added 2026-07-02 (WS-2): these element-wise ops were absent from the map and
+  // silently defaulted to the 50 000 global threshold — an inconsistency with their
+  // siblings above (surfaced by parallel-pairing.md). Benchmarked (tools/benchmark/
+  // parallel/run.ts sqrt square) — memory-bound, speedup 0.12–0.65×, no persistent
+  // break-even → 'never', matching the class.
+  sqrt: "never",
+  square: "never",
   // tensor contraction: parallelize when contracted-axis volume >= 8K
   tensordot: 8192,
   // reductions: overhead dominates
@@ -354,6 +361,60 @@ var DEFAULT_THRESHOLD_BY_OP = {
   variance: "never",
   parallelStatProd: "never",
   normalCDF: "never",
+  // Added 2026-07-02 (WS-2): reductions that were absent from the map and defaulted
+  // to the global threshold; benchmarked memory-bound (0.09–1.19×, occasional noise
+  // spikes but no persistent win) → 'never'.
+  norm: "never",
+  dot: "never",
+  // Added 2026-07-02 (WS-2): `min`/`max` are now `OpName`s (added to the union) so
+  // they're tunable. Same memory-bound reduction profile as sum/mean/norm above →
+  // 'never'. Their `functions/` call sites previously dispatched to the worker pool
+  // unconditionally (no `shouldParallelize` gate), paying dispatch overhead on every
+  // call; they now respect this threshold (sequential) with a `shouldParallelize` gate.
+  min: "never",
+  max: "never",
+  // Added 2026-07-03 (WS-2, DGT sweep): the remaining memory-bound reductions that
+  // defaulted to the 50 000 global threshold and dispatched unconditionally at every
+  // `functions/` call site. Same class as sum/mean/min/max/norm/dot → 'never'. Now
+  // gated INSIDE the ComputePool reduction methods (inline sequential fallback), so
+  // ALL call sites honor the threshold without per-site edits. `std` derives from
+  // `variance`; `min`/`max` derive from `minMax`.
+  minMax: "never",
+  std: "never",
+  prod: "never",
+  distance: "never",
+  // Added 2026-07-04 (WS-2 completion): the five OpNames that were absent from
+  // this map and silently rode the untested 50 000 global default. Benchmarked
+  // (tools/benchmarks/ws2-missing-ops.mjs, medians of 9 interleaved reps):
+  // histogram 0.23-0.56x, transpose 0.01-0.28x, matvec 0.00-0.05x, outer
+  // 0.01-0.50x at every size up to 4.2M elements - memory-bound / copy-dominated,
+  // no break-even -> 'never'. Their ComputePool methods previously dispatched to
+  // the worker pool UNCONDITIONALLY (no shouldParallelize gate); they now gate
+  // with an inline sequential fallback like the reductions above.
+  histogram: "never",
+  transpose: "never",
+  matvec: "never",
+  outer: "never",
+  // integrateFanOut loses ~50-100x for cheap integrands (0.01-0.02x at 128-32768
+  // evals). The fan-out is CALLER-OPT-IN (integration.ts dispatches only when the
+  // caller passes workerCount > 1), so this entry documents the default posture;
+  // no shouldParallelize call consults it. Expensive (ms-scale) integrands are the
+  // one case where the fan-out pays off.
+  integrateChunk: "never",
+  // Added 2026-07-05 (WS-2 addendum): the bitwise family gated via a NAMELESS
+  // shouldParallelize(len) -> the untested global 50k. Benchmarked
+  // (tools/benchmarks/ws2-bitwise-ops.mjs, medians of 9 interleaved reps):
+  // bitAnd 0.07-0.15x, bitNot 0.06-0.09x, leftShift 0.04-0.07x at every size up
+  // to 4M elements - Int32Array element-wise is maximally memory-bound; the
+  // worker path loses 7-25x. All seven -> 'never'; the methods now pass their
+  // op name so these entries actually govern.
+  bitAnd: "never",
+  bitOr: "never",
+  bitXor: "never",
+  bitNot: "never",
+  leftShift: "never",
+  rightArithShift: "never",
+  rightLogShift: "never",
   // signal: overhead dominates or break-even never reached
   parallelFFT: "never",
   parallelConv: "never",
@@ -525,6 +586,17 @@ var ComputePool = class {
     }
     return this.workerPool.shouldParallelize(elementCount);
   }
+  /**
+   * Wrap a sequentially-computed reduction result in the `ParallelResult`
+   * envelope. Used by the reduction methods below so that ops whose threshold
+   * says "don't parallelize at this size" (notably the memory-bound reductions
+   * pinned to `'never'`) compute inline instead of paying a worker round-trip —
+   * previously every reduction dispatched to the pool unconditionally, ignoring
+   * its threshold.
+   */
+  seqResult(result) {
+    return { result, duration: 0, chunks: 1, parallelized: false };
+  }
   /**
    * Execute a method in the worker pool
    */
@@ -541,22 +613,35 @@ var ComputePool = class {
    * Parallel sum of array elements
    */
   async sum(data) {
-    const result = await this.workerPool.sum(data);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(data.length, "sum")) {
+      let s = 0;
+      for (let i = 0; i < data.length; i++) s += data[i];
+      return this.seqResult(s);
+    }
+    return toParallelResult(await this.workerPool.sum(data));
   }
   /**
    * Parallel product of array elements
    */
   async prod(data) {
-    const result = await this.workerPool.prod(data);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(data.length, "prod")) {
+      let p = 1;
+      for (let i = 0; i < data.length; i++) p *= data[i];
+      return this.seqResult(p);
+    }
+    return toParallelResult(await this.workerPool.prod(data));
   }
   /**
    * Parallel dot product
    */
   async dot(a, b) {
-    const result = await this.workerPool.dot(a, b);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(a.length, "dot")) {
+      if (a.length !== b.length) throw new Error("dot: vectors must have the same length");
+      let s = 0;
+      for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+      return this.seqResult(s);
+    }
+    return toParallelResult(await this.workerPool.dot(a, b));
   }
   /**
    * Parallel element-wise operation
@@ -589,6 +674,16 @@ var ComputePool = class {
    * Parallel matrix transpose
    */
   async transpose(data, rows, cols) {
+    if (!this.shouldParallelize(data.length, "transpose")) {
+      if (data.length !== rows * cols) {
+        throw new Error(`transpose: data length ${data.length} !== rows*cols (${rows * cols})`);
+      }
+      const out = new Float64Array(rows * cols);
+      for (let i = 0; i < rows; i++) {
+        for (let j = 0; j < cols; j++) out[j * rows + i] = data[i * cols + j];
+      }
+      return this.seqResult(out);
+    }
     const result = await this.workerPool.transpose(data, rows, cols);
     return toParallelResult(result);
   }
@@ -620,34 +715,89 @@ var ComputePool = class {
    * Find min and max values in parallel
    */
   async minMax(data) {
-    const result = await this.workerPool.minMax(data);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(data.length, "minMax") && !this.shouldParallelize(data.length, "min")) {
+      let min = Infinity;
+      let max = -Infinity;
+      let minIdx = -1;
+      let maxIdx = -1;
+      for (let i = 0; i < data.length; i++) {
+        if (data[i] < min) {
+          min = data[i];
+          minIdx = i;
+        }
+        if (data[i] > max) {
+          max = data[i];
+          maxIdx = i;
+        }
+      }
+      return this.seqResult({ min, max, minIdx, maxIdx });
+    }
+    return toParallelResult(await this.workerPool.minMax(data));
   }
   /**
    * Compute variance, mean, and standard deviation in parallel
    */
   async variance(data) {
-    const result = await this.workerPool.variance(data);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(data.length, "variance")) {
+      const n = data.length;
+      let mean = 0;
+      for (let i = 0; i < n; i++) mean += data[i];
+      mean = n > 0 ? mean / n : 0;
+      let acc = 0;
+      for (let i = 0; i < n; i++) acc += (data[i] - mean) ** 2;
+      const variance = n > 0 ? acc / n : 0;
+      return this.seqResult({ mean, variance, std: Math.sqrt(variance) });
+    }
+    return toParallelResult(await this.workerPool.variance(data));
   }
   /**
    * Compute norm (Euclidean length) in parallel
    */
   async norm(data) {
-    const result = await this.workerPool.norm(data);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(data.length, "norm")) {
+      let s = 0;
+      for (let i = 0; i < data.length; i++) s += data[i] * data[i];
+      return this.seqResult(Math.sqrt(s));
+    }
+    return toParallelResult(await this.workerPool.norm(data));
   }
   /**
    * Compute Euclidean distance in parallel
    */
   async distance(a, b) {
-    const result = await this.workerPool.distance(a, b);
-    return toParallelResult(result);
+    if (!this.shouldParallelize(a.length, "distance")) {
+      if (a.length !== b.length) throw new Error("distance: vectors must have the same length");
+      let s = 0;
+      for (let i = 0; i < a.length; i++) s += (a[i] - b[i]) ** 2;
+      return this.seqResult(Math.sqrt(s));
+    }
+    return toParallelResult(await this.workerPool.distance(a, b));
   }
   /**
    * Compute histogram in parallel
    */
   async histogram(data, bins, min, max) {
+    if (!this.shouldParallelize(data.length, "histogram")) {
+      let lo = min;
+      let hi = max;
+      if (lo === void 0 || hi === void 0) {
+        lo = Infinity;
+        hi = -Infinity;
+        for (let i = 0; i < data.length; i++) {
+          if (data[i] < lo) lo = data[i];
+          if (data[i] > hi) hi = data[i];
+        }
+      }
+      const counts = new Array(bins).fill(0);
+      const width = (hi - lo) / bins || 1;
+      for (let i = 0; i < data.length; i++) {
+        let b = Math.floor((data[i] - lo) / width);
+        if (b >= bins) b = bins - 1;
+        if (b < 0) b = 0;
+        counts[b]++;
+      }
+      return this.seqResult(counts);
+    }
     const result = await this.workerPool.histogram(data, bins, min, max);
     return toParallelResult(result);
   }
@@ -857,6 +1007,21 @@ var ComputePool = class {
    * Parallel matrix-vector multiplication
    */
   async matvec(matrix, rows, cols, vector) {
+    if (!this.shouldParallelize(matrix.length, "matvec")) {
+      if (matrix.length !== rows * cols) {
+        throw new Error(`matvec: matrix length ${matrix.length} !== rows*cols (${rows * cols})`);
+      }
+      if (vector.length !== cols) {
+        throw new Error(`matvec: vector length ${vector.length} !== cols (${cols})`);
+      }
+      const out = new Float64Array(rows);
+      for (let i = 0; i < rows; i++) {
+        let s = 0;
+        for (let j = 0; j < cols; j++) s += matrix[i * cols + j] * vector[j];
+        out[i] = s;
+      }
+      return this.seqResult(out);
+    }
     const result = await this.workerPool.matvec(matrix, rows, cols, vector);
     return toParallelResult(result);
   }
@@ -864,6 +1029,13 @@ var ComputePool = class {
    * Parallel outer product
    */
   async outer(a, b) {
+    if (!this.shouldParallelize(a.length * b.length, "outer")) {
+      const out = new Float64Array(a.length * b.length);
+      for (let i = 0; i < a.length; i++) {
+        for (let j = 0; j < b.length; j++) out[i * b.length + j] = a[i] * b[j];
+      }
+      return this.seqResult(out);
+    }
     const result = await this.workerPool.outer(a, b);
     return toParallelResult(result);
   }
@@ -1123,7 +1295,7 @@ var ComputePool = class {
     if (a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "bitAnd")) {
       return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitAnd"));
     }
     const start = performance.now();
@@ -1142,7 +1314,7 @@ var ComputePool = class {
     if (a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "bitOr")) {
       return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitOr"));
     }
     const start = performance.now();
@@ -1161,7 +1333,7 @@ var ComputePool = class {
     if (a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "bitXor")) {
       return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitXor"));
     }
     const start = performance.now();
@@ -1177,7 +1349,7 @@ var ComputePool = class {
    * Unary bitwise NOT on an `Int32Array`.
    */
   async bitNot(a) {
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "bitNot")) {
       return toParallelResult(await this.workerPool.bitwiseNot(a));
     }
     const start = performance.now();
@@ -1197,7 +1369,7 @@ var ComputePool = class {
     if (typeof b !== "number" && a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "leftShift")) {
       const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "leftShift") : await this.workerPool.bitwiseBinary(a, b, "leftShift");
       return toParallelResult(result2);
     }
@@ -1217,7 +1389,7 @@ var ComputePool = class {
     if (typeof b !== "number" && a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "rightArithShift")) {
       const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "rightArithShift") : await this.workerPool.bitwiseBinary(a, b, "rightArithShift");
       return toParallelResult(result2);
     }
@@ -1239,7 +1411,7 @@ var ComputePool = class {
     if (typeof b !== "number" && a.length !== b.length) {
       throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
     }
-    if (this.shouldParallelize(a.length)) {
+    if (this.shouldParallelize(a.length, "rightLogShift")) {
       const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "rightLogShift") : await this.workerPool.bitwiseBinary(a, b, "rightLogShift");
       return toParallelResult(result2);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-parallel",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "WebWorker parallelization for MathTS computations",
   "author": "Daniel Simon Jr.",
   "license": "MIT",