numbl 0.4.19 → 0.4.21

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

@@ -0,0 +1,107 @@
+/**
+ * Sparse direct solvers on the CSC representation (real arithmetic):
+ * Kronecker product, structural triangularity checks, triangular solves,
+ * up-looking sparse Cholesky, left-looking sparse LU with partial pivoting
+ * (Gilbert-Peierls), permutations, fill-reducing orderings (minimum degree,
+ * reverse Cuthill-McKee), and the `A \ b` driver used by mldivide.
+ *
+ * Complex sparse matrices are not handled here; callers fall back to the
+ * dense path for them.
+ */
+import { type RuntimeSparseMatrix, type RuntimeTensor, type SparseTriInfo } from "../runtime/types.js";
+type Sp = RuntimeSparseMatrix;
+export declare const SINGULAR_WARNING = "Matrix is singular to working precision.";
+/** Convert a dense tensor to CSC (dropping zeros). */
+export declare function denseToSparse(t: RuntimeTensor): Sp;
+/** Build CSC from column-major dense data, dropping zeros. */
+export declare function denseDataToSparse(data: Float64Array, m: number, n: number): Sp;
+/** Sparse permutation matrix P with P(k, p[k]) = 1, so (P*A)(k,:) = A(p[k],:). */
+export declare function permutationMatrix(p: Int32Array | number[]): Sp;
+/** 1-based row vector from a 0-based permutation. */
+export declare function permVectorTensor(p: Int32Array): RuntimeTensor;
+export declare function invertPerm(p: Int32Array): Int32Array;
+/** C = A(p, q) for 0-based permutations p (rows) and q (columns). */
+export declare function sparsePermute(A: Sp, p: Int32Array, q: Int32Array): Sp;
+export declare function sparseKron(A: Sp, B: Sp): Sp;
+/**
+ * One O(nnz) pass over the pattern: is the matrix upper / lower triangular
+ * (explicitly stored zeros ignored), and where is each diagonal entry. The
+ * result is cached on the matrix object.
+ */
+export declare function triangularInfo(S: Sp): SparseTriInfo;
+/** True if every stored nonzero lies on or above the diagonal. */
+export declare function sparseIsUpper(S: Sp): boolean;
+/** True if every stored nonzero lies on or below the diagonal. */
+export declare function sparseIsLower(S: Sp): boolean;
+/** Exact numerical symmetry (A == A'), real sparse only. */
+export declare function sparseIsSymmetric(S: Sp): boolean;
+/** Solve R * X = B for upper-triangular R (n×n), B column-major n×nrhs.
+ *  Returns the solution in a fresh array and whether a zero pivot was hit. */
+export declare function sparseSolveUpper(R: Sp, B: Float64Array, nrhs: number): {
+    x: Float64Array;
+    singular: boolean;
+};
+/** Solve L * X = B for lower-triangular L (n×n). */
+export declare function sparseSolveLower(L: Sp, B: Float64Array, nrhs: number): {
+    x: Float64Array;
+    singular: boolean;
+};
+export interface CholResult {
+    /** Lower factor with L * L' = A (only when ok). */
+    L: Sp;
+    ok: boolean;
+    /** 0 on success, otherwise the 1-based column at which the pivot failed. */
+    p: number;
+}
+/**
+ * Cholesky factorization of a symmetric positive definite sparse matrix.
+ * Only the upper triangle of A is read; symmetry is not checked. On failure
+ * returns the leading (p-1)×(p-1) factor computed so far.
+ */
+export declare function sparseChol(A: Sp): CholResult;
+export interface LuResult {
+    /** Unit lower triangular, m × min(m,n), rows in pivot order. */
+    L: Sp;
+    /** Upper triangular, min(m,n) × n. */
+    U: Sp;
+    /** Row permutation: row k of P*A*Q is row p[k] of A. */
+    p: Int32Array;
+    /** Column permutation: column k of P*A*Q is column q[k] of A. */
+    q: Int32Array;
+    singular: boolean;
+}
+/**
+ * LU factorization P*A*Q = L*U of a real sparse matrix with threshold
+ * partial pivoting (tol = 1 is plain partial pivoting; smaller values prefer
+ * the diagonal entry when it is at least tol times the largest candidate).
+ */
+export declare function sparseLu(A: Sp, q: Int32Array | null, tol: number): LuResult;
+export declare function identityPerm(n: number): Int32Array;
+/**
+ * Minimum degree ordering on the pattern of A + A', computed on an explicit
+ * elimination graph. Returns a 0-based permutation p such that A(p,p) tends
+ * to have a sparser Cholesky factor. This is a plain minimum-degree
+ * ordering, not MATLAB's approximate minimum degree, so the permutation
+ * differs from MATLAB's `amd` while serving the same purpose.
+ */
+export declare function minimumDegreeOrdering(A: Sp): Int32Array;
+/**
+ * Reverse Cuthill-McKee ordering on the pattern of A + A'. Returns a 0-based
+ * permutation that tends to reduce the bandwidth of A(p,p).
+ */
+export declare function reverseCuthillMcKee(A: Sp): Int32Array;
+/** Column ordering for LU: minimum degree on the pattern of A'*A. */
+export declare function columnOrdering(A: Sp): Int32Array;
+/**
+ * Solve A * X = B for square real sparse A and dense B (n × nrhs,
+ * column-major). Returns null when the caller should use the dense path
+ * (non-square, complex, or nearly full A).
+ */
+export declare function sparseSolve(A: Sp, B: Float64Array, nrhs: number): Float64Array | null;
+/** Solve with precomputed LU factors: X = Q * U \ (L \ (P * B)). */
+export declare function luSolve(lu: LuResult, B: Float64Array, nrhs: number): Float64Array;
+/** Solve with LU factors of A for the transposed system A' * X = B. */
+export declare function luSolveTransposed(lu: LuResult, B: Float64Array, nrhs: number): Float64Array;
+/** Inverse of a square real sparse matrix, returned sparse. */
+export declare function sparseInverse(A: Sp): Sp;
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * MATLAB-style warnings from helper code that has no Runtime handle.
+ *
+ * The Runtime installs a sink that routes messages through its output
+ * channel ("Warning: <msg>"); before a Runtime exists, messages fall back
+ * to console.warn.
+ */
+export declare function setWarningSink(fn: (msg: string) => void): void;
+export declare function emitWarning(msg: string): void;

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

