numbl 0.2.0 → 0.3.0

package/dist-lib/numbl-core/jit/e2/complexChainKernelEmit.d.ts

@@ -0,0 +1,79 @@
+/**
+ * e2 — complex multi-LHS fused chain C kernel emission (paired-buffer).
+ *
+ * Sister to [chainKernelEmit.ts](./chainKernelEmit.ts) for chains that
+ * produce at least one complex tensor. Mirrors the codegen shape of
+ * [e1/complexKernelEmit.ts](../e1/complexKernelEmit.ts) and uses the
+ * same fusion envelope (+ - * .* unary +/- conj real imag, real/complex
+ * widening, ImagLiteral). Anything outside that subset (`./`,
+ * `abs(complex)`, transcendentals on complex) is rejected at the e2
+ * lowerer level, which causes the driver to bail to the interpreter
+ * per-op complex path — matching e1's fusion fallthrough behavior.
+ *
+ *     void e2cc_<hash>(int64_t n,
+ *                      const double *in_<cta>_re, const double *in_<cta>_im,
+ *                      const double *in_<rtb>,
+ *                      [in_<lhs_input>_re/_im or in_<lhs_input> ...,]
+ *                      double s_<csc>_re, double s_<csc>_im,
+ *                      double s_<rsc>,
+ *                      [out_<lhs>_re, out_<lhs>_im or out_<lhs> ...])
+ *     {
+ *         #pragma omp simd
+ *         for (int64_t i = 0; i < n; i++) {
+ *             double <clhs1>_re, <clhs1>_im, ..., <rlhs1>, ...;
+ *             <clhs1>_re = ...; <clhs1>_im = ...;
+ *             <rlhs1> = ...;
+ *             out_<clhs>_re[i] = <clhs>_re; out_<clhs>_im[i] = <clhs>_im;
+ *             out_<rlhs>[i] = <rlhs>;
+ *         }
+ *     }
+ *
+ * Complex chains deliberately stick to `#pragma omp simd` regardless of
+ * `--par`: per-element bodies are ~6 flops spread across paired re/im
+ * buffers (memory-bandwidth-bound), and thread-spawn overhead dominates
+ * the compute win at realistic N. Matches e1's stance.
+ */
+import type { ChainAssignSpec } from "./emitShared.js";
+export interface E2ComplexKernelInputs {
+    /** Env tensor names, split by complex-ness. */
+    complexTensorNames: string[];
+    realTensorNames: string[];
+    /** Env scalar names, split by complex-ness. */
+    complexScalarNames: string[];
+    realScalarNames: string[];
+    /** Chain LHS names that need `in_<name>` because they're read before
+     *  being written. Split by complex-ness of the LHS. */
+    complexInputLhsNames: string[];
+    realInputLhsNames: string[];
+    /** Chain LHS names that escape the chain. Split by complex-ness. */
+    complexEscapeLhsNames: string[];
+    realEscapeLhsNames: string[];
+}
+export interface E2ComplexChainEmitResult {
+    kernelName: string;
+    cSource: string;
+    koffiSig: string;
+    hash: string;
+    /** In signature order: complex tensors, real tensors. */
+    complexInputTensors: string[];
+    realInputTensors: string[];
+    /** In signature order: complex input LHSs, real input LHSs. */
+    complexInputLhsNames: string[];
+    realInputLhsNames: string[];
+    /** In signature order: complex scalars, real scalars. */
+    complexInputScalars: string[];
+    realInputScalars: string[];
+    /** In signature order: complex escape LHSs, real escape LHSs. */
+    complexEscapeLhsNames: string[];
+    realEscapeLhsNames: string[];
+    chainLength: number;
+}
+/** Per-assign LHS info — complex-ness of the RHS determines whether
+ *  this stmt emits a paired (re/im) local or a single real local. */
+export interface ComplexChainAssignSpec extends ChainAssignSpec {
+    /** True when THIS stmt's RHS is complex. Chain-LHS type can differ
+     *  per reassignment; we track per-stmt so a `a = real; a = complex;`
+     *  sequence sees `a` as complex only after the second assign. */
+    rhsIsComplex: boolean;
+}
+export declare function emitE2ComplexChainKernel(assigns: ComplexChainAssignSpec[], inputs: E2ComplexKernelInputs): E2ComplexChainEmitResult;

