numbl 0.2.0 → 0.3.3

package/dist-lib/numbl-core/jit/e1/scalarFnKernel.d.ts

@@ -1,44 +0,0 @@
-/**
- * e1 (experimental) — whole-function scalar kernel emission.
- *
- * Complements [kernelEmit.ts](./kernelEmit.ts) (which handles tensor
- * fusible chains) by covering the other big win case: a user function
- * that is entirely scalar arithmetic — e.g. the inner loop of a
- * Horner-style series, a Runge-Kutta step on a handful of doubles,
- * benchmarks/scalar_bench.m's `run_bench(N, M)`.
- *
- * Under `--opt e1`, when a JIT-able function's signature and body are
- * purely scalar, we call `generateC()` (the same emitter the C-JIT
- * uses at `--opt 2`) and wrap its output with a thin inline JS
- * function that shells out to `$h.compileKernel(...)`. The C source
- * and koffi signature are inlined as JS string literals, so
- * `--dump-js` shows the complete picture.
- *
- * Scope for the prototype:
- *   - All params are scalar doubles / booleans (CParamDesc.kind === "scalar")
- *   - All outputs are scalar / boolean (COutputDesc.kind === "scalar" | "boolean")
- *   - No tic/toc, no Index reads (no errFlag), no disp(...) calls
- *
- * Anything outside that envelope returns `null` and the caller falls
- * back to the plain JS-JIT path, which still benefits from e1's
- * per-chain tensor kernels.
- */
-import type { FunctionDef } from "../../interpreter/types.js";
-import type { JitStmt, JitType } from "../jitTypes.js";
-import type { GeneratedFn } from "../jitLower.js";
-import type { Interpreter } from "../../interpreter/interpreter.js";
-export interface ScalarFnKernelResult {
-    /** The inline-compileKernel JS source. The JIT caller splices this
-     *  in place of the normal JS-JIT body. */
-    jsSource: string;
-    /** Content-addressed kernel name from generateC, for logging. */
-    kernelName: string;
-    /** Raw C source (also embedded in `jsSource` as a string literal).
-     *  Exposed for `--dump-c` / logging. */
-    cSource: string;
-}
-/**
- * Try to emit a whole-function scalar kernel for the given lowered IR.
- * Returns null when the function is not a pure-scalar candidate.
- */
-export declare function tryEmitScalarFnKernel(interp: Interpreter, fn: FunctionDef, body: JitStmt[], outputNames: string[], localVars: Set<string>, outputType: JitType | null, outputTypes: JitType[], argTypes: JitType[], nargout: number, generatedIRBodies: Map<string, GeneratedFn>): ScalarFnKernelResult | null;

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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-/**
- * 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 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

@@ -1,71 +0,0 @@
-/**
- * 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[];

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

@@ -1,25 +0,0 @@
-/**
- * Shared fusible-operation name sets for JIT fusion analysis.
- *
- * Both the C-JIT and JS-JIT fusion paths use these to determine which
- * tensor Call nodes are fusible element-wise unary ops or absorbable
- * trailing reductions. The numeric op codes live in their respective
- * backend files (feasibility.ts for C, jitHelpersTensor.ts for JS).
- */
-/** Tensor unary builtins fusible into per-element loops. */
-export declare const FUSIBLE_TENSOR_UNARY_OPS: ReadonlySet<string>;
-/**
- * JS-JIT-safe subset: excludes transcendentals (exp, sin, cos, tan, etc.)
- * which V8 can't SIMD-vectorize. Fusing these into a scalar per-element
- * loop is slower than calling libnumbl_ops per-op (which uses -fopenmp-simd).
- * The C-JIT uses the full set because GCC/Clang vectorize via #pragma omp simd.
- */
-export declare const FUSIBLE_TENSOR_UNARY_OPS_JS: ReadonlySet<string>;
-/**
- * Two-argument tensor element-wise builtins fusible into per-element loops.
- * These are parsed as Call nodes (not Binary nodes) and need separate
- * recognition in isPureElementwise / emitScalarExpr.
- */
-export declare const FUSIBLE_TENSOR_BINARY_OPS: ReadonlySet<string>;
-/** Tensor reduction builtins absorbable as trailing reductions. */
-export declare const FUSIBLE_TENSOR_REDUCTION_OPS: ReadonlySet<string>;

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

@@ -1,7 +0,0 @@
-/**
- * JIT compilation entry point for interpreter function calls.
- */
-import type { Interpreter } from "../interpreter/interpreter.js";
-import type { FunctionDef } from "../interpreter/types.js";
-export declare const JIT_SKIP: unique symbol;
-export declare function tryJitCall(interp: Interpreter, fn: FunctionDef, args: unknown[], nargout: number): unknown | typeof JIT_SKIP;

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

@@ -1,25 +0,0 @@
-/**
- * JIT compilation for inline for/while loops.
- *
- * When the interpreter encounters a for or while loop, these functions
- * attempt to JIT-compile the loop as a synthetic function: inputs are
- * variables from the enclosing scope, outputs are variables assigned
- * inside the loop body. On success the compiled code runs and output
- * values are written back to the interpreter environment.
- */
-import type { Interpreter } from "../interpreter/interpreter.js";
-import type { Stmt } from "../parser/types.js";
-/**
- * Attempt to JIT-compile and execute a for-loop statement.
- * Returns true if JIT succeeded, false to fall back to interpretation.
- */
-export declare function tryJitFor(interp: Interpreter, stmt: Stmt & {
-    type: "For";
-}): boolean;
-/**
- * Attempt to JIT-compile and execute a while-loop statement.
- * Returns true if JIT succeeded, false to fall back to interpretation.
- */
-export declare function tryJitWhile(interp: Interpreter, stmt: Stmt & {
-    type: "While";
-}): boolean;

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

