mathjslab/lib/types/LinearAlgebra.d.ts

MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.

import { type ComplexType } from './Complex';
import { type ElementType, MultiArray } from './MultiArray';
import { type BuiltInFunctionSignature, type NodeReturnList } from './AST';
/**
 * `LinearAlgebra` configuration options type.
 */
type LinearAlgebraConfig = {
    /**
     * LU Waste.
     */
    wasteLU: number;
    qrPhaseEpsilon: number;
};
export declare const LinearAlgebraConfigKeyTable: (keyof LinearAlgebraConfig)[];
/**
 * # LinearAlgebra
 *
 * LinearAlgebra abstract class. Implements static methods related to linear algebra operations and algorithms.
 *
 * ## 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 {
    /**
     * `LinearAlgebra` default settings.
     */
    static readonly defaultSettings: LinearAlgebraConfig;
    /**
     * `LinearAlgebra` current settings.
     */
    static readonly settings: LinearAlgebraConfig;
    /**
     * Set configuration options for `LinearAlgebra`.
     * @param config Configuration options.
     */
    static readonly set: (config: Partial<LinearAlgebraConfig>) => void;
    /**
     * Identity matrix
     * @param args
     * * `eye(N)` - create identity N x N
     * * `eye(N,M)` - create identity N x M
     * * `eye([N,M])` - create identity N x M
     * @returns Identity matrix
     */
    static readonly eye: (...args: MultiArray[] | ComplexType[]) => MultiArray | ComplexType;
    /**
     * Return a diagonal matrix with vector V on diagonal K.
     * @param args
     * @returns
     */
    static readonly diag: (...args: MultiArray[] | ComplexType[]) => MultiArray;
    /**
     * 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;
    /**
     * Transpose.
     * @param M Matrix.
     * @returns Transpose matrix.
     */
    static readonly transpose: (M: MultiArray) => MultiArray;
    /**
     * Complex conjugate transpose.
     * @param M Matrix.
     * @returns Complex conjugate transpose matrix.
     */
    static readonly ctranspose: (M: MultiArray) => MultiArray;
    /**
     * Matrix product.
     * @param left Matrix.
     * @param right Matrix.
     * @returns left * right.
     */
    static mul(left: MultiArray, right: MultiArray): MultiArray;
    /**
     * Matrix power (multiple multiplication).
     * @param left
     * @param right
     * @returns
     */
    static readonly power: (left: MultiArray, right: ComplexType) => MultiArray;
    /**
     * 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;
    };
    /**
     * PLU matrix factorization.
     * @param M Matrix.
     * @returns L, U and P matrices as multiple output.
     */
    static readonly lu: (M: MultiArray) => NodeReturnList;
    /**
     * 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;
    /**
     * 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;
    /**
     * 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;
    /**
     * 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?: any) => MultiArray;
    /**
     *
     * @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;
    };
    /**
     *
     * @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;
    };
    /**
     * 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;
    /**
     * 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]: Function;
    };
    /**
     * Declarative signatures for linear-algebra built-ins.
     *
     * The interpreter uses this table for shared arity/class validation before
     * dispatching to the functions table.
     */
    static readonly signatures: Record<string, BuiltInFunctionSignature>;
}
export { LinearAlgebra };
declare const _default: {
    LinearAlgebra: typeof LinearAlgebra;
};
export default _default;