@danielsimonjr/mathts-parallel 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -10,6 +10,34 @@ export { Transfer } from '@danielsimonjr/mathts-workerpool';
  * @packageDocumentation
  */
 
+/**
+ * Recognised kernel / operation names.
+ *
+ * These are the string identifiers passed to `shouldParallelize(length, op)` so
+ * the per-op threshold map can be consulted before falling back to the global
+ * `thresholdElements`.  The list covers:
+ *   - Element-wise float ops dispatched through `ComputePool.unary/elementwise/scale`
+ *   - Reduction ops (`sum`, `mean`, `variance`, etc.)
+ *   - Linear-algebra ops (`matmul`, `matrixPower`, `characteristicPolynomial`)
+ *   - Signal-processing ops (`parallelFFT`, `parallelConv`, `spectrogram`, `fft2d`)
+ *   - Geometry ops (`distanceMatrix`)
+ *   - 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';
+/**
+ * Per-op threshold override.  The value is the minimum element count required
+ * before parallelizing the named operation.  Special string aliases:
+ *
+ *  - `'never'`  → `Number.MAX_SAFE_INTEGER` (never parallelize)
+ *  - `'always'` → `0`                       (always parallelize when pool is ready)
+ */
+type OpThreshold = number | 'never' | 'always';
+/**
+ * Resolve an `OpThreshold` alias to its numeric equivalent.
+ * @internal
+ */
+declare function resolveOpThreshold(t: OpThreshold): number;
 /**
  * Configuration for ComputePool
  * Extends the base WorkerPoolConfig with MathTS-specific options
@@ -21,8 +49,20 @@ interface ComputePoolConfig {
     minWorkers: number;
     /** Maximum number of workers */
     maxWorkers: number;
-    /** Minimum elements before parallelizing */
+    /**
+     * Global minimum element count before parallelizing.
+     * Acts as the fallback for ops not listed in `thresholdByOp`.
+     */
     thresholdElements: number;
+    /**
+     * Per-operation parallelization thresholds.
+     *
+     * Values measured on a noisy CI container (2026-05-23) — re-run on target
+     * hardware to retune.  Source: tools/benchmark/parallel/run.ts
+     *
+     * Ops absent from this map fall back to `thresholdElements`.
+     */
+    thresholdByOp?: Partial<Record<OpName, OpThreshold>>;
     /** Elements per chunk for parallel operations */
     chunkSize: number;
     /** Worker type: 'auto' | 'web' | 'thread' */
