@danielsimonjr/mathts-parallel 0.1.1 → 0.2.0

package/dist/index.js

@@ -3,11 +3,390 @@ import {
   MathWorkerPool,
   Transfer
 } from "@danielsimonjr/mathts-workerpool";
+
+// src/strategies/chunk.ts
+var DEFAULT_CHUNK_OPTIONS = {
+  minChunkSize: 1e3,
+  maxChunks: typeof navigator !== "undefined" ? navigator.hardwareConcurrency || 4 : 4,
+  targetChunkSize: 0,
+  // 0 = auto
+  balanced: true
+};
+function calculateOptimalChunks(totalElements, options = {}) {
+  const { minChunkSize, maxChunks, targetChunkSize } = {
+    ...DEFAULT_CHUNK_OPTIONS,
+    ...options
+  };
+  if (totalElements === 0) return 0;
+  if (targetChunkSize > 0) {
+    return Math.min(maxChunks, Math.ceil(totalElements / targetChunkSize));
+  }
+  const maxPossibleChunks = Math.floor(totalElements / minChunkSize);
+  return Math.max(1, Math.min(maxChunks, maxPossibleChunks));
+}
+function chunkFloat64Array(data, options = {}) {
+  const { minChunkSize, balanced } = { ...DEFAULT_CHUNK_OPTIONS, ...options };
+  const totalElements = data.length;
+  if (totalElements === 0) {
+    return {
+      chunks: [],
+      chunkInfo: [],
+      totalElements: 0,
+      numChunks: 0
+    };
+  }
+  const numChunks = calculateOptimalChunks(totalElements, options);
+  if (numChunks <= 1) {
+    return {
+      chunks: [data],
+      chunkInfo: [
+        {
+          startIndex: 0,
+          endIndex: totalElements,
+          length: totalElements,
+          chunkIndex: 0
+        }
+      ],
+      totalElements,
+      numChunks: 1
+    };
+  }
+  const chunks = [];
+  const chunkInfo = [];
+  if (balanced) {
+    const baseChunkSize = Math.floor(totalElements / numChunks);
+    const remainder = totalElements % numChunks;
+    let currentIndex = 0;
+    for (let i = 0; i < numChunks; i++) {
+      const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
+      const endIndex = currentIndex + thisChunkSize;
+      chunks.push(data.subarray(currentIndex, endIndex));
+      chunkInfo.push({
+        startIndex: currentIndex,
+        endIndex,
+        length: thisChunkSize,
+        chunkIndex: i
+      });
+      currentIndex = endIndex;
+    }
+  } else {
+    const chunkSize = Math.max(minChunkSize, Math.ceil(totalElements / numChunks));
+    let currentIndex = 0;
+    let chunkIndex = 0;
+    while (currentIndex < totalElements) {
+      const endIndex = Math.min(currentIndex + chunkSize, totalElements);
+      const thisChunkSize = endIndex - currentIndex;
+      chunks.push(data.subarray(currentIndex, endIndex));
+      chunkInfo.push({
+        startIndex: currentIndex,
+        endIndex,
+        length: thisChunkSize,
+        chunkIndex
+      });
+      currentIndex = endIndex;
+      chunkIndex++;
+    }
+  }
+  return {
+    chunks,
+    chunkInfo,
+    totalElements,
+    numChunks: chunks.length
+  };
+}
+function chunkArray(data, options = {}) {
+  const { balanced } = { ...DEFAULT_CHUNK_OPTIONS, ...options };
+  const totalElements = data.length;
+  if (totalElements === 0) {
+    return {
+      chunks: [],
+      chunkInfo: [],
+      totalElements: 0,
+      numChunks: 0
+    };
+  }
+  const numChunks = calculateOptimalChunks(totalElements, options);
+  if (numChunks <= 1) {
+    return {
+      chunks: [data],
+      chunkInfo: [
+        {
+          startIndex: 0,
+          endIndex: totalElements,
+          length: totalElements,
+          chunkIndex: 0
+        }
+      ],
+      totalElements,
+      numChunks: 1
+    };
+  }
+  const chunks = [];
+  const chunkInfo = [];
+  if (balanced) {
+    const baseChunkSize = Math.floor(totalElements / numChunks);
+    const remainder = totalElements % numChunks;
+    let currentIndex = 0;
+    for (let i = 0; i < numChunks; i++) {
+      const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
+      const endIndex = currentIndex + thisChunkSize;
+      chunks.push(data.slice(currentIndex, endIndex));
+      chunkInfo.push({
+        startIndex: currentIndex,
+        endIndex,
+        length: thisChunkSize,
+        chunkIndex: i
+      });
+      currentIndex = endIndex;
+    }
+  } else {
+    const chunkSize = Math.ceil(totalElements / numChunks);
+    let currentIndex = 0;
+    let chunkIndex = 0;
+    while (currentIndex < totalElements) {
+      const endIndex = Math.min(currentIndex + chunkSize, totalElements);
+      const thisChunkSize = endIndex - currentIndex;
+      chunks.push(data.slice(currentIndex, endIndex));
+      chunkInfo.push({
+        startIndex: currentIndex,
+        endIndex,
+        length: thisChunkSize,
+        chunkIndex
+      });
+      currentIndex = endIndex;
+      chunkIndex++;
+    }
+  }
+  return {
+    chunks,
+    chunkInfo,
+    totalElements,
+    numChunks: chunks.length
+  };
+}
+function mergeFloat64Chunks(chunks) {
+  if (chunks.length === 0) return new Float64Array(0);
+  if (chunks.length === 1) return chunks[0];
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const result = new Float64Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+function mergeArrayChunks(chunks) {
+  if (chunks.length === 0) return [];
+  if (chunks.length === 1) return chunks[0];
+  return chunks.flat();
+}
+function shouldParallelize(elementCount, threshold = 1e4) {
+  return elementCount >= threshold;
+}
+function partitionRange(start, end, options = {}) {
+  const totalElements = end - start;
+  const numChunks = calculateOptimalChunks(totalElements, options);
+  if (numChunks <= 1) {
+    return [[start, end]];
+  }
+  const partitions = [];
+  const baseChunkSize = Math.floor(totalElements / numChunks);
+  const remainder = totalElements % numChunks;
+  let currentIndex = start;
+  for (let i = 0; i < numChunks; i++) {
+    const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
+    const endIndex = currentIndex + thisChunkSize;
+    partitions.push([currentIndex, endIndex]);
+    currentIndex = endIndex;
+  }
+  return partitions;
+}
+function partition2D(rows, cols, options = {}) {
+  const rowPartitions = partitionRange(0, rows, options);
+  return rowPartitions.map(([rowStart, rowEnd]) => [rowStart, rowEnd, 0, cols]);
+}
+
+// src/ops/bitwise.ts
+function applyBinaryChunk(a, b, out, start, length, outStart, op) {
+  const end = start + length;
+  switch (op) {
+    case "bitAnd":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] & b[i];
+      return;
+    case "bitOr":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] | b[i];
+      return;
+    case "bitXor":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] ^ b[i];
+      return;
+    case "leftShift":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] << b[i];
+      return;
+    case "rightArithShift":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] >> b[i];
+      return;
+    case "rightLogShift":
+      for (let i = start; i < end; i++) out[outStart + (i - start)] = a[i] >>> b[i];
+      return;
+  }
+}
+function runBinary(a, b, op, options = {}) {
+  if (a.length !== b.length) {
+    throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
+  }
+  const out = new Int32Array(a.length);
+  if (a.length === 0) return out;
+  const numChunks = Math.max(1, calculateOptimalChunks(a.length, options));
+  const base = Math.floor(a.length / numChunks);
+  const remainder = a.length % numChunks;
+  let start = 0;
+  for (let c = 0; c < numChunks; c++) {
+    const len = base + (c < remainder ? 1 : 0);
+    if (len === 0) continue;
+    applyBinaryChunk(a, b, out, start, len, start, op);
+    start += len;
+  }
+  return out;
+}
+function bitAnd(a, b, options) {
+  return runBinary(a, b, "bitAnd", options);
+}
+function bitOr(a, b, options) {
+  return runBinary(a, b, "bitOr", options);
+}
+function bitXor(a, b, options) {
+  return runBinary(a, b, "bitXor", options);
+}
+function leftShift(a, b, options) {
+  if (typeof b === "number") return runBinaryScalar(a, b, "leftShift", options);
+  return runBinary(a, b, "leftShift", options);
+}
+function rightArithShift(a, b, options) {
+  if (typeof b === "number") return runBinaryScalar(a, b, "rightArithShift", options);
+  return runBinary(a, b, "rightArithShift", options);
+}
+function rightLogShift(a, b, options) {
+  if (typeof b === "number") return runBinaryScalar(a, b, "rightLogShift", options);
+  return runBinary(a, b, "rightLogShift", options);
+}
+function bitNot(a, options = {}) {
+  const out = new Int32Array(a.length);
+  if (a.length === 0) return out;
+  const numChunks = Math.max(1, calculateOptimalChunks(a.length, options));
+  const base = Math.floor(a.length / numChunks);
+  const remainder = a.length % numChunks;
+  let start = 0;
+  for (let c = 0; c < numChunks; c++) {
+    const len = base + (c < remainder ? 1 : 0);
+    if (len === 0) continue;
+    const end = start + len;
+    for (let i = start; i < end; i++) out[i] = ~a[i];
+    start += len;
+  }
+  return out;
+}
+function runBinaryScalar(a, scalar, op, options = {}) {
+  const out = new Int32Array(a.length);
+  if (a.length === 0) return out;
+  const numChunks = Math.max(1, calculateOptimalChunks(a.length, options));
+  const base = Math.floor(a.length / numChunks);
+  const remainder = a.length % numChunks;
+  let start = 0;
+  for (let c = 0; c < numChunks; c++) {
+    const len = base + (c < remainder ? 1 : 0);
+    if (len === 0) continue;
+    const end = start + len;
+    switch (op) {
+      case "leftShift":
+        for (let i = start; i < end; i++) out[i] = a[i] << scalar;
+        break;
+      case "rightArithShift":
+        for (let i = start; i < end; i++) out[i] = a[i] >> scalar;
+        break;
+      case "rightLogShift":
+        for (let i = start; i < end; i++) out[i] = a[i] >>> scalar;
+        break;
+      // The non-shift ops never go through the scalar path — caller
+      // routes only the three shift ops here. Listed for exhaustiveness.
+      case "bitAnd":
+        for (let i = start; i < end; i++) out[i] = a[i] & scalar;
+        break;
+      case "bitOr":
+        for (let i = start; i < end; i++) out[i] = a[i] | scalar;
+        break;
+      case "bitXor":
+        for (let i = start; i < end; i++) out[i] = a[i] ^ scalar;
+        break;
+    }
+    start += len;
+  }
+  return out;
+}
+
+// src/ComputePool.ts
+function resolveOpThreshold(t) {
+  if (t === "never") return Number.MAX_SAFE_INTEGER;
+  if (t === "always") return 0;
+  return t;
+}
+var DEFAULT_THRESHOLD_BY_OP = {
+  // element-wise: overhead dominates at all tested sizes
+  add: "never",
+  subtract: "never",
+  multiply: "never",
+  divide: "never",
+  pow: "never",
+  scale: "never",
+  abs: "never",
+  negate: "never",
+  exp: "never",
+  log: "never",
+  sin: "never",
+  cos: "never",
+  tan: "never",
+  sign: "never",
+  // tensor contraction: parallelize when contracted-axis volume >= 8K
+  tensordot: 8192,
+  // reductions: overhead dominates
+  sum: "never",
+  mean: "never",
+  variance: "never",
+  parallelStatProd: "never",
+  normalCDF: "never",
+  // signal: overhead dominates or break-even never reached
+  parallelFFT: "never",
+  parallelConv: "never",
+  fft2d: "never",
+  // geometry: overhead dominates
+  distanceMatrix: "never",
+  // special functions: parallel wins above these sizes
+  erfc: 1e5,
+  besselJ: 1e6,
+  spectrogram: 65536,
+  // linear algebra: parallel wins above these element counts
+  matmul: 4096,
+  // break-even at 64×64 (4,096 elements)
+  matrixPower: 9216,
+  // break-even at ~96×96
+  characteristicPolynomial: 9216,
+  // break-even at ~96×96
+  // hypothesis tests: element-wise reduction (chiSquare) and post-sort
+  // dot-product (KS/MW/SW). Threshold 4096 per Slice 3.10 spec.
+  chiSquareTest: 4096,
+  kolmogorovSmirnovTest: 4096,
+  mannWhitneyTest: 4096,
+  shapiroWilkTest: 4096,
+  // distribution batch sampling: per-sample cost (rejection/transcendental) amortises
+  // worker overhead above 100 000 samples (Slice 5.12).
+  sampleChunk: 1e5
+};
 var DEFAULT_POOL_CONFIG = {
   enabled: true,
   minWorkers: 1,
   maxWorkers: typeof navigator !== "undefined" ? navigator.hardwareConcurrency || 4 : 4,
   thresholdElements: 5e4,
+  thresholdByOp: DEFAULT_THRESHOLD_BY_OP,
   chunkSize: 1e4,
   workerType: "auto",
   workerIdleTimeout: 6e4,
@@ -34,6 +413,80 @@ function toWorkerConfig(config) {
     taskTimeout: config.taskTimeout
   };
 }
