@danielsimonjr/mathts-functions 0.33.0 → 0.35.0

package/dist/numeric/control-equations.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Control-theory matrix equations — `dlyap`/`care`/`dare`.
+ *
+ * These solve the algebraic matrix equations that underlie LQR (linear-
+ * quadratic regulator) and Kalman-filter design:
+ *
+ *   - {@link dlyap} — discrete Lyapunov equation `A X Aᵀ − X + Q = 0`, solved
+ *     directly via the Kronecker-product linear system
+ *     `(I − A⊗A) vec(X) = vec(Q)` (exact for the small `n` this targets;
+ *     the codebase's `linsolve` does the O(n²)³ = O(n⁶) dense solve).
+ *   - {@link care} — continuous algebraic Riccati equation
+ *     `AᵀX + XA − X B R⁻¹ Bᵀ X + Q = 0`, solved via the **matrix sign
+ *     function** applied to the Hamiltonian `H = [[A, −BR⁻¹Bᵀ], [−Q, −Aᵀ]]`.
+ *     This avoids both complex eigenvectors (this codebase's `eig` only
+ *     returns real eigenvector columns — see `matrix-functions.ts` — so a
+ *     Hamiltonian-eigenvector approach isn't usable here) and the need for a
+ *     stabilizing initial gain that a Kleinman/Newton iteration would
+ *     require (the natural starting point `X₀ = 0` is not stabilizing for
+ *     e.g. the classic double-integrator `A = [[0,1],[0,0]]`, which is only
+ *     marginally stable). The sign-function Newton iteration converges
+ *     unconditionally (given the standard stabilizability/detectability
+ *     assumptions) directly from `H` itself.
+ *   - {@link dare} — discrete algebraic Riccati equation
+ *     `AᵀXA − X − AᵀXB(R + BᵀXB)⁻¹BᵀXA + Q = 0`, solved via the
+ *     **structure-preserving doubling algorithm** (SDA), the discrete-time
+ *     analogue of the sign-function method above: it iterates a triple
+ *     `(Aₖ, Gₖ, Hₖ)` with quadratic convergence and, likewise, needs no
+ *     stabilizing initial gain.
+ *
+ * All three return the (numerically symmetrized) stabilizing solution `X`.
+ * Both `care`/`dare` require `R` invertible and `(A, B)` stabilizable — the
+ * standard LQR well-posedness assumptions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Solve the discrete-time Lyapunov (Stein) equation `A X Aᵀ − X + Q = 0` for
+ * `X`, given square `A` and `Q` of the same size.
+ *
+ * Builds the Kronecker-product linear system `(I − A⊗A) vec(X) = vec(Q)`
+ * explicitly (practical for the `n ≲ 20` this targets — the system has
+ * `n²` unknowns) and solves it with `linsolve`.
+ *
+ * @example
+ * dlyap([[0.5, 0], [0, 0.5]], [[1, 0], [0, 1]]) // => (4/3) * I  (since 0.25x - x + 1 = 0)
+ */
+export declare function dlyap(A: number[][], Q: number[][]): number[][];
+/**
+ * Solve the continuous-time algebraic Riccati equation (CARE)
+ * `AᵀX + XA − X B R⁻¹ Bᵀ X + Q = 0` for the stabilizing symmetric `X`,
+ * given `A` (n×n), `B` (n×m), `Q` (n×n, typically PSD), `R` (m×m, invertible).
+ *
+ * Method: Newton iteration for the **matrix sign function** of the
+ * Hamiltonian `H = [[A, −BR⁻¹Bᵀ], [−Q, −Aᵀ]]` (2n×2n):
+ *
+ *   `Zₖ₊₁ = ½(cₖ Zₖ + cₖ⁻¹ Zₖ⁻¹)`,  `Z₀ = H`,  `cₖ = √(‖Zₖ⁻¹‖₁ / ‖Zₖ‖₁)`
+ *
+ * converging quadratically to `S = sign(H)`. The projector `P = ½(I − S)`
+ * has range equal to `H`'s stable (Re λ < 0) invariant subspace; taking its
+ * first `n` columns `U = [U₁; U₂]` (split at the `n`-th row) gives
+ * `X = U₂ U₁⁻¹` (real arithmetic throughout — no complex eigenvectors
+ * needed, unlike the classical Hamiltonian-eigenvector construction).
+ *
+ * @example
+ * care([[0, 1], [0, 0]], [[0], [1]], [[1, 0], [0, 1]], [[1]])
+ * // => [[sqrt(3), 1], [1, sqrt(3)]]  (pinned vs scipy.linalg.solve_continuous_are)
+ */
+export declare function care(A: number[][], B: number[][], Q: number[][], R: number[][]): number[][];
+/**
+ * Solve the discrete-time algebraic Riccati equation (DARE)
+ * `AᵀXA − X − AᵀXB(R + BᵀXB)⁻¹BᵀXA + Q = 0` for the stabilizing symmetric
+ * `X`, given `A` (n×n), `B` (n×m), `Q` (n×n, typically PSD), `R` (m×m,
+ * invertible).
+ *
+ * Method: the **structure-preserving doubling algorithm** (SDA) — the
+ * discrete-time analogue of the sign-function iteration used by {@link care}.
+ * Starting from `A₀ = A`, `G₀ = B R⁻¹ Bᵀ`, `H₀ = Q`, it iterates
+ *
+ *   `Aₖ₊₁ = Aₖ(I + GₖHₖ)⁻¹Aₖ`
+ *   `Gₖ₊₁ = Gₖ + Aₖ(I + GₖHₖ)⁻¹Gₖ Aₖᵀ`
+ *   `Hₖ₊₁ = Hₖ + Aₖᵀ Hₖ(I + GₖHₖ)⁻¹Aₖ`
+ *
+ * with `Hₖ → X` quadratically. Like {@link care}'s sign-function method, this
+ * needs no stabilizing initial gain (unlike a Kleinman/Newton iteration on
+ * the DARE directly) — only the standard stabilizability/detectability
+ * assumptions.
+ *
+ * @example
+ * dare([[1, 1], [0, 1]], [[0], [1]], [[1, 0], [0, 1]], [[1]])
+ * // => [[2.94712297, 2.36920541], [2.36920541, 4.61313426]]
+ * //    (pinned vs scipy.linalg.solve_discrete_are)
+ */
+export declare function dare(A: number[][], B: number[][], Q: number[][], R: number[][]): number[][];
+//# sourceMappingURL=control-equations.d.ts.map

package/dist/numeric/control-equations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-equations.d.ts","sourceRoot":"","sources":["../../src/numeric/control-equations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAuJH;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAgB9D;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CA6C3F;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CA+B3F"}

package/dist/numeric/eigsh.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Iterative symmetric eigensolver — Lanczos tridiagonalization + Rayleigh-Ritz.
+ *
+ * For large symmetric problems where the dense `eigs` (full O(n^3)
+ * eigendecomposition of the whole matrix) is prohibitive, `eigsh` extracts
+ * just the `k` largest or smallest eigenpairs. It builds an orthonormal
+ * Krylov basis `V` via the Lanczos iteration (with full reorthogonalization
+ * against every prior Lanczos vector, for numerical stability at the small
+ * sizes this is exercised at), forming the small tridiagonal projection
+ * `T = Vᵀ A V`. `T`'s eigenproblem is solved directly (cyclic Jacobi
+ * rotations — `T` is dense-symmetric-small by construction) and lifted back
+ * through `V` (Rayleigh-Ritz) to approximate `A`'s eigenpairs. Accepts either
+ * a dense matrix or a matvec callback (a linear operator, matching the
+ * `krylov.ts` convention) — the matvec form never forms `A` and requires
+ * `opts.n` since the dimension can't otherwise be inferred.
+ *
+ * @packageDocumentation
+ */
+/** A symmetric linear operator: either a dense matrix or a matvec callback `x -> A x`. */
+export type EigshOperatorInput = number[][] | ((x: number[]) => number[]);
+/** Options accepted by {@link eigsh}. */
+export interface EigshOptions {
+    /** Which end of the spectrum to return: `'LM'` (largest, default) or `'SM'` (smallest). */
+    which?: 'LM' | 'SM';
+    /** Dimension of `A` — required when `A` is a matvec callback. */
+    n?: number;
+    /** Convergence tolerance for diagonalizing the small tridiagonal projection (default 1e-10). */
+    tol?: number;
+    /** Maximum Lanczos steps (default `min(max(2k + 20, 20), n)`). */
+    maxIter?: number;
+}
+/**
+ * Result of {@link eigsh}.
+ *
+ * `eigenvectors` is an `n x k` matrix with eigenvectors stored as **columns**:
+ * `eigenvectors[i][j]` is the `i`-th component of the `j`-th eigenvector,
+ * which corresponds to `eigenvalues[j]`.
+ */
+export interface EigshResult {
+    /** The `k` selected eigenvalues, ordered by `which` (largest-first for `'LM'`, smallest-first for `'SM'`). */
+    eigenvalues: number[];
+    /** The `k` corresponding eigenvectors, as columns of an `n x k` matrix. */
+    eigenvectors: number[][];
+}
+/**
+ * `eigsh` — the `k` largest or smallest eigenpairs of a **symmetric** matrix
+ * via the Lanczos iteration, for problems too large for the dense `eigs`.
+ *
+ * `A` may be a dense `number[][]` or a matvec callback `x => A x` (in which
+ * case `opts.n` is required — the dimension can't be inferred from a
+ * function). Eigenvectors are returned as **columns** of an `n x k` matrix:
+ * `result.eigenvectors[i][j]` is the `i`-th component of the eigenvector for
+ * `result.eigenvalues[j]`.
+ *
+ * @example
+ * eigsh([[2, 1, 0], [1, 2, 1], [0, 1, 2]], 1, { which: 'LM' })
+ * // => { eigenvalues: [2 + Math.SQRT2], eigenvectors: [[...]] }
+ */
+export declare function eigsh(a: EigshOperatorInput, k?: number, opts?: EigshOptions): EigshResult;
+//# sourceMappingURL=eigsh.d.ts.map

package/dist/numeric/eigsh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eigsh.d.ts","sourceRoot":"","sources":["../../src/numeric/eigsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;AAE1E,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,iEAAiE;IACjE,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,8GAA8G;IAC9G,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;CAC1B;AAkKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,SAAI,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,WAAW,CAmDpF"}

package/dist/numeric/krylov.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Iterative Krylov-subspace linear solvers.
+ *
+ * For the large sparse systems a dense factorization (`lusolve`, `qr`, …)
+ * can't handle — none of these methods ever form or fill in `A`. Each solver
+ * accepts either a dense matrix or a matvec callback (a "linear operator" in
+ * the SciPy/Trilinos sense), plus an optional preconditioner:
+ *
+ * - `cg` — Conjugate Gradient, for symmetric positive-definite `A`.
+ * - `minres` — MINRES, for symmetric (possibly indefinite) `A`.
+ * - `gmres` — restarted GMRES, for general nonsymmetric `A`.
+ * - `bicgstab` — BiCGSTAB, for general nonsymmetric `A`.
+ *
+ * @packageDocumentation
+ */
+/** A linear operator: either a dense matrix or a matvec callback `x -> A x`. */
+export type LinearOperatorInput = number[][] | ((x: number[]) => number[]);
+/** Preconditioner: `'jacobi'` (diagonal, dense-matrix only) or a custom `M⁻¹` callback. */
+export type Preconditioner = 'jacobi' | ((r: number[]) => number[]);
+/** Common options accepted by every solver in this module. */
+export interface KrylovOptions {
+    /** Initial guess (default: the zero vector). */
+    x0?: number[];
+    /** Relative-residual convergence tolerance (default 1e-10). */
+    tol?: number;
+    /** Maximum iterations (default `min(10 * n, 1000)`). */
+    maxIter?: number;
+    /** Preconditioner: `'jacobi'` or a custom `(r) => M⁻¹r` callback. */
+    preconditioner?: Preconditioner;
+}
+/** Options for {@link gmres}, adding the restart length. */
+export interface GmresOptions extends KrylovOptions {
+    /** Restart length (default 30). */
+    restart?: number;
+}
+/** Result returned by every solver in this module. */
+export interface KrylovResult {
+    /** Approximate solution. */
+    x: number[];
+    /** Number of iterations performed. */
+    iterations: number;
+    /** Whether the relative residual dropped below `tol`. */
+    converged: boolean;
+    /** Final relative residual `‖b − A x‖₂ / ‖b‖₂`. */
+    residual: number;
+}
+/**
+ * Conjugate Gradient (CG) — for symmetric positive-definite `A`.
+ *
+ * @example
+ * cg([[4, 1], [1, 3]], [1, 2]) // => { x: [1/11, 7/11], converged: true, ... }
+ */
+export declare function cg(a: LinearOperatorInput, b: number[], opts?: KrylovOptions): KrylovResult;
+/**
+ * MINRES — for symmetric (possibly indefinite) `A`.
+ *
+ * Builds the preconditioned Lanczos tridiagonalization of `A` and, at each
+ * step, solves the growing `(k+1) x k` tridiagonal least-squares problem
+ * `min ||beta1 e1 - T_k y||` via a small dense Householder QR. This is the
+ * textbook MINRES minimization restated directly (rather than the
+ * incrementally-updated Givens-rotation form), which keeps it simple to
+ * verify against a closed-form oracle at the cost of some redundant work
+ * per iteration — acceptable since `maxIter` is bounded by `min(10n, 1000)`.
+ *
+ * @example
+ * minres([[0, 1], [1, 0]], [1, 2]) // => { x: [2, 1], converged: true, ... }
+ */
+export declare function minres(a: LinearOperatorInput, b: number[], opts?: KrylovOptions): KrylovResult;
+/**
+ * Restarted GMRES — for general nonsymmetric `A`.
+ *
+ * @example
+ * gmres([[3, 1], [0, 2]], [4, 2]) // => { x: [1, 1], converged: true, ... }
+ */
+export declare function gmres(a: LinearOperatorInput, b: number[], opts?: GmresOptions): KrylovResult;
+/**
+ * BiCGSTAB — for general nonsymmetric `A`.
+ *
+ * @example
+ * bicgstab([[3, 1], [0, 2]], [4, 2]) // => { x: [1, 1], converged: true, ... }
+ */
+export declare function bicgstab(a: LinearOperatorInput, b: number[], opts?: KrylovOptions): KrylovResult;
+//# sourceMappingURL=krylov.d.ts.map

package/dist/numeric/krylov.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"krylov.d.ts","sourceRoot":"","sources":["../../src/numeric/krylov.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;AAE3E,2FAA2F;AAC3F,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;AAEpE,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmGD;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAwC1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAyF9F;AA8CD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,YAAY,CA2F5F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAqEhG"}

package/dist/numeric/matrix-functions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Complex matrix functions — `funm`/`cosm`/`sinm` for a general real matrix.
+ *
+ * `funm(A, f)` evaluates a scalar analytic function `f` at a square matrix
+ * `A`, returning the complex matrix `f(A)`. Unlike `sqrtm`/`matrixLogm`
+ * (which only handle real matrices whose spectrum stays on the principal
+ * branch — positive reals for sqrt/log), `funm` accepts any real spectrum
+ * (negative, complex-conjugate pairs, …) because the result is allowed to be
+ * complex-valued.
+ *
+ * Algorithm (diagonalizable matrices with distinct eigenvalues):
+ *   - If `A` is diagonal, `f(A)` is exact and trivial: apply `f` to each
+ *     diagonal entry (handles repeated eigenvalues fine, since a diagonal
+ *     matrix is always diagonalizable regardless of eigenvalue multiplicity).
+ *   - Otherwise, compute `A`'s eigenvalues `λ_1, …, λ_n` (via the shared
+ *     `@danielsimonjr/mathts-matrix` `eig` — Householder + Francis QR) and,
+ *     when they are all distinct, apply the Lagrange-Sylvester interpolation
+ *     formula for a diagonalizable matrix with simple spectrum:
+ *
+ *       f(A) = Σ_i f(λ_i) · L_i(A),   L_i(A) = Π_{j≠i} (A − λ_j I) / (λ_i − λ_j)
+ *
+ *     evaluated in complex arithmetic (`A` embedded with zero imaginary
+ *     part). This needs only eigenvalues, not eigenvectors, and is exact for
+ *     any polynomial or entire function `f` (cos, sin, sqrt, exp, log, …)
+ *     whenever the spectrum is simple.
+ *
+ * Limitation (documented, not yet implemented): matrices with repeated (or
+ * numerically indistinguishable) eigenvalues that are NOT diagonal — i.e.
+ * genuinely defective/non-diagonalizable matrices, or diagonalizable
+ * matrices with a repeated eigenvalue and off-diagonal structure — are not
+ * supported; `funm` throws rather than silently return a wrong answer. A
+ * full Schur-Parlett block recurrence (Higham 2008 Ch. 9) would lift this
+ * restriction; that is future work, not required by the current call sites.
+ *
+ * @packageDocumentation
+ */
+/** A complex number as a plain `{re, im}` pair. */
+export interface ComplexValue {
+    re: number;
+    im: number;
+}
+/** A complex-valued dense matrix, stored as parallel real/imaginary 2-D arrays. */
+export interface ComplexMatrix {
+    re: number[][];
+    im: number[][];
+}
+/** A scalar analytic function to be applied to a matrix's spectrum. */
+export type ScalarComplexFunction = (z: ComplexValue) => ComplexValue;
+/**
+ * Evaluate the matrix function `f(A)` for a square real matrix `A`, returning
+ * a complex matrix `{re, im}`.
+ *
+ * Supports diagonal matrices unconditionally (exact, elementwise), and
+ * general diagonalizable matrices whose eigenvalues are pairwise distinct
+ * (Lagrange-Sylvester interpolation on the spectrum — see module docs).
+ * Throws for matrices with repeated or numerically indistinguishable
+ * eigenvalues that are not diagonal (defective / non-diagonalizable case;
+ * not yet supported — see module docs for the Schur-Parlett follow-up).
+ *
+ * @param A - Square real matrix, as a plain 2-D array.
+ * @param f - Scalar function to apply to each eigenvalue, e.g. `cos`, `sin`,
+ *   `sqrt`, `exp`, `log`, extended to complex arguments.
+ * @returns `{ re, im }` — the (possibly complex) matrix `f(A)`.
+ */
+export declare function funm(A: number[][], f: ScalarComplexFunction): ComplexMatrix;
+/** Complex cosine: `cos(z) = cos(re)cosh(im) - i sin(re)sinh(im)`. */
+export declare function complexCos(z: ComplexValue): ComplexValue;
+/** Complex sine: `sin(z) = sin(re)cosh(im) + i cos(re)sinh(im)`. */
+export declare function complexSin(z: ComplexValue): ComplexValue;
+/** Matrix cosine `cos(A)`, via {@link funm} with {@link complexCos}. */
+export declare function cosm(A: number[][]): ComplexMatrix;
+/** Matrix sine `sin(A)`, via {@link funm} with {@link complexSin}. */
+export declare function sinm(A: number[][]): ComplexMatrix;
+//# sourceMappingURL=matrix-functions.d.ts.map