@@ -84,9 +124,14 @@ declare class ComputePool {
      */
     isReady(): boolean;
     /**
-     * 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: number): boolean;
+    shouldParallelize(elementCount: number, op?: OpName): boolean;
     /**
      * Execute a method in the worker pool
      */
@@ -99,6 +144,10 @@ declare class ComputePool {
      * Parallel sum of array elements
      */
     sum(data: Float64Array): Promise<ParallelResult<number>>;
+    /**
+     * Parallel product of array elements
+     */
+    prod(data: Float64Array): Promise<ParallelResult<number>>;
     /**
      * Parallel dot product
      */
@@ -170,6 +219,100 @@ declare class ComputePool {
      * Apply unary function in parallel
      */
     unary(data: Float64Array, fn: 'abs' | 'sqrt' | 'exp' | 'log' | 'sin' | 'cos' | 'tan' | 'negate' | 'square'): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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).
+     */
+    applyKernel(data: Float64Array, fnSource: string): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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).
+     */
+    applyKernel2(a: Float64Array, b: Float64Array, fnSource: string): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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
+     */
+    integrateFanOut(fnSource: string, a: number, b: number, workerCount: number, nodes: number[], weights: number[]): Promise<number>;
+    /**
+     * 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
+     */
+    distributionSampleFanOut(distName: string, params: number[], n: number, baseSeed: number, workerCount: number): Promise<Float64Array>;
+    /**
+     * 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
+     */
+    fftBatch(real: Float64Array, imag: Float64Array, frameCount: number, frameLength: number, inverse?: boolean): Promise<ParallelResult<{
+        real: Float64Array;
+        imag: Float64Array;
+    }>>;
+    /**
+     * 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
+     */
+    distanceMatrix(points: Float64Array, n: number, dim: number): Promise<ParallelResult<Float64Array>>;
     /**
      * Parallel absolute value
      */
@@ -242,6 +385,49 @@ declare class ComputePool {
      * Parallel element-wise division
      */
     divide(a: Float64Array, b: Float64Array): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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`.
+     */
+    pow(a: Float64Array, b: Float64Array): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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`.
+     */
+    sign(data: Float64Array): Promise<ParallelResult<Float64Array>>;
+    /**
+     * 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
+     */
+    tensordot(a: Float64Array, aShape: readonly number[], b: Float64Array, bShape: readonly number[], axesA: readonly number[], axesB: readonly number[]): Promise<ParallelResult<{
+        data: Float64Array;
+        shape: number[];
+    }>>;
     /**
      * Compute mean in parallel (uses variance internally)
      */
@@ -258,6 +444,37 @@ declare class ComputePool {
      * Find maximum value in parallel
      */
     max(data: Float64Array): Promise<ParallelResult<number>>;
+    /**
+     * Element-wise bitwise AND on two `Int32Array`s.
+     */
+    bitAnd(a: Int32Array, b: Int32Array): Promise<ParallelResult<Int32Array>>;
+    /**
+     * Element-wise bitwise OR on two `Int32Array`s.
+     */
+    bitOr(a: Int32Array, b: Int32Array): Promise<ParallelResult<Int32Array>>;
+    /**
+     * Element-wise bitwise XOR on two `Int32Array`s.
+     */
+    bitXor(a: Int32Array, b: Int32Array): Promise<ParallelResult<Int32Array>>;
+    /**
+     * Unary bitwise NOT on an `Int32Array`.
+     */
+    bitNot(a: Int32Array): Promise<ParallelResult<Int32Array>>;
+    /**
+     * Element-wise left shift. `b` may be a per-element `Int32Array` of
+     * shift counts or a single scalar `number` applied uniformly.
+     */
+    leftShift(a: Int32Array, b: Int32Array | number): Promise<ParallelResult<Int32Array>>;
+    /**
+     * Element-wise arithmetic (sign-preserving) right shift.
+     */
+    rightArithShift(a: Int32Array, b: Int32Array | number): Promise<ParallelResult<Int32Array>>;
+    /**
+     * 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.
+     */
+    rightLogShift(a: Int32Array, b: Int32Array | number): Promise<ParallelResult<Int32Array>>;
     /**
      * Terminate the worker pool
      */
@@ -270,6 +487,11 @@ declare class ComputePool {
      * Get current configuration
      */
     getConfig(): ComputePoolConfig;
+    /**
+     * Maximum number of workers configured for this pool.
+     * Used by distribution sampling fan-out to determine chunk count.
+     */
+    get workerCount(): number;
     /**
      * Get the underlying MathWorkerPool for advanced operations
      */
@@ -853,6 +1075,77 @@ declare function partitionRange(start: number, end: number, options?: ChunkOptio
  */
 declare function partition2D(rows: number, cols: number, options?: ChunkOptions): Array<[number, number, number, number]>;
 
+/**
+ * Parallel Bitwise Operations
+ *
+ * Element-wise bitwise operations on Int32Array buffers. Operations are
+ * applied in a chunked fashion so the work pattern mirrors the other
+ * parallel ops (`elementwise`, `scale`, etc.). The actual chunk kernel
+ * runs in-process: the MathWorkerPool kernel registry in
+ * `@danielsimonjr/mathts-workerpool` is keyed on `Float64Array` buffers,
+ * so cross-thread bitwise dispatch is intentionally out of scope here.
+ *
+ * The chunking still matters: it bounds peak-allocation pressure for
+ * very large arrays and keeps the call shape uniform with the rest of
+ * the parallel API, so the typed-function `Int32Array, Int32Array`
+ * signatures look identical to the `Float64Array, Float64Array` ones.
+ *
+ * Semantics follow JavaScript bitwise semantics on 32-bit signed
+ * integers (two's complement). For shift counts JavaScript itself
+ * masks to the low 5 bits — we preserve that behavior.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The set of supported binary bitwise op codes.
+ *
+ * - `bitAnd`   : `a & b`
+ * - `bitOr`    : `a | b`
+ * - `bitXor`   : `a ^ b`
+ * - `leftShift`       : `a << b`
+ * - `rightArithShift` : `a >> b`  (sign-extending)
+ * - `rightLogShift`   : `a >>> b` (zero-filling, returned as Int32 — values
+ *   above 2^31 wrap into negative range, as in `(x >>> n) | 0`)
+ */
+type BitwiseBinaryOp = 'bitAnd' | 'bitOr' | 'bitXor' | 'leftShift' | 'rightArithShift' | 'rightLogShift';
+/**
+ * Bitwise AND on two equal-length `Int32Array`s.
+ */
+declare function bitAnd(a: Int32Array, b: Int32Array, options?: ChunkOptions): Int32Array;
+/**
+ * Bitwise OR on two equal-length `Int32Array`s.
+ */
+declare function bitOr(a: Int32Array, b: Int32Array, options?: ChunkOptions): Int32Array;
+/**
+ * Bitwise XOR on two equal-length `Int32Array`s.
+ */
+declare function bitXor(a: Int32Array, b: Int32Array, options?: ChunkOptions): Int32Array;
+/**
+ * Element-wise left shift: `a[i] << b[i]`.
+ *
+ * `b` may be either an `Int32Array` of per-element shift counts or a
+ * single scalar `number` (applied uniformly). Shift counts are masked
+ * to the low 5 bits by JavaScript itself — values ≥ 32 fold back into
+ * `[0, 31]`.
+ */
+declare function leftShift(a: Int32Array, b: Int32Array | number, options?: ChunkOptions): Int32Array;
+/**
+ * Element-wise arithmetic (sign-preserving) right shift: `a[i] >> b[i]`.
+ */
+declare function rightArithShift(a: Int32Array, b: Int32Array | number, options?: ChunkOptions): Int32Array;
+/**
+ * Element-wise logical (zero-filling) right shift: `a[i] >>> b[i]`.
+ *
+ * Result is stored as `Int32Array`, so values ≥ 2^31 wrap into the
+ * negative range — equivalent to `(x >>> n) | 0`.
+ */
+declare function rightLogShift(a: Int32Array, b: Int32Array | number, options?: ChunkOptions): Int32Array;
+/**
+ * Unary bitwise NOT: `~a[i]`. Returns a fresh `Int32Array`.
+ */
+declare function bitNot(a: Int32Array, options?: ChunkOptions): Int32Array;
+
 /**
  * Threshold-based Dispatch Strategy
  *
@@ -990,4 +1283,4 @@ interface PoolStats {
     activeTasks: number;
 }
 
-export { 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 OperationCategory, type ParallelResult, type PoolOptions, type PoolStats, type ReduceOptions, type ThresholdConfig, ThresholdDispatcher, calculateChunks, calculateOptimalChunks, chunkArray, chunkFloat64Array, computePool, dispatch, 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, shouldParallelize$1 as shouldChunkParallelize, shouldParallelize, thresholdDispatcher };
+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 };