numbl 0.1.7 → 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/fusedChainHelpers.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Chain-level helpers shared by the JS and C fused-codegen backends.
+ *
+ * The per-element scalar expression walker lives in `fusedScalarEmit.ts`;
+ * this module covers the surrounding logic that decides which chain dests
+ * need a write-back to their tensor buffer, and the reduction-accumulator
+ * init/combine snippets for inline reductions.
+ *
+ * Reductions are parameterized over a small `ReductionLiterals` record so
+ * each backend supplies its own spelling of `0` vs `0.0`, `===` vs `==`,
+ * `-Infinity` vs `(-1.0/0.0)`, etc. — the control structure is identical.
+ */
+import { BinaryOperation } from "../parser/types.js";
+import type { FusibleChain } from "./fusion.js";
+/**
+ * Compute the set of distinct dest names in a fused chain and which of
+ * them require a write-back into their tensor buffer.
+ *
+ * A dest normally needs write-back; the exception is the chain's last
+ * tensor if it is fully consumed by a trailing reduction (in which case
+ * the scalar reduction accumulator is the only output — materialising
+ * the tensor buffer would be wasted work). If that last-dest tensor is
+ * ALSO a named output of the enclosing function, the write-back is kept
+ * so the caller sees the updated buffer.
+ */
+export declare function determineWriteBack(chain: FusibleChain, outputTensorNames: ReadonlySet<string>): {
+    destNames: Set<string>;
+    writeBack: Set<string>;
+    reductionConsumes: boolean;
+};
+/**
+ * Target-specific literal spellings used by the reduction helpers.
+ *
+ * The structure of the reduction snippets is identical between JS and
+ * C, but the literals differ: JS uses `1`, `-Infinity`, `===`/`!==`,
+ * while C uses `1.0`, `(-1.0/0.0)`, `==`/`!=`. The caller picks a
+ * record for its target and reuses it.
+ */
+export interface ReductionLiterals {
+    /** Additive identity (`0` for JS, `0.0` for C). */
+    zero: string;
+    /** Multiplicative identity / truthy (`1` or `1.0`). */
+    one: string;
+    /** Positive infinity literal (`Infinity` or `(1.0/0.0)`). */
+    posInf: string;
+    /** Negative infinity literal (`-Infinity` or `(-1.0/0.0)`). */
+    negInf: string;
+    /** Strict-equality operator (`===` for JS, `==` for C). */
+    eq: string;
+    /** Strict-inequality operator (`!==` for JS, `!=` for C). */
+    neq: string;
+}
+export declare const JS_REDUCTION_LITERALS: ReductionLiterals;
+export declare const C_REDUCTION_LITERALS: ReductionLiterals;
+/** Initial value expression for a reduction accumulator. */
+export declare function reductionInit(reduceName: string, lits: ReductionLiterals): string;
+/** Statement that folds a per-element `valueExpr` into the accumulator. */
+export declare function reductionCombine(reduceName: string, accVar: string, valueExpr: string, lits: ReductionLiterals): string;
+/**
+ * Statement that folds a per-chain `val` into an enclosing accumulator
+ * `dest` via the outer-loop op (e.g. `ir_acc = ir_acc + sum(...)`).
+ *
+ * Target-neutral: `+=` / `-=` / `*=` have identical syntax in JS and C.
+ */
+export declare function accumulateOp(op: BinaryOperation, dest: string, val: string): string;

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