package/dist/numeric/matrix-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-functions.d.ts","sourceRoot":"","sources":["../../src/numeric/matrix-functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;IACf,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC;AAoHtE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAuD3E;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAKxD;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAKxD;AAED,wEAAwE;AACxE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,CAEjD;AAED,sEAAsE;AACtE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,CAEjD"}

package/dist/numeric/structured-solvers.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Structured and indefinite direct linear solvers.
+ *
+ * These exploit matrix structure (tridiagonal, banded, Toeplitz, symmetric
+ * indefinite) to solve `Ax = b` in less than the O(n^3) a general dense LU
+ * (`lusolve`) would cost, or — for `ldl` — to factor matrices `cholesky`
+ * cannot handle because they are not positive-definite (e.g. KKT systems):
+ *
+ * - `thomasSolve` — the Thomas algorithm, O(n) for tridiagonal systems.
+ * - `solveBanded` — banded-aware Gaussian elimination (no pivoting; touches
+ *   only the O(n(l+u)) entries inside the band), for systems with `l` lower
+ *   and `u` upper nonzero diagonals.
+ * - `toeplitzSolve` — the Levinson–Durbin recursion, O(n^2) for a Toeplitz
+ *   system given only its first row and column.
+ * - `ldl` — Bunch–Kaufman-pivoted LDLᵀ factorization of a symmetric
+ *   (possibly indefinite) matrix, with 1x1/2x2 diagonal blocks.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Thomas algorithm — O(n) solve of a tridiagonal system `Ax = d`.
+ *
+ * `A` is the tridiagonal matrix with subdiagonal `sub` (length n−1),
+ * diagonal `diag` (length n), and superdiagonal `sup` (length n−1). No
+ * pivoting is performed (as with any tridiagonal Thomas solve); the matrix
+ * should be diagonally dominant or otherwise stable without it.
+ *
+ * @example
+ * thomasSolve([-1, -1], [2, 2, 2], [-1, -1], [1, 0, 1]) // => [1, 1, 1]
+ */
+export declare function thomasSolve(sub: number[], diag: number[], sup: number[], d: number[]): number[];
+/**
+ * Banded-aware Gaussian elimination — solve `Ax = b` for a matrix with `l`
+ * nonzero lower diagonals and `u` nonzero upper diagonals (all other entries
+ * are assumed zero, though `A` is passed as a full dense matrix). Only the
+ * O(n(l+u)) entries inside the band are touched during elimination and
+ * back-substitution. No pivoting is performed — as with {@link thomasSolve},
+ * the matrix should be diagonally dominant or otherwise stable without it.
+ *
+ * @example
+ * solveBanded(1, 1, [[2, -1, 0], [-1, 2, -1], [0, -1, 2]], [1, 0, 1]) // => [1, 1, 1]
+ */
+export declare function solveBanded(l: number, u: number, A: number[][], b: number[]): number[];
+/**
+ * Levinson–Durbin recursion — O(n²) solve of a Toeplitz system `Tx = b`
+ * given only the first column `c` and first row `r` (`c[0]` must equal
+ * `r[0]`, the shared diagonal value). `T[i][j] = c[i-j]` for `i >= j`, else
+ * `r[j-i]`.
+ *
+ * Order-recursively builds the solution together with two auxiliary
+ * "predictor" vectors — one for `T`, one for `Tᵀ` (mutually coupled via the
+ * persymmetry `J T J = Tᵀ` that every Toeplitz matrix has, `J` the
+ * reversal/exchange matrix) — which is what makes a general (non-symmetric)
+ * Toeplitz system solvable in O(n²) rather than O(n³).
+ *
+ * @example
+ * toeplitzSolve([2, 1], [2, 1], [1, 2]) // => [0, 1]
+ */
+export declare function toeplitzSolve(c: number[], r: number[], b: number[]): number[];
+/** Result of {@link ldl}. */
+export interface LDLResult {
+    /** Unit lower-triangular factor. */
+    L: number[][];
+    /** Block-diagonal factor (1x1 or 2x2 blocks along the diagonal). */
+    D: number[][];
+    /**
+     * Permutation such that `(P A Pᵀ)[i][j] = A[perm[i]][perm[j]]` and
+     * `L D Lᵀ = P A Pᵀ`.
+     */
+    perm: number[];
+}
+/**
+ * Bunch–Kaufman-pivoted LDLᵀ factorization of a symmetric (possibly
+ * indefinite) matrix `A`, useful for symmetric systems `cholesky` can't
+ * handle because they aren't positive-definite (e.g. KKT / saddle-point
+ * systems from constrained optimization).
+ *
+ * Reconstruction identity: `L D Lᵀ = P A Pᵀ`, where `P` is the permutation
+ * matrix with `P[i][perm[i]] = 1`, i.e. `(P A Pᵀ)[i][j] = A[perm[i]][perm[j]]`.
+ * `L` is unit lower-triangular; `D` is block-diagonal with 1x1 or 2x2 blocks
+ * (2x2 blocks appear where a pivot would otherwise be too small relative to
+ * the rest of its column, per the standard Bunch–Kaufman pivot selection).
+ *
+ * @example
+ * const { L, D, perm } = ldl([[1, 2, 3], [2, 1, 4], [3, 4, 1]]);
+ * // L D L^T reconstructs A with rows/cols permuted by perm.
+ */
+export declare function ldl(A: number[][]): LDLResult;
+//# sourceMappingURL=structured-solvers.d.ts.map