@@ -27,6 +27,7 @@ import "./cell-struct.js";
 import "./time-system.js";
 import "./datetime.js";
 import "./sparse.js";
+import "./sparse-solvers.js";
 import "./graph.js";
 import "./gallery.js";
 import "./special-math.js";

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

@@ -0,0 +1,16 @@
+/**
+ * Sparse direct-solver builtins: fill-reducing orderings (symrcm, amd,
+ * colamd), random sparse matrices (sprand, sprandn, sprandsym), and the
+ * `decomposition` object that stores factors for repeated solves.
+ *
+ * The factorizations themselves live in helpers/sparse-direct.ts; chol, lu,
+ * kron, inv and the operators `\` and `/` dispatch to them from
+ * linear-algebra.ts and helpers/arithmetic.ts.
+ */
+import type { RuntimeValue } from "../../runtime/types.js";
+/**
+ * Hook for the mldivide / mrdivide operator builtins: `dA \ B` and `B / dA`
+ * with a decomposition object. Returns undefined when neither operand is a
+ * decomposition so the ordinary operator runs.
+ */
+export declare function tryDecompositionDivide(name: "mldivide" | "mrdivide", a: RuntimeValue, b: RuntimeValue): RuntimeValue | undefined;

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 = 8;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 9;
 export interface LapackBridge {
     /** Returns the native addon's version number. */
     addonVersion?(): number;
@@ -207,6 +207,34 @@ export interface LapackBridge {
         VL?: Float64Array;
         VR?: Float64Array;
     };
+    /**
+     * Eigenvalue decomposition of an n×n real *symmetric* matrix stored in
+     * column-major order. Uses LAPACK dsyev (only the lower triangle is read).
+     * Unlike `eig`, the eigenvalues are real and returned in ascending order and
+     * the eigenvectors are orthonormal, including across repeated eigenvalues.
+     * @param data      Column-major Float64Array of length n*n (not modified).
+     * @param n         Matrix dimension.
+     * @param computeV  true → also compute the orthonormal eigenvectors.
+     * @returns         Object with w (ascending eigenvalues) and optionally V.
+     */
+    eigSym?(data: Float64Array, n: number, computeV: boolean): {
+        w: Float64Array;
+        V?: Float64Array;
+    };
+    /**
+     * Eigenvalue decomposition of an n×n complex *Hermitian* matrix stored in
+     * column-major order. Uses LAPACK zheev (only the lower triangle is read).
+     * @param dataRe    Real parts — column-major Float64Array of length n*n.
+     * @param dataIm    Imaginary parts — column-major Float64Array of length n*n.
+     * @param n         Matrix dimension.
+     * @param computeV  true → also compute the unitary eigenvector basis.
+     * @returns         Object with w (real, ascending) and optionally VRe/VIm.
+     */
+    eigHerm?(dataRe: Float64Array, dataIm: Float64Array, n: number, computeV: boolean): {
+        w: Float64Array;
+        VRe?: Float64Array;
+        VIm?: Float64Array;
+    };
     /**
      * Eigenvalue decomposition of an n×n complex matrix stored in column-major order.
      * Uses LAPACK zgeev.

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

@@ -0,0 +1,33 @@
+/**
+ * Pure-TypeScript Hermitian eigensolver — a zheev-equivalent for the ts-lapack
+ * bridge (browser path, no native LAPACK addon).
+ *
+ * Ported from the netlib LAPACK reference (zheev → zhetd2 / zungtr → zsteqr).
+ * One structural deviation: zsteqr accumulates the QL/QR rotations directly
+ * into the complex matrix Q, whereas here DSTEQR is run with COMPZ = 'I' to
+ * get the real orthogonal eigenvector matrix S of the tridiagonal, and the
+ * back-transformation V = Q * S is done as one complex-times-real matrix
+ * product afterwards. Both are O(n^3); this way the tridiagonal QL/QR lives in
+ * exactly one place (src/ts-lapack/src/SRC/dsteqr.ts) instead of two.
+ *
+ * Because zlarfg produces a real beta, the tridiagonal form is real symmetric,
+ * so DSTEQR applies unchanged.
+ *
+ * Eigenvalues come back real and in ascending order; eigenvectors form a
+ * unitary basis (V^H * V = I), matching dsyev/zheev and MATLAB.
+ *
+ * All matrices are column-major with leading dimension n, split into parallel
+ * real/imag Float64Arrays — matching the bridge's eigHerm I/O shape.
+ */
+/**
+ * ZHEEV-equivalent. `dataRe`/`dataIm` hold the full n×n Hermitian matrix in
+ * column-major order (only the lower triangle is read); they are not modified.
+ *
+ * Returns the eigenvalues in ascending order, plus a unitary eigenvector basis
+ * when `computeV` is set.
+ */
+export declare function eigHermTs(dataRe: Float64Array, dataIm: Float64Array, n: number, computeV: boolean): {
+    w: Float64Array;
+    VRe?: Float64Array;
+    VIm?: Float64Array;
+};

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

@@ -173,6 +173,15 @@ export declare class RuntimeStructArray extends Refcounted {
 }
 /** Sparse matrix in CSC (Compressed Sparse Column) format, matching MATLAB's
  *  internal representation. */
+/** Cached structural analysis of a sparse matrix (see helpers/sparse-direct). */
+export interface SparseTriInfo {
+    upper: boolean;
+    lower: boolean;
+    /** Index into ir/pr of the diagonal entry of each column, or -1. */
+    diagPos: Int32Array;
+    /** Diagonal values (0 where absent). */
+    diag: Float64Array;
+}
 export declare class RuntimeSparseMatrix extends Refcounted {
     readonly kind: "sparse_matrix";
     m: number;
@@ -181,6 +190,9 @@ export declare class RuntimeSparseMatrix extends Refcounted {
     jc: Int32Array;
     pr: Float64Array;
     pi: Float64Array | undefined;
+    /** Lazily computed by triangularInfo(); valid because sparse matrices are
+     *  never mutated in place (indexed assignment builds a new matrix). */
+    _triInfo: SparseTriInfo | undefined;
     constructor(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array);
 }
 /** Dictionary mapping unique keys to values (MATLAB R2022b+). */

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

package/dist-lib/ts-lapack/src/BLAS/dsymv.d.ts

@@ -0,0 +1 @@
+export declare function dsymv(uplo: number, n: number, alpha: number, a: Float64Array, aOff: number, lda: number, x: Float64Array, xOff: number, incx: number, beta: number, y: Float64Array, yOff: number, incy: number): void;

package/dist-lib/ts-lapack/src/BLAS/dsyr2.d.ts

@@ -0,0 +1 @@
+export declare function dsyr2(uplo: number, n: number, alpha: number, x: Float64Array, xOff: number, incx: number, y: Float64Array, yOff: number, incy: number, a: Float64Array, aOff: number, lda: number): void;

package/dist-lib/ts-lapack/src/SRC/dlae2.d.ts

@@ -0,0 +1,4 @@
+export declare function dlae2(a: number, b: number, c: number): {
+    rt1: number;
+    rt2: number;
+};

package/dist-lib/ts-lapack/src/SRC/dlaev2.d.ts

@@ -0,0 +1,6 @@
+export declare function dlaev2(a: number, b: number, c: number): {
+    rt1: number;
+    rt2: number;
+    cs1: number;
+    sn1: number;
+};

package/dist-lib/ts-lapack/src/SRC/dlanst.d.ts

@@ -0,0 +1 @@
+export declare function dlanst(norm: number, n: number, d: Float64Array, dOff: number, e: Float64Array, eOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dlansy.d.ts

@@ -0,0 +1 @@
+export declare function dlansy(norm: number, uplo: number, n: number, a: Float64Array, aOff: number, lda: number, work: Float64Array, workOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dlasrt.d.ts

@@ -0,0 +1 @@
+export declare function dlasrt(id: number, n: number, d: Float64Array, dOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dorgtr.d.ts

@@ -0,0 +1 @@
+export declare function dorgtr(uplo: number, n: number, a: Float64Array, aOff: number, lda: number, tau: Float64Array, tauOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dsteqr.d.ts

@@ -0,0 +1,4 @@
+export declare const COMPZ_N = 0;
+export declare const COMPZ_V = 1;
+export declare const COMPZ_I = 2;
+export declare function dsteqr(compz: number, n: number, d: Float64Array, dOff: number, e: Float64Array, eOff: number, z: Float64Array, zOff: number, ldz: number, work: Float64Array, workOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dsyev.d.ts

@@ -0,0 +1 @@
+export declare function dsyev(wantz: boolean, uplo: number, n: number, a: Float64Array, aOff: number, lda: number, w: Float64Array, wOff: number): number;

package/dist-lib/ts-lapack/src/SRC/dsytd2.d.ts

@@ -0,0 +1 @@
+export declare function dsytd2(uplo: number, n: number, a: Float64Array, aOff: number, lda: number, d: Float64Array, dOff: number, e: Float64Array, eOff: number, tau: Float64Array, tauOff: number): number;