deepbox 0.1.0

package/dist/index-Dx42TZaY.d.ts

@@ -0,0 +1,809 @@
+import { T as Tensor } from './Tensor-g8mUClel.js';
+import { A as Axis } from './tensor-B96jjJLQ.js';
+
+/**
+ * Cholesky decomposition.
+ *
+ * Factorizes symmetric positive definite matrix A into L * L^T where L is lower triangular.
+ *
+ * **Algorithm**: Cholesky-Banachiewicz algorithm
+ * **Time Complexity**: O(N³/3) - approximately half the cost of LU decomposition
+ * **Space Complexity**: O(N²) for output matrix
+ *
+ * **Mathematical Background**:
+ * For a symmetric positive definite matrix A, the Cholesky decomposition is:
+ * A = L * L^T
+ * where L is lower triangular with positive diagonal elements.
+ *
+ * **Numerical Stability**:
+ * - Only works for positive definite matrices (all eigenvalues > 0)
+ * - More stable than LU for this class of matrices
+ * - No pivoting required due to positive definiteness
+ *
+ * **Parameters**:
+ * @param a - Symmetric positive definite matrix of shape (N, N)
+ *
+ * **Returns**: L - Lower triangular matrix where A = L * L^T
+ *
+ * **Requirements**:
+ * - Input must be 2D square matrix
+ * - Matrix must be symmetric: A = A^T
+ * - Matrix must be positive definite: x^T * A * x > 0 for all x ≠ 0
+ *
+ * **Properties**:
+ * - A = L @ L^T
+ * - L is lower triangular (L[i,j] = 0 for j > i)
+ * - L has positive diagonal elements
+ * - Much faster than LU decomposition for positive definite matrices
+ * - Determinant: det(A) = (product of L[i,i])²
+ *
+ * @example
+ * ```ts
+ * import { cholesky } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * // Positive definite matrix
+ * const A = tensor([[4, 12, -16], [12, 37, -43], [-16, -43, 98]]);
+ * const L = cholesky(A);
+ *
+ * // Verify: A ≈ L @ L^T
+ * ```
+ *
+ * @throws {ShapeError} If input is not 2D square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If matrix is not symmetric
+ * @throws {DataValidationError} If matrix is not positive definite
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Cholesky_decomposition | Wikipedia: Cholesky decomposition}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 4.2.1
+ */
+declare function cholesky(a: Tensor): Tensor;
+
+/**
+ * Compute eigenvalues and eigenvectors of a square matrix.
+ *
+ * Solves A * v = λ * v where λ are eigenvalues and v are eigenvectors.
+ *
+ * **Algorithm**:
+ * - Symmetric matrices: Jacobi iteration (stable, accurate)
+ * - General matrices: QR iteration with Hessenberg reduction
+ *
+ * **Limitations**:
+ * - Only real eigenvalues are supported. Non-symmetric matrices whose
+ *   spectrum includes complex eigenvalues will cause an
+ *   {@link InvalidParameterError} to be thrown.
+ * - For symmetric/Hermitian matrices, use `eigh()` for better performance
+ * - May not converge for some matrices (bounded QR iterations; see options)
+ *
+ * **Parameters**:
+ * @param a - Square matrix of shape (N, N)
+ * @param options - Optional configuration overrides (see {@link EigOptions})
+ * @param options.maxIter - Maximum QR iterations (default: 300)
+ * @param options.tol - Convergence tolerance for subdiagonal norm (default: 1e-10)
+ *
+ * **Returns**: [eigenvalues, eigenvectors]
+ * - eigenvalues: Real values of shape (N,)
+ * - eigenvectors: Column vectors of shape (N, N) where eigenvectors[:,i] corresponds to eigenvalues[i]
+ *
+ * **Requirements**:
+ * - Input must be square matrix
+ * - Matrix must have only real eigenvalues
+ * - For symmetric matrices, use eigh() for better performance
+ *
+ * **Properties**:
+ * - A @ v[:,i] = λ[i] * v[:,i]
+ * - Eigenvectors are normalized
+ *
+ * @example
+ * ```ts
+ * import { eig } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [2, 1]]);
+ * const [eigenvalues, eigenvectors] = eig(A);
+ *
+ * // Verify: A @ eigenvectors[:,i] ≈ eigenvalues[i] * eigenvectors[:,i]
+ * ```
+ *
+ * @throws {ShapeError} If input is not square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ * @throws {InvalidParameterError} If matrix has complex eigenvalues
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix | Wikipedia: Eigendecomposition}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 7.5.2
+ */
+type EigOptions = {
+    readonly maxIter?: number;
+    readonly tol?: number;
+};
+declare function eig(a: Tensor, options?: EigOptions): [Tensor, Tensor];
+/**
+ * Compute eigenvalues only (faster than eig).
+ *
+ * **Parameters**:
+ * @param a - Square matrix of shape (N, N)
+ *
+ * **Returns**: eigenvalues - Array of real eigenvalues
+ *
+ * **Limitations**:
+ * - Matrices with complex eigenvalues are not supported and will throw
+ *   {@link InvalidParameterError}
+ *
+ * @example
+ * ```ts
+ * import { eigvals } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [2, 1]]);
+ * const eigenvalues = eigvals(A);
+ * console.log(eigenvalues);  // [3, -1]
+ * ```
+ */
+declare function eigvals(a: Tensor, options?: EigOptions): Tensor;
+/**
+ * Compute eigenvalues only of symmetric matrix (faster than eigh).
+ *
+ * **Parameters**:
+ * @param a - Symmetric square matrix of shape (N, N)
+ *
+ * **Returns**: eigenvalues - Array of real eigenvalues
+ *
+ * @example
+ * ```ts
+ * import { eigvalsh } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [2, 1]]);
+ * const eigenvalues = eigvalsh(A);
+ * console.log(eigenvalues);  // [-1, 3]
+ * ```
+ *
+ * @throws {ShapeError} If input is not square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input is not symmetric
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ */
+declare function eigvalsh(a: Tensor): Tensor;
+/**
+ * Compute eigenvalues and eigenvectors of a symmetric/Hermitian matrix.
+ *
+ * More efficient than eig() for symmetric matrices.
+ *
+ * **Parameters**:
+ * @param a - Symmetric matrix of shape (N, N)
+ *
+ * **Returns**: [eigenvalues, eigenvectors]
+ * - All eigenvalues are real
+ * - Eigenvectors are orthonormal
+ *
+ * @example
+ * ```ts
+ * import { eigh } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [2, 1]]);  // Symmetric
+ * const [eigenvalues, eigenvectors] = eigh(A);
+ * ```
+ *
+ * @throws {ShapeError} If input is not square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input is not symmetric
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ */
+declare function eigh(a: Tensor): [Tensor, Tensor];
+
+/**
+ * LU decomposition with partial pivoting.
+ *
+ * Factorizes matrix A into P * A = L * U where:
+ * - P is a permutation matrix
+ * - L is lower triangular with unit diagonal
+ * - U is upper triangular
+ *
+ * **Algorithm**: Gaussian elimination with partial pivoting
+ *
+ * **Parameters**:
+ * @param a - Input matrix of shape (M, N)
+ *
+ * **Returns**: [P, L, U]
+ * - P: Permutation matrix of shape (M, M)
+ * - L: Lower triangular matrix of shape (M, K) where K = min(M, N)
+ * - U: Upper triangular matrix of shape (K, N)
+ *
+ * **Requirements**:
+ * - Input must be 2D matrix
+ *
+ * **Properties**:
+ * - P @ A = L @ U
+ * - L has unit diagonal (L[i,i] = 1)
+ * - Partial pivoting ensures numerical stability
+ *
+ * @example
+ * ```ts
+ * import { lu } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[2, 1, 1], [4, 3, 3], [8, 7, 9]]);
+ * const [P, L, U] = lu(A);
+ *
+ * // Verify: P @ A ≈ L @ U
+ * ```
+ *
+ * @throws {ShapeError} If input is not 2D
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * **Note**: Rank-deficient matrices (with zero pivots) are handled gracefully.
+ * The factorization will still produce valid P, L, U factors.
+ *
+ * @see {@link https://en.wikipedia.org/wiki/LU_decomposition | Wikipedia: LU decomposition}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 3.4.1
+ */
+declare function lu(a: Tensor): [Tensor, Tensor, Tensor];
+
+/**
+ * QR decomposition.
+ *
+ * Factorizes matrix A into Q * R where Q is orthogonal and R is upper triangular.
+ *
+ * **Algorithm**: Householder reflections
+ *
+ * **Parameters**:
+ * @param a - Input matrix of shape (M, N)
+ * @param mode - Decomposition mode:
+ *   - 'reduced': Q has shape (M, K), R has shape (K, N) where K = min(M, N)
+ *   - 'complete': Q has shape (M, M), R has shape (M, N)
+ *
+ * **Returns**: [Q, R]
+ * - Q: Orthogonal matrix (Q^T * Q = I)
+ * - R: Upper triangular matrix
+ *
+ * **Requirements**:
+ * - Input must be 2D matrix
+ *
+ * **Properties**:
+ * - A = Q @ R
+ * - Q is orthogonal: Q^T @ Q = I
+ * - R is upper triangular
+ *
+ * @example
+ * ```ts
+ * import { qr } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[12, -51, 4], [6, 167, -68], [-4, 24, -41]]);
+ * const [Q, R] = qr(A);
+ *
+ * // Verify: A ≈ Q @ R
+ * // Verify: Q is orthogonal (Q^T @ Q ≈ I)
+ * ```
+ *
+ * @throws {ShapeError} If input is not 2D
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/QR_decomposition | Wikipedia: QR decomposition}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 5.2.1
+ */
+declare function qr(a: Tensor, mode?: "reduced" | "complete"): [Tensor, Tensor];
+
+/**
+ * Singular Value Decomposition.
+ *
+ * Factorizes matrix A into three matrices: A = U * Σ * V^T
+ *
+ * **Algorithm**: One-sided Jacobi (Hestenes) SVD
+ *
+ * **Numerical Stability**: Uses orthogonal rotations on A's columns to
+ * directly compute singular values and right singular vectors without forming
+ * A^T A. This is substantially more stable for ill-conditioned matrices than
+ * the normal-equations approach.
+ *
+ * **Implementation Details**:
+ * 1. Apply cyclic Jacobi rotations to orthogonalize columns of A
+ * 2. Column norms converge to singular values
+ * 3. Right singular vectors are accumulated as the product of rotations
+ * 4. Left singular vectors are normalized columns of the rotated matrix
+ *
+ * **Parameters**:
+ * @param a - Input matrix of shape (M, N)
+ * @param fullMatrices - If true, U has shape (M, M) and V has shape (N, N).
+ *                       If false, U has shape (M, K) and V has shape (N, K) where K = min(M, N)
+ *
+ * **Returns**: [U, s, Vt]
+ * - U: Left singular vectors of shape (M, M) or (M, K)
+ * - s: Singular values of shape (K,) in descending order
+ * - Vt: Right singular vectors transposed of shape (N, N) or (K, N)
+ *
+ * **Requirements**:
+ * - Input must be 2D matrix
+ * - Works with any M x N matrix
+ *
+ * **Properties**:
+ * - A = U @ diag(s) @ Vt
+ * - U and V are orthogonal matrices
+ * - Singular values are non-negative and sorted in descending order
+ *
+ * @example
+ * ```ts
+ * import { svd } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [3, 4], [5, 6]]);
+ * const [U, s, Vt] = svd(A);
+ *
+ * console.log(U.shape);   // [3, 3] if fullMatrices=true, [3, 2] if false
+ * console.log(s.shape);   // [2]
+ * console.log(Vt.shape);  // [2, 2] if fullMatrices=true, [2, 2] if false
+ *
+ * // Reconstruction: A ≈ U @ diag(s) @ Vt
+ * ```
+ *
+ * @throws {ShapeError} If input is not 2D
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Singular_value_decomposition | Wikipedia: SVD}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 8.6.2
+ */
+declare function svd(a: Tensor, fullMatrices?: boolean): [Tensor, Tensor, Tensor];
+
+/**
+ * Compute the inverse of a matrix.
+ *
+ * Finds matrix A^(-1) such that A * A^(-1) = I.
+ *
+ * **Parameters**:
+ * @param a - Square matrix of shape (N, N)
+ *
+ * **Returns**: Inverse matrix
+ *
+ * **Requirements**:
+ * - Matrix must be square
+ * - Matrix must be non-singular (det(A) ≠ 0)
+ *
+ * **Properties**:
+ * - A * inv(A) = I
+ * - inv(inv(A)) = A
+ * - inv(AB) = inv(B) * inv(A)
+ *
+ * @example
+ * ```ts
+ * import { inv } from 'deepbox/linalg';
+ * import { tensor, matmul } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [3, 4]]);
+ * const Ainv = inv(A);
+ *
+ * // Verify: A * A^(-1) ≈ I
+ * const I = matmul(A, Ainv);
+ * ```
+ *
+ * @throws {ShapeError} If matrix is not square or not 2D
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If matrix is singular or contains non-finite values
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Invertible_matrix | Wikipedia: Matrix inverse}
+ */
+declare function inv(a: Tensor): Tensor;
+/**
+ * Compute the Moore-Penrose pseudo-inverse.
+ *
+ * Generalization of matrix inverse for non-square or singular matrices.
+ *
+ * **Parameters**:
+ * @param a - Input matrix of shape (M, N)
+ * @param rcond - Cutoff for small singular values
+ *
+ * **Returns**: Pseudo-inverse of shape (N, M)
+ *
+ * **Properties**:
+ * - A * pinv(A) * A = A
+ * - pinv(A) * A * pinv(A) = pinv(A)
+ * - For full rank square matrix: pinv(A) = inv(A)
+ * - For overdetermined system: pinv(A) gives least squares solution
+ *
+ * **Algorithm**: Using SVD
+ * A = U * Σ * V^T
+ * pinv(A) = V * Σ^+ * U^T
+ * where Σ^+ is pseudo-inverse of Σ (1/s_i for s_i > rcond, else 0)
+ *
+ * @example
+ * ```ts
+ * import { pinv } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * // Non-square matrix
+ * const A = tensor([[1, 2], [3, 4], [5, 6]]);
+ * const Apinv = pinv(A);
+ *
+ * console.log(Apinv.shape);  // [2, 3]
+ * ```
+ *
+ * @throws {ShapeError} If input is not 2D matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {InvalidParameterError} If rcond is negative or non-finite
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_inverse | Wikipedia: Pseudo-inverse}
+ */
+declare function pinv(a: Tensor, rcond?: number): Tensor;
+
+/**
+ * Matrix or vector norm.
+ *
+ * Computes various matrix and vector norms.
+ *
+ * **Parameters**:
+ * @param x - Input array
+ * @param ord - Order of the norm:
+ *   For vectors:
+ *   - undefined or 2: L2 norm (Euclidean)
+ *   - 1: L1 norm (Manhattan)
+ *   - Infinity: Max norm
+ *   - -Infinity: Min norm
+ *   - 0: L0 "norm" (number of non-zero elements)
+ *   - p: Lp norm (p > 0). Negative p (except -Infinity) is invalid.
+ *   For matrices:
+ *   - 'fro': Frobenius norm
+ *   - 'nuc': Nuclear norm (sum of singular values)
+ *   - 1: Max column sum
+ *   - -1: Min column sum
+ *   - 2: Largest singular value
+ *   - -2: Smallest singular value
+ *   - Infinity: Max row sum
+ *   - -Infinity: Min row sum
+ * @param axis - Axis along which to compute norm
+ * @param keepdims - Keep reduced dimensions
+ *
+ * **Returns**: Norm value (scalar or tensor)
+ *
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ * @throws {InvalidParameterError} If norm order or axis values are invalid
+ * @throws {ShapeError} If axis configuration is incompatible with input
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Matrix_norm | Wikipedia: Matrix norm}
+ */
+declare function norm(x: Tensor, ord?: number | "fro" | "nuc", axis?: Axis | Axis[], keepdims?: boolean): Tensor | number;
+/**
+ * Condition number of a matrix.
+ *
+ * Measures how sensitive the solution of A*x=b is to changes in b.
+ * Large condition number indicates ill-conditioned matrix.
+ *
+ * **Formula**: cond(A) = ||A|| * ||A^(-1)||
+ *
+ * **Parameters**:
+ * @param a - Input matrix
+ * @param p - Norm order (same as norm())
+ *
+ * **Returns**: Condition number (>= 1, infinity for singular matrices)
+ *
+ * @throws {ShapeError} If input is not a 2D matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ * @throws {InvalidParameterError} If p is unsupported
+ */
+declare function cond(a: Tensor, _p?: number | "fro"): number;
+
+/**
+ * Compute the determinant of a matrix.
+ *
+ * Uses LU decomposition with partial pivoting for numerical stability.
+ * The determinant is computed as: det(A) = pivSign * product(diag(U))
+ *
+ * **Algorithm**: LU decomposition
+ * **Time Complexity**: O(N³) for N×N matrix
+ * **Space Complexity**: O(N²) for LU factorization
+ *
+ * **Parameters**:
+ * @param a - Square matrix of shape (N, N)
+ *
+ * **Returns**: Determinant value (scalar)
+ *
+ * **Properties**:
+ * - det(A) = 0 if and only if A is singular (non-invertible)
+ * - det(AB) = det(A) * det(B)
+ * - det(A^T) = det(A)
+ * - det(cA) = c^N * det(A) for scalar c and N×N matrix A
+ * - det(I) = 1 for identity matrix
+ *
+ * @example
+ * ```ts
+ * import { det } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [3, 4]]);
+ * console.log(det(A));  // -2
+ * ```
+ *
+ * @throws {ShapeError} If input is not a 2D square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Determinant | Wikipedia: Determinant}
+ */
+declare function det(a: Tensor): number;
+/**
+ * Compute sign and natural logarithm of the determinant.
+ *
+ * More numerically stable than det() for large matrices or matrices with
+ * very large/small determinants that would overflow/underflow.
+ *
+ * **Algorithm**: LU decomposition
+ * **Time Complexity**: O(N³)
+ * **Space Complexity**: O(N²)
+ *
+ * **Parameters**:
+ * @param a - Square matrix
+ *
+ * **Returns**: [sign, logdet]
+ * - sign: +1, -1, or 0 (as 0D tensor)
+ * - logdet: Natural log of |det(A)| (as 0D tensor), -Infinity if singular
+ *
+ * **Mathematical Relation**:
+ * det(A) = sign * exp(logdet)
+ *
+ * **Advantages over det()**:
+ * - Avoids overflow for large determinants
+ * - Avoids underflow for small determinants
+ * - More numerically stable for ill-conditioned matrices
+ *
+ * @example
+ * ```ts
+ * import { slogdet } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [3, 4]]);
+ * const [sign, logdet] = slogdet(A);
+ * // det(A) = sign * exp(logdet)
+ * ```
+ *
+ * @throws {ShapeError} If input is not a 2D square matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ */
+declare function slogdet(a: Tensor): [Tensor, Tensor];
+/**
+ * Compute the trace of a matrix.
+ *
+ * Sum of diagonal elements. Supports offset diagonals.
+ *
+ * **Algorithm**: Direct summation
+ * **Time Complexity**: O(min(M, N)) where M×N is matrix size
+ * **Space Complexity**: O(1)
+ *
+ * **Parameters**:
+ * @param a - Input matrix (at least 2D)
+ * @param offset - Integer offset from main diagonal:
+ *   - 0: main diagonal (default)
+ *   - >0: upper diagonal (k-th diagonal above main)
+ *   - <0: lower diagonal (k-th diagonal below main)
+ * @param axis1 - First axis to take the diagonal from (default: 0)
+ * @param axis2 - Second axis to take the diagonal from (default: 1)
+ *
+ * **Returns**: Trace values as tensor (one per slice if input is batched)
+ *
+ * **Properties**:
+ * - trace(A) = sum of eigenvalues (for square matrices)
+ * - trace(AB) = trace(BA) (cyclic property)
+ * - trace(A + B) = trace(A) + trace(B) (linearity)
+ * - trace(cA) = c * trace(A) for scalar c
+ * - trace(A^T) = trace(A)
+ *
+ * @example
+ * ```ts
+ * import { trace } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
+ * console.log(trace(A));  // 1 + 5 + 9 = 15
+ * console.log(trace(A, 1));  // 2 + 6 = 8 (upper diagonal)
+ * console.log(trace(A, -1));  // 4 + 8 = 12 (lower diagonal)
+ * ```
+ *
+ * @throws {ShapeError} If input is not at least 2D
+ * @throws {InvalidParameterError} If axis values are invalid/identical or offset is non-integer
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ */
+declare function trace(a: Tensor, offset?: number, axis1?: Axis, axis2?: Axis): Tensor;
+/**
+ * Compute the rank of a matrix.
+ *
+ * Number of linearly independent rows/columns.
+ * Uses SVD to count singular values above a threshold.
+ *
+ * **Algorithm**: SVD-based rank computation
+ * **Time Complexity**: O(min(M,N) * M * N) for M×N matrix
+ * **Space Complexity**: O(M*N) for SVD computation
+ *
+ * **Parameters**:
+ * @param a - Input matrix of shape (M, N)
+ * @param tol - Threshold for small singular values (optional)
+ *   - Default: max(M,N) * largest_singular_value * machine_epsilon
+ *   - Singular values > tol are counted as non-zero
+ *
+ * **Returns**: Rank (integer between 0 and min(M, N))
+ *
+ * **Properties**:
+ * - 0 ≤ rank(A) ≤ min(M, N)
+ * - rank(A) = rank(A^T)
+ * - rank(A) = number of non-zero singular values
+ * - Full rank: rank(A) = min(M, N)
+ * - Rank deficient: rank(A) < min(M, N)
+ *
+ * @example
+ * ```ts
+ * import { matrixRank } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[1, 2], [2, 4]]);  // Rank 1 (linearly dependent rows)
+ * console.log(matrixRank(A));  // 1
+ *
+ * const B = tensor([[1, 0], [0, 1]]);  // Full rank
+ * console.log(matrixRank(B));  // 2
+ * ```
+ *
+ * @throws {ShapeError} If input is not a 2D matrix
+ * @throws {DTypeError} If input has string dtype
+ * @throws {InvalidParameterError} If tol is negative or non-finite
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ */
+declare function matrixRank(a: Tensor, tol?: number): number;
+
+/**
+ * Least squares solution to A * x = b.
+ *
+ * Finds x that minimizes ||A*x - b||^2 (Euclidean norm).
+ * Works for overdetermined (M > N), underdetermined (M < N), and square systems.
+ *
+ * **Algorithm**: SVD-based least squares
+ *
+ * **Parameters**:
+ * @param a - Coefficient matrix of shape (M, N)
+ * @param b - Target values of shape (M,) or (M, K)
+ * @param rcond - Cutoff for small singular values (default: machine epsilon * max(M,N))
+ *
+ * **Returns**: Object with:
+ * - x: Least squares solution of shape (N,) or (N, K)
+ * - residuals: Sum of squared residuals ||b - A*x||^2
+ * - rank: Effective rank of A
+ * - s: Singular values of A
+ *
+ * **Requirements**:
+ * - A can be any M x N matrix
+ * - First dimension of A must match first dimension of b
+ *
+ * @example
+ * ```ts
+ * import { lstsq } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * // Overdetermined system (more equations than unknowns)
+ * const A = tensor([[1, 1], [1, 2], [1, 3]]);
+ * const b = tensor([2, 3, 5]);
+ * const result = lstsq(A, b);
+ *
+ * console.log(result.x);  // Best fit solution
+ * console.log(result.residuals);  // Residual error
+ * ```
+ *
+ * @throws {ShapeError} If A is not 2D matrix
+ * @throws {ShapeError} If b is not 1D or 2D tensor
+ * @throws {ShapeError} If dimensions don't match
+ * @throws {DTypeError} If input has string dtype
+ * @throws {InvalidParameterError} If rcond is negative or non-finite
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Least_squares | Wikipedia: Least squares}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 5.5.4
+ */
+declare function lstsq(a: Tensor, b: Tensor, rcond?: number): {
+    readonly x: Tensor;
+    readonly residuals: Tensor;
+    readonly rank: number;
+    readonly s: Tensor;
+};
+
+/**
+ * Solve linear system A * x = b.
+ *
+ * Finds vector x that satisfies the equation A * x = b.
+ *
+ * **Algorithm**: LU decomposition with partial pivoting
+ *
+ * **Parameters**:
+ * @param a - Coefficient matrix of shape (N, N)
+ * @param b - Right-hand side of shape (N,) or (N, K) for multiple RHS
+ *
+ * **Returns**: Solution x of same shape as b
+ *
+ * **Requirements**:
+ * - A must be square matrix
+ * - A must be non-singular (invertible)
+ * - Number of rows in A must equal length of b
+ *
+ * @example
+ * ```ts
+ * import { solve } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const A = tensor([[3, 1], [1, 2]]);
+ * const b = tensor([9, 8]);
+ * const x = solve(A, b);
+ *
+ * // Verify: A @ x ≈ b
+ * console.log(x);  // [2, 3]
+ * ```
+ *
+ * @throws {ShapeError} If A is not square
+ * @throws {ShapeError} If dimensions don't match
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If A is singular
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/System_of_linear_equations | Wikipedia: Linear systems}
+ * @see Golub & Van Loan, "Matrix Computations", Algorithm 3.4.1
+ */
+declare function solve(a: Tensor, b: Tensor): Tensor;
+/**
+ * Solve triangular system.
+ *
+ * More efficient than solve() when A is already triangular.
+ *
+ * **Parameters**:
+ * @param a - Triangular matrix of shape (N, N)
+ * @param b - Right-hand side of shape (N,) or (N, K)
+ * @param lower - If true, A is lower triangular; if false, upper triangular
+ *
+ * **Returns**: Solution x
+ *
+ * @example
+ * ```ts
+ * import { solveTriangular } from 'deepbox/linalg';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const L = tensor([[2, 0], [3, 4]]);  // Lower triangular
+ * const b = tensor([6, 18]);
+ * const x = solveTriangular(L, b, true);
+ * ```
+ *
+ * @throws {ShapeError} If A is not square
+ * @throws {ShapeError} If dimensions don't match
+ * @throws {DTypeError} If input has string dtype
+ * @throws {DataValidationError} If A is singular (zero diagonal)
+ * @throws {DataValidationError} If input contains non-finite values (NaN, Infinity)
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Triangular_matrix | Wikipedia: Triangular matrix}
+ */
+declare function solveTriangular(a: Tensor, b: Tensor, lower?: boolean): Tensor;
+
+type index_EigOptions = EigOptions;
+declare const index_cholesky: typeof cholesky;
+declare const index_cond: typeof cond;
+declare const index_det: typeof det;
+declare const index_eig: typeof eig;
+declare const index_eigh: typeof eigh;
+declare const index_eigvals: typeof eigvals;
+declare const index_eigvalsh: typeof eigvalsh;
+declare const index_inv: typeof inv;
+declare const index_lstsq: typeof lstsq;
+declare const index_lu: typeof lu;
+declare const index_matrixRank: typeof matrixRank;
+declare const index_norm: typeof norm;
+declare const index_pinv: typeof pinv;
+declare const index_qr: typeof qr;
+declare const index_slogdet: typeof slogdet;
+declare const index_solve: typeof solve;
+declare const index_solveTriangular: typeof solveTriangular;
+declare const index_svd: typeof svd;
+declare const index_trace: typeof trace;
+declare namespace index {
+  export { type index_EigOptions as EigOptions, index_cholesky as cholesky, index_cond as cond, index_det as det, index_eig as eig, index_eigh as eigh, index_eigvals as eigvals, index_eigvalsh as eigvalsh, index_inv as inv, index_lstsq as lstsq, index_lu as lu, index_matrixRank as matrixRank, index_norm as norm, index_pinv as pinv, index_qr as qr, index_slogdet as slogdet, index_solve as solve, index_solveTriangular as solveTriangular, index_svd as svd, index_trace as trace };
+}
+
+export { type EigOptions as E, eigh as a, eigvals as b, cholesky as c, eigvalsh as d, eig as e, inv as f, cond as g, det as h, index as i, slogdet as j, lstsq as k, lu as l, matrixRank as m, norm as n, solve as o, pinv as p, qr as q, solveTriangular as r, svd as s, trace as t };