package/dist/numeric/structured-solvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-solvers.d.ts","sourceRoot":"","sources":["../../src/numeric/structured-solvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA+B/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAwCtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA8E7E;AAED,6BAA6B;AAC7B,MAAM,WAAW,SAAS;IACxB,oCAAoC;IACpC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACd,oEAAoE;IACpE,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACd;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,SAAS,CAwG5C"}

package/dist/signal/conv.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Convolution Operations
+ *
+ * Implements 1D and 2D convolution using both direct and FFT methods.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Convolution mode - determines output size
+ */
+export type ConvMode = 'full' | 'same' | 'valid';
+/**
+ * Direct 1D convolution (for small inputs)
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full', 'same', or 'valid'
+ * @returns Convolution result
+ */
+export declare function convDirect(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * FFT-based 1D convolution (efficient for large inputs)
+ *
+ * Uses the convolution theorem: conv(x,h) = IFFT(FFT(x) * FFT(h))
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full', 'same', or 'valid'
+ * @returns Convolution result
+ */
+export declare function convFFT(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * 1D Convolution with automatic method selection
+ *
+ * Automatically selects direct or FFT method based on input sizes.
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full' (default), 'same', or 'valid'
+ * @returns Convolution result
+ *
+ * @example
+ * ```typescript
+ * // Simple convolution
+ * const signal = [1, 2, 3, 4, 5];
+ * const kernel = [1, 0, -1]; // Edge detection
+ * const result = conv(signal, kernel, 'same');
+ * ```
+ */
+export declare function conv(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Cross-correlation of two signals
+ *
+ * Cross-correlation is convolution with the kernel reversed.
+ *
+ * @param x - First signal
+ * @param h - Second signal
+ * @param mode - Output mode
+ * @returns Cross-correlation result
+ */
+export declare function xcorr(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Auto-correlation of a signal
+ *
+ * @param x - Input signal
+ * @param mode - Output mode
+ * @returns Auto-correlation result
+ */
+export declare function autocorr(x: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Direct 2D convolution
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode
+ * @returns 2D convolution result
+ */
+export declare function conv2Direct(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+/**
+ * FFT-based 2D convolution
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode
+ * @returns 2D convolution result
+ */
+export declare function conv2FFT(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+/**
+ * 2D Convolution with automatic method selection
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode: 'full' (default), 'same', or 'valid'
+ * @returns 2D convolution result
+ *
+ * @example
+ * ```typescript
+ * // Edge detection with Sobel kernel
+ * const image = [
+ *   [1, 2, 3],
+ *   [4, 5, 6],
+ *   [7, 8, 9],
+ * ];
+ * const sobelX = [
+ *   [-1, 0, 1],
+ *   [-2, 0, 2],
+ *   [-1, 0, 1],
+ * ];
+ * const edges = conv2(image, sobelX, 'same');
+ * ```
+ */
+export declare function conv2(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+//# sourceMappingURL=conv.d.ts.map

package/dist/signal/conv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conv.d.ts","sourceRoot":"","sources":["../../src/signal/conv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAYjD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CA8CV;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAsDV;AAOD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAClB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAWV;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAKV;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,CAEtF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,EAAE,EAClB,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,EAAE,CA8DZ;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,EAAE,EAClB,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,EAAE,CAiGZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,EAAE,CAgBhG"}

package/dist/signal/fft-helpers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Real FFT: compute the full FFT of a real signal and keep only the first
+ * `floor(n/2)+1` bins — the non-redundant half of the conjugate-symmetric spectrum.
+ *
+ * @param x Real input signal
+ * @returns `{ re, im }` arrays of length `floor(n/2)+1`
+ */
+export declare function rfft(x: number[]): {
+    re: number[];
+    im: number[];
+};
+/**
+ * Inverse real FFT: reconstruct the full conjugate-symmetric spectrum of length `n`
+ * from the non-redundant half produced by {@link rfft} (bins `n/2+1..n-1` are the
+ * conjugates of bins `n/2-1..1`), inverse-FFT it, and return the real parts.
+ *
+ * @param spec `{ re, im }` half-spectrum (bins `0..floor(n/2)`)
+ * @param n Length of the reconstructed real signal
+ * @returns Real-valued signal of length `n`
+ */
+export declare function irfft(spec: {
+    re: number[];
+    im: number[];
+}, n: number): number[];
+/**
+ * Shift the zero-frequency component to the center of the spectrum (roll by `floor(n/2)`).
+ */
+export declare function fftshift(x: number[]): number[];
+/**
+ * Inverse of {@link fftshift} (roll by `ceil(n/2)`).
+ */
+export declare function ifftshift(x: number[]): number[];
+/**
+ * DFT sample frequencies: `[0, 1, ..., ceil(n/2)-1, -floor(n/2), ..., -1] / (n*d)`.
+ *
+ * @param n Number of samples
+ * @param d Sample spacing (default 1)
+ */
+export declare function fftfreq(n: number, d?: number): number[];
+/**
+ * DFT sample frequencies matching {@link rfft} output: `[0, 1, ..., floor(n/2)] / (n*d)`.
+ *
+ * @param n Number of samples
+ * @param d Sample spacing (default 1)
+ */
+export declare function rfftfreq(n: number, d?: number): number[];
+/**
+ * 2-D FFT: FFT each row, then FFT each column of the result. Delegates directly to
+ * the package's N-dimensional `fft`, which already performs exactly this row-then-
+ * column transform when given a 2-D array.
+ */
+export declare function fftn(x: number[][]): {
+    re: number[][];
+    im: number[][];
+};
+//# sourceMappingURL=fft-helpers.d.ts.map

package/dist/signal/fft-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fft-helpers.d.ts","sourceRoot":"","sources":["../../src/signal/fft-helpers.ts"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,CAYhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAY/E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,MAAM,EAAE,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,MAAM,EAAE,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAKtE"}