@@ -1,22 +0,0 @@
-/**
- * JIT compilation for the top-level script body (the main workspace).
- *
- * Wraps the list of non-function, non-classdef statements of a script as
- * a synthetic `FunctionDef` whose parameters are the live-in env vars
- * and whose outputs are every variable assigned in the script. On
- * success the compiled code runs once and all output values are written
- * back to the interpreter's workspace env.
- *
- * Mirrors `tryJitLoop` in jitLoop.ts — same lowering, same JS/C backend
- * pipeline, same progressive type widening. The differences:
- *   - the synthetic body is the list of stmts directly, not a single For/While
- *   - every assigned variable is live-out (the whole workspace is live)
- *   - cache key is per-Interpreter (a single script AST per interp run)
- */
-import type { Interpreter } from "../interpreter/interpreter.js";
-import type { Stmt } from "../parser/types.js";
-/**
- * Attempt to JIT-compile and execute the top-level script body.
- * Returns true if JIT succeeded, false to fall back to interpretation.
- */
-export declare function tryJitTopLevel(interp: Interpreter, stmts: Stmt[]): boolean;

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

@@ -1,33 +0,0 @@
-/**
- * Tensor indexing helpers for JIT-compiled code.
- *
- * Three tiers of helpers, from most general to most specialized:
- * 1. Generic (idx1, idx2, idxN) — handle any base type, real or complex
- * 2. Real-tensor fast path (idx1r, idx2r, idx3r) — skip type/imag checks
- * 3. Hoisted-base (idx*r_h, set*r_h) — take pre-extracted data/len/shape
- *
- * All helpers use 1-based MATLAB indexing and include per-dimension bounds
- * checks to ensure consistency with the interpreter.
- */
-import { type FloatXArrayType, type RuntimeTensor } from "../../runtime/types.js";
-export declare class JitBailToInterpreter extends Error {
-    readonly reason: string;
-    constructor(reason: string);
-}
-export declare function bce(): never;
-export declare function idx1(base: unknown, i: number): unknown;
-export declare function idx2(base: unknown, ri: number, ci: number): unknown;
-export declare function idxN(base: unknown, indices: number[]): unknown;
-export declare function idx1r(base: RuntimeTensor, i: number): number;
-export declare function idx2r(base: RuntimeTensor, ri: number, ci: number): number;
-export declare function idx3r(base: RuntimeTensor, i1: number, i2: number, i3: number): number;
-export declare function idx1r_h(data: FloatXArrayType, len: number, i: number): number;
-export declare function idx2r_h(data: FloatXArrayType, len: number, rows: number, ri: number, ci: number): number;
-export declare function idx3r_h(data: FloatXArrayType, len: number, d0: number, d1: number, i1: number, i2: number, i3: number): number;
-export declare function set1r_h(data: FloatXArrayType, len: number, i: number, v: number): void;
-export declare function set2r_h(data: FloatXArrayType, len: number, rows: number, ri: number, ci: number, v: number): void;
-export declare function set3r_h(data: FloatXArrayType, len: number, d0: number, d1: number, i1: number, i2: number, i3: number, v: number): void;
-export declare function setRange1r_h(dstData: FloatXArrayType, dstLen: number, dstStart: number, dstEnd: number, srcData: FloatXArrayType, srcLen: number, srcStart: number, srcEnd: number): void;
-export declare function subarrayCopy1r(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
-export declare function subarrayCopy1rRow(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
-export declare function setCol2r_h(dstData: FloatXArrayType, dstRows: number, dstLen: number, col: number, srcData: FloatXArrayType, srcLen: number): void;

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

@@ -1,17 +0,0 @@
-/**
- * Fused per-element loop emission for the JS-JIT.
- *
- * Given a FusibleChain (from fusion.ts), emits a single block-scoped
- * JavaScript `for` loop that evaluates all the chain's tensor assigns
- * as inline scalar expressions per element — no $h.tAdd / $h.tMul
- * helper calls, no intermediate tensor allocations.
- *
- * Tensor var references become either:
- *   - `__<name>_data[__i]`  for input params / pre-existing tensors
- *   - `__f_<name>`           for chain-produced intermediates (scalar local)
- *
- * The optional trailing reduction is absorbed as an inline accumulator
- * 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;

package/dist-lib/numbl-core/runtime/alloc.d.ts

@@ -1,23 +0,0 @@
-/**
- * Allocate an UNINITIALIZED typed array — skips the zero-fill that
- * `new Float64Array(n)` / `new FloatXArray(n)` perform by default.
- *
- * On Node, `Buffer.allocUnsafe` returns un-zeroed memory; wrapping it
- * in a TypedArray view costs ~10× less than the zero-fill for a 16 MB
- * buffer (~45 µs vs ~470 µs at N=2M doubles).
- *
- * SAFETY CONTRACT (very important):
- *   The caller MUST write every element before reading it.  Any element
- *   that is read before being written will contain arbitrary stale bytes
- *   from recently-freed memory.  If you cannot guarantee full coverage,
- *   use `new Float64Array(n)` / `new FloatXArray(n)` instead.
- *
- * In non-Node environments (browser, Deno without node-compat, …) where
- * `Buffer` is unavailable, we fall back to the zero-filling constructor
- * — still correct, just slower.
- */
-import { FloatXArray } from "./types.js";
-type FloatXInstance = InstanceType<typeof FloatXArray>;
-export declare function uninitFloat64(n: number): Float64Array<ArrayBuffer>;
-export declare function uninitFloatX(n: number): FloatXInstance;
-export {};