numbl 0.4.0 → 0.4.2

package/dist-lib/numbl-core/helpers/effectively-real.d.ts

@@ -0,0 +1,25 @@
+/**
+ * "Effectively real" helpers.
+ *
+ * numbl's JIT cannot always prove at compile time that the result of an
+ * operation is real (e.g. `sqrt(1 - x.^2/2)` — the argument's sign is not
+ * statically provable, so `sqrt` lifts to the complex path). The result is
+ * a complex-typed tensor whose imaginary lane is entirely zero — an
+ * artifact of static typing, not a value the user asked to be complex.
+ *
+ * Value-sensitive builtins (`isreal`, `min`, `max`, `sort`, …) must treat
+ * such a tensor exactly as they would a real one: otherwise `min`/`max`
+ * silently switch to magnitude ordering and `isreal` reports `false`,
+ * diverging from the interpreter (`--opt 0`, which never creates the
+ * artifact) and from MATLAB on real data. These helpers detect the
+ * all-zero imaginary lane and drop it so the real code path runs.
+ */
+import type { RuntimeValue } from "../runtime/index.js";
+import { type RuntimeTensor } from "../runtime/types.js";
+/** True when `imag` is absent or every element is exactly zero. */
+export declare function imagAllZero(imag: ArrayLike<number> | undefined): boolean;
+/** If `t` carries an all-zero imaginary lane, return a real view sharing
+ *  its data; otherwise return `t` unchanged. */
+export declare function stripZeroImagTensor(t: RuntimeTensor): RuntimeTensor;
+/** Tensor-aware variant for the generic `RuntimeValue` channel. */
+export declare function stripZeroImagValue(v: RuntimeValue): RuntimeValue;

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

@@ -189,5 +189,5 @@ export declare class Interpreter {
     };
     isHandleClass: (classInfo: ClassInfo) => boolean;
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
-    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => unknown[];
+    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => void;
 }

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

@@ -41,4 +41,16 @@ export declare function collectClassProperties(this: Interpreter, classInfo: Cla
 };
 export declare function isHandleClass(this: Interpreter, classInfo: ClassInfo): boolean;
 export declare function evalInLocalScope(this: Interpreter, codeArg: unknown, fileName?: string): unknown;
-export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): unknown[];
+/**
+ * Apply `arguments`-block defaults and build name-value struct parameters,
+ * binding the results into the *current* function environment.
+ *
+ * Must be called with `this.env` already set to the function scope and the
+ * caller-supplied positional arguments already bound to their parameters.
+ * Default expressions are evaluated in that scope so they can reference
+ * earlier arguments (e.g. `mergeIdx = surfaceop.defaultIdx(dom)`), matching
+ * MATLAB. Entries are matched to parameters by name via `fn.params`, which
+ * also handles the constructor case where the output variable is prepended
+ * to `params` (shifting argument positions by one).
+ */
+export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): void;

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

@@ -44,6 +44,7 @@ export * from "./tensor_ops/tensor_eye.js";
 export * from "./tensor_ops/tensor_fill_nd.js";
 export * from "./tensor_ops/tensor_fill_square.js";
 export * from "./tensor_ops/tensor_flip.js";
+export * from "./tensor_ops/tensor_imag_all_zero.js";
 export * from "./tensor_ops/tensor_linspace.js";
 export * from "./tensor_ops/tensor_logical_real.js";
 export * from "./tensor_ops/tensor_logspace.js";

package/dist-lib/numbl-core/jit/builtins/runtime/tensor_ops/tensor_imag_all_zero.d.ts

@@ -0,0 +1 @@
+export function mtoc2_tensor_imag_all_zero(a: any): boolean;

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, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace } from "../../graphics/types.js";
+export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
+import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
 export interface ParsedLineSpec {
     color?: string;
     lineStyle?: string;
@@ -75,6 +75,20 @@ export declare function parseImagescArgs(args: RuntimeValue[]): ImagescTrace;
  *   contour(..., Name, Value)
  */
 export declare function parseContourArgs(args: RuntimeValue[], filled: boolean): ContourTrace;
+/** Result of computing contour geometry: the MATLAB contour matrix `C`
+ *  (column-major `2 × n` data) plus the level list actually used. */
+export interface ContourMatrix {
+    /** Column-major `2 × n` data for a `RTV.tensor(data, [2, n])`. */
+    data: number[];
+    n: number;
+    levelList: number[];
+}
+/** Compute the MATLAB contour matrix for a parsed contour trace via marching
+ *  squares. Each marching-squares segment is emitted as its own two-vertex
+ *  contour line (header `[level; 2]` followed by the two `[x; y]` vertices) —
+ *  a valid contour matrix whose geometry matches MATLAB's connected polylines
+ *  segment-for-segment. */
+export declare function computeContourMatrix(trace: ContourTrace): ContourMatrix;
 /**
  * Parse mesh() arguments — same as surf but with different default rendering.
  */
@@ -237,3 +251,15 @@ export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;
  * vectors, X and Y are expanded to a meshgrid.
  */
 export declare function parseQuiverArgs(args: RuntimeValue[]): QuiverTrace[];
+/**
+ * Parse quiver3() arguments.
+ *
+ * Supported forms:
+ *   quiver3(Z, U, V, W)
+ *   quiver3(X, Y, Z, U, V, W)
+ *   quiver3(..., scale)         — scale: nonnegative number or 'off'
+ *   quiver3(..., LineSpec)
+ *   quiver3(..., LineSpec, 'filled')
+ *   quiver3(..., Name, Value)   — Color, LineStyle, LineWidth, ShowArrowHead, …
+ */
+export declare function parseQuiver3Args(args: RuntimeValue[]): Quiver3Trace;

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

@@ -33,6 +33,9 @@ export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
     type: "close_all";
 } | {
     type: "clf";
+} | {
+    type: "cla";
+    reset: boolean;
 } | {
     type: "set_subplot";
     rows: unknown;
@@ -66,6 +69,7 @@ export declare function viewCall(plotInstructions: PlotInstruction[], args: Runt
 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 surfaceCall(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;
@@ -101,6 +105,7 @@ export declare function piechartCall(plotInstructions: PlotInstruction[], args:
 export declare function donutchartCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function heatmapCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function quiverCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function quiver3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function legendCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function drawnow(plotInstructions: PlotInstruction[], options: ExecOptions): void;
 export declare function pause(seconds: unknown): void;

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

@@ -116,13 +116,16 @@ export declare class RuntimeClassInstance extends Refcounted {
     bindField(rt: RefcountRuntime, name: string, value: RuntimeValue): void;
     protected _destroy(rt: RefcountRuntime): void;
 }
-/** A 1-D array of class instances that all share the same class.
- *  Created by default horzcat/vertcat when the class doesn't overload them. */
+/** An array of class instances that all share the same class. Created by
+ *  default horzcat/vertcat when the class doesn't overload them. `elements`
+ *  are stored in column-major order; `shape` is the 2-D `[rows, cols]` size
+ *  (defaults to a `1×N` row vector when omitted). */
 export declare class RuntimeClassInstanceArray extends Refcounted {
     readonly kind: "class_instance_array";
     className: string;
     elements: RuntimeClassInstance[];
-    constructor(className: string, elements: RuntimeClassInstance[]);
+    shape: [number, number];
+    constructor(className: string, elements: RuntimeClassInstance[], shape?: [number, number]);
     protected _destroy(rt: RefcountRuntime): void;
 }
 export declare class RuntimeComplexNumber extends Refcounted {

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.0";
+export declare const NUMBL_VERSION = "0.4.2";