numbl 0.3.0 → 0.4.0

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/heavyOps.d.ts

@@ -1,15 +0,0 @@
-/**
- * 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/jitBailSafety.d.ts

@@ -1,41 +0,0 @@
-/**
- * Bail-safety gate for JIT bodies that contain I/O side effects.
- *
- * Mid-execution bails (JitBailToInterpreter / JitFuncHandleBailError)
- * cause the interpreter to re-run the body from the top. If the body
- * already emitted I/O before the bail, that output gets duplicated —
- * which the user would notice.
- *
- * Rule: a body with any I/O statement may only be JIT-compiled if we
- * can prove no bail can happen during execution. If there's no I/O,
- * the body can be JIT'd normally (a bail just restarts silently).
- *
- * Walkers are IR-level — they see the actual lowered constructs that
- * map 1:1 to runtime bail sites. The walkers recurse into the bodies
- * of `UserCall`-ed functions (via `generatedIRBodies`), since a bail
- * inside a callee still forces the caller to re-run.
- */
-import type { JitStmt } from "./jitTypes.js";
-import type { GeneratedFn } from "./jitLower.js";
-/**
- * Names of I/O-emitting builtins that the JIT is willing to lower as
- * ExprStmt calls. Any `Call` to one of these in the lowered IR marks
- * the body as having observable I/O.
- */
-export declare const JIT_IO_BUILTINS: Set<string>;
-/**
- * Walk a body + its transitively called function bodies and return
- * whether the combined execution graph contains an I/O call.
- */
-export declare function irHasIO(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;
-/**
- * Walk a body + its transitively called function bodies and return
- * whether any construct exists that can throw `JitBailToInterpreter`
- * or `JitFuncHandleBailError` at runtime.
- *
- * Bail-risky constructs:
- *   - AssignIndex / AssignIndexCol: may bail on out-of-bounds grow.
- *   - FuncHandleCall / UserDispatchCall: return-type check may bail.
- *   - UserCall: recurse into callee body.
- */
-export declare function irHasBailRisk(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;

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/jitLoopAnalysis.d.ts

@@ -1,37 +0,0 @@
-/**
- * Static AST analysis to determine input/output variables for loop JIT.
- *
- * Walks the loop body (and condition for while) to collect:
- * - assigned: variables written inside the loop
- * - referenced: variables read inside the loop
- * - hasReturn: whether the loop body contains a return statement
- */
-import type { Stmt } from "../parser/types.js";
-export interface LoopVarInfo {
-    /** Variables referenced in the loop that must come from enclosing scope */
-    inputs: string[];
-    /** Variables assigned in the loop body (written back after JIT execution) */
-    outputs: string[];
-    /** Whether the loop body contains a return statement (skip JIT if true) */
-    hasReturn: boolean;
-}
-/** Analyze a for loop statement for JIT compilation. */
-export declare function analyzeForLoop(stmt: Stmt & {
-    type: "For";
-}): LoopVarInfo;
-/**
- * Collect the names of all variables read in a sibling-tail starting at
- * `startIdx` of the given stmt list. Used by the loop JIT to filter the
- * loop's output set so that loop-internal temporaries don't get written
- * back when no later code reads them.
- */
-export declare function collectReadsFromSiblings(stmts: Stmt[], startIdx: number, out: Set<string>): void;
-/**
- * Analyze a top-level script body (list of statements) for JIT compilation.
- * Used by `tryJitTopLevel` to wrap the whole main script as a synthetic fn.
- */
-export declare function analyzeTopLevel(stmts: Stmt[]): LoopVarInfo;
-/** Analyze a while loop statement for JIT compilation. */
-export declare function analyzeWhileLoop(stmt: Stmt & {
-    type: "While";
-}): LoopVarInfo;

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

@@ -1,122 +0,0 @@
-/**
- * AST -> JIT IR lowering with type propagation. Orchestrator that owns
- * the shared context types (LowerCtx, SliceAlias), the public result
- * types (GeneratedFn, LoweringResult), and the `lowerFunction` entry
- * point. Actual statement and expression lowering lives in
- * jitLowerStmt.ts and jitLowerExpr.ts; type-level helpers are in
- * jitLowerTypes.ts.
- *
- * Returns null if any unsupported construct is encountered, causing the
- * entire function to fall back to interpretation.
- */
-import type { FunctionDef } from "../interpreter/types.js";
-import type { Interpreter } from "../interpreter/interpreter.js";
-import type { JitType, JitExpr, JitStmt } from "./jitTypes.js";
-import { type TypeEnv } from "./jitLowerTypes.js";
-/**
- * Lowered IR for a user function reached during a top-level lowering.
- *
- * JS-JIT caches the callee as generated JS source in `generatedFns` and
- * is done. C-JIT needs to re-analyze the callee's IR (for recursive
- * feasibility + emitting a static C function per callee), so we also
- * cache the raw IR here. One entry per unique `jitName`; matches the
- * JS-JIT specialization key.
- */
-export interface GeneratedFn {
-    fn: FunctionDef;
-    argTypes: JitType[];
-    outputNames: string[];
-    outputTypes: JitType[];
-    body: JitStmt[];
-    localVars: Set<string>;
-    nargout: number;
-}
-export interface LoweringResult {
-    body: JitStmt[];
-    outputNames: string[];
-    localVars: Set<string>;
-    hasTensorOps: boolean;
-    /** Generated JS code for called user functions: jitName → code */
-    generatedFns: Map<string, string>;
-    /** Lowered IR for called user functions: jitName → IR + metadata.
-     *  Populated alongside `generatedFns` by `lowerUserFuncCall`; the
-     *  C-JIT uses it for recursive feasibility and per-callee C emission. */
-    generatedIRBodies: Map<string, GeneratedFn>;
-    /** Type of the first output variable after lowering */
-    outputType: JitType | null;
-    /** Types of all output variables in outputNames order. Mirrors the
-     *  shape of JS-JIT's `return [out0, out1, ...]`. */
-    outputTypes: JitType[];
-    /** Final typed environment after lowering the body. The hybrid
-     *  loop-extraction pass uses this to look up live-in/live-out var
-     *  types without re-running type inference. */
-    endEnv: TypeEnv;
-}
-/**
- * A "slice alias" records that a MATLAB local was bound to a colon-slice of
- * a real tensor (e.g. `pt = pts(:, i)`). Rather than materializing the slice
- * as a RuntimeTensor per iteration, we remember the base tensor and a
- * per-dim "template" of indices — scalar expressions captured at bind time
- * for the non-colon dims, and `"colon"` placeholders for the colon dims.
- * Subsequent reads like `pt(k)` substitute `k` into the colon positions and
- * emit a direct scalar read on the base tensor, which compiles cleanly
- * through the existing hoisted `idx{1,2,3}r_h` fast path.
- */
-export interface SliceAlias {
-    baseName: string;
-    baseType: JitType;
-    /**
-     * One entry per index of the original bind expression, in source order.
-     * A `"colon"` slot expects to be filled by the read-site's colon indices.
-     * An `"expr"` slot carries a JitExpr that will be substituted as-is.
-     */
-    template: ({
-        kind: "colon";
-    } | {
-        kind: "expr";
-        expr: JitExpr;
-    })[];
-    /** Sizes of the slice's colon dimensions, in source order. */
-    sliceShape: number[];
-    /** Indices into `template` where colon slots live, in source order. */
-    colonPositions: number[];
-}
-export interface LowerCtx {
-    env: TypeEnv;
-    localVars: Set<string>;
-    params: Set<string>;
-    /** First bail reason encountered during lowering; lets callers surface
-     *  a hint for why JS-JIT declined a function (purely diagnostic, only
-     *  consulted by the `NUMBL_LOG_CJIT_MISSES` tally). Writes should use
-     *  `setBailReason()` which is idempotent — only the first reason sticks. */
-    bailReason?: string;
-    bailLine?: number;
-    /** Type of the deepest expr whose lowering was attempted — used as a
-     *  last-resort bail reason hint when no more specific reason was set. */
-    lastExprType?: string;
-    lastExprLine?: number;
-    /** Variables that are actually assigned in the function body. */
-    assignedVars: Set<string>;
-    /**
-     * Map from a MATLAB local name to its slice alias, if any. A name is
-     * present here iff the most recent assignment to it was a whole-tensor
-     * colon slice. Reads of the name as a plain Ident bail; reads of
-     * `name(...)` substitute through the template and emit a direct scalar
-     * read of the base tensor. See `tryLowerAsSliceBind`.
-     */
-    sliceAliases: Map<string, SliceAlias>;
-    _hasTensorOps?: boolean;
-    interp?: Interpreter;
-    /** The nargout this specialization was requested with — inlined wherever
-     *  the body reads the `nargout` identifier, since the JIT specializes per
-     *  nargout already. */
-    nargout?: number;
-    generatedFns: Map<string, string>;
-    generatedIRBodies: Map<string, GeneratedFn>;
-    loweringInProgress: Set<string>;
-    /** Pre-built line break table for offset→line lookup. */
-    lineTable?: number[];
-}
-/** Idempotent bail-reason setter. Only the first reason per function sticks. */
-export declare function setBailReason(ctx: LowerCtx, reason: string, line?: number): void;
-export declare function lowerFunction(fn: FunctionDef, argTypes: JitType[], nargout: number, interp?: Interpreter, generatedFns?: Map<string, string>, loweringInProgress?: Set<string>, generatedIRBodies?: Map<string, GeneratedFn>): LoweringResult | null;

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

@@ -1,27 +0,0 @@
-/**
- * Expression lowering for the JIT. Paired with jitLowerStmt.ts; the two
- * sides are mutually recursive (stmt bodies contain exprs; function-call
- * exprs may trigger nested lowering of a callee's body). jitLower.ts is
- * the orchestrator that ties them together via LowerCtx + lowerFunction.
- */
-import type { Expr } from "../parser/types.js";
-import { type JitExpr } from "./jitTypes.js";
-import type { LowerCtx } from "./jitLower.js";
-export declare function lowerExpr(ctx: LowerCtx, expr: Expr): JitExpr | null;
-/**
- * Stage 21: lower `src(a:b)` on a real-tensor base into a
- * `RangeSliceRead` IR node producing a fresh column-vector tensor.
- *
- * Accepts `Range` with no step (default step 1). `start` and `end`
- * must lower to numeric/boolean scalar exprs. The result is a real
- * tensor with shape `[?, 1]` — the exact length is runtime-dependent.
- *
- * Caller responsibility: match the parent expression shape
- * `Index(Ident(src), [Range])` or `FuncCall(src, [Range])` before
- * calling. Returns null if the source isn't a real tensor or the
- * range isn't the expected shape.
- */
-export declare function tryLowerRangeSliceRead(ctx: LowerCtx, baseName: string, rangeExpr: Expr): JitExpr | null;
-export declare function lowerIBuiltinCall(ctx: LowerCtx, expr: Expr & {
-    type: "FuncCall";
-}): JitExpr | null;

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

@@ -1,9 +0,0 @@
-/**
- * Statement lowering for the JIT. Paired with jitLowerExpr.ts; the two
- * sides are mutually recursive. jitLower.ts is the orchestrator that ties
- * them together via LowerCtx + lowerFunction.
- */
-import type { Stmt } from "../parser/types.js";
-import { type JitStmt } from "./jitTypes.js";
-import type { LowerCtx } from "./jitLower.js";
-export declare function lowerStmts(ctx: LowerCtx, stmts: Stmt[]): JitStmt[] | null;

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

@@ -1,29 +0,0 @@
-/**
- * Type-level helpers for the JIT lowering pass.
- *
- * Pure functions for:
- * - Sign algebra (how signs combine through arithmetic)
- * - Binary/unary operation result type inference
- * - Type environment management (clone, merge, equality)
- * - Known MATLAB constants
- *
- * These have no dependency on LowerCtx or the lowering state.
- */
-import { BinaryOperation, UnaryOperation } from "../parser/types.js";
-import { type JitExpr, type JitType, type SignCategory } from "./jitTypes.js";
-export declare const KNOWN_CONSTANTS: Record<string, number>;
-export type TypeEnv = Map<string, JitType>;
-export declare function cloneEnv(env: TypeEnv): TypeEnv;
-/** Merge two type environments at a join point. Returns null if any type becomes unknown. */
-export declare function mergeEnvs(a: TypeEnv, b: TypeEnv): TypeEnv | null;
-/** Check if two type environments are identical (by JSON comparison). */
-export declare function envsEqual(a: TypeEnv, b: TypeEnv): boolean;
-export declare function addSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
-export declare function mulSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
-export declare function combineSigns(a: SignCategory | undefined, b: SignCategory | undefined, op: BinaryOperation): SignCategory | undefined;
-export declare function binaryResultType(op: BinaryOperation, left: JitType, right: JitType, 
-/** Lowered operand exprs. Optional because tests / older callers pass
- *  only types. When provided, enables structural nonneg detection for
- *  patterns like `x .* x` that the type-only path can't see. */
-leftExpr?: JitExpr, rightExpr?: JitExpr): JitType | null;
-export declare function unaryResultType(op: UnaryOperation, operand: JitType): JitType | null;

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;