mathjslab

import { type ComplexType } from './Complex'; import { CharString } from './CharString'; import { type ElementType, MultiArray } from './MultiArray'; import { type BuiltInFunctionSignature, type NodeReturnList, type FunctionSignatureEntry } from './AST'; /** * Runtime configuration for higher-level linear algebra algorithms. */ type LinearAlgebraConfig = { /** * Numerical tolerance used to treat small LU pivots/residuals as zero. */ wasteLU: number; /** * Small phase-normalization threshold used by QR/LQ decompositions. */ qrPhaseEpsilon: number; }; type CrossDimensionArgument = ElementType | number; /** Public list of accepted `LinearAlgebra.set` configuration keys. */ export declare const LinearAlgebraConfigKeyTable: (keyof LinearAlgebraConfig)[]; /** * # LinearAlgebra * * MATLAB/Octave-facing linear algebra built-ins and decomposition helpers. * * This layer adapts `MultiArray` values to the lower-level BLAS/LAPACK-style * routines and publishes built-in signature metadata used by interpreter call * validation. Keep public methods aligned with MATLAB/Octave behavior first; * internal helper methods may expose more algorithm-specific shapes. * * ## References * * * [Linear Algebra at Wolfram MathWorld](https://mathworld.wolfram.com/LinearAlgebra.html) * * [Fundamental Theorem of Linear Algebra at Wolfram MathWorld](https://mathworld.wolfram.com/FundamentalTheoremofLinearAlgebra.html) * * [Linear algebra at Wikipedia](https://en.wikipedia.org/wiki/Linear_algebra) */ declare abstract class LinearAlgebra { /** * Immutable snapshot of default linear-algebra settings. */ static readonly defaultSettings: LinearAlgebraConfig; /** * Mutable current linear-algebra settings. */ static readonly settings: LinearAlgebraConfig; /** * Update linear-algebra runtime configuration. * * @param config Partial configuration object. * @throws Error when a configuration key is unknown. */ static readonly set: (config: Partial<LinearAlgebraConfig>) => void; /** * Signature metadata for the MATLAB/Octave `eye` built-in. */ static readonly eyeSignature: BuiltInFunctionSignature; /** * Create an identity matrix or scalar identity value. * * Supported forms mirror MATLAB/Octave: `eye()`, `eye(n)`, `eye([m n])`, * and `eye(m, n)`. * * @param args * Dimension arguments. * @returns Identity scalar or matrix. */ static readonly eye: (...args: MultiArray[] | ComplexType[]) => MultiArray | ComplexType; /** * Signature metadata for the MATLAB/Octave `diag` built-in. */ static readonly diagSignature: BuiltInFunctionSignature; /** * Extract a diagonal vector from a matrix or create a diagonal matrix from * a vector/scalar. * * The one- and two-argument forms follow MATLAB/Octave `diag`; the * three-argument form creates an explicit `m` by `n` diagonal matrix. * * @param args Value, optional offset, and optional explicit dimensions. * @returns Diagonal vector or matrix. */ static readonly diag: (...args: MultiArray[] | ComplexType[]) => MultiArray; static readonly traceSignature: BuiltInFunctionSignature; /** * Sum of diagonal elements. * @param M Matrix. * @returns Trace of matrix. */ static readonly trace: (M: MultiArray) => ComplexType; /** * Transpose and apply function. * @param M Matrix. * @returns Transpose matrix with `func` applied to each element. */ private static readonly applyTranspose; static readonly transposeSignature: BuiltInFunctionSignature; /** * Transpose scalar, character, or matrix values. * @param M Value to transpose. * @returns Transposed value. */ static readonly transpose: <T extends ElementType>(M: T) => T extends CharString ? MultiArray : T; static readonly ctransposeSignature: BuiltInFunctionSignature; /** * Complex conjugate transpose scalar, character, or matrix values. * @param M Value to conjugate-transpose. * @returns Complex conjugate transpose value. */ static readonly ctranspose: <T extends ElementType>(M: T) => T extends CharString ? MultiArray : T; static readonly mulSignature: BuiltInFunctionSignature; /** * Matrix product. * @param left Matrix. * @param right Matrix. * @returns left * right. */ static mul(left: MultiArray, right: MultiArray): MultiArray; static readonly powerSignature: BuiltInFunctionSignature; private static readonly multiplyMatrices; private static readonly formatDimensions; private static readonly hermitianEigenExpansion; /** * Matrix power for square matrices and scalar exponents. * * MATLAB/Octave-compatible integer powers are computed through * exponentiation by squaring. Non-integer scalar exponents currently use * the Hermitian/symmetric eigenvalue expansion supported by the numerical * backend. * * @param left Square matrix base. * @param right Integer real scalar exponent. * @returns Matrix power result. */ static readonly power: (left: MultiArray, right: ComplexType) => MultiArray; /** * Scalar base raised to a Hermitian/symmetric matrix exponent. * * MATLAB/Octave define `a^B` for scalar `a` and square matrix `B` through * an eigenvalue expansion. The current numerical backend exposes a * Hermitian/symmetric eigensolver, so this method intentionally accepts * that well-conditioned subset and rejects general square matrices until a * general eigensolver or Schur path is available. * * @param left Scalar base. * @param right Hermitian/symmetric matrix exponent. * @returns Matrix result `V * diag(left .^ lambda) * V'`. */ static readonly scalarPower: (left: ComplexType, right: MultiArray) => MultiArray; static readonly detSignature: BuiltInFunctionSignature; /** * Matrix determinant using LU decomposition with pivot sign correction. * Uses `LinearAlgebra.luDecomposition`. * @param M Matrix. * @returns Matrix determinant. */ static readonly det: (M: MultiArray) => ComplexType; /** * Computes the LU decomposition with partial pivoting. * @param M Input square matrix. * @returns An object { L, U, P, swaps } where: * - L: lower-triangular with unit diagonal (MultiArray) * - U: upper-triangular (MultiArray) * - P: permutation matrix (MultiArray) * - swaps: number of row swaps performed (integer) * * ## References * * https://www.codeproject.com/Articles/1203224/A-Note-on-PA-equals-LU-in-Javascript * * https://rosettacode.org/wiki/LU_decomposition#JavaScript */ static readonly luDecomposition: (A: MultiArray) => { L: MultiArray; U: MultiArray; P: MultiArray; swaps: number; }; static readonly luSignature: BuiltInFunctionSignature; /** * PLU matrix factorization. * @param M Matrix. * @returns L, U and P matrices as multiple output. */ static readonly lu: (M: MultiArray) => NodeReturnList; static readonly invSignature: BuiltInFunctionSignature; /** * Returns the inverse of matrix `M`. * inv(A) wrapper using LAPACK.getrf_blocked + LAPACK.getrs. * Behavior: MATLAB-like: if factorization reports info !== 0, emit warning and return matrix filled with Inf. * @param M Matrix. * @returns Inverted matrix. */ static readonly inv: (A: MultiArray) => MultiArray; static readonly condSignature: BuiltInFunctionSignature; /** * Matrix condition number for inversion. * * The default and `p = 2` forms use the singular value ratio. The * remaining MATLAB-compatible orders use `norm(A, p) * norm(inv(A), p)`. * * @param A Input matrix. * @param normType Optional norm type: `1`, `2`, `Inf`, or `'fro'`. * @returns Scalar condition number. */ static readonly cond: (A: MultiArray, normType?: ComplexType | CharString) => ComplexType; static readonly rankSignature: BuiltInFunctionSignature; /** * Numerical matrix rank estimated from singular values. * * MATLAB defines the default tolerance as `max(size(A)) * eps(norm(A))` * and counts singular values strictly larger than the tolerance. * * @param A Input matrix. * @param tolerance Optional singular-value tolerance. * @returns Rank as a scalar double value. */ static readonly rank: (A: MultiArray, tolerance?: ComplexType) => ComplexType; /** * Condition number through a matrix norm and inverse. * * @param A Input matrix. * @param normType Matrix norm type. * @returns `norm(A, p) * norm(inv(A), p)`. */ private static readonly squareMatrixNormCondition; /** * Matrix norm subset required by condition-number computation. * * @param matrix Input matrix. * @param normType Norm type. * @returns Requested matrix norm. */ private static readonly matrixNorm; /** * Compute squared singular values through the smaller Gram matrix. * * @param A Input matrix. * @returns Sorted nonnegative squared singular values. */ private static readonly singularValuesSquared; /** * Compute singular values in ascending order. * * @param A Input matrix. * @returns Sorted nonnegative singular values. */ private static readonly singularValues; /** * Estimate rank by Gaussian elimination with partial pivoting. * * This uses the MATLAB-compatible tolerance computed by `rank` but avoids * deciding exact dependencies through the squared condition of `A' * A`. * * @param A Input matrix. * @param tolerance Pivot tolerance. * @returns Estimated rank. */ private static readonly rankByElimination; /** * Matrix left division wrapper for the language-level `\` operator. * * This keeps parser/interpreter arithmetic routed through the * MATLAB/Octave-facing linear algebra layer while `LAPACK` remains the * numerical backend. * * @param A Coefficient matrix. * @param B Right-hand side matrix. * @returns Solution matrix `X` for `A * X = B`. */ static readonly mldivide: (A: MultiArray, B: MultiArray) => MultiArray; /** * Matrix right division wrapper for the language-level `/` operator. * * Implements `A / B` through the MATLAB/Octave identity * `((B') \ (A'))'`, routing the actual solve through `mldivide`. * * @param A Numerator matrix. * @param B Denominator matrix. * @returns Solution matrix `X` for `X * B = A`. */ static readonly mrdivide: (A: MultiArray, B: MultiArray) => MultiArray; static readonly gaussSignature: BuiltInFunctionSignature; /** * Gaussian elimination algorithm for solving systems of linear equations. * Adapted from: https://github.com/itsravenous/gaussian-elimination * ## References * * https://mathworld.wolfram.com/GaussianElimination.html * @param M Matrix. * @param m Vector. * @returns Solution of linear system. */ static readonly gauss: (M: MultiArray, m: MultiArray) => MultiArray; static readonly dotSignature: BuiltInFunctionSignature; /** * High-performance dot product. Fully ND-aware, column-major, no index * conversions (≈2-3× faster). Computes sum(conj(A).*B, dim) with minimal * per-element overhead. * C = dot(A,B) or C = dot(A,B,dim) * Sums conj(A).*B along the specified dimension (zero-based operateDim). If dim is omitted, * use the first non-singleton dimension (zero-based). * @param A First array (MultiArray). * @param B Second array (MultiArray). * @param dim (optional) Dimension along which to operate (ComplexType representing integer, 1-based externally). * @returns Scalar (ComplexType) if result is single value, else a MultiArray. */ static readonly dot: (A: MultiArray, B: MultiArray, dim?: ComplexType) => MultiArray | ComplexType; static readonly crossSignature: BuiltInFunctionSignature; private static readonly dimensionArgumentToNumber; /** * Cross product along dimension `dim` (MATLAB semantics). * A and B must have the same size except along `dim` where size must be 3. * dim is optional and is 1-based like MATLAB; internally converted to 0-based. * @param A * @param B * @param dim * @returns */ static readonly cross: (A: MultiArray, B: MultiArray, dim?: CrossDimensionArgument) => MultiArray; static readonly kronSignature: BuiltInFunctionSignature; /** * * @param A * @param B * @returns */ static readonly kron: (A: ElementType, B: ElementType) => MultiArray; /** * Normalize phases so that R diagonal becomes real non-negative: * For k = 0..minmn-1: * phi = R[k][k] / |R[k][k]| * R[k, j] := R[k, j] / phi (j = k..n-1) * Q[i, k] := Q[i, k] * phi (i = 0..m-1) * @param Q * @param R * @param phis */ static readonly qrPhaseNormalize: (phis: ComplexType[], R: MultiArray, Q?: MultiArray) => void; /** * Normalize LQ Householder phases in place. * * `phis` must come from the same LQ factorization that produced `L`. * When `Q` is supplied, the inverse phase adjustment is applied there so * the product represented by the factorization is preserved. * * @param phis Phase factors produced during LQ factorization. * @param L Lower/trapezoidal factor to normalize. * @param Q Optional unitary/orthogonal factor to update consistently. */ static readonly lqPhaseNormalize: (phis: ComplexType[], L: MultiArray, Q?: MultiArray) => void; /** * * @param A * @param result * @returns */ static readonly qrDecomposition: (A: MultiArray, result: 1 | 2 | 3) => { Q?: MultiArray; R: MultiArray; P?: MultiArray; }; static readonly qrSignature: BuiltInFunctionSignature; /** * * @param M * @returns */ static readonly qr: (M: MultiArray) => NodeReturnList; /** * eigDecomposition - wrapper that performs eigen decomposition using blocked tridiagonalization. * * Returns object depending on `result`: * 1 -> { values: MultiArray } (column vector n x 1) * 2 -> { values: MultiArray, vectors: MultiArray } (vector columns are eigenvectors) * 3 -> { values: MultiArray, vectors: MultiArray, T: MultiArray } (T = tridiagonal matrix) * * Uses: * - LAPACK.sytrd_blocked_w(Acopy, nb) -> { diag: ComplexType[], offdiag: ComplexType[], taus: ComplexType[] } * - LAPACK.steqr_values(diag, offdiag) -> ComplexType[] * - LAPACK.steqr_vectors(diag, offdiag) -> { D: ComplexType[], V: MultiArray } * - LAPACK.orgtr_blocked_w(Acopy, taus, nb) -> MultiArray Q0 * - BLAS.gemm_block(Q0, Z, Vout, Complex.one(), Complex.zero(), nb) */ /** * eigDecomposition - updated to use steqr_values/steqr_vectors returning MultiArray * * Returns: * result === 1 -> { values: MultiArray } * result === 2 -> { values: MultiArray, vectors: MultiArray } * result === 3 -> { values: MultiArray, vectors: MultiArray, T: MultiArray } */ static readonly eigDecomposition_original: (A: MultiArray, result: 1 | 2 | 3, nb?: number, order?: "asc" | "desc" | "none") => { values: MultiArray; vectors?: MultiArray; T?: MultiArray; }; /** * Compute a Hermitian/symmetric eigenvalue decomposition. * * The `result` selector mirrors MATLAB/Octave output arity: `1` computes * eigenvalues only, `2` computes eigenvectors and eigenvalues, and `3` also * exposes the tridiagonal intermediate matrix for diagnostics. * * @param A Square Hermitian/symmetric input matrix. * @param result Requested output shape. * @param order Eigenvalue ordering policy. * @param blockSize Optional block size for blocked tridiagonalization. * @returns Decomposition result with fields determined by `result`. */ static readonly eigDecomposition: (A: MultiArray, result: 1 | 2 | 3, order?: "asc" | "desc" | "none", blockSize?: number) => { values: MultiArray; vectors?: MultiArray; T?: MultiArray; }; static readonly eigSignature: BuiltInFunctionSignature; /** * MATLAB/Octave-style wrapper for `eig`. * * The returned `NodeReturnList` delays the actual decomposition until the * caller asks for a specific number of outputs. One output returns the * eigenvalues, two outputs return `[V, D]`, and three outputs return * `[V, D, T]` where `T` is the tridiagonal intermediate used for * diagnostics. */ static eig: (M: MultiArray) => NodeReturnList; static readonly testSignature: BuiltInFunctionSignature; /** * Small return-list fixture used by tests of multiple-output plumbing. * * The argument is intentionally unused; it keeps the signature parallel to * runtime helpers that receive a matrix before building a lazy return list. * * @param A Matrix argument kept for call-shape compatibility. * @returns A lazy return list with deterministic placeholder values. */ static test(A: MultiArray): NodeReturnList; /** * LinearAlgebra functions. */ static readonly functions: { [F in keyof LinearAlgebra | string]: FunctionSignatureEntry; }; } export { LinearAlgebra }; declare const _default: { LinearAlgebra: typeof LinearAlgebra; }; export default _default;