numbl 0.1.1 → 0.1.2

package/dist-lib/numbl-core/diagnostics/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Aggregate compilation error — collects multiple errors from parsing/lowering
+ * across workspace files so that all errors can be reported at once.
+ */
+export declare class CompilationErrors extends Error {
+    errors: Error[];
+    constructor(errors: Error[]);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Shared error diagnostic utilities for extracting structured error info
+ * with source context (snippets). Used by both the CLI and the web worker.
+ */
+import { type CallFrame } from "../runtime/error.js";
+import type { WorkspaceFile } from "../workspace/index.js";
+interface DiagnosticInfo {
+    message: string;
+    errorType: "syntax" | "semantic" | "runtime" | "unknown";
+    file: string | null;
+    line: number | null;
+    snippet: string | null;
+    callStack?: CallFrame[] | null;
+}
+/** Look up source text for a given filename. */
+export declare function getSourceForFile(file: string, mainFileName: string, mainSource: string, wsFiles: WorkspaceFile[] | undefined): string | null;
+/**
+ * Extract structured diagnostic info from any error, returning an array.
+ * For CompilationErrors, returns one DiagnosticInfo per inner error.
+ * For all other errors, returns a single-element array.
+ */
+export declare function diagnoseErrors(error: unknown, mainSource: string, mainFileName: string, wsFiles?: WorkspaceFile[]): DiagnosticInfo[];
+/** Format multiple DiagnosticInfo as a human-readable string for console output. */
+export declare function formatDiagnostics(infos: DiagnosticInfo[], getSource?: (file: string) => string | null): string;
+/** Format a DiagnosticInfo as a human-readable string for console output. */
+export declare function formatDiagnostic(info: DiagnosticInfo, getSource?: (file: string) => string | null): string;
+export {};

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

@@ -0,0 +1,70 @@
+/**
+ * Entry point for code execution.
+ *
+ * Parses source, sets up the LoweringContext and Runtime,
+ * creates an Interpreter, and runs the AST.
+ */
+import type { RuntimeValue } from "./runtime/index.js";
+import type { PlotInstruction } from "../graphics/types.js";
+import type { FileIOAdapter } from "./fileIOAdapter.js";
+import type { SystemAdapter } from "./systemAdapter.js";
+import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
+import type { NativeBridge } from "./workspace/index.js";
+export interface ExecOptions {
+    onOutput?: (text: string) => void;
+    onDrawnow?: (plotInstructions: PlotInstruction[]) => void;
+    displayResults?: boolean;
+    maxIterations?: number;
+    initialVariableValues?: Record<string, RuntimeValue>;
+    /** Optional callback for verbose compilation logging. */
+    log?: (message: string) => void;
+    /** Enable profiling of builtin function calls. */
+    profile?: boolean;
+    /** Called each time a JIT function is compiled, with a description and the generated JS. */
+    onJitCompile?: (description: string, jsCode: string) => void;
+    /** Initial hold state for plotting (persisted across REPL executions). */
+    initialHoldState?: boolean;
+    /** Override or add builtins for this execution only. */
+    customBuiltins?: Record<string, (nargout: number, args: any[]) => any>;
+    /** Platform-specific file I/O adapter (e.g. Node.js fs). */
+    fileIO?: FileIOAdapter;
+    /** Platform-specific system adapter (env vars, cwd, platform info). */
+    system?: SystemAdapter;
+    /** Synchronous callback for the `input()` builtin. Displays prompt, returns user's line. */
+    onInput?: (prompt: string) => string;
+    /** Optimization level for interpreter (0 = none, >=1 = JIT scalar functions). */
+    optimization?: number;
+}
+export interface BuiltinProfileEntry {
+    totalTimeMs: number;
+    callCount: number;
+}
+export interface BuiltinProfileBreakdown {
+    /** Calls from the registry fallback (rt.builtins). */
+    fallback: BuiltinProfileEntry;
+    /** Calls from the interpreter (IBuiltin.resolve → apply). */
+    interp: BuiltinProfileEntry;
+    /** Calls from JIT-compiled code (ib_* helpers). */
+    jit: BuiltinProfileEntry;
+}
+export interface ProfileData {
+    executionTimeMs: number;
+    jitCompileTimeMs: number;
+    builtins: Record<string, BuiltinProfileBreakdown>;
+    dispatches: Record<string, BuiltinProfileEntry>;
+}
+export interface ExecResult {
+    output: string[];
+    generatedJS: string;
+    plotInstructions: PlotInstruction[];
+    returnValue: RuntimeValue;
+    variableValues: Record<string, RuntimeValue>;
+    holdState: boolean;
+    profileData?: ProfileData;
+    dispatchUnknownCounts?: Record<string, number>;
+    /** Updated search paths (set when addpath/rmpath was called). */
+    searchPaths?: string[];
+    /** Updated workspace files (set when addpath/rmpath was called). */
+    workspaceFiles?: WorkspaceFile[];
+}
+export declare function executeCode(source: string, options?: ExecOptions, workspaceFiles?: WorkspaceFile[], mainFileName?: string, searchPaths?: string[], nativeBridge?: NativeBridge): ExecResult;

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

@@ -0,0 +1,6 @@
+export interface ExternalAccessDirectives {
+    /** Variable names declared at file/script scope (outside any function) */
+    fileScope: Set<string>;
+    /** Function name -> variable names declared within that function */
+    functionScope: Map<string, Set<string>>;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Platform-agnostic file I/O adapter interface.
+ *
+ * numbl-core defines this interface but never imports Node.js fs.
+ * Concrete implementations (e.g. NodeFileIOAdapter) are injected
+ * from the CLI or other host environments via ExecOptions.fileIO.
+ */
+export interface FileIOAdapter {
+    /** Open a file, returns an integer file identifier (fid). */
+    fopen(filename: string, permission: string): number;
+    /** Close a file (or 'all'). Returns 0 on success, -1 on error. */
+    fclose(fid: number | "all"): number;
+    /** Read one line, stripping the newline. Returns -1 at EOF. */
+    fgetl(fid: number): string | number;
+    /** Read one line, keeping the newline. Returns -1 at EOF. */
+    fgets(fid: number): string | number;
+    /** Read an entire file as a string. */
+    fileread(filename: string): string;
+    /** Returns 1 if at EOF, 0 otherwise. */
+    feof(fid: number): number;
+    /** Returns the error message string for the last operation on fid. */
+    ferror(fid: number): string;
+    /** Write a string to a file descriptor (used by fprintf). */
+    fwrite(fid: number, text: string): void;
+    /** Read raw bytes from a file. Returns the bytes actually read (may be fewer than count at EOF). Optional. */
+    freadBytes?(fid: number, count: number): Uint8Array;
+    /** Write raw bytes to a file. Returns number of bytes written. Optional. */
+    fwriteBytes?(fid: number, data: Uint8Array): number;
+    /** Seek to a position in a file. origin: -1=bof, 0=cof, 1=eof. Returns 0 on success, -1 on error. Optional. */
+    fseek?(fid: number, offset: number, origin: number): number;
+    /** Return current file position. Optional. */
+    ftell?(fid: number): number;
+    /** Scan a directory for workspace files (.m, .js, .wasm). Optional. */
+    scanDirectory?(dirPath: string): import("../numbl-core/workspace/index.js").WorkspaceFile[];
+    /** Resolve a path to absolute. Optional. */
+    resolvePath?(dirPath: string): string;
+    /** Check whether a path exists and whether it is a file or directory. Optional. */
+    existsPath?(path: string): "file" | "dir" | null;
+    /** Create a directory (and parents). Returns true on success. Optional. */
+    mkdir?(dirPath: string): boolean;
+    /** Download a URL to a file. Optional. */
+    websave?(url: string, filename: string): void;
+    /** Fetch content from a URL and return as a string. Optional. */
+    webread?(url: string): string;
+    /** Delete files matching a pattern (supports globs). Optional. */
+    deleteFile?(pattern: string): void;
+    /** Remove a directory. If recursive is true, remove contents first. Returns true on success. Optional. */
+    rmdir?(dirPath: string, recursive: boolean): boolean;
+    /** Extract a ZIP file to an output folder. Returns list of extracted file paths. Optional. */
+    unzip?(zipfilename: string, outputfolder: string): string[];
+    /** Return the temporary directory path. Optional. */
+    tempdir?(): string;
+    /** List directory entries. Returns array of {name, folder, bytes, isdir, mtimeMs}. Optional. */
+    listDir?(dirPath: string): {
+        name: string;
+        folder: string;
+        bytes: number;
+        isdir: boolean;
+        mtimeMs: number;
+    }[];
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Unified function resolution.
+ *
+ * Single source of truth for resolving a function name + arg types + call site
+ * to a definitive target. Used by both codegen (compile-time) and JIT (runtime).
+ */
+import type { FunctionIndex } from "./lowering/loweringContext.js";
+import type { CallSite } from "./runtime/runtimeHelpers.js";
+import type { ItemType } from "./lowering/itemTypes.js";
+export type ResolvedTarget = {
+    kind: "classMethod";
+    className: string;
+    methodName: string;
+    compileArgTypes: ItemType[];
+    stripInstance: boolean;
+} | {
+    kind: "localFunction";
+    name: string;
+    argTypes: ItemType[];
+    source: {
+        from: "main";
+    } | {
+        from: "classFile";
+        className: string;
+        methodScope?: string;
+    } | {
+        from: "workspaceFile";
+        wsName: string;
+    } | {
+        from: "privateFile";
+        callerFile: string;
+    };
+} | {
+    kind: "privateFunction";
+    name: string;
+    argTypes: ItemType[];
+    callerFile: string;
+} | {
+    kind: "workspaceFunction";
+    name: string;
+    argTypes: ItemType[];
+} | {
+    kind: "workspaceClassConstructor";
+    className: string;
+    argTypes: ItemType[];
+} | {
+    kind: "builtin";
+    name: string;
+};
+/**
+ * Definitively resolve a function name to a single target using the FunctionIndex.
+ * Returns null only if the function is truly not found.
+ *
+ * @param name - Function name to resolve
+ * @param argTypes - Argument types (may include undefined for unknown)
+ * @param callSite - Where the call originates
+ * @param index - The upfront function index
+ */
+export declare function resolveFunction(name: string, argTypes: ItemType[], callSite: CallSite, index: FunctionIndex): ResolvedTarget | null;

package/dist-lib/numbl-core/helpers/arithmetic.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Arithmetic, comparison, and related internal helpers.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+/** Add two RuntimeValues */
+export declare function mAdd(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Subtract two RuntimeValues */
+export declare function mSub(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Multiply two RuntimeValues (matrix multiply for 2D tensors, scalar otherwise) */
+export declare function mMul(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise multiply */
+export declare function mElemMul(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Divide */
+export declare function mDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise divide */
+export declare function mElemDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Left division (mldivide): a \ b — for scalars b/a, for matrices solve a*x = b */
+export declare function mLeftDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise left division (ldivide): a .\ b = b ./ a */
+export declare function mElemLeftDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Power */
+export declare function mPow(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise power */
+export declare function mElemPow(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Negation */
+export declare function mNeg(v: RuntimeValue): RuntimeValue;
+/** Transpose (non-conjugate for complex scalars and tensors) */
+export declare function mTranspose(v: RuntimeValue): RuntimeValue;
+/** Conjugate transpose (Hermitian transpose) - transposes and conjugates */
+export declare function mConjugateTranspose(v: RuntimeValue): RuntimeValue;
+export declare function mEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mNotEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mLess(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mLessEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mGreater(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mGreaterEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/**
+ * Check if two shapes are compatible for broadcasting and compute the output shape.
+ * Broadcasting: dimensions must be equal or one of them must be 1.
+ * Returns null if shapes are incompatible, otherwise returns the broadcast shape.
+ */
+export declare function getBroadcastShape(shapeA: number[], shapeB: number[]): number[] | null;
+/**
+ * Iterate over all elements of a broadcast result in column-major order,
+ * calling `visit(aIdx, bIdx, outIdx)` for each output element.
+ */
+export declare function broadcastIterate(aShape: number[], bShape: number[], outShape: number[], visit: (aIdx: number, bIdx: number, outIdx: number) => void): void;

package/dist-lib/numbl-core/helpers/bessel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bessel function implementations (pure numeric, no runtime dependencies).
+ *
+ * Provides besselj, bessely, besseli, besselk for real-valued arguments.
+ */
+export declare function lanczosGamma(x: number): number;
+export declare function besselj(nu: number, x: number): number;
+export declare function bessely(nu: number, x: number): number;
+export declare function besseli(nu: number, x: number): number;
+export declare function besselk(nu: number, x: number): number;
+/**
+ * Airy function of the first kind, Ai(x).
+ */
+export declare function airyAi(x: number): number;
+/**
+ * Derivative of Airy function of the first kind, Ai'(x).
+ */
+export declare function airyAiPrime(x: number): number;
+/**
+ * Airy function of the second kind, Bi(x).
+ */
+export declare function airyBi(x: number): number;
+/**
+ * Derivative of Airy function of the second kind, Bi'(x).
+ */
+export declare function airyBiPrime(x: number): number;
+interface CR {
+    re: number;
+    im: number;
+}
+/**
+ * Compute all four complex Airy functions at once: Ai(z), Ai'(z), Bi(z), Bi'(z).
+ */
+export declare function airyAllComplex(zr: number, zi: number): {
+    ai: CR;
+    aip: CR;
+    bi: CR;
+    bip: CR;
+};
+export {};

package/dist-lib/numbl-core/helpers/check-helpers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Helpers for writing builtin check functions.
+ * These make check implementations shorter and easier to read.
+ */
+import { type FloatXArrayType } from "../runtime/types.js";
+import { RTV, RuntimeValue } from "../runtime/index.js";
+/** Ensure data is Float64Array (needed by LAPACK bridges). */
+export declare function toF64(data: FloatXArrayType): Float64Array;
+/**
+ * Extract and normalize a string argument at runtime.
+ * Strips surrounding quotes and lowercases the result.
+ * Works with both raw string args and RuntimeChar/RuntimeString values.
+ */
+export declare function parseStringArgLower(arg: unknown): string;
+/**
+ * Parse runtime economy-mode argument (0 or 'econ') used by qr, svd, etc.
+ * Returns true for economy mode, false otherwise.
+ */
+export declare function parseEconArgRuntime(arg: RuntimeValue | undefined): boolean;
+/**
+ * Build a (possibly complex) eigenvector matrix from LAPACK's packed real format.
+ *
+ * For complex conjugate eigenvalue pairs, LAPACK stores eigenvectors as:
+ *   Column j:   real part
+ *   Column j+1: imaginary part
+ * Eigenvector for eigenvalue j   is V(:,j) + i*V(:,j+1)
+ * Eigenvector for eigenvalue j+1 is V(:,j) - i*V(:,j+1)
+ */
+export declare function buildEigenvectorMatrix(packedV: Float64Array, wi: Float64Array, n: number, hasComplex: boolean): import("../runtime/types.js").RuntimeTensor;
+/**
+ * Build a tensor, attaching the imaginary part only when it contains non-zero values.
+ * Replaces the repeated `hasComplex ? RTV.tensor(re, shape, im) : RTV.tensor(re, shape)` pattern.
+ */
+export declare function maybeComplexTensor(re: FloatXArrayType | Float64Array, shape: number[], im: FloatXArrayType | Float64Array | undefined): ReturnType<typeof RTV.tensor>;
+/**
+ * Build a diagonal matrix from a vector of values (column-major).
+ * For square matrices pass just n; for rectangular pass [rows, cols].
+ * Optionally includes an imaginary diagonal.
+ */
+export declare function buildDiagMatrix(realVals: Float64Array | FloatXArrayType, imagVals: Float64Array | FloatXArrayType | undefined, size: number | [number, number]): ReturnType<typeof RTV.tensor>;
+/**
+ * In-place Gauss-Jordan elimination with partial pivoting on a column-major
+ * augmented matrix [A | B] of size `rows × totalCols`.
+ */
+export declare function gaussJordanEliminate(aug: FloatXArrayType, rows: number, totalCols: number): void;
+/**
+ * Call a registered builtin from within another builtin's apply().
+ * Convenience wrapper that includes the caller name in error messages.
+ */
+export declare function applyBuiltin(caller: string, name: string, args: RuntimeValue[], nargout: number): RuntimeValue;

package/dist-lib/numbl-core/helpers/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in constant values
+ */
+import { RuntimeValue } from "../runtime/index.js";
+export declare function getConstant(name: string): RuntimeValue | undefined;
+export declare function getAllConstantNames(): string[];

package/dist-lib/numbl-core/helpers/dummy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dummy no-op built-in function names.
+ * Used as placeholders for unsupported functionality.
+ */
+export declare function getDummyBuiltinNames(): string[];

package/dist-lib/numbl-core/helpers/erf.d.ts

@@ -0,0 +1,5 @@
+export declare const erfScalar: (x: number) => number;
+export declare const erfcScalar: (x: number) => number;
+export declare const erfinvScalar: (x: number) => number;
+export declare const erfcinvScalar: (x: number) => number;
+export declare const erfcxScalar: (x: number) => number;

package/dist-lib/numbl-core/helpers/linsolve.d.ts

@@ -0,0 +1,26 @@
+/**
+ * linsolve(A, B) — solve the linear system A * X = B.
+ *
+ * If A is square (m × m), uses LU factorisation (dgesv / dgetrf+solve).
+ * If A is non-square, uses QR / LQ factorisation (dgels / dgeqrf+solve):
+ *   overdetermined  (m > n): least-squares solution minimising ||A*X - B||₂
+ *   underdetermined (m < n): minimum-norm solution minimising ||X||₂
+ *
+ * Both the native LAPACK addon and the ts-lapack TypeScript fallback are
+ * supported; the native addon is preferred when available.
+ */
+import { FloatXArrayType } from "../runtime/types.js";
+/**
+ * Dispatch linsolve to the native addon (preferred) or ts-lapack fallback.
+ * Returns null only when neither bridge exposes `linsolve` (should not happen
+ * in practice since ts-lapack always has it).
+ */
+export declare function linsolveLapack(A: FloatXArrayType, m: number, n: number, B: FloatXArrayType, nrhs: number): Float64Array | null;
+/**
+ * Dispatch complex linsolve to the native addon (preferred) or ts-lapack fallback.
+ * The ts-lapack fallback throws — native addon is required for complex linsolve.
+ */
+export declare function linsolveComplexLapack(ARe: FloatXArrayType, AIm: FloatXArrayType, m: number, n: number, BRe: FloatXArrayType, BIm: FloatXArrayType, nrhs: number): {
+    re: Float64Array;
+    im: Float64Array;
+};

package/dist-lib/numbl-core/helpers/ode-rk.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Adaptive explicit Runge-Kutta ODE solvers.
+ *
+ * Algorithm and coefficients follow the scipy RK45 implementation.
+ * See: https://github.com/scipy/scipy/blob/main/scipy/integrate/_ivp/rk.py
+ *
+ * Pure numerical code — no runtime types.
+ */
+export interface RKTableau {
+    name: string;
+    order: number;
+    errorOrder: number;
+    nStages: number;
+    /** Nodes c_i, length nStages */
+    C: number[];
+    /** RK coefficients a_{s,j}, nStages rows, lower-triangular */
+    A: number[][];
+    /** Higher-order weights, length nStages */
+    B: number[];
+    /** Error coefficients E = bhat - b, length nStages + 1 */
+    E: number[];
+    /** Dense output polynomial coefficients, (nStages+1) x nInterp */
+    P: number[][];
+    /** Number of interpolation polynomial columns */
+    nInterp: number;
+}
+/**
+ * Dormand-Prince 5(4) pair — used by ode45.
+ *
+ * Error controlled assuming 4th-order accuracy; steps taken with
+ * 5th-order formula (local extrapolation). Quartic interpolation
+ * polynomial from Shampine [2].
+ */
+export declare const dormandPrince45: RKTableau;
+/**
+ * Bogacki-Shampine 3(2) pair — used by ode23.
+ *
+ * Error controlled assuming 2nd-order accuracy; steps taken with
+ * 3rd-order formula (local extrapolation). Cubic Hermite polynomial
+ * for the dense output.
+ */
+export declare const bogackiShampine23: RKTableau;
+export interface StepData {
+    tOld: number;
+    tNew: number;
+    h: number;
+    yOld: number[];
+    yNew: number[];
+    /** Q = K^T P, dimensions neq x nInterp */
+    Q: number[][];
+}
+/**
+ * Evaluate the dense output polynomial at fractional position x in [0,1].
+ *
+ * Matches scipy RkDenseOutput._call_impl:
+ *   y = y_old + h * Q @ [x, x^2, ..., x^nInterp]
+ */
+export declare function denseOutputEval(yOld: number[], Q: number[][], h: number, x: number): number[];
+export interface OdeOptions {
+    relTol: number;
+    absTol: number;
+    maxStep: number;
+    initialStep: number;
+    events?: (t: number, y: number[]) => [number[], boolean[], number[]];
+}
+export interface OdeResult {
+    t: number[];
+    y: number[][];
+    te: number[];
+    ye: number[][];
+    ie: number[];
+    steps: StepData[];
+}
+/**
+ * Solve y' = f(t,y) using an adaptive embedded Runge-Kutta method.
+ *
+ * Step control follows scipy RungeKutta._step_impl exactly.
+ */
+export declare function solveRK(tableau: RKTableau, f: (t: number, y: number[]) => number[], tspan: number[], y0: number[], opts: Partial<OdeOptions>): OdeResult;
+export declare function interpolateAtPoints(result: OdeResult, tRequested: number[]): {
+    t: number[];
+    y: number[][];
+};

package/dist-lib/numbl-core/helpers/prng.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Seedable PRNG (xoshiro128**) for random number generation
+ */
+import { RuntimeValue } from "../runtime/index.js";
+export declare function setRngShuffle(): void;
+export declare function setRngSeed(seed: number): void;
+export declare function seedRng(seed: number): void;
+/** Return a random float in [0, 1) using seeded or unseeded PRNG */
+export declare function rngRandom(): number;
+export declare function boxMullerRandom(): number;
+/** Return the current RNG state as a struct {Type, Seed, State} */
+export declare function getRngStateStruct(): RuntimeValue;
+/** Restore RNG state from a struct previously returned by rng() */
+export declare function restoreRngState(s: {
+    kind: "struct";
+    fields: Map<string, RuntimeValue>;
+}): void;

package/dist-lib/numbl-core/helpers/reduction/cumulative.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cumulative and difference builtins: cumsum, cumprod, cummax, cummin, diff.
+ */
+import { RuntimeValue } from "../../runtime/index.js";
+/** Generic cumulative operation along a specified or default dimension.
+ *  Supports cumsum(A), cumsum(A, dim), etc. for arbitrary N-D arrays. */
+export declare function cumOp(name: string, args: RuntimeValue[], accumFn: (acc: number, val: number) => number, initial?: number, complexAccumFn?: (accRe: number, accIm: number, valRe: number, valIm: number) => [number, number]): RuntimeValue;
+export declare function diffOnce(v: RuntimeValue, dim?: number): RuntimeValue;

package/dist-lib/numbl-core/helpers/reduction/min-max.d.ts

@@ -0,0 +1,5 @@
+/**
+ * min/max builtin functions.
+ */
+import { RuntimeValue } from "../../runtime/index.js";
+export declare function minMaxImpl(name: string, args: RuntimeValue[], nargout: number, initial: number, isBetter: (candidate: number, current: number) => boolean, twoArgFn: (a: number, b: number) => number): RuntimeValue | RuntimeValue[];

package/dist-lib/numbl-core/helpers/reduction-helpers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared helpers for reduction operations: dimension iteration, type checks,
+ * reduction factories, sparse helpers, and logical/complex scan utilities.
+ */
+import { RuntimeValue } from "../runtime/index.js";
+import { type RuntimeTensor, type RuntimeSparseMatrix } from "../runtime/types.js";
+/** Iterate over all 1-D fibers along `dim` (1-based).
+ * For each fiber, calls `callback(outIndex, srcIndices)` where
+ * `srcIndices` is an array of flat indices into the source data.
+ * Returns `{ resultShape, totalElems }` (resultShape is squeezed).
+ * Returns null if dim exceeds the tensor's rank. */
+export declare function forEachSlice(shape: number[], dim: number, callback: (outIdx: number, srcIndices: number[]) => void): {
+    resultShape: number[];
+    totalElems: number;
+} | null;
+/** Return 1-based dim to reduce along (first non-singleton), or 0 for "reduce to scalar". */
+export declare function firstReduceDim(shape: number[]): number;
+/** Return a deep copy of a tensor (data + shape + optional imag). */
+export declare function copyTensor(v: RuntimeTensor): RuntimeValue;
+/**
+ * Complex product reduction. Can't use the independent real/imag approach
+ * because (a+bi)(c+di) = (ac-bd)+(ad+bc)i mixes both parts.
+ */
+export declare function complexProd(v: RuntimeTensor, dim?: number): RuntimeValue;
+/** Scan tensor elements for logical reduction (any/all).
+ * mode 'any': returns true if any element is nonzero.
+ * mode 'all': returns true if all elements are nonzero (true for empty). */
+export declare function scanLogical(data: ArrayLike<number>, imag: ArrayLike<number> | undefined, mode: "any" | "all"): boolean;
+/** Reduce a tensor along a dimension using a logical test (any/all). */
+export declare function logicalAlongDim(v: RuntimeTensor, dim: number, mode: "any" | "all"): RuntimeValue;
+/** Sum a sparse matrix along dim 1 (columns) or dim 2 (rows).
+ *  Returns sparse for dim=1, dense tensor for dim=2. */
+export declare function sparseSum(v: RuntimeSparseMatrix, dim: number): RuntimeValue;
+/** any/all on sparse matrix along a dimension.
+ *  Returns sparse for dim=1, dense for dim=2. */
+export declare function sparseAnyAll(v: RuntimeSparseMatrix, dim: number, mode: "any" | "all"): RuntimeValue;
+/** Type check for reductions that return Num without dim arg, Tensor with dim arg. */
+/** Strip trailing 'omitnan'/'includenan' from args. Returns cleaned args and flag. */
+export declare function parseNanFlag(args: RuntimeValue[]): {
+    args: RuntimeValue[];
+    omitNaN: boolean;
+};
+/** Filter NaN values from a Float64Array, returning a new (possibly shorter) array. */
+export declare function filterNaN(arr: ArrayLike<number>): Float64Array;
+export type ReductionKernel = {
+    reduceAll: (v: RuntimeTensor) => RuntimeValue;
+    reduceDim: (v: RuntimeTensor, dim: number) => RuntimeValue;
+};
+/** Create an accumulator-based reduction kernel (sum, mean, etc.) */
+export declare function accumKernel(reduceFn: (acc: number, val: number) => number, initial: number, finalizeFn?: (acc: number, count: number) => number): ReductionKernel;
+/** Create a slice-based reduction kernel (median, mode, etc.) */
+export declare function sliceKernel(sliceFn: (slice: ArrayLike<number>) => number): ReductionKernel;
+/** Create an accumulator kernel that skips NaN values. */
+export declare function accumKernelOmitNaN(reduceFn: (acc: number, val: number) => number, initial: number, finalizeFn?: (acc: number, count: number) => number): ReductionKernel;
+/** Create a slice kernel that filters NaN before applying the function. */
+export declare function sliceKernelOmitNaN(sliceFn: (slice: ArrayLike<number>) => number): ReductionKernel;
+/** Helper: extract all numeric values from a RuntimeValue as a plain array. */
+export declare function toNumArray(v: RuntimeValue, name: string): number[];

package/dist-lib/numbl-core/helpers/registry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Builtin name registry: tracks which names are recognized as builtins.
+ */
+/** Register additional builtin names so isBuiltin() recognizes them. */
+export declare function registerExtraBuiltinNames(names: Iterable<string>): void;
+export declare function isBuiltin(name: string): boolean;
+export declare function getAllBuiltinNames(): string[];

package/dist-lib/numbl-core/helpers/shape-utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared shape/size argument parsing and value coercion for builtins.
+ */
+import { type RuntimeValue } from "../runtime/index.js";
+import { type RuntimeTensor } from "../runtime/types.js";
+/** Promote a scalar (number, logical, complex) to a 1×1 tensor. Tensors pass through. */
+export declare function coerceToTensor(v: RuntimeValue, name: string): RuntimeTensor;

package/dist-lib/numbl-core/helpers/sparse-arithmetic.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sparse matrix arithmetic operations (with complex support).
+ */
+import { type RuntimeValue, type RuntimeSparseMatrix, type RuntimeTensor } from "../runtime/types.js";
+/** Convert a sparse matrix to dense. */
+declare function sparseToDense(S: RuntimeSparseMatrix): RuntimeTensor;
+export declare function sparseNeg(S: RuntimeSparseMatrix): RuntimeSparseMatrix;
+export declare function sparseTranspose(S: RuntimeSparseMatrix): RuntimeSparseMatrix;
+export declare function sparseConjugateTranspose(S: RuntimeSparseMatrix): RuntimeSparseMatrix;
+export declare function mAddSparse(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mSubSparse(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mMulSparse(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mElemMulSparse(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mElemDivSparse(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Convert sparse to dense RuntimeTensor (exported for use in arithmetic dispatch). */
+export { sparseToDense };

package/dist-lib/numbl-core/helpers/string.d.ts

@@ -0,0 +1,5 @@
+/**
+ * String manipulation builtin functions
+ */
+import { type RuntimeValue } from "../runtime/index.js";
+export declare function sprintfFormat(fmt: string, args: RuntimeValue[]): string;

package/dist-lib/numbl-core/interpreter/builtins/arithmetic.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Binary scalar builtins: atan2, min, max, mod, rem, power.
+ */
+export {};