@danielsimonjr/mathts-parallel 0.2.2 → 0.3.1

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' | '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:
@@ -72,6 +72,22 @@ interface ComputePoolConfig {
     /** Default task timeout in milliseconds */
     taskTimeout: number;
 }
+/**
+ * Default per-op thresholds derived from benchmark data (tools/benchmark/parallel/run.ts,
+ * 2026-05-23).  Values measured on a noisy CI container — re-run on target hardware to retune.
+ *
+ *  'never'  → Number.MAX_SAFE_INTEGER  (benchmark showed no reliable speedup)
+ *  'always' → 0                        (always parallelize when pool is ready)
+ *  number   → minimum element count before dispatching to workers
+ */
+/**
+ * Canonical, benchmark-tuned per-op parallelization thresholds. This is the
+ * single source of truth consulted by `ComputePool.shouldParallelize` — the
+ * authority the typed functions actually dispatch through. The coarser
+ * category-level {@link ThresholdDispatcher} derives its overlapping values
+ * (e.g. matmul) from here so the two cannot silently diverge.
+ */
+declare const DEFAULT_THRESHOLD_BY_OP: Partial<Record<OpName, OpThreshold>>;
 /**
  * Default ComputePool configuration
  */
@@ -132,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
      */
@@ -1179,11 +1204,14 @@ interface ThresholdConfig {
     general: number;
 }
 /**
- * Default thresholds optimized for typical hardware
+ * Default category-level thresholds.
  *
- * These thresholds account for worker creation overhead vs computation benefit.
- * Smaller thresholds for compute-intensive operations (matmul, decomposition).
- * Larger thresholds for memory-bound operations (elementwise, reduce).
+ * NOTE: `ComputePool.shouldParallelize` (op-level, {@link DEFAULT_THRESHOLD_BY_OP})
+ * is the authority the typed functions dispatch through. This category map is a
+ * coarser helper; where a category overlaps a tuned op (matmul) its value is
+ * derived from the canonical const so the two cannot diverge. The remaining
+ * categories (no single ComputePool op equivalent — many are 'never') keep
+ * heuristic defaults for compute-vs-memory-bound work.
  */
 declare const DEFAULT_THRESHOLDS: ThresholdConfig;
 /**
@@ -1283,4 +1311,4 @@ interface PoolStats {
     activeTasks: number;
 }
 
-export { type BitwiseBinaryOp, type ChunkInfo, type ChunkOptions, type ChunkResult, ComputePool, type ComputePoolConfig, DEFAULT_POOL_CONFIG, DEFAULT_THRESHOLDS, type DispatchResult, type ElementwiseOptions, type ExecOptions, type ExecutionMode, type MapOptions, type MatmulOptions, type OpName, type OpThreshold, type OperationCategory, type ParallelResult, type PoolOptions, type PoolStats, type ReduceOptions, type ThresholdConfig, ThresholdDispatcher, bitAnd, bitNot, bitOr, bitXor, calculateChunks, calculateOptimalChunks, chunkArray, chunkFloat64Array, computePool, dispatch, leftShift, mergeArrayChunks, mergeFloat64Chunks, parallelAbs, parallelAdd, parallelCos, parallelCount, parallelDistance, parallelDivide, parallelDot, parallelElementwise, parallelEvery, parallelExp, parallelFilter, parallelFind, parallelForEach, parallelHistogram, parallelLog, parallelMap, parallelMatmul, parallelMatvec, parallelMax, parallelMean, parallelMin, parallelMinMax, parallelMultiply, parallelNegate, parallelNorm, parallelOuter, parallelReduce, parallelScale, parallelSin, parallelSome, parallelSort, parallelSqrt, parallelSquare, parallelStd, parallelSubtract, parallelSum, parallelTan, parallelTranspose, parallelUnary, parallelVariance, partition2D, partitionRange, resolveOpThreshold, rightArithShift, rightLogShift, shouldParallelize$1 as shouldChunkParallelize, shouldParallelize, thresholdDispatcher };
+export { type BitwiseBinaryOp, type ChunkInfo, type ChunkOptions, type ChunkResult, ComputePool, type ComputePoolConfig, DEFAULT_POOL_CONFIG, DEFAULT_THRESHOLDS, DEFAULT_THRESHOLD_BY_OP, type DispatchResult, type ElementwiseOptions, type ExecOptions, type ExecutionMode, type MapOptions, type MatmulOptions, type OpName, type OpThreshold, type OperationCategory, type ParallelResult, type PoolOptions, type PoolStats, type ReduceOptions, type ThresholdConfig, ThresholdDispatcher, bitAnd, bitNot, bitOr, bitXor, calculateChunks, calculateOptimalChunks, chunkArray, chunkFloat64Array, computePool, dispatch, leftShift, mergeArrayChunks, mergeFloat64Chunks, parallelAbs, parallelAdd, parallelCos, parallelCount, parallelDistance, parallelDivide, parallelDot, parallelElementwise, parallelEvery, parallelExp, parallelFilter, parallelFind, parallelForEach, parallelHistogram, parallelLog, parallelMap, parallelMatmul, parallelMatvec, parallelMax, parallelMean, parallelMin, parallelMinMax, parallelMultiply, parallelNegate, parallelNorm, parallelOuter, parallelReduce, parallelScale, parallelSin, parallelSome, parallelSort, parallelSqrt, parallelSquare, parallelStd, parallelSubtract, parallelSum, parallelTan, parallelTranspose, parallelUnary, parallelVariance, partition2D, partitionRange, resolveOpThreshold, rightArithShift, rightLogShift, shouldParallelize$1 as shouldChunkParallelize, shouldParallelize, thresholdDispatcher };

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,46 @@ 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",
   // signal: overhead dominates or break-even never reached
   parallelFFT: "never",
   parallelConv: "never",
@@ -525,6 +572,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 +599,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 +660,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 +701,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 +993,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 +1015,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);
   }
@@ -1483,11 +1641,15 @@ async function parallelCount(data, predicate, options = {}) {
 }
 
 // src/strategies/threshold.ts
+function opThreshold(op, fallback) {
+  const raw = DEFAULT_THRESHOLD_BY_OP[op];
+  return typeof raw === "number" ? raw : fallback;
+}
 var DEFAULT_THRESHOLDS = {
-  matmul: 1e4,
-  // ~100x100 matrix
+  matmul: opThreshold("matmul", 4096),
+  // canonical: DEFAULT_THRESHOLD_BY_OP.matmul
   elementwise: 5e4,
-  // ~50K elements
+  // ~50K elements (memory-bound; ComputePool ops mostly 'never')
   reduce: 1e5,
   // ~100K elements
   map: 1e4,
@@ -1495,7 +1657,7 @@ var DEFAULT_THRESHOLDS = {
   sort: 5e3,
   // ~5K elements
   decomposition: 2500,
-  // ~50x50 matrix
+  // ~50x50 matrix (no single canonical op; heuristic)
   general: 5e4
   // Default ~50K
 };
@@ -1608,6 +1770,7 @@ export {
   ComputePool,
   DEFAULT_POOL_CONFIG,
   DEFAULT_THRESHOLDS,
+  DEFAULT_THRESHOLD_BY_OP,
   ThresholdDispatcher,
   Transfer,
   bitAnd,

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "@danielsimonjr/mathts-parallel",
-  "version": "0.2.2",
-  "description": "WebWorker parallelization for MathTS computations",
-  "author": "Daniel Simon Jr.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "clean": "rm -rf dist",
-    "build:prod": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean --minify --treeshake"
-  },
-  "dependencies": {
-    "@danielsimonjr/mathts-workerpool": "^0.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/danielsimonjr/mathts",
-    "directory": "parallel"
-  },
-  "keywords": [
-    "math",
-    "typescript",
-    "parallel",
-    "webworker",
-    "worker-pool"
-  ]
-}
+{
+  "name": "@danielsimonjr/mathts-parallel",
+  "version": "0.3.1",
+  "description": "WebWorker parallelization for MathTS computations",
+  "author": "Daniel Simon Jr.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "build:prod": "tsup src/index.ts src/matrix.worker.ts --format esm --dts --clean --minify --treeshake"
+  },
+  "dependencies": {
+    "@danielsimonjr/mathts-workerpool": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/mathts",
+    "directory": "parallel"
+  },
+  "keywords": [
+    "math",
+    "typescript",
+    "parallel",
+    "webworker",
+    "worker-pool"
+  ]
+}