numbl 0.1.4 → 0.1.6

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

@@ -54,11 +54,20 @@ export interface BuiltinProfileBreakdown {
     /** Calls from JIT-compiled code (ib_* helpers). */
     jit: BuiltinProfileEntry;
 }
+export interface HotLoopEntry {
+    file: string;
+    line: number;
+    kind: "for" | "while";
+    iterations: number;
+    callCount: number;
+    totalTimeMs: number;
+}
 export interface ProfileData {
     executionTimeMs: number;
     jitCompileTimeMs: number;
     builtins: Record<string, BuiltinProfileBreakdown>;
     dispatches: Record<string, BuiltinProfileEntry>;
+    hotLoops: HotLoopEntry[];
 }
 export interface ExecResult {
     output: string[];

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

@@ -39,6 +39,10 @@ export type ResolvedTarget = {
     kind: "workspaceFunction";
     name: string;
     argTypes: ItemType[];
+} | {
+    kind: "jsUserFunction";
+    name: string;
+    argTypes: ItemType[];
 } | {
     kind: "workspaceClassConstructor";
     className: string;

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

@@ -0,0 +1,51 @@
+/**
+ * Core GMRES (Generalized Minimum Residual) algorithm.
+ *
+ * Callback-based interface so the same code handles both dense matrices
+ * (dispatched through the LAPACK bridge) and function-handle arguments
+ * (dispatched through the runtime).
+ */
+export interface GmresResult {
+    x: Float64Array;
+    flag: number;
+    relres: number;
+    iter: [number, number];
+    resvec: Float64Array;
+}
+export type MatvecFn = (x: Float64Array) => Float64Array;
+export type PrecSolveFn = (r: Float64Array) => Float64Array;
+/**
+ * Restarted GMRES with left preconditioning and Givens rotations.
+ *
+ * @param matvec    Computes A*x
+ * @param precSolve Computes M\x (or null for no preconditioning)
+ * @param b         Right-hand side (length n)
+ * @param n         System dimension
+ * @param restart   Inner iteration count (use n for no restart)
+ * @param tol       Convergence tolerance on relative preconditioned residual
+ * @param maxit     Maximum number of outer iterations
+ * @param x0        Initial guess (or null for zeros)
+ */
+export declare function gmresCore(matvec: MatvecFn, precSolve: PrecSolveFn | null, b: Float64Array, n: number, restart: number, tol: number, maxit: number, x0: Float64Array | null): GmresResult;
+export interface ComplexVec {
+    re: Float64Array;
+    im: Float64Array;
+}
+export interface GmresComplexResult {
+    x: ComplexVec;
+    flag: number;
+    relres: number;
+    iter: [number, number];
+    resvec: Float64Array;
+}
+export type ComplexMatvecFn = (x: ComplexVec) => ComplexVec;
+export type ComplexPrecSolveFn = (r: ComplexVec) => ComplexVec;
+/** Restarted GMRES for complex systems. */
+export declare function gmresCoreComplex(matvec: ComplexMatvecFn, precSolve: ComplexPrecSolveFn | null, b: ComplexVec, n: number, restart: number, tol: number, maxit: number, x0: ComplexVec | null): GmresComplexResult;
+/** Complex LU solve in-place (split re/im). LU and ipiv from zgetrf-style factorization. */
+export declare function complexLuSolveInPlace(n: number, LURe: Float64Array, LUIm: Float64Array, ipiv: Int32Array, rhsRe: Float64Array, rhsIm: Float64Array): void;
+/**
+ * Apply row permutation + forward/back substitution to solve a pre-factored
+ * LU system in-place.  LU and ipiv come from dgetrf (1-based pivots).
+ */
+export declare function luSolveInPlace(n: number, LU: Float64Array, ipiv: Int32Array, rhs: Float64Array): void;

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

@@ -119,6 +119,9 @@ export declare class Interpreter {
     interpretWorkspaceFunction: (target: Extract<ResolvedTarget, {
         kind: "workspaceFunction";
     }>, args: unknown[], nargout: number) => unknown;
+    interpretJsUserFunction: (target: Extract<ResolvedTarget, {
+        kind: "jsUserFunction";
+    }>, args: unknown[], nargout: number) => unknown;
     interpretClassMethod: (target: Extract<ResolvedTarget, {
         kind: "classMethod";
     }>, args: unknown[], nargout: number) => unknown;

package/dist-lib/numbl-core/interpreter/interpreterFunctions.d.ts

@@ -9,6 +9,9 @@ import { Environment, type FunctionDef } from "./types.js";
 import type { Interpreter } from "./interpreter.js";
 export declare function callFunction(this: Interpreter, name: string, args: unknown[], nargout: number): unknown;
 export declare function interpretTarget(this: Interpreter, target: ResolvedTarget, args: unknown[], nargout: number): unknown;
+export declare function interpretJsUserFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "jsUserFunction";
+}>, args: unknown[], nargout: number): unknown;
 export declare function interpretLocalFunction(this: Interpreter, target: Extract<ResolvedTarget, {
     kind: "localFunction";
 }>, args: unknown[], nargout: number): unknown;

package/dist-lib/numbl-core/interpreter/interpreterSpecialBuiltins.d.ts

@@ -12,9 +12,14 @@ export interface InterpreterContext {
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
     callFunction: (name: string, args: unknown[], nargout: number) => unknown;
     rt: Runtime;
-    /** Resolve a workspace function or class name to its source file path,
-     *  or undefined if no workspace file provides that name. */
-    lookupWorkspaceFile: (name: string) => string | undefined;
+    /** Resolve a workspace function or class name to its source file,
+     *  or undefined if no workspace file provides that name.
+     *  `kind` distinguishes a regular .m function from a .numbl.js
+     *  user function (treated as a MEX-equivalent) or a class file. */
+    lookupWorkspaceFile: (name: string) => {
+        path: string;
+        kind: "function" | "jsfunction" | "class";
+    } | undefined;
 }
 export declare const FALL_THROUGH: unique symbol;
 export type InterpreterSpecialBuiltinHandler = (ctx: InterpreterContext, args: unknown[], nargout: number) => unknown | typeof FALL_THROUGH;

package/dist-lib/numbl-core/interpreter/jit/jitHelpers.d.ts

@@ -3,3 +3,12 @@
  * Passed as `$h` to generated functions.
  */
 export declare const jitHelpers: Record<string, unknown>;
+import type { IBuiltin } from "../builtins/index.js";
+/**
+ * Build a per-runtime jitHelpers map for an execution that has .numbl.js
+ * user functions. The result is a clone of the global jitHelpers extended
+ * with `ib_<name>` entries (single-output fast path) for each js user
+ * function and an overridden `ibcall` (multi-output) that consults the
+ * js user function map first before falling back to the global registry.
+ */
+export declare function buildPerRuntimeJitHelpers(jsUserFunctions: ReadonlyMap<string, IBuiltin>): Record<string, any>;

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

@@ -1,25 +1,40 @@
 /**
- * Loader for .js user functions.
+ * Loader for .numbl.js user functions.
  *
- * Evaluates .js files that define IBuiltins via register({ resolve, jitEmit? }).
+ * Evaluates .numbl.js files that define IBuiltins via
+ *   register({ resolve, jitEmit? }).
  * Supports optional WASM and native shared library bindings via directives:
  *   // wasm: <name>
  *   // native: <name>
+ *
+ * The `.numbl.js` extension distinguishes numbl user functions from
+ * unrelated `.js` files (config files, source maps, etc.) so that they can
+ * be auto-discovered from the current working directory like `.m` files.
  */
 import type { WorkspaceFile, NativeBridge } from "./workspace/index.js";
 import type { IBuiltin } from "./interpreter/builtins/types.js";
+/** A loaded JS user function ready for registration in the workspace. */
+export interface LoadedJsUserFunction {
+    name: string;
+    fileName: string;
+    builtin: IBuiltin;
+}
+/** Returns true if the file is a numbl JS user function file (`*.numbl.js`). */
+export declare function isNumblJsFile(fileName: string): boolean;
 /**
- * Load .js user function files and return them as IBuiltin objects.
+ * Load .numbl.js user function files and return them as LoadedJsUserFunction
+ * records. Each loaded record carries the function name, source file name,
+ * and the IBuiltin object built from the file's `register()` call.
  *
- * Each .js file calls register({ resolve, jitEmit? }) to define an IBuiltin.
- * resolve(argTypes, nargout) returns { outputTypes, apply } or null.
+ * Each .numbl.js file calls register({ resolve, jitEmit? }) to define an
+ * IBuiltin. resolve(argTypes, nargout) returns { outputTypes, apply } or null.
  *
- * A .js file can specify bindings via directives at the top of the file:
+ * A .numbl.js file can specify bindings via directives at the top of the file:
  *   // wasm: <name>    — load a WASM module (looked up by name in wasmFiles)
- *   // native: <name>  — load a native shared library (resolved relative to .js file)
+ *   // native: <name>  — load a native shared library (resolved relative to file)
  *
  * Files whose basename starts with `_` are library files. They must not call
- * register() and instead export values via `return`. Other .js files can import
- * them with `importJS("_name")`.
+ * register() and instead export values via `return`. Other .numbl.js files
+ * can import them with `importJS("_name")`.
  */
-export declare function loadJsUserFunctions(jsFiles: WorkspaceFile[], wasmFiles?: WorkspaceFile[], nativeBridge?: NativeBridge): IBuiltin[];
+export declare function loadJsUserFunctions(jsFiles: WorkspaceFile[], wasmFiles?: WorkspaceFile[], nativeBridge?: NativeBridge): LoadedJsUserFunction[];

package/dist-lib/numbl-core/lowering/loweringContext.d.ts

@@ -5,6 +5,7 @@
  * building, and on-demand context creation for workspace/class files.
  */
 import { type AbstractSyntaxTree, type Stmt } from "../parser/index.js";
+import type { IBuiltin } from "../interpreter/builtins/index.js";
 import type { WorkspaceFile } from "../../numbl-core/workspace/index.js";
 import { type ClassInfo } from "./classInfo.js";
 import { type ExternalAccessDirectives } from "../externalAccessDirective.js";
@@ -17,6 +18,11 @@ interface WorkspaceRegistry {
         fileName: string;
         source: string;
     }>;
+    /** JS user functions (.numbl.js): functionName → { fileName, builtin } */
+    jsUserFunctionsByName: Map<string, {
+        fileName: string;
+        builtin: IBuiltin;
+    }>;
     /** Per-workspace-file lowering contexts (created on demand) */
     fileContexts: Map<string, LoweringContext>;
     /** Workspace classes: qualifiedName → ClassInfo */
@@ -138,6 +144,11 @@ export declare class LoweringContext {
     isWorkspaceFunction(name: string): boolean;
     /** Clear workspace-level registrations so they can be rebuilt after addpath/rmpath. */
     clearWorkspaceRegistrations(): void;
+    /**
+     * Register a JS user function (.numbl.js) in the workspace registry.
+     * Uses first-wins semantics so search-path priority is honored.
+     */
+    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
     /**
      * Get the effective directory for this context's file, used for
      * private function resolution. If the file is inside a private/ folder,
@@ -200,7 +211,7 @@ export declare class LoweringContext {
      * Should be called once after registerWorkspaceFiles() and registerLocalFunctionAST().
      * Parses all workspace files eagerly to discover subfunctions.
      */
-    buildFunctionIndex(jsUserFunctionNames?: string[]): FunctionIndex;
+    buildFunctionIndex(): FunctionIndex;
     /** Get the function index (must call buildFunctionIndex() first on any context sharing the same registry). */
     get functionIndex(): FunctionIndex;
 }

package/dist-lib/numbl-core/native/lapack-bridge.d.ts

@@ -18,7 +18,7 @@
  * Expected native addon version. Bump this whenever the C++ addon API changes
  * (must match ADDON_VERSION in numbl_addon.cpp).
  */
-export declare const NATIVE_ADDON_EXPECTED_VERSION = 1;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 2;
 export interface LapackBridge {
     /** Returns the native addon's version number. */
     addonVersion?(): number;
@@ -395,6 +395,38 @@ export interface LapackBridge {
     elemwise?(a: Float64Array, b: Float64Array, op: number): Float64Array;
     /** Scalar-tensor element-wise op. scalarOnLeft: true → scalar op arr[i], false → arr[i] op scalar */
     elemwiseScalar?(scalar: number, arr: Float64Array, op: number, scalarOnLeft: boolean): Float64Array;
+    /**
+     * Restarted GMRES solver for A*x = b (real, dense matrices only).
+     * Uses BLAS dgemv for matvec and LAPACK dgetrf+dgetrs for preconditioner.
+     * @param A       Column-major Float64Array of length n*n (not modified).
+     * @param n       System dimension.
+     * @param b       Right-hand side Float64Array of length n.
+     * @param restart Inner iterations per restart cycle (use n for no restart).
+     * @param tol     Convergence tolerance on relative preconditioned residual.
+     * @param maxit   Maximum number of outer iterations.
+     * @param M1      Preconditioner factor 1 (n×n column-major), or null.
+     * @param M2      Preconditioner factor 2 (n×n column-major), or null.
+     * @param x0      Initial guess (length n), or null for zeros.
+     * @returns       Object with x, flag, relres, iter (Int32Array[2]), resvec.
+     */
+    gmres?(A: Float64Array, n: number, b: Float64Array, restart: number, tol: number, maxit: number, M1: Float64Array | null, M2: Float64Array | null, x0: Float64Array | null): {
+        x: Float64Array;
+        flag: number;
+        relres: number;
+        iter: Int32Array;
+        resvec: Float64Array;
+    };
+    /**
+     * Complex restarted GMRES solver for A*x = b (split real/imag dense matrices).
+     */
+    gmresComplex?(ARe: Float64Array, AIm: Float64Array, n: number, bRe: Float64Array, bIm: Float64Array, restart: number, tol: number, maxit: number, M1Re: Float64Array | null, M1Im: Float64Array | null, M2Re: Float64Array | null, M2Im: Float64Array | null, x0Re: Float64Array | null, x0Im: Float64Array | null): {
+        xRe: Float64Array;
+        xIm: Float64Array;
+        flag: number;
+        relres: number;
+        iter: Int32Array;
+        resvec: Float64Array;
+    };
     /** Element-wise binary op on complex Float64Arrays. op: 0=add, 1=sub, 2=mul, 3=div */
     elemwiseComplex?(aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, op: number): {
         re: Float64Array;

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

@@ -46,6 +46,8 @@ export declare class RuntimeError extends Error {
      * Format error with location and snippet context.
      */
     toString(): string;
+    /** Format error with MATLAB-style call stack. */
+    private _formatWithCallStack;
     /** Look up a single trimmed source line from fileSources. */
     private _getSourceLine;
 }

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

@@ -5,8 +5,8 @@
  * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
  */
 import { type RuntimeValue } from "./types.js";
-export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace } from "../../graphics/types.js";
+export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, } from "../../graphics/types.js";
+import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace } from "../../graphics/types.js";
 export interface ParsedLineSpec {
     color?: string;
     lineStyle?: string;
@@ -35,6 +35,15 @@ export declare function parsePlot3Args(args: RuntimeValue[]): Plot3Trace[];
  *   surf(..., Name, Value) — name-value pairs
  */
 export declare function parseSurfArgs(args: RuntimeValue[]): SurfTrace;
+/**
+ * Parse pcolor() arguments.
+ *
+ * Supported forms:
+ *   pcolor(C)         — C is m×n, X = 1:n, Y = 1:m
+ *   pcolor(X, Y, C)   — X, Y, C are m×n matrices (or X is 1×n / Y is m×1)
+ *   pcolor(..., Name, Value) — name-value pairs (EdgeColor, FaceAlpha)
+ */
+export declare function parsePcolorArgs(args: RuntimeValue[]): PcolorTrace;
 /**
  * Parse scatter() arguments.
  *

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

@@ -80,6 +80,7 @@ export declare class Runtime {
     system?: SystemAdapter;
     builtins: Record<string, (nargout: number, args: unknown[]) => unknown>;
     customBuiltins: Record<string, (nargout: number, args: unknown[]) => unknown>;
+    jitHelpers: Record<string, any> | null;
     compileSpecialized: ((name: string, argTypes: ItemType[], callSite: CallSite) => ((...args: any[]) => any) | null) | null;
     evalLocalCallback: ((code: string, initialVars: Record<string, RuntimeValue>, onOutput: (text: string) => void, fileName?: string) => {
         returnValue: unknown;
@@ -94,6 +95,14 @@ export declare class Runtime {
     private profileStack;
     private profileAccum;
     private profileCounts;
+    hotLoops: Map<string, {
+        file: string;
+        line: number;
+        kind: "for" | "while";
+        iterations: number;
+        callCount: number;
+        totalTimeMs: number;
+    }>;
     constructor(options: ExecOptions, initialVariableValues?: Record<string, RuntimeValue> | undefined);
     private initBuiltins;
     profileEnter(key: string): void;
@@ -284,6 +293,7 @@ export declare class Runtime {
     surf_call(args: RuntimeValue[]): void;
     scatter_call(args: RuntimeValue[]): void;
     imagesc_call(args: RuntimeValue[]): void;
+    pcolor_call(args: RuntimeValue[]): void;
     contour_call(args: RuntimeValue[], filled: boolean): void;
     mesh_call(args: RuntimeValue[]): void;
     bar_call(args: RuntimeValue[]): void;

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

@@ -50,18 +50,24 @@ export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
 } | {
     type: "set_colorbar";
     value: unknown;
+    location?: unknown;
 } | {
     type: "set_colormap";
     name: unknown;
+    data?: number[][];
 } | {
     type: "set_axis";
     value: unknown;
+} | {
+    type: "set_caxis";
+    limits: [number, number];
 }): void;
 export declare function viewCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function plotCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function plot3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function imagescCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function pcolorCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function contourCall(plotInstructions: PlotInstruction[], args: RuntimeValue[], filled: boolean): void;
 export declare function meshCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function scatterCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;

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

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