package/dist-lib/numbl-core/jit/e2/emitShared.d.ts

@@ -0,0 +1,71 @@
+/**
+ * e2 — shared kernel-emission helpers used by both the chain emitter
+ * and the reduction emitter. The two emitters build the same kernel
+ * shape up to a few trailing differences (reduction init / combine /
+ * out_acc output), so everything that's identical lives here.
+ */
+import type { JitExpr } from "../jitTypes.js";
+import { type FusedTarget } from "../fusedScalarEmit.js";
+import type { ScalarOpTarget } from "../scalarEmit.js";
+/**
+ * C helper included in every e2 kernel prologue.
+ *
+ * `-ffast-math` implies `-ffinite-math-only`, which lets the compiler
+ * assume no NaN/Inf values and constant-fold `x != x` to 0 and `x == x`
+ * to 1. The NaN-detection idiom `mask = x ~= x` would silently return all
+ * zeros. `numbl_is_nan_fp` inspects the IEEE-754 bit pattern directly —
+ * the optimizer cannot look through `memcpy` to apply finite-math
+ * assumptions, so this survives the flag.
+ */
+export declare const E2_C_PROLOGUE: string;
+/**
+ * e2-specific scalar op target.
+ *
+ * Identical to `C_SCALAR_TARGET` except `binEq` / `binNe`: when both
+ * operand strings are the same C expression (i.e. the source was `x == x`
+ * or `x ~= x`), the standard `==` / `!=` forms are constant-folded to
+ * 1 / 0 by `-ffinite-math-only`. Replace them with the bit-pattern NaN
+ * helper so the self-comparison gives the correct IEEE 754 result.
+ */
+export declare const E2_C_SCALAR_TARGET: ScalarOpTarget;
+export interface ChainAssignSpec {
+    lhsName: string;
+    rhs: JitExpr;
+}
+export interface KernelInputs {
+    /** Regular env input tensor names (NOT chain LHSs). */
+    tensorNames: string[];
+    /** Scalar env input names. */
+    scalarNames: string[];
+    /** Chain LHS names that need `in_<name>` because they're read before
+     *  being written. */
+    inputLhsNames: string[];
+    /** Chain LHS names that escape the chain (materialized via
+     *  `out_<name>`). Does NOT include a reduce-target name — that one
+     *  is always chain-local by construction. */
+    escapeLhsNames: string[];
+}
+export declare const cInputPtr: (name: string) => string;
+export declare const cOutputPtr: (name: string) => string;
+export declare const cScalarParam: (name: string) => string;
+/** FusedTarget for the per-element body. Resolves Var reads to either
+ *  the chain-local stack name (once the corresponding assign has run)
+ *  or `in_<name>[i]` (before that point), mangles scalar param names,
+ *  and dispatches whitelisted builtins through their `jitEmitC`. */
+export declare function makeFusedTarget(locallyAssigned: ReadonlySet<string>): FusedTarget;
+/** Unique chain LHS names in source order — for the leading
+ *  `double <a>, <b>;` declaration. */
+export declare function uniqueLhsOrdered(chain: ChainAssignSpec[]): string[];
+/** All tensor-typed names visible to emitFusedScalarExpr: regular env
+ *  tensors, `in_<lhs>` tensors, and chain LHSs. */
+export declare function allTensorVarsFor(inputs: KernelInputs, chain: ChainAssignSpec[]): Set<string>;
+/** Emit one `<lhs> = <rhsC>;` line per chain assign, growing
+ *  `locallyAssigned` as we go so later stmts resolve earlier LHSs to
+ *  the stack-local. */
+export declare function emitChainAssignLines(chain: ChainAssignSpec[], allTensorVars: ReadonlySet<string>, ft: FusedTarget, locallyAssigned: Set<string>): string[];
+/** Kernel param list (tensor → inputLhs → scalar → escapeLhs). Callers
+ *  append any trailing params (e.g. `double *out_acc`). */
+export declare function buildParamList(inputs: KernelInputs): string[];
+/** koffi type list in the same order as `buildParamList`. Callers
+ *  append any trailing entries. */
+export declare function buildKoffiParts(inputs: KernelInputs): string[];