+function _rowMajorStrides(shape) {
+  const strides = new Array(shape.length);
+  let stride = 1;
+  for (let i = shape.length - 1; i >= 0; i--) {
+    strides[i] = stride;
+    stride *= shape[i];
+  }
+  return strides;
+}
+function _flatIndex(idx, strides) {
+  let flat = 0;
+  for (let i = 0; i < idx.length; i++) flat += idx[i] * strides[i];
+  return flat;
+}
+function _forEachIndex(sizes, cb) {
+  const rank = sizes.length;
+  if (rank === 0) {
+    cb([]);
+    return;
+  }
+  const idx = new Array(rank).fill(0);
+  const total = sizes.reduce((a, b) => a * b, 1);
+  for (let n = 0; n < total; n++) {
+    cb(idx.slice());
+    for (let d = rank - 1; d >= 0; d--) {
+      idx[d]++;
+      if (idx[d] < sizes[d]) break;
+      idx[d] = 0;
+    }
+  }
+}
+function tensordotChunkKernel(a, aShape, b, bShape, axesA, axesB, resultShape, outStart, outEnd) {
+  const aStrides = _rowMajorStrides(aShape);
+  const bStrides = _rowMajorStrides(bShape);
+  const outStrides = _rowMajorStrides(resultShape);
+  const aRank = aShape.length;
+  const bRank = bShape.length;
+  const contractedAxesA = Array.from(axesA);
+  const contractedAxesB = Array.from(axesB);
+  const contractedSetA = new Set(contractedAxesA);
+  const contractedSetB = new Set(contractedAxesB);
+  const aFreeAxes = [];
+  const bFreeAxes = [];
+  for (let i = 0; i < aRank; i++) if (!contractedSetA.has(i)) aFreeAxes.push(i);
+  for (let i = 0; i < bRank; i++) if (!contractedSetB.has(i)) bFreeAxes.push(i);
+  const contractedSizes = contractedAxesA.map((ax) => aShape[ax]);
+  const chunkLen = outEnd - outStart;
+  const result = new Float64Array(chunkLen);
+  const outRank = resultShape.length;
+  const outIdx = new Array(outRank);
+  for (let outFlat = outStart; outFlat < outEnd; outFlat++) {
+    let rem = outFlat;
+    for (let d = 0; d < outRank; d++) {
+      outIdx[d] = Math.floor(rem / outStrides[d]);
+      rem -= outIdx[d] * outStrides[d];
+    }
+    const aFreeVals = outIdx.slice(0, aFreeAxes.length);
+    const bFreeVals = outIdx.slice(aFreeAxes.length);
+    let acc = 0;
+    _forEachIndex(contractedSizes, (contractVals) => {
+      const aIdx = new Array(aRank).fill(0);
+      for (let fi = 0; fi < aFreeAxes.length; fi++) aIdx[aFreeAxes[fi]] = aFreeVals[fi];
+      for (let ci = 0; ci < contractedAxesA.length; ci++)
+        aIdx[contractedAxesA[ci]] = contractVals[ci];
+      const bIdx = new Array(bRank).fill(0);
+      for (let fi = 0; fi < bFreeAxes.length; fi++) bIdx[bFreeAxes[fi]] = bFreeVals[fi];
+      for (let ci = 0; ci < contractedAxesB.length; ci++)
+        bIdx[contractedAxesB[ci]] = contractVals[ci];
+      acc += a[_flatIndex(aIdx, aStrides)] * b[_flatIndex(bIdx, bStrides)];
+    });
+    result[outFlat - outStart] = acc;
+  }
+  return result;
+}
 var ComputePool = class {
   workerPool;
   config;
@@ -54,9 +507,22 @@ var ComputePool = class {
     return this.workerPool.isReady();
   }
   /**
-   * Determine if operation should be parallelized
+   * Determine if operation should be parallelized.
+   *
+   * When `op` is supplied the per-op threshold map is consulted first;
+   * if the op is absent from the map the global `thresholdElements` fallback
+   * is used.  When `op` is omitted the global threshold is always used (for
+   * backward-compatibility with existing callers that don't know the op name).
    */
-  shouldParallelize(elementCount) {
+  shouldParallelize(elementCount, op) {
+    const byOp = this.config.thresholdByOp;
+    if (op !== void 0 && byOp !== void 0 && op in byOp) {
+      const raw = byOp[op];
+      if (raw !== void 0) {
+        const threshold = resolveOpThreshold(raw);
+        return this.config.enabled && elementCount >= threshold && this.workerPool.isReady();
+      }
+    }
     return this.workerPool.shouldParallelize(elementCount);
   }
   /**
@@ -78,6 +544,13 @@ var ComputePool = class {
     const result = await this.workerPool.sum(data);
     return toParallelResult(result);
   }
+  /**
+   * Parallel product of array elements
+   */
+  async prod(data) {
+    const result = await this.workerPool.prod(data);
+    return toParallelResult(result);
+  }
   /**
    * Parallel dot product
    */
@@ -188,6 +661,141 @@ var ComputePool = class {
     const result = await this.workerPool.unary(data, fn);
     return toParallelResult(result);
   }
+  /**
+   * Apply a caller-supplied unary numeric function in parallel.
+   *
+   * @param data - Input values
+   * @param fnSource - Source of a self-contained `(x: number) => number`
+   *   expression. It must not reference free variables / closures, since it
+   *   is eval'd in an isolated worker context. Used to parallelize element-wise
+   *   math (special functions, distribution PDFs/CDFs).
+   */
+  async applyKernel(data, fnSource) {
+    const result = await this.workerPool.applyKernel(data, fnSource);
+    return toParallelResult(result);
+  }
+  /**
+   * Apply a caller-supplied binary numeric function in parallel.
+   *
+   * @param a - First operand array
+   * @param b - Second operand array (must match the length of `a`)
+   * @param fnSource - Source of a self-contained `(a: number, b: number) =>
+   *   number` expression (no free variables / closures).
+   */
+  async applyKernel2(a, b, fnSource) {
+    const result = await this.workerPool.applyKernel2(a, b, fnSource);
+    return toParallelResult(result);
+  }
+  /**
+   * Fan-out Gauss-Legendre quadrature over `workerCount` sub-intervals.
+   *
+   * Partitions `[a, b]` into `workerCount` equal sub-domains and dispatches one
+   * `integrateChunk` worker task per sub-domain.  Each task evaluates the
+   * integrand (supplied as a stringified closure) with the given GL nodes and
+   * weights and returns its partial integral.  The partial sums are aggregated
+   * on the main thread.
+   *
+   * **Closure contract:** `fnSource` must be a self-contained `(x: number) =>
+   * number` expression — no free variables referencing outer scope, because it
+   * is eval'd inside an isolated worker context.  Call-site validation (via
+   * `validateClosureSource`) should have already rejected unsafe closures before
+   * reaching this method.
+   *
+   * @param fnSource    - Stringified integrand, e.g. `"(x) => Math.sin(x)"`
+   * @param a           - Lower integration bound
+   * @param b           - Upper integration bound
+   * @param workerCount - Number of sub-intervals / worker tasks
+   * @param nodes       - GL nodes on [-1, 1]
+   * @param weights     - Corresponding GL weights
+   * @returns Sum of partial integrals = approximate value of ∫ₐᵇ f(x) dx
+   */
+  async integrateFanOut(fnSource, a, b, workerCount, nodes, weights) {
+    const h = (b - a) / workerCount;
+    const tasks = [];
+    for (let k = 0; k < workerCount; k++) {
+      const subA = a + k * h;
+      const subB = a + (k + 1) * h;
+      tasks.push(
+        this.workerPool.exec("integrateChunk", [fnSource, subA, subB, nodes, weights])
+      );
+    }
+    const partials = await Promise.all(tasks);
+    return partials.reduce((acc, v) => acc + v, 0);
+  }
+  /**
+   * Fan-out distribution batch sampling across `workerCount` workers.
+   *
+   * Partitions `n` samples into `workerCount` equal chunks (last chunk absorbs
+   * the remainder) and dispatches one `sampleChunk` task per chunk. Each chunk
+   * uses an independent seed derived from `baseSeed` via SplitMix64-style
+   * hashing:
+   *
+   *   `chunkSeed = (baseSeed ^ (chunkIdx * 0x9E3779B97F4A7C15)) >>> 0`
+   *
+   * This Fibonacci-hashing multiplier gives good avalanche: even baseSeed=0
+   * produces K distinct seeds, and adjacent chunk indices produce uncorrelated
+   * sequences. See the `sampleChunk` worker kernel for the full rationale.
+   *
+   * @param distName    - One of 'normal', 'gamma', 'beta', 'studentT', 'exponential'
+   * @param params      - Distribution parameters (order matches factory functions)
+   * @param n           - Total number of samples to generate
+   * @param baseSeed    - Base seed for reproducible output
+   * @param workerCount - Number of parallel worker tasks
+   * @returns Concatenated Float64Array of `n` samples
+   */
+  async distributionSampleFanOut(distName, params, n, baseSeed, workerCount) {
+    const SPLIT_MIX_CONST = 2654435769;
+    const baseChunkSize = Math.floor(n / workerCount);
+    const tasks = [];
+    for (let k = 0; k < workerCount; k++) {
+      const chunkCount = k < workerCount - 1 ? baseChunkSize : n - baseChunkSize * (workerCount - 1);
+      const chunkSeed = (baseSeed ^ (Math.imul(k, SPLIT_MIX_CONST) | 0)) >>> 0;
+      tasks.push(
+        this.workerPool.exec("sampleChunk", [distName, params, chunkSeed, chunkCount])
+      );
+    }
+    const buffers = await Promise.all(tasks);
+    const out = new Float64Array(n);
+    let offset = 0;
+    for (const buf of buffers) {
+      const chunk = new Float64Array(buf);
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out;
+  }
+  /**
+   * Compute a batch of independent radix-2 FFTs in parallel.
+   *
+   * `real` and `imag` each hold `frameCount` concatenated frames of
+   * `frameLength` samples (`frameLength` must be a power of two). Each frame
+   * is FFT'd independently and the frames are distributed across workers.
+   *
+   * Used to parallelize the embarrassingly-parallel FFT batches in
+   * `spectrogram` (one FFT per windowed frame) and `fft2d` (rows then columns).
+   *
+   * @param real - Concatenated real parts (`frameCount * frameLength` values)
+   * @param imag - Concatenated imaginary parts (same layout as `real`)
+   * @param frameCount - Number of independent frames
+   * @param frameLength - Samples per frame (power of two)
+   * @param inverse - Compute the inverse FFT when true
+   */
+  async fftBatch(real, imag, frameCount, frameLength, inverse = false) {
+    const result = await this.workerPool.fftBatch(real, imag, frameCount, frameLength, inverse);
+    return toParallelResult(result);
+  }
+  /**
+   * Compute an all-pairs Euclidean distance matrix in parallel.
+   *
+   * @param points - Flattened `n * dim` coordinate array (row-major)
+   * @param n - Number of points
+   * @param dim - Coordinate dimension
+   * @returns Flat row-major `n * n` distance matrix
+   */
+  async distanceMatrix(points, n, dim) {
+    const result = await this.workerPool.distanceMatrix(points, n, dim);
+    return toParallelResult(result);
+  }
   /**
    * Parallel absolute value
    */
@@ -298,49 +906,350 @@ var ComputePool = class {
     return this.elementwise(a, b, "multiply");
   }
   /**
-   * Parallel element-wise division
+   * Parallel element-wise division
+   */
+  async divide(a, b) {
+    return this.elementwise(a, b, "divide");
+  }
+  /**
+   * Parallel element-wise exponentiation.
+   *
+   * `out[i] = a[i] ** b[i]`
+   *
+   * Delegates to `applyKernel2` with the `Math.pow` kernel. The default
+   * per-op threshold for `pow` is `'never'` (overhead dominates); the
+   * sequential path is taken unless the caller overrides `thresholdByOp.pow`.
+   */
+  async pow(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
+    }
+    if (this.shouldParallelize(a.length, "pow")) {
+      return this.applyKernel2(a, b, "(a, b) => Math.pow(a, b)");
+    }
+    const start = performance.now();
+    const result = new Float64Array(a.length);
+    for (let i = 0; i < a.length; i++) {
+      result[i] = a[i] ** b[i];
+    }
+    return {
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
+  }
+  /**
+   * Parallel element-wise sign function.
+   *
+   * `out[i] = Math.sign(data[i])`  →  -1 | 0 | 1, with NaN → NaN (IEEE 754).
+   *
+   * Delegates to `applyKernel` with the `Math.sign` kernel. The default
+   * per-op threshold for `sign` is `'never'` (overhead dominates); the
+   * sequential path is taken unless the caller overrides `thresholdByOp.sign`.
+   */
+  async sign(data) {
+    if (this.shouldParallelize(data.length, "sign")) {
+      return this.applyKernel(data, "(x) => Math.sign(x)");
+    }
+    const start = performance.now();
+    const result = new Float64Array(data.length);
+    for (let i = 0; i < data.length; i++) {
+      result[i] = Math.sign(data[i]);
+    }
+    return {
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
+  }
+  /**
+   * General tensor contraction (tensordot) over specified axis pairs.
+   *
+   * Contracts axis `axesA[i]` of `a` with axis `axesB[i]` of `b` for each
+   * pair index `i`. The result shape is the non-contracted axes of `a` followed
+   * by the non-contracted axes of `b` (NumPy convention).
+   *
+   * Parallelization threshold: contracted-axis volume (product of contracted
+   * dimensions) >= 8 192. When parallelized, output elements are distributed
+   * in contiguous slices across workers via the `tensordotChunk` kernel.
+   *
+   * @param a      - Flat row-major Float64Array for tensor A
+   * @param aShape - Shape of tensor A
+   * @param b      - Flat row-major Float64Array for tensor B
+   * @param bShape - Shape of tensor B
+   * @param axesA  - Axes of A to contract (same length as axesB)
+   * @param axesB  - Axes of B to contract (same length as axesA)
+   * @returns `{ data: Float64Array; shape: number[] }` — flat result + result shape
+   */
+  async tensordot(a, aShape, b, bShape, axesA, axesB) {
+    if (axesA.length !== axesB.length) {
+      throw new Error(
+        `tensordot: axesA.length (${axesA.length}) !== axesB.length (${axesB.length})`
+      );
+    }
+    const aRank = aShape.length;
+    const bRank = bShape.length;
+    const aContracted = /* @__PURE__ */ new Set();
+    const bContracted = /* @__PURE__ */ new Set();
+    for (let i = 0; i < axesA.length; i++) {
+      const ax = axesA[i];
+      const bx = axesB[i];
+      if (!Number.isInteger(ax) || ax < 0 || ax >= aRank) {
+        throw new Error(`tensordot: axesA[${i}]=${ax} is out of range for aShape (rank ${aRank})`);
+      }
+      if (!Number.isInteger(bx) || bx < 0 || bx >= bRank) {
+        throw new Error(`tensordot: axesB[${i}]=${bx} is out of range for bShape (rank ${bRank})`);
+      }
+      if (aShape[ax] !== bShape[bx]) {
+        throw new Error(
+          `tensordot: dimension mismatch on contracted axes: aShape[${ax}]=${aShape[ax]} vs bShape[${bx}]=${bShape[bx]}`
+        );
+      }
+      aContracted.add(ax);
+      bContracted.add(bx);
+    }
+    const resultShape = [];
+    for (let i = 0; i < aRank; i++) {
+      if (!aContracted.has(i)) resultShape.push(aShape[i]);
+    }
+    for (let i = 0; i < bRank; i++) {
+      if (!bContracted.has(i)) resultShape.push(bShape[i]);
+    }
+    const resultSize = resultShape.reduce((acc, d) => acc * d, 1);
+    const contractedVolume = Array.from(axesA).reduce((acc, ax) => acc * aShape[ax], 1);
+    const start = performance.now();
+    if (this.shouldParallelize(contractedVolume, "tensordot") && resultSize > 0) {
+      const chunkSize = this.config.chunkSize;
+      const chunks = [];
+      for (let i = 0; i < resultSize; i += chunkSize) {
+        chunks.push([i, Math.min(i + chunkSize, resultSize)]);
+      }
+      const aShapeArr = Array.from(aShape);
+      const bShapeArr = Array.from(bShape);
+      const axesAArr = Array.from(axesA);
+      const axesBArr = Array.from(axesB);
+      const chunkResults = await Promise.all(
+        chunks.map(
+          ([outStart, outEnd]) => this.workerPool.exec("tensordotChunk", [
+            a.buffer,
+            aShapeArr,
+            b.buffer,
+            bShapeArr,
+            axesAArr,
+            axesBArr,
+            resultShape,
+            outStart,
+            outEnd
+          ])
+        )
+      );
+      const data2 = new Float64Array(resultSize);
+      let offset = 0;
+      for (const buf of chunkResults) {
+        const chunk = new Float64Array(buf);
+        data2.set(chunk, offset);
+        offset += chunk.length;
+      }
+      return {
+        result: { data: data2, shape: resultShape },
+        duration: performance.now() - start,
+        chunks: chunks.length,
+        parallelized: true
+      };
+    }
+    const data = resultSize === 0 ? new Float64Array(0) : tensordotChunkKernel(a, aShape, b, bShape, axesA, axesB, resultShape, 0, resultSize);
+    return {
+      result: { data, shape: resultShape },
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
+  }
+  /**
+   * Compute mean in parallel (uses variance internally)
+   */
+  async mean(data) {
+    const result = await this.variance(data);
+    return {
+      ...result,
+      result: result.result.mean
+    };
+  }
+  /**
+   * Compute standard deviation in parallel
+   */
+  async std(data) {
+    const result = await this.variance(data);
+    return {
+      ...result,
+      result: result.result.std
+    };
+  }
+  /**
+   * Find minimum value in parallel
+   */
+  async min(data) {
+    const result = await this.minMax(data);
+    return {
+      ...result,
+      result: result.result.min
+    };
+  }
+  /**
+   * Find maximum value in parallel
+   */
+  async max(data) {
+    const result = await this.minMax(data);
+    return {
+      ...result,
+      result: result.result.max
+    };
+  }
+  // =========================================================================
+  // Bitwise Operations (Int32Array)
+  // =========================================================================
+  //
+  // Above the elementwise threshold these dispatch to the `Int32Array`-keyed
+  // worker kernels in `@danielsimonjr/mathts-workerpool` (`bitwiseChunk`,
+  // `bitwiseScalarChunk`, `bitwiseNotChunk`). Below threshold they fall back
+  // to the pure in-process drivers in `./ops/bitwise.ts`. The fallback path
+  // uses those drivers verbatim so the algorithm lives in one place.
+  /**
+   * Element-wise bitwise AND on two `Int32Array`s.
+   */
+  async bitAnd(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
+    }
+    if (this.shouldParallelize(a.length)) {
+      return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitAnd"));
+    }
+    const start = performance.now();
+    const result = bitAnd(a, b);
+    return {
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
+  }
+  /**
+   * Element-wise bitwise OR on two `Int32Array`s.
+   */
+  async bitOr(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
+    }
+    if (this.shouldParallelize(a.length)) {
+      return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitOr"));
+    }
+    const start = performance.now();
+    const result = bitOr(a, b);
+    return {
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
+  }
+  /**
+   * Element-wise bitwise XOR on two `Int32Array`s.
    */
-  async divide(a, b) {
-    return this.elementwise(a, b, "divide");
+  async bitXor(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`Array lengths must match: ${a.length} vs ${b.length}`);
+    }
+    if (this.shouldParallelize(a.length)) {
+      return toParallelResult(await this.workerPool.bitwiseBinary(a, b, "bitXor"));
+    }
+    const start = performance.now();
+    const result = bitXor(a, b);
+    return {
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
+    };
   }
   /**
-   * Compute mean in parallel (uses variance internally)
+   * Unary bitwise NOT on an `Int32Array`.
    */
-  async mean(data) {
-    const result = await this.variance(data);
+  async bitNot(a) {
+    if (this.shouldParallelize(a.length)) {
+      return toParallelResult(await this.workerPool.bitwiseNot(a));
+    }
+    const start = performance.now();
+    const result = bitNot(a);
     return {
-      ...result,
-      result: result.result.mean
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
     };
   }
   /**
-   * Compute standard deviation in parallel
+   * Element-wise left shift. `b` may be a per-element `Int32Array` of
+   * shift counts or a single scalar `number` applied uniformly.
    */
-  async std(data) {
-    const result = await this.variance(data);
+  async leftShift(a, b) {
+    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)) {
+      const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "leftShift") : await this.workerPool.bitwiseBinary(a, b, "leftShift");
+      return toParallelResult(result2);
+    }
+    const start = performance.now();
+    const result = leftShift(a, b);
     return {
-      ...result,
-      result: result.result.std
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
     };
   }
   /**
-   * Find minimum value in parallel
+   * Element-wise arithmetic (sign-preserving) right shift.
    */
-  async min(data) {
-    const result = await this.minMax(data);
+  async rightArithShift(a, b) {
+    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)) {
+      const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "rightArithShift") : await this.workerPool.bitwiseBinary(a, b, "rightArithShift");
+      return toParallelResult(result2);
+    }
+    const start = performance.now();
+    const result = rightArithShift(a, b);
     return {
-      ...result,
-      result: result.result.min
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
     };
   }
   /**
-   * Find maximum value in parallel
+   * Element-wise logical (zero-filling) right shift. Results are stored
+   * as `Int32Array`, so values ≥ 2^31 wrap into the negative range —
+   * matching `(x >>> n) | 0` JavaScript semantics.
    */
-  async max(data) {
-    const result = await this.minMax(data);
+  async rightLogShift(a, b) {
+    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)) {
+      const result2 = typeof b === "number" ? await this.workerPool.bitwiseScalar(a, b, "rightLogShift") : await this.workerPool.bitwiseBinary(a, b, "rightLogShift");
+      return toParallelResult(result2);
+    }
+    const start = performance.now();
+    const result = rightLogShift(a, b);
     return {
-      ...result,
-      result: result.result.max
+      result,
+      duration: performance.now() - start,
+      chunks: 1,
+      parallelized: false
     };
   }
   /**
@@ -362,6 +1271,13 @@ var ComputePool = class {
   getConfig() {
     return { ...this.config };
   }
+  /**
+   * Maximum number of workers configured for this pool.
+   * Used by distribution sampling fan-out to determine chunk count.
+   */
+  get workerCount() {
+    return this.config.maxWorkers;
+  }
   /**
    * Get the underlying MathWorkerPool for advanced operations
    */
