numbl 0.4.5 → 0.4.6

package/dist-lib/numbl-core/executors/plugins.d.ts

@@ -10,6 +10,15 @@
  * registered executor.
  */
 import type { Registry } from "./registry.js";
+import type { Executor } from "./types.js";
+/** The three C-JIT executors, registered at Node bootstrap. */
+export interface CJitExecutors {
+    topLevel: Executor;
+    loop: Executor;
+    call: Executor;
+}
+/** Register the C-JIT executors. Called once at Node bootstrap. */
+export declare function registerCJitExecutors(execs: CJitExecutors): void;
 /** Optimization mode label.
  *
  *   - `"0"` — pure AST interpreter, no executors registered.

package/dist-lib/numbl-core/helpers/marching-cubes-tables.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Marching-cubes lookup tables (Paul Bourke / Lorensen-Cline).
+ *
+ * Vendored verbatim from mikolalysenko/isosurface (MIT). Generated from
+ * lib/marchingcubes.js; do not edit by hand.
+ */
+export declare const edgeTable: Uint32Array<ArrayBuffer>;
+export declare const triTable: number[][];
+export declare const cubeVerts: number[][];
+export declare const edgeIndex: number[][];

package/dist-lib/numbl-core/helpers/marching-cubes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Marching cubes over a regular scalar grid, plus the MATLAB `isosurface`
+ * argument parsing. Backs the `isosurface` builtin.
+ *
+ * The 256-case lookup tables are vendored in `marching-cubes-tables.ts`
+ * (MIT, mikolalysenko/isosurface — Paul Bourke's classic table). The loop
+ * here adds the two things that library lacks for our use:
+ *   - vertices interpolated from arbitrary X/Y/Z coordinate arrays (so it is
+ *     correct for ndgrid, meshgrid, vector, and implicit grids), and
+ *   - cross-cell vertex sharing (keyed by grid-edge identity), which MATLAB
+ *     produces by default and which downstream code (e.g. triangle adjacency)
+ *     relies on.
+ */
+import type { RuntimeValue } from "../runtime/types.js";
+export interface IsoMesh {
+    /** Physical vertex coordinates, one `[x, y, z]` per vertex. */
+    vertices: number[][];
+    /** Triangles as 0-based vertex-index triples. */
+    faces: number[][];
+    /** Per-vertex scalar color data (present only when a colors array is given). */
+    colors?: number[];
+}
+type ScalarFn = (i: number, j: number, k: number) => number;
+type CoordFn = (i: number, j: number, k: number) => [number, number, number];
+/**
+ * Extract the isosurface of `getVal` at `iso` over an `m×n×p` grid.
+ * `getCoord` maps a grid corner to its physical position; `getColor` (if
+ * given) supplies a scalar field interpolated onto the surface vertices.
+ */
+export declare function marchingCubes(dims: [number, number, number], getVal: ScalarFn, getCoord: CoordFn, iso: number, opts?: {
+    share?: boolean;
+    getColor?: ScalarFn;
+}): IsoMesh;
+/**
+ * Parse `isosurface(...)` arguments and compute the mesh.
+ *
+ * Forms (by numeric-argument count, after stripping 'verbose'/'noshare'):
+ *   1: isosurface(V)               4: isosurface(X,Y,Z,V)
+ *   2: isosurface(V,iso)           5: isosurface(X,Y,Z,V,iso)
+ *   3: isosurface(V,iso,colors)    6: isosurface(X,Y,Z,V,iso,colors)
+ *
+ * When the isovalue is omitted it is chosen automatically (see autoIsovalue) —
+ * an approximation that does not match MATLAB's exact histogram heuristic.
+ */
+export declare function isosurfaceFromArgs(args: RuntimeValue[]): IsoMesh;
+export {};

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

@@ -1,4 +1,10 @@
 /**
  * Array construction builtins: zeros, ones, nan/NaN, eye, linspace, logspace.
  */
-export {};
+import type { RuntimeValue } from "../../runtime/types.js";
+import type { JitType } from "../../jitTypes.js";
+/** Drop a trailing class-name spec from the JIT arg types (used in `match`
+ *  so the size cases still apply when a class string is present). */
+export declare function stripClassNameTypes(argTypes: JitType[]): JitType[];
+/** Drop a trailing class-name spec from the runtime args (used in `apply`). */
+export declare function stripClassNameArgs(args: RuntimeValue[]): RuntimeValue[];

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

@@ -0,0 +1,10 @@
+/**
+ * Interpreter IBuiltins for computational geometry functions: delaunay,
+ * delaunayn, inpolygon.
+ *
+ * delaunay/delaunayn are backed by the qhull WASM module, installed as the
+ * Delaunay backend at startup (see geometry-bridge.ts and the qhull-node /
+ * qhull-browser loaders). The backend must be installed before these builtins
+ * run; otherwise they throw.
+ */
+export {};

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

@@ -28,6 +28,7 @@ import "./time-system.js";
 import "./datetime.js";
 import "./sparse.js";
 import "./special-math.js";
+import "./geometry.js";
 import "./misc.js";
 import "./dictionary.js";
 import "./help-text.js";

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

@@ -119,6 +119,7 @@ export declare class Interpreter {
     evalBinary: (expr: Extract<Expr, {
         type: "Binary";
     }>) => unknown;
+    evalCondition: (expr: Expr) => unknown;
     evalUnary: (expr: Extract<Expr, {
         type: "Unary";
     }>) => unknown;

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

@@ -20,6 +20,17 @@ export declare function evalArgs(this: Interpreter, argExprs: Expr[]): unknown[]
 export declare function evalBinary(this: Interpreter, expr: Extract<Expr, {
     type: "Binary";
 }>): unknown;
+/**
+ * Evaluate an `if`/`while`/`elseif` condition.
+ *
+ * MATLAB short-circuits the element-wise `&` and `|` operators when they
+ * appear at the top of a conditional expression and the left operand is
+ * scalar — e.g. `if nargin<4 | isempty(x)` must NOT evaluate `isempty(x)`
+ * when `nargin<4` (otherwise `x` may be undefined). Outside this context
+ * `&`/`|` evaluate both operands element-wise, so the special handling
+ * lives here rather than in `evalBinary`.
+ */
+export declare function evalCondition(this: Interpreter, expr: Expr): unknown;
 export declare function evalUnary(this: Interpreter, expr: Extract<Expr, {
     type: "Unary";
 }>): unknown;

package/dist-lib/numbl-core/jit/builtins/runtime/snippets.c.gen.d.ts

@@ -0,0 +1,4 @@
+/** C snippet bodies, keyed by basename (e.g. `disp_double.h`).
+ *  C-JIT only (`--opt 2`, Node). Registered at bootstrap via
+ *  `setCSnippets` so the browser bundle never pulls it in. */
+export declare const C_SNIPPETS: Record<string, string>;

package/dist-lib/numbl-core/jit/builtins/runtime/snippets.gen.d.ts

@@ -72,8 +72,6 @@ export * from "./tensor_ops/tensor_var.js";
 export * from "./tensor_ops/tensor_zeros_nd.js";
 export * from "./tensor_ops/tensor_zeros_square.js";
 export * from "./text/strcmp.js";
-/** C snippet bodies, keyed by basename (e.g. `disp_double.h`). */
-export declare const C_SNIPPETS: Record<string, string>;
 /** JS snippet bodies (with `export` keywords stripped), keyed by
  *  basename (e.g. `disp_double.js`). Inlined into emitted JS. The
  *  functions may reference host hooks (`$write`, …) as free

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

@@ -14,6 +14,8 @@
  * pulls dependencies in first.
  */
 import type { Builtin } from "../builtins/registry.js";
+/** Register the C runtime-snippet table. Called once at Node bootstrap. */
+export declare function setCSnippets(snippets: Record<string, string>): void;
 /** Minimal Workspace shape consulted at emit time. Importing the
  *  concrete Workspace class would create a cycle (workspace ↔ codegen);
  *  the structural type below captures exactly what codegen needs. */

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

@@ -0,0 +1,29 @@
+/**
+ * Geometry bridge — a module-level singleton that holds the Delaunay
+ * triangulation backend.
+ *
+ * Startup (CLI, browser worker, test-runner) loads the qhull WASM module
+ * (exact, robust to cospherical/coplanar input) and installs it here. The
+ * builtins require it: if no backend is set, delaunay/delaunayn throw.
+ *
+ * Usage (startup):
+ *   import { setDelaunayBackend } from './numbl-core/native/geometry-bridge.js';
+ *   const qhull = await loadQhull();
+ *   setDelaunayBackend((points, dim) => qhull.delaunay(points, dim).facets);
+ *
+ * Usage (builtin):
+ *   import { getDelaunayBackend } from '../native/geometry-bridge.js';
+ *   const backend = getDelaunayBackend();
+ *   if (!backend) throw ...;
+ *   const cells = backend(points, dim);
+ */
+/**
+ * Compute a Delaunay triangulation of `points` (an array of dim-dimensional
+ * tuples). Returns an array of simplices, each a list of `dim+1` 0-based input
+ * point indices.
+ */
+export type DelaunayBackend = (points: number[][], dim: number) => number[][];
+/** Install (or clear, with null) the Delaunay backend. */
+export declare function setDelaunayBackend(fn: DelaunayBackend | null): void;
+/** Get the current Delaunay backend, or null if none is installed. */
+export declare function getDelaunayBackend(): DelaunayBackend | null;

package/dist-lib/numbl-core/native/qhull-browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser/worker loader for the qhull WASM Delaunay backend.
+ *
+ * The CLI installs the backend in cli.ts (reading the `.wasm` from disk). In
+ * the browser there is no filesystem, so we let Vite emit the `.wasm` as an
+ * asset (`?url`), fetch its bytes, and pass them to the emscripten module as
+ * `wasmBinary` — this avoids relying on the glue locating the binary next to
+ * itself at runtime.
+ *
+ * `ensureQhullBackend()` is idempotent and best-effort: on any failure it
+ * resolves anyway (so it never crashes the worker), but then no backend is
+ * installed and a later `delaunay`/`delaunayn` call throws (see geometry.ts).
+ */
+/** Load and install the qhull backend (once). Safe to await before every run. */
+export declare function ensureQhullBackend(): Promise<void>;

package/dist-lib/numbl-core/native/qhull-node.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Node loader for the qhull WASM Delaunay backend.
+ *
+ * In Node the emscripten module reads its `.wasm` from disk on its own, so no
+ * asset wiring is needed (unlike the browser; see qhull-browser.ts). This is
+ * used by the CLI, the vitest setup, and is re-exported from the library entry
+ * (lib.ts) so programmatic consumers can install the backend before calling
+ * `delaunay` / `delaunayn`.
+ *
+ * Idempotent: the first call starts loading and caches the promise.
+ */
+/** Load the qhull WASM module and install it as the Delaunay backend (once). */
+export declare function loadQhullNodeBackend(): Promise<void>;

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

@@ -77,6 +77,24 @@ export declare function parsePatchArgs(args: RuntimeValue[]): PatchTrace;
  *   fill(ax, ___)
  */
 export declare function parseFillArgs(args: RuntimeValue[]): PatchTrace[];
+/**
+ * Parse trimesh() arguments into a canonical PatchTrace.
+ *
+ * trimesh draws a triangular mesh and (per the MATLAB docs) returns a patch
+ * object, so it maps onto the PatchTrace model: the connectivity matrix T
+ * supplies the faces (one triangle per row, 1-based vertex indices) and the
+ * x/y[/z] vectors supply the vertices.
+ *
+ * Supported forms:
+ *   trimesh(T, x, y)              — 2-D triangular mesh
+ *   trimesh(T, x, y, z)           — 3-D triangular mesh
+ *   trimesh(T, x, y, z, c)        — c is per-vertex color data
+ *   trimesh(TO)                   — triangulation object (struct exposing
+ *                                   ConnectivityList + Points)
+ *   trimesh(___, Name, Value)     — patch properties
+ *   trimesh(ax, ___)              — leading axes handle (ignored)
+ */
+export declare function parseTriMeshArgs(args: RuntimeValue[]): PatchTrace;
 /**
  * Parse surf() arguments.
  *

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

@@ -73,6 +73,7 @@ export declare function plotCall(plotInstructions: PlotInstruction[], args: Runt
 export declare function plot3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function lineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function patchCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function trimeshCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function fillCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfaceCall(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.4.5";
+export declare const NUMBL_VERSION = "0.4.6";