package/dist-lib/numbl-core/jit/e2/install.d.ts

@@ -0,0 +1,11 @@
+/**
+ * e2 — Node-only install hook.
+ *
+ * Sets the module-level `e2CompileFn` to the real `compileAndLoad`
+ * driver from `c/compile.ts`. The browser bundle never imports this
+ * file, so `e2CompileFn` stays at the throwing stub and any attempt
+ * to use `--opt e2` from the web fails with a clear message.
+ *
+ * Idempotent: re-importing in tests doesn't re-install.
+ */
+export {};

package/dist-lib/numbl-core/jit/e2/liveness.d.ts

@@ -0,0 +1,29 @@
+/**
+ * e2 — AST liveness helpers.
+ *
+ * Used by the chain classifier to decide whether a chain LHS is
+ * actually used outside the chain's own stmts. If not, it can be
+ * compiled as a per-element stack-local instead of being materialized
+ * as a tensor output buffer.
+ *
+ * The "scope" passed in is the innermost enclosing function body or
+ * top-level script body — chosen so that for-bodies, if-bodies, etc.
+ * are scanned recursively (MATLAB has flat function-level scoping for
+ * locals, so a name introduced inside a for-loop is visible to other
+ * stmts in the same function body).
+ *
+ * The walk excludes the chain's own stmts (and the trailing-reduction
+ * stmt if any) from the scan, applying the exclusion at every nesting
+ * level — so a chain inside a for-body whose LHS is read by another
+ * stmt in the same function body counts as referenced, but the chain
+ * stmts themselves don't trigger a false positive.
+ */
+import type { Stmt } from "../../parser/types.js";
+/**
+ * True iff `name` appears anywhere in `scopeBody` outside the stmts
+ * listed in `excludeStmts`. The exclusion is by reference identity
+ * and is applied at every nesting level — pass the chain stmts (and
+ * the trailing-reduction stmt if any) so they don't trigger false
+ * positives.
+ */
+export declare function isNameReferencedOutsideStmts(scopeBody: readonly Stmt[], excludeStmts: ReadonlySet<Stmt>, name: string): boolean;

package/dist-lib/numbl-core/jit/e2/loopKernel.d.ts

@@ -0,0 +1,49 @@
+/**
+ * e2 whole-loop C JIT.
+ *
+ * For a `for varName = lo:hi <body> end` where the body fits a supported
+ * shape, emit a single C function that runs all n iterations and call it
+ * once, instead of walking the AST on every iteration.
+ *
+ * Without this path, `--opt e2` pays ~70–100 ns per iter on a trivial
+ * `s = s + i` just for AST dispatch; a compiled C loop runs it in <1 ns.
+ *
+ * Current supported body shapes (all may mix in one loop):
+ *   - scalar assign           `s = s + sin(i) * cos(i) + sqrt(i*0.01)`
+ *   - scalar indexed read     `s = s + x(i)`                   (real tensor x)
+ *   - scalar indexed write    `y(i) = sin(i*0.01)`             (preallocated y)
+ *   - tensor local (elemwise) `c = a.*b + i*0.001`             (per-element
+ *                                                               expression is
+ *                                                               inlined into any
+ *                                                               consuming sum();
+ *                                                               last-iter value
+ *                                                               is also written
+ *                                                               back to the env
+ *                                                               for MATLAB
+ *                                                               post-loop
+ *                                                               visibility)
+ *   - reductions              `s = s + sum(c)`                 (c is a
+ *                                                               tensor_local —
+ *                                                               chained
+ *                                                               tensor_locals
+ *                                                               fuse through)
+ *
+ * Not supported (falls through to the interpreter / other JIT paths):
+ *   - non-`lo:hi` loop shapes (stepped ranges, `for i = v`)
+ *   - complex or logical tensor inputs
+ *   - matrix-matrix / matrix-vector multiplication
+ *   - bsxfun / broadcast across shapes
+ *   - function-handle calls, user-function calls
+ *   - control flow inside the body (if / while / return)
+ *   - multi-dimensional tensor access
+ */
+import type { Stmt } from "../../parser/types.js";
+import type { Interpreter } from "../../interpreter/interpreter.js";
+/**
+ * Attempt to compile and execute a for-loop as one C kernel under
+ * `--opt e2`. Returns true on success, false to fall back to the regular
+ * interpreter path (the caller will run the loop normally).
+ */
+export declare function tryE2Loop(interp: Interpreter, stmt: Stmt & {
+    type: "For";
+}): boolean;