@@ -566,209 +1482,6 @@ async function parallelCount(data, predicate, options = {}) {
   };
 }
 
-// src/strategies/chunk.ts
-var DEFAULT_CHUNK_OPTIONS = {
-  minChunkSize: 1e3,
-  maxChunks: typeof navigator !== "undefined" ? navigator.hardwareConcurrency || 4 : 4,
-  targetChunkSize: 0,
-  // 0 = auto
-  balanced: true
-};
-function calculateOptimalChunks(totalElements, options = {}) {
-  const { minChunkSize, maxChunks, targetChunkSize } = {
-    ...DEFAULT_CHUNK_OPTIONS,
-    ...options
-  };
-  if (totalElements === 0) return 0;
-  if (targetChunkSize > 0) {
-    return Math.min(maxChunks, Math.ceil(totalElements / targetChunkSize));
-  }
-  const maxPossibleChunks = Math.floor(totalElements / minChunkSize);
-  return Math.max(1, Math.min(maxChunks, maxPossibleChunks));
-}
-function chunkFloat64Array(data, options = {}) {
-  const { minChunkSize, balanced } = { ...DEFAULT_CHUNK_OPTIONS, ...options };
-  const totalElements = data.length;
-  if (totalElements === 0) {
-    return {
-      chunks: [],
-      chunkInfo: [],
-      totalElements: 0,
-      numChunks: 0
-    };
-  }
-  const numChunks = calculateOptimalChunks(totalElements, options);
-  if (numChunks <= 1) {
-    return {
-      chunks: [data],
-      chunkInfo: [
-        {
-          startIndex: 0,
-          endIndex: totalElements,
-          length: totalElements,
-          chunkIndex: 0
-        }
-      ],
-      totalElements,
-      numChunks: 1
-    };
-  }
-  const chunks = [];
-  const chunkInfo = [];
-  if (balanced) {
-    const baseChunkSize = Math.floor(totalElements / numChunks);
-    const remainder = totalElements % numChunks;
-    let currentIndex = 0;
-    for (let i = 0; i < numChunks; i++) {
-      const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
-      const endIndex = currentIndex + thisChunkSize;
-      chunks.push(data.subarray(currentIndex, endIndex));
-      chunkInfo.push({
-        startIndex: currentIndex,
-        endIndex,
-        length: thisChunkSize,
-        chunkIndex: i
-      });
-      currentIndex = endIndex;
-    }
-  } else {
-    const chunkSize = Math.max(minChunkSize, Math.ceil(totalElements / numChunks));
-    let currentIndex = 0;
-    let chunkIndex = 0;
-    while (currentIndex < totalElements) {
-      const endIndex = Math.min(currentIndex + chunkSize, totalElements);
-      const thisChunkSize = endIndex - currentIndex;
-      chunks.push(data.subarray(currentIndex, endIndex));
-      chunkInfo.push({
-        startIndex: currentIndex,
-        endIndex,
-        length: thisChunkSize,
-        chunkIndex
-      });
-      currentIndex = endIndex;
-      chunkIndex++;
-    }
-  }
-  return {
-    chunks,
-    chunkInfo,
-    totalElements,
-    numChunks: chunks.length
-  };
-}
-function chunkArray(data, options = {}) {
-  const { balanced } = { ...DEFAULT_CHUNK_OPTIONS, ...options };
-  const totalElements = data.length;
-  if (totalElements === 0) {
-    return {
-      chunks: [],
-      chunkInfo: [],
-      totalElements: 0,
-      numChunks: 0
-    };
-  }
-  const numChunks = calculateOptimalChunks(totalElements, options);
-  if (numChunks <= 1) {
-    return {
-      chunks: [data],
-      chunkInfo: [
-        {
-          startIndex: 0,
-          endIndex: totalElements,
-          length: totalElements,
-          chunkIndex: 0
-        }
-      ],
-      totalElements,
-      numChunks: 1
-    };
-  }
-  const chunks = [];
-  const chunkInfo = [];
-  if (balanced) {
-    const baseChunkSize = Math.floor(totalElements / numChunks);
-    const remainder = totalElements % numChunks;
-    let currentIndex = 0;
-    for (let i = 0; i < numChunks; i++) {
-      const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
-      const endIndex = currentIndex + thisChunkSize;
-      chunks.push(data.slice(currentIndex, endIndex));
-      chunkInfo.push({
-        startIndex: currentIndex,
-        endIndex,
-        length: thisChunkSize,
-        chunkIndex: i
-      });
-      currentIndex = endIndex;
-    }
-  } else {
-    const chunkSize = Math.ceil(totalElements / numChunks);
-    let currentIndex = 0;
-    let chunkIndex = 0;
-    while (currentIndex < totalElements) {
-      const endIndex = Math.min(currentIndex + chunkSize, totalElements);
-      const thisChunkSize = endIndex - currentIndex;
-      chunks.push(data.slice(currentIndex, endIndex));
-      chunkInfo.push({
-        startIndex: currentIndex,
-        endIndex,
-        length: thisChunkSize,
-        chunkIndex
-      });
-      currentIndex = endIndex;
-      chunkIndex++;
-    }
-  }
-  return {
-    chunks,
-    chunkInfo,
-    totalElements,
-    numChunks: chunks.length
-  };
-}
-function mergeFloat64Chunks(chunks) {
-  if (chunks.length === 0) return new Float64Array(0);
-  if (chunks.length === 1) return chunks[0];
-  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  const result = new Float64Array(totalLength);
-  let offset = 0;
-  for (const chunk of chunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return result;
-}
-function mergeArrayChunks(chunks) {
-  if (chunks.length === 0) return [];
-  if (chunks.length === 1) return chunks[0];
-  return chunks.flat();
-}
-function shouldParallelize(elementCount, threshold = 1e4) {
-  return elementCount >= threshold;
-}
-function partitionRange(start, end, options = {}) {
-  const totalElements = end - start;
-  const numChunks = calculateOptimalChunks(totalElements, options);
-  if (numChunks <= 1) {
-    return [[start, end]];
-  }
-  const partitions = [];
-  const baseChunkSize = Math.floor(totalElements / numChunks);
-  const remainder = totalElements % numChunks;
-  let currentIndex = start;
-  for (let i = 0; i < numChunks; i++) {
-    const thisChunkSize = baseChunkSize + (i < remainder ? 1 : 0);
-    const endIndex = currentIndex + thisChunkSize;
-    partitions.push([currentIndex, endIndex]);
-    currentIndex = endIndex;
-  }
-  return partitions;
-}
-function partition2D(rows, cols, options = {}) {
-  const rowPartitions = partitionRange(0, rows, options);
-  return rowPartitions.map(([rowStart, rowEnd]) => [rowStart, rowEnd, 0, cols]);
-}
-
 // src/strategies/threshold.ts
 var DEFAULT_THRESHOLDS = {
   matmul: 1e4,
@@ -897,12 +1610,17 @@ export {
   DEFAULT_THRESHOLDS,
   ThresholdDispatcher,
   Transfer,
+  bitAnd,
+  bitNot,
+  bitOr,
+  bitXor,
   calculateChunks,
   calculateOptimalChunks,
   chunkArray,
   chunkFloat64Array,
   computePool,
   dispatch,
+  leftShift,
   mergeArrayChunks,
   mergeFloat64Chunks,
   parallelAbs,
@@ -947,6 +1665,9 @@ export {
   parallelVariance,
   partition2D,
   partitionRange,
+  resolveOpThreshold,
+  rightArithShift,
+  rightLogShift,
   shouldParallelize as shouldChunkParallelize,
   shouldParallelize2 as shouldParallelize,
   thresholdDispatcher