@@ -0,0 +1,69 @@
+/**
+ * Shared per-element scalar-expression emission for fused loops.
+ *
+ * Both the JS-JIT and C-JIT fused-chain emitters walk the chain's
+ * expression trees and emit each sub-expression in "per-element"
+ * form — tensor Vars become `data[__i]` reads (or a scalar local for
+ * chain-produced intermediates), Binary/Unary/Call map to scalar
+ * operations that will run once per element of the fused loop.
+ *
+ * The walk itself is identical between the two backends; only the
+ * leaf syntax differs (JS `Math.sin` vs C `sin`, integer literal
+ * formatting, mangling prefix). A backend supplies a `FusedTarget`
+ * describing those leaves and a value-form `ScalarOpTarget` for the
+ * arithmetic/comparison/logical switches.
+ *
+ * Note: the op target used here must emit comparison / logical ops
+ * in *numeric* form (result is a double 0.0/1.0 suitable for tensor
+ * write-back). For C this coincides with the regular value target;
+ * for JS a second target instance is needed because value-form
+ * comparisons return a JS boolean.
+ */
+import type { JitExpr } from "./jitTypes.js";
+import type { FusibleChain } from "./fusion.js";
+import { type ScalarOpTarget } from "./scalarEmit.js";
+/** Scalar local name for a chain-produced tensor intermediate. */
+export declare function fusedLocal(name: string): string;
+export interface FusedTarget {
+    /** Format a numeric literal (e.g. `1` for JS, `1.0` for C). */
+    formatNumber(v: number): string;
+    /** Mangle a scalar variable reference (non-tensor). */
+    mangle(name: string): string;
+    /**
+     * Emit a per-element read of tensor var `name` — i.e. the expression
+     * that yields `data[__i]` for that tensor. The backend decides how
+     * 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.
+     * JS `Math.sin` vs C `sin`). Return `null` to reject.
+     *
+     * `name` is the builtin name (e.g. `"sin"`, `"mod"`, `"rem"`);
+     * `args` are already-emitted per-element scalar expressions.
+     */
+    emitBuiltinCall(name: string, args: string[]): string | null;
+}
+/** Shared walker: emit a JitExpr as a per-element scalar expression. */
+export declare function emitFusedScalarExpr(expr: JitExpr, chainLocals: ReadonlySet<string>, allTensorVars: ReadonlySet<string>, opTarget: ScalarOpTarget, fusedTarget: FusedTarget): string;
+/**
+ * Find the first tensor-param name referenced in a chain's assigns.
+ * Used by both backends to pick the length-determining tensor.
+ */
+export declare function findTensorParamInChain(chain: FusibleChain, paramTensors: ReadonlySet<string>, allTensorVars: ReadonlySet<string>): string | null;
+/**
+ * Collect distinct tensor names referenced in the chain's expression
+ * trees that are NOT produced by the chain itself (i.e. read from
+ * outside: params or pre-existing locals). Both backends need this to
+ * pick a length-reference tensor when no formal param is in the chain.
+ */
+export declare function collectInputTensors(chain: FusibleChain, allTensorVars: ReadonlySet<string>): Set<string>;

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

@@ -0,0 +1,71 @@
+/**
+ * Fusion analysis for JIT backends (shared by JS-JIT and C-JIT).
+ *
+ * Scans a statement list for runs of tensor element-wise assigns that
+ * can be collapsed into a single per-element `for` loop. Each such run
+ * is a "fusible chain."
+ *
+ * A chain breaks on:
+ *   - control flow (If/For/While)
+ *   - any non-Assign statement
+ *   - a tensor assign whose RHS references a tensor that is NOT an input
+ *     param and NOT previously assigned within the same chain
+ *   - a scalar assign (left for the per-op emitter)
+ *
+ * An optional **trailing reduction** is absorbed when the statement
+ * immediately after a tensor chain is of the form
+ *   `acc = acc + reduce(lastChainVar)`   or
+ *   `acc = reduce(lastChainVar)`
+ * where `reduce` is sum/prod/max/min/mean/any/all. Absorbing the
+ * reduction lets the fused loop emit an inline accumulator instead of
+ * materialising the intermediate buffer.
+ */
+import type { JitExpr, JitStmt } from "./jitTypes.js";
+import { BinaryOperation } from "../parser/types.js";
+/** One tensor assign inside a fusible chain. */
+export interface FusedAssign {
+    /** Destination tensor variable name. */
+    destName: string;
+    /** RHS expression tree (all tensor ops are element-wise). */
+    expr: JitExpr;
+}
+/** A trailing reduction absorbed into the fused loop. */
+export interface FusedReduction {
+    /** Scalar accumulator variable name (e.g. `chain_acc`). */
+    accName: string;
+    /** Reduction builtin name (e.g. `sum`). */
+    reduceName: string;
+    /** The tensor variable being reduced (last chain dest). */
+    tensorName: string;
+    /**
+     * When true, the scalar statement is `acc = acc OP reduce(tensor)`,
+     * and `accOp` says which binary op combines the old accumulator with
+     * the reduction result. When false, it's a plain `acc = reduce(tensor)`.
+     */
+    hasAccumulate: boolean;
+    accOp?: BinaryOperation;
+}
+/** Describes one fusible chain found in a statement list. */
+export interface FusibleChain {
+    /** Index of the first statement in the chain (within the parent list). */
+    startIdx: number;
+    /** Number of statements consumed (tensor assigns + optional reduction). */
+    length: number;
+    /** The tensor assigns to fuse. */
+    assigns: FusedAssign[];
+    /** Optional trailing reduction. */
+    reduction?: FusedReduction;
+}
+/**
+ * Scan a statement list and return all fusible chains.
+ *
+ * `paramTensors` is the set of tensor parameter names (input data that
+ * will be read via `data[i]` in the fused loop).
+ * `allTensorVars` is the full set of tensor-typed variables (params +
+ * locals + outputs).
+ * `allowedUnaryOps` optionally restricts which tensor unary Call names
+ * are fusible. Defaults to `FUSIBLE_TENSOR_UNARY_OPS` (full set).
+ * The JS backend passes a restricted set that excludes transcendentals
+ * (V8 can't vectorize them, so fusing them is slower than per-op calls).
+ */
+export declare function findFusibleChains(stmts: JitStmt[], paramTensors: ReadonlySet<string>, allTensorVars: ReadonlySet<string>, allowedUnaryOps?: ReadonlySet<string>): FusibleChain[];