package/dist-lib/numbl-core/jit/e2/loopKernelEmit.d.ts

@@ -0,0 +1,75 @@
+/**
+ * e2 whole-loop C emission.
+ *
+ * Given a classified loop body (`BodyStmt[]`) plus the parameter lists
+ * that describe how env values flow in and out, emit a single C
+ * function that runs the whole `for varName = lo:hi` loop in one call.
+ *
+ * Three BodyStmt shapes are supported:
+ *
+ *   scalar_assign    `s = s + sin(i)`          → one C statement per iter
+ *   tensor_write     `y(i) = sin(i*0.01)`      → `v_y[(int64_t)idx-1] = ...`
+ *   tensor_local     `c = a.*b + i*0.001`      → no code emitted here; its
+ *                                                 per-element expression is
+ *                                                 substituted into whichever
+ *                                                 reduction consumes it
+ *
+ * Reductions: a `scalar_assign` carries a list of `sum(<tensor_local>)`
+ * rewrites that were pulled out of its RHS upstream. Each is emitted as
+ * an inline inner `for __j` loop that accumulates the tensor_local's
+ * per-element expression into a fresh local. Chained tensor_locals
+ * (`d = sqrt(c+1)` where c is itself a tensor_local) fuse through
+ * recursively, so no intermediate buffer is materialized.
+ */
+import type { JitExpr } from "../jitTypes.js";
+/** Scalar math builtins we emit as direct C library calls. We bypass
+ *  each IBuiltin's `jitEmitC` here because some of those reject based
+ *  on type narrowing (e.g. `sqrt` requires `isNonneg` and we don't
+ *  propagate sign through Binary ops) — but in a pure-real scalar loop
+ *  the C semantics (NaN on negative sqrt, etc.) match what a MATLAB
+ *  user gets from `sqrt` on real numeric input.
+ *
+ *  Exported so the driver's pre-lowering analysis can treat these
+ *  names as non-env references. */
+export declare const LOOP_SCALAR_BUILTINS: Record<string, string>;
+/** A fused reduction lifted out of a `scalar_assign`'s RHS.
+ *  `sum(<tensorLocal>)` in the source becomes a synthetic scalar ident
+ *  `synthName`; the emitter materializes it as an inline inner loop
+ *  that accumulates `tensorLocal`'s per-element expression. */
+export interface Reduction {
+    synthName: string;
+    tensorLocal: string;
+    op: "sum";
+}
+/** A body statement in a form ready for C emission. */
+export type BodyStmt = {
+    kind: "scalar_assign";
+    name: string;
+    rhs: JitExpr;
+    reductions: Reduction[];
+} | {
+    kind: "tensor_write";
+    name: string;
+    idxRhs: JitExpr;
+    rhs: JitExpr;
+} | {
+    kind: "tensor_local";
+    name: string;
+    elemExpr: JitExpr;
+    lengthTensor: string;
+};
+/** Mangle a MATLAB scalar name to a C local-variable name. Prefix keeps
+ *  it out of the way of our bookkeeping locals (`lo`, `hi`, `__iv`). */
+export declare function v(name: string): string;
+/** Name for the `int64_t` length companion that travels alongside each
+ *  tensor param so inner reductions can bound their inline `__j` loop. */
+export declare function lenN(name: string): string;
+/** Names of all tensor_locals in the body, in body-declaration order.
+ *  Callers use this to allocate matching output buffers in the same
+ *  order as the kernel's param list. */
+export declare function tensorLocalNames(body: BodyStmt[]): string[];
+export declare function emitLoopKernel(scalarInputVars: string[], tensorInputVars: string[], tensorInoutVars: string[], inoutVars: string[], loopVar: string, body: BodyStmt[]): {
+    cSource: string;
+    kernelName: string;
+    koffiSig: string;
+};

