numbl 0.4.1 → 0.4.3

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/helpers/eigs-select.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Selection + ordering logic for `eigs` (a subset of eigenvalues).
+ *
+ * `eigs` in numbl piggybacks on the dense `eig`: the runtime computes every
+ * eigenvalue, then this module picks the requested `k` of them according to
+ * `sigma` and returns their original indices in the order `eigs` reports
+ * them. It is pure (operates on plain number arrays) so it can be unit
+ * tested without the runtime.
+ */
+export type SigmaKind = "largestabs" | "smallestabs" | "largestreal" | "smallestreal" | "bothendsreal" | "largestimag" | "smallestimag" | "bothendsimag";
+export type SigmaSpec = {
+    kind: SigmaKind;
+} | {
+    kind: "scalar";
+    re: number;
+    im: number;
+};
+/** Map a text sigma value to a canonical kind, or `null` if unrecognized. */
+export declare function normalizeSigmaString(s: string): SigmaKind | null;
+/**
+ * Pick `k` eigenvalues (by original index) and return them in the order
+ * `eigs` reports for the given `sigma`. `re`/`im` are the real/imaginary
+ * parts of all `n` eigenvalues.
+ */
+export declare function selectEigsIndices(re: number[], im: number[], k: number, sigma: SigmaSpec): number[];

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

@@ -0,0 +1,34 @@
+/**
+ * `axis(...)` argument parsing — the single place that turns every `axis`
+ * call form into `PlotInstruction`s.
+ *
+ * Supported forms (evaluated left to right, later options overriding earlier
+ * ones):
+ *   - a limit vector `[xmin xmax ymin ymax (zmin zmax (cmin cmax))]`, where a
+ *     non-finite bound (`inf`/`-inf`) leaves that bound automatic;
+ *   - a scalar `0/1` or logical `false/true` toggling axes visibility;
+ *   - a style word (`tight`, `padded`, `fill`, `equal`, `image`, `square`,
+ *     `vis3d`, `normal`, `tickaligned`);
+ *   - a limit mode (`manual`, `auto`, `'auto x'`, `'auto y'`, `'auto z'`,
+ *     `'auto xy'`, `'auto xz'`, `'auto yz'`);
+ *   - a y-direction (`xy`, `ij`);
+ *   - a visibility word (`on`, `off`).
+ *
+ * A leading axes handle (numbl has no real axes handles) is accepted and
+ * skipped, so `axis(ax, ...)` works. The query forms `lim = axis` /
+ * `lim = axis(ax)` carry no setting argument; the runtime detects them via
+ * the `false` return value and computes the limits separately.
+ */
+import type { RuntimeValue } from "./types.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+/**
+ * Process an `axis(...)` call, pushing instructions onto `instructions`.
+ *
+ * @param freezeLimits  Optional provider of the current limit vector
+ *   `[xmin xmax ymin ymax (zmin zmax)]`, used to implement `axis manual`
+ *   (freeze the current limits). When omitted, `axis manual` records the
+ *   request without concrete values.
+ * @returns `true` if any setting was applied. `false` means the call carried
+ *   no setting argument (a query, e.g. `lim = axis`).
+ */
+export declare function applyAxisCommand(args: RuntimeValue[], instructions: PlotInstruction[], freezeLimits?: () => number[]): boolean;

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

@@ -308,6 +308,11 @@ export declare class Runtime {
     nargoutchk(actualNargout: unknown, minArgs: unknown, maxArgs: unknown): void;
     /** Read the hold state, for `ishold()` queries. */
     ishold(): RuntimeValue;
+    /** Current axis limits of the active axes, as MATLAB's `axis` query
+     *  returns them: `[xmin xmax ymin ymax]` (2-D) or with `zmin zmax`
+     *  appended (3-D). Reduces the accumulated plot instructions into a figure
+     *  state and reads the current axes' explicit/data-derived limits. */
+    currentAxisLimits(): number[];
     drawnow(): void;
     pause(seconds: unknown): void;
     readInput(prompt: string): string;

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