package/dist-lib/numbl-core/jit/e2/multiReductionDriver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * e2 — multi-reduction driver.
+ *
+ * Handles a scalar `Assign` whose RHS contains TWO or more reduction
+ * calls (`sum`, `prod`, `max`, `min`, `mean`) over the same single
+ * tensor variable, e.g.
+ *
+ *     red_acc = red_acc + sum(x) + mean(x) + max(x) + min(x);
+ *
+ * The default interpreter path makes one pass through the tensor per
+ * reduction (4× the memory traffic of the optimal). The e2 driver
+ * detects the pattern, compiles ONE kernel that computes every
+ * requested reduction in a single pass, and substitutes the reduction
+ * subtrees in the RHS with the kernel's scalar outputs before
+ * evaluating the residual expression.
+ *
+ * Reuses [e1/multiReductionKernel.ts](../e1/multiReductionKernel.ts)
+ * for the C emission (same shape works for both backends).
+ */
+import type { Stmt } from "../../parser/types.js";
+import type { Interpreter } from "../../interpreter/interpreter.js";
+export declare function tryE2MultiReduction(interp: Interpreter, stmt: Stmt & {
+    type: "Assign";
+}): boolean;

package/dist-lib/numbl-core/jit/e2/reductionKernelEmit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * e2 — reduction kernel emission.
+ *
+ * Handles two related patterns in a single emitter:
+ *
+ *   (A) Standalone reduction:
+ *           acc = [acc OP] reduce(elemwiseExpr)
+ *       Empty chain prefix; the kernel walks the inputs once and
+ *       accumulates `reduce(per-element-expr)` into a scalar buffer.
+ *
+ *   (B) Chain + trailing reduction:
+ *           lhs1 = ...; lhs2 = ...; ...; lhsK = ...;
+ *           acc = [acc OP] reduce(lhsK)
+ *       The chain runs in the same per-element loop; lhsK is purely
+ *       chain-local (never materialized) — the kernel accumulates
+ *       reduce(lhsK) into the scalar buffer. Other chain LHSs may
+ *       still escape (extra `out_<name>` outputs).
+ *
+ * Both cases use the same kernel shape:
+ *
+ *     void e2r_<hash>(int64_t n,
+ *                     ..in_*.., ..in_lhs_input.., ..s_*..,
+ *                     ..out_escape.., double *out_acc)
+ *     {
+ *         double acc = <init>;
+ *         #pragma omp simd
+ *         for (int64_t i = 0; i < n; i++) {
+ *             double <chain_lhs1>, ..., <chain_lhsK>;
+ *             <chain_lhs1> = <stmt0_rhs_C>;
+ *             ...
+ *             <chain_lhsK> = <stmtK_rhs_C>;
+ *             out_<escape>[i] = <escape>;
+ *             <reduce-combine>(acc, <reduce_value_expr>);
+ *         }
+ *         *out_acc = acc;
+ *     }
+ *
+ * For "mean": JS combines `acc /= n` after reading the buffer back.
+ * For "max"/"min": uses if-update inside the loop (works under
+ * `-ffast-math` + `#pragma omp simd`).
+ */
+import type { JitExpr } from "../jitTypes.js";
+import { type ChainAssignSpec, type KernelInputs } from "./emitShared.js";
+export interface ReductionEmitSpec {
+    /** Chain prefix (length 0 for standalone-reduction). */
+    chain: ChainAssignSpec[];
+    /** Reduction op name: sum, prod, max, min, mean, any, all. */
+    reduceName: string;
+    /** Per-element value expression to feed the reduction.
+     *  - For (A) standalone: the elemwise expression `reduce(...)` was
+     *    given.
+     *  - For (B) chain + trailing: a `Var(lastChainLhsName)` JitExpr —
+     *    the emitter resolves it to the stack-local. */
+    reduceValueExpr: JitExpr;
+    inputs: KernelInputs;
+}
+export interface E2ReductionEmitResult {
+    kernelName: string;
+    cSource: string;
+    koffiSig: string;
+    hash: string;
+    inputTensors: string[];
+    inputLhsNames: string[];
+    inputScalars: string[];
+    escapeLhsNames: string[];
+    /** True when the kernel produces a scalar reduction output (always
+     *  true for this emitter; here for symmetry with other entries). */
+    hasReductionOutput: true;
+    reduceName: string;
+    chainLength: number;
+}
+export declare function emitE2ReductionKernel(spec: ReductionEmitSpec, par?: boolean): E2ReductionEmitResult;

package/dist-lib/numbl-core/jit/e2/scalarFnDriver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * e2 — whole-function scalar C-kernel driver.
+ *
+ * Mirrors what e1 does for pure-scalar functions (benchmarks/scalar_bench.m's
+ * `run_bench` is the motivating case) but triggers straight from the
+ * interpreter's `callUserFunction` entry, not through the JS-JIT outer.
+ * Under `--opt e2` the JS-JIT is disabled (optimization clamped to 0),
+ * so we can't lean on `tryEmitScalarFnKernel` + the `$h.compileKernel`
+ * plumbing; instead we invoke the shared lowering + C-emit pipeline
+ * directly and call the resulting koffi function with plain scalar
+ * args and Float64Array(1) out-buffers per output.
+ *
+ * Scope:
+ *   - All args are scalar `number` or `boolean` RuntimeValues.
+ *   - Declared outputs (the first `nargout || 1` of them) all lower to
+ *     scalar / boolean types.
+ *   - The body survives `checkCFeasibility` (no tic/toc, no Index
+ *     writes, no disp, etc.).
+ *
+ * Outside this envelope we return `E2_SKIP` and the caller proceeds
+ * with the interpreter path. Compilation failures are HARD errors —
+ * mirrors the e2 multi-reduction/chain drivers' policy.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+export declare const E2_SKIP: unique symbol;
+/** Try to run `fn(args)` via a whole-function C kernel. Returns
+ *  `E2_SKIP` to fall through to the interpreter. */
+export declare function tryE2ScalarFn(interp: Interpreter, fn: FunctionDef, args: unknown[], nargout: number): unknown | typeof E2_SKIP;

package/dist-lib/numbl-core/jit/fusedScalarEmit.d.ts

@@ -35,6 +35,14 @@ export interface FusedTarget {
      * the data pointer is named and whether it's aliased locally.
      */
     tensorElemRead(name: string): string;
+    /**
+     * Emit a read of tensor `name` at a runtime 1-based scalar index
+     * `idxC` — i.e. `data[(int64_t)idx - 1]`. Used by the e2 whole-loop
+     * kernel (scalar-context access; elemwise backends can leave this
+     * undefined, the emitter will throw on an Index node). Returns `null`
+     * to reject.
+     */
+    tensorScalarIndexRead?(name: string, idxC: string): string | null;
     /**
      * Emit a call to a scalar math builtin. The backend decides which
      * builtins it supports and how they map to library functions (e.g.

package/dist-lib/numbl-core/jit/heavyOps.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared heavy-op heuristic for fused-loop emitters (e1 and e2).
+ *
+ * Counts the number of "expensive" math operations in a JitExpr — the
+ * kind of work that's heavy enough per element that OpenMP thread-
+ * spawn overhead pays off at N >= 100k. Arithmetic-only chains skip
+ * the parallel-for pragma because threads slow them down: the body
+ * becomes memory-bandwidth-bound and adding threads only adds overhead.
+ */
+import type { JitExpr } from "./jitTypes.js";
+export declare function countHeavyOps(expr: JitExpr): number;
+/** Minimum element count before `#pragma omp parallel for simd` kicks
+ *  in. Below this the thread-spawn cost dominates the work.
+ *  Overridable via `NUMBL_OMP_THRESHOLD` for benchmarks. */
+export declare function ompParallelThreshold(): number;

package/dist-lib/numbl-core/jit/js/jitCodegen.d.ts

@@ -4,4 +4,4 @@
  * IR walkers for hoist-pass data collection are in jitCodegenHoist.ts.
  */
 import { type JitStmt } from "../jitTypes.js";
-export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string, fuse?: boolean, experimental?: string): string;
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string, experimental?: string, par?: boolean): string;

package/dist-lib/numbl-core/jit/js/jsFusedCodegen.d.ts

@@ -14,4 +14,4 @@
  * inside the same loop.
  */
 import type { FusibleChain } from "../fusion.js";
-export declare function emitJsFusedChain(lines: string[], indent: string, chain: FusibleChain, allTensorVars: ReadonlySet<string>, paramTensors: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>, _localTensorNames: ReadonlySet<string>, mangle: (n: string) => string, experimental?: string): void;
+export declare function emitJsFusedChain(lines: string[], indent: string, chain: FusibleChain, allTensorVars: ReadonlySet<string>, paramTensors: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>, _localTensorNames: ReadonlySet<string>, complexTensorNames: ReadonlySet<string>, complexScalarVars: ReadonlySet<string>, mangle: (n: string) => string, experimental?: string, par?: boolean): void;

package/dist-lib/numbl-core/jit/js/jsMultiReduction.d.ts

@@ -0,0 +1,70 @@
+/**
+ * JS-side multi-reduction block emission.
+ *
+ * Detection + dispatch for scalar Assigns of the form
+ *
+ *   acc = <expr tree with >=2 reductions over a single tensor Var>
+ *
+ * On match, the JS codegen emits a block that runs a single-pass
+ * reduction loop (either an inline JS loop, or a compiled C kernel
+ * under --opt e1), stashes each reduction result in a local, and then
+ * emits the Assign's RHS with each reduction Call substituted by the
+ * local that holds its value. The RHS-substitution contract lives in
+ * `jitCodegen._multiReductionSubst`, which this module installs and
+ * clears around the `emitExpr` call the caller provides.
+ *
+ * Limited to:
+ *   - sum / prod / max / min / mean (short-circuit any/all excluded)
+ *   - a single tensor Var argument to every reduction
+ *   - all reductions read the same tensor name
+ *   - the tensor is real-typed
+ *   - at least two reductions in the RHS
+ *
+ * NaN semantics for max/min are matched to MATLAB omit-NaN behaviour:
+ * IEEE unordered compare already skips NaN, and an `any_non_nan` flag
+ * drives the all-NaN → NaN fallback.
+ */
+import type { JitExpr, JitStmt } from "../jitTypes.js";
+import { type MultiReduceOp } from "../e1/multiReductionKernel.js";
+export interface MultiReductionMatch {
+    /** The scalar Assign being emitted (target + original RHS). */
+    stmt: JitStmt & {
+        tag: "Assign";
+    };
+    /** The tensor variable name all reductions read. */
+    tensorName: string;
+    /** Distinct ops that actually appear, in first-occurrence order. Used
+     *  to size the kernel's output buffer and decide which accumulators
+     *  to declare on the JS fallback path. */
+    ops: MultiReduceOp[];
+    /** Every reduction Call node found in the RHS, paired with its op.
+     *  The JS emitter builds a substitution map from each Call to the
+     *  local that holds its result. */
+    sites: {
+        call: JitExpr & {
+            tag: "Call";
+        };
+        op: MultiReduceOp;
+    }[];
+}
+/** Try to match the multi-reduction pattern on a single statement. */
+export declare function tryMatchMultiReduction(stmt: JitStmt): MultiReductionMatch | null;
+/**
+ * Emit the multi-reduction block. Writes into `lines`.
+ *
+ * The block:
+ *   1. Aliases `<tensorName>.data` to a local and reads its length.
+ *   2. Under e1, compiles/dispatches a single-pass C kernel that fills
+ *      a Float64Array scratch with the accumulator values, with an
+ *      inline JS fallback at small `n`. Under non-e1, emits just the
+ *      JS loop.
+ *   3. Post-loop: `mean = sum / n`, and a NaN fixup for max/min when
+ *      every input element was NaN.
+ *   4. Installs `_multiReductionSubst` pointing each reduction Call at
+ *      its local, emits the Assign's RHS via the caller-provided
+ *      `emitExpr`, and writes the final `<target> = <rhs>;`.
+ */
+export declare function emitMultiReductionBlock(lines: string[], indent: string, match: MultiReductionMatch, mangleName: (n: string) => string, emitExprWithSubst: (expr: JitExpr, subst: Map<JitExpr, string>) => string, experimental: string | undefined, par: boolean): void;
+/** Reset per-function counter so generated names stay stable between
+ *  compiles of the same IR. Called from `generateJS`. */
+export declare function resetMultiReductionState(): void;

package/dist-lib/numbl-core/version.d.ts

@@ -1,2 +1,2 @@
 /** Numbl version, used for JIT disk cache invalidation. */
-export declare const NUMBL_VERSION = "0.2.0";
+export declare const NUMBL_VERSION = "0.3.0";

package/native/numbl_addon.cpp

@@ -22,9 +22,11 @@
 #include "numbl_addon_common.h"
 #include <cstdlib>
 
+#ifndef __APPLE__
 extern "C" {
   void openblas_set_num_threads(int num_threads);
 }
+#endif
 
 // ── Addon version ────────────────────────────────────────────────────────────
 // Bump this integer whenever the addon's API changes (new functions, signature
@@ -58,9 +60,16 @@ static Napi::Value AddonVersion(const Napi::CallbackInfo& info) {
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   // Use single-threaded BLAS unless the user explicitly set the env var.
   // Multi-threaded BLAS adds overhead for the many small matmuls in numbl.
+#ifdef __APPLE__
+  // Accelerate reads VECLIB_MAXIMUM_THREADS from the environment on first use.
+  if (!std::getenv("VECLIB_MAXIMUM_THREADS")) {
+    setenv("VECLIB_MAXIMUM_THREADS", "1", 0);
+  }
+#else
   if (!std::getenv("OPENBLAS_NUM_THREADS")) {
     openblas_set_num_threads(1);
   }
+#endif
   exports.Set(Napi::String::New(env, "addonVersion"),
               Napi::Function::New(env, AddonVersion));
   exports.Set(Napi::String::New(env, "inv"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numbl",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Run .m source files in the browser and on the command line by compiling to JavaScript",
   "license": "Apache-2.0",
   "type": "module",
@@ -61,9 +61,7 @@
     "test:coverage:all": "bash scripts/coverage-all.sh",
     "test:scripts": "bash numbl_test_scripts/run_all.sh",
     "test:browser": "playwright test",
-    "test:scripts:c-jit": "bash numbl_test_scripts/run_c_jit.sh",
-    "test:scripts:c-jit-fuse": "bash numbl_test_scripts/run_c_jit_fuse.sh",
-    "test:scripts:c-jit-parity": "bash numbl_test_scripts/run_c_jit_parity.sh",
+    "test:scripts:e1": "bash numbl_test_scripts/run_e1.sh",
     "build:wasm": "bash numbl_test_scripts/build_wasm.sh",
     "update-readme": "tsx scripts/update-readme-usage.ts",
     "check-readme": "tsx scripts/update-readme-usage.ts --check",