@pawells/math-extended 1.0.5 → 2.0.0

package/build/matrices/decompositions.d.ts

@@ -1,4 +1,4 @@
-import { IMatrix } from './types.js';
+import { TMatrix } from './types.js';
 /**
  * Result of eigenvalue decomposition containing eigenvalues and their corresponding eigenvectors.
  *
@@ -10,20 +10,23 @@ type TEigenDecompositionResult = {
     /** Array of eigenvalues λ in descending order */
     eigenvalues: number[];
     /** Matrix where each column is an eigenvector corresponding to the eigenvalue at the same index */
-    eigenvectors: IMatrix;
+    eigenvectors: TMatrix;
 };
 /**
- * Result of LU decomposition where A = L × U.
+ * Result of LU decomposition with partial pivoting where P × A = L × U.
  *
  * LU decomposition factors a square matrix into the product of a lower triangular matrix L
- * and an upper triangular matrix U. This is useful for solving systems of linear equations,
+ * and an upper triangular matrix U, with a permutation vector P recording the row swaps
+ * performed during partial pivoting. This is useful for solving systems of linear equations,
  * computing determinants, and matrix inversion.
  */
 type TLUDecompositionResult = {
     /** Lower triangular matrix with 1's on the diagonal */
-    readonly L: IMatrix;
+    readonly L: TMatrix;
     /** Upper triangular matrix containing the pivots */
-    readonly U: IMatrix;
+    readonly U: TMatrix;
+    /** Permutation vector: P[i] is the original row index that now occupies row i */
+    readonly P: number[];
 };
 /**
  * Result of QR decomposition where A = Q × R.
@@ -34,9 +37,9 @@ type TLUDecompositionResult = {
  */
 type TQRDecompositionResult = {
     /** Orthogonal matrix where Q^T × Q = I */
-    readonly Q: IMatrix;
+    readonly Q: TMatrix;
     /** Upper triangular matrix */
-    readonly R: IMatrix;
+    readonly R: TMatrix;
 };
 /**
  * Result of Singular Value Decomposition (SVD) where A = U × Σ × V^T.
@@ -48,11 +51,11 @@ type TQRDecompositionResult = {
  */
 type TSVDDecompositionResult = {
     /** Matrix of left singular vectors (orthogonal columns) */
-    readonly U: IMatrix;
+    readonly U: TMatrix;
     /** Array of singular values σ in descending order (diagonal elements of Σ matrix) */
     readonly S: number[];
     /** Transpose of the matrix of right singular vectors (V^T where V has orthogonal columns) */
-    readonly VT: IMatrix;
+    readonly VT: TMatrix;
 };
 /**
  * Performs Cholesky decomposition for symmetric positive definite matrices A = L × L^T.
@@ -74,22 +77,22 @@ type TSVDDecompositionResult = {
  * @throws {Error} If matrix is not square, not symmetric, or not positive definite
  *
  * @example
- * ```ts
- * // Symmetric positive definite matrix
- * const A = [[4, 2], [2, 3]];
- * const L = MatrixCholesky(A);
- * // L = [[2, 0], [1, √2]] ≈ [[2, 0], [1, 1.414]]
- *
- * // Verify: L × L^T should equal A
- * const LT = MatrixTranspose(L);
- * const reconstructed = MatrixMultiply(L, LT);
- * // reconstructed ≈ [[4, 2], [2, 3]]
- * ```
- *
- * @complexity Time: O(n³/3), Space: O(n²) - About 2x faster than general LU decomposition
- * @see {@link MatrixLU} For general square matrices that may not be positive definite
+     * ```typescript
+     * ```ts
+     * // Symmetric positive definite matrix
+     * const A = [[4, 2], [2, 3]];
+     * const L = MatrixCholesky(A);
+     * // L = [[2, 0], [1, √2]] ≈ [[2, 0], [1, 1.414]]
+     * // Verify: L × L^T should equal A
+     * const LT = MatrixTranspose(L);
+     * const reconstructed = MatrixMultiply(L, LT);
+     * // reconstructed ≈ [[4, 2], [2, 3]]
+     * ```
+     * @complexity Time: O(n³/3), Space: O(n²) - About 2x faster than general LU decomposition
+     * @see {@link MatrixLU} For general square matrices that may not be positive definite
+     * ```
  */
-export declare function MatrixCholesky(matrix: IMatrix): IMatrix;
+export declare function MatrixCholesky(matrix: TMatrix): TMatrix;
 /**
  * Performs eigenvalue decomposition for square matrices to find A × v = λ × v.
  *
@@ -114,24 +117,24 @@ export declare function MatrixCholesky(matrix: IMatrix): IMatrix;
  * @throws {Error} If matrix is not square, contains invalid values, or has complex eigenvalues
  *
  * @example
- * ```ts
- * // Simple 2x2 matrix
- * const A = [[3, 1], [0, 2]];
- * const { eigenvalues, eigenvectors } = MatrixEigen(A);
- * // eigenvalues: [3, 2]
- * // eigenvectors: matrix where each column corresponds to an eigenvalue
- *
- * // Verify eigenvalue equation: A × v = λ × v
- * const v = Matrix_GetColumn(eigenvectors, 0); // First eigenvector
- * const Av = MatrixMultiplyVector(A, v);
- * const lambdaV = Matrix_ScaleVector(v, eigenvalues[0]);
- * // Av should approximately equal lambdaV
- * ```
- *
- * @complexity O(n³) time for an n×n matrix
- * @see {@link MatrixEigenQRIteration} For the iterative algorithm used for larger matrices
+     * ```typescript
+     * ```ts
+     * // Simple 2x2 matrix
+     * const A = [[3, 1], [0, 2]];
+     * const { eigenvalues, eigenvectors } = MatrixEigen(A);
+     * // eigenvalues: [3, 2]
+     * // eigenvectors: matrix where each column corresponds to an eigenvalue
+     * // Verify eigenvalue equation: A × v = λ × v
+     * const v = Matrix_GetColumn(eigenvectors, 0); // First eigenvector
+     * const Av = MatrixMultiplyVector(A, v);
+     * const lambdaV = Matrix_ScaleVector(v, eigenvalues[0]);
+     * // Av should approximately equal lambdaV
+     * ```
+     * @complexity O(n³) time for an n×n matrix
+     * @see {@link MatrixEigenQRIteration} For the iterative algorithm used for larger matrices
+     * ```
  */
-export declare function MatrixEigen(matrix: IMatrix): TEigenDecompositionResult;
+export declare function MatrixEigen(matrix: TMatrix): TEigenDecompositionResult;
 /**
  * Simplified QR iteration algorithm for eigenvalue computation of larger matrices.
  *
@@ -155,51 +158,46 @@ export declare function MatrixEigen(matrix: IMatrix): TEigenDecompositionResult;
  * @complexity O(n³) per iteration, typically converges in O(n) iterations
  * @see {@link MatrixQR} For the QR decomposition used in each iteration
  */
-export declare function MatrixEigenQRIteration(matrix: IMatrix, iterations?: number): TEigenDecompositionResult;
+export declare function MatrixEigenQRIteration(matrix: TMatrix, iterations?: number): TEigenDecompositionResult;
 /**
- * Performs LU decomposition of a square matrix A = L × U using Doolittle's method.
+ * Performs LU decomposition of a square matrix with partial pivoting: P × A = L × U.
  *
  * LU decomposition factors a square matrix into the product of a lower triangular matrix L
- * and an upper triangular matrix U. This decomposition is fundamental for solving linear
- * systems, computing determinants, and matrix inversion.
+ * and an upper triangular matrix U, with a permutation vector P recording the row swaps
+ * performed during partial (column) pivoting. Partial pivoting selects the largest-magnitude
+ * element in each column as the pivot, improving numerical stability.
  *
  * **Mathematical Background:**
  * - L is lower triangular with 1's on the diagonal (unit lower triangular)
  * - U is upper triangular containing the pivot elements
- * - The decomposition exists if all leading principal minors are non-zero
- * - Gaussian elimination with partial pivoting would be more stable, but this
- *   implementation uses Doolittle's method without pivoting for simplicity
+ * - P is a permutation vector where P[i] is the original row index at position i
+ * - The relationship is: P × A = L × U
  *
  * **Applications:**
- * - Solving linear systems: Ax = b becomes LUx = b, solve Ly = b then Ux = y
- * - Computing determinant: det(A) = det(L) × det(U) = det(U) = ∏ᵢ U[i,i]
- * - Matrix inversion: A⁻¹ = U⁻¹L⁻¹
+ * - Solving linear systems: Ax = b — apply permutation, solve Ly = Pb, then Ux = y
+ * - Computing determinant: det(A) = ∏ᵢ U[i,i] (with sign from permutation parity)
+ * - Matrix inversion: used internally by `MatrixInverse` for n > 3
  *
- * @param matrix - Square matrix to decompose (must be non-singular and not require pivoting)
- * @returns Object containing L (lower triangular) and U (upper triangular) matrices
- * @throws {Error} If matrix is not square, singular, or contains invalid values
- *
- * @note This implementation does not use partial pivoting (row swapping). It will fail for matrices with zero-valued or near-zero leading minors even if the matrix is otherwise invertible (e.g., [[0,1],[1,0]]). For general matrices, use MatrixInverse instead.
+ * @param matrix - Square matrix to decompose (must be non-singular)
+ * @returns Object `{ L, U, P }` — lower triangular, upper triangular, and permutation vector
+ * @throws {MatrixError} If matrix is not square, singular (zero pivot), or contains invalid values
  *
  * @example
- * ```ts
- * const A = [[2, 1], [1, 1]];
- * const { L, U } = MatrixLU(A);
- * // L = [[1, 0], [0.5, 1]], U = [[2, 1], [0, 0.5]]
- *
- * // Verify: L × U should equal A
- * const product = MatrixMultiply(L, U);
- * // product ≈ [[2, 1], [1, 1]]
- *
- * // Solve Ax = b using LU decomposition
- * const b = [3, 2];
- * // First solve Ly = b, then Ux = y
- * ```
- *
- * @complexity Time: O(n³/3), Space: O(n²)
- * @see {@link MatrixCholesky} For symmetric positive definite matrices (more efficient)
+     * ```typescript
+     * ```ts
+     * const A = [[2, 1], [1, 1]];
+     * const { L, U, P } = MatrixLU(A);
+     * // L = [[1, 0], [0.5, 1]], U = [[2, 1], [0, 0.5]], P = [0, 1]
+     * // Verify: L × U should equal P-permuted A
+     * const product = MatrixMultiply(L, U);
+     * // product ≈ [[2, 1], [1, 1]]
+     * ```
+     * @complexity Time: O(n³/3), Space: O(n²)
+     * @see {@link MatrixCholesky} For symmetric positive definite matrices (more efficient)
+     * @see {@link MatrixSolve} For solving Ax = b directly
+     * ```
  */
-export declare function MatrixLU(matrix: IMatrix): TLUDecompositionResult;
+export declare function MatrixLU(matrix: TMatrix): TLUDecompositionResult;
 /**
  * Performs QR decomposition A = Q × R using Modified Gram-Schmidt orthogonalization.
  *
@@ -224,25 +222,24 @@ export declare function MatrixLU(matrix: IMatrix): TLUDecompositionResult;
  * @throws {Error} If matrix has more columns than rows or columns are linearly dependent
  *
  * @example
- * ```ts
- * const A = [[1, 1], [1, 0], [0, 1]]; // 3×2 matrix
- * const { Q, R } = MatrixQR(A);
- * // Q: 3×2 orthogonal matrix with Q^T × Q = I₂
- * // R: 2×2 upper triangular matrix
- *
- * // Verify: Q × R should equal A
- * const reconstructed = MatrixMultiply(Q, R);
- * // reconstructed ≈ A
- *
- * // Check orthogonality: Q^T × Q should be identity
- * const QT = MatrixTranspose(Q);
- * const identity = MatrixMultiply(QT, Q);
- * ```
- *
- * @complexity Time: O(mn²), Space: O(mn) where m ≥ n
- * @see {@link MatrixGramSchmidt} {@link MatrixLU} {@link MatrixEigenQRIteration}
+     * ```typescript
+     * ```ts
+     * const A = [[1, 1], [1, 0], [0, 1]]; // 3×2 matrix
+     * const { Q, R } = MatrixQR(A);
+     * // Q: 3×2 orthogonal matrix with Q^T × Q = I₂
+     * // R: 2×2 upper triangular matrix
+     * // Verify: Q × R should equal A
+     * const reconstructed = MatrixMultiply(Q, R);
+     * // reconstructed ≈ A
+     * // Check orthogonality: Q^T × Q should be identity
+     * const QT = MatrixTranspose(Q);
+     * const identity = MatrixMultiply(QT, Q);
+     * ```
+     * @complexity Time: O(mn²), Space: O(mn) where m ≥ n
+     * @see {@link MatrixGramSchmidt} {@link MatrixLU} {@link MatrixEigenQRIteration}
+     * ```
  */
-export declare function MatrixQR(matrix: IMatrix, allowDependentColumns?: boolean): TQRDecompositionResult;
+export declare function MatrixQR(matrix: TMatrix, allowDependentColumns?: boolean): TQRDecompositionResult;
 /**
  * Performs Singular Value Decomposition (SVD) of a matrix A = U × Σ × V^T.
  *
@@ -276,31 +273,30 @@ export declare function MatrixQR(matrix: IMatrix, allowDependentColumns?: boolea
  * @throws {Error} If matrix contains invalid values (NaN, Infinity)
  *
  * @example
- * ```ts
- * const A = [[1, 2], [3, 4], [5, 6]]; // 3×2 matrix
- * const { U, S, VT } = MatrixSVD(A);
- * // U: 3×2 matrix with orthonormal columns
- * // S: [σ₁, σ₂] singular values in descending order
- * // VT: 2×2 orthogonal matrix (V transposed)
- *
- * // Verify reconstruction: U × diag(S) × VT ≈ A
- * const Sigma = Matrix_Diagonal(S);
- * const reconstructed = MatrixMultiply(MatrixMultiply(U, Sigma), VT);
- *
- * // Matrix rank from singular values (count non-zero values)
- * const rank = S.filter(s => s > 1e-10).length;
- *
- * // Condition number for stability analysis
- * const conditionNumber = S[0] / S[S.length - 1];
- * ```
- *
- * @complexity Time: O(min(m²n, mn²)), Space: O(m² + n²)
- * @see {@link MatrixQR} {@link MatrixEigenQRIteration} {@link Matrix_PseudoInverse}
+     * ```typescript
+     * ```ts
+     * const A = [[1, 2], [3, 4], [5, 6]]; // 3×2 matrix
+     * const { U, S, VT } = MatrixSVD(A);
+     * // U: 3×2 matrix with orthonormal columns
+     * // S: [σ₁, σ₂] singular values in descending order
+     * // VT: 2×2 orthogonal matrix (V transposed)
+     * // Verify reconstruction: U × diag(S) × VT ≈ A
+     * const Sigma = Matrix_Diagonal(S);
+     * const reconstructed = MatrixMultiply(MatrixMultiply(U, Sigma), VT);
+     * // Matrix rank from singular values (count non-zero values)
+     * const rank = S.filter(s => s > 1e-10).length;
+     * // Condition number for stability analysis
+     * const conditionNumber = S[0] / S[S.length - 1];
+     * ```
+     * @complexity Time: O(min(m²n, mn²)), Space: O(m² + n²)
+     * @see {@link MatrixQR} {@link MatrixEigenQRIteration} {@link Matrix_PseudoInverse}
+     * ```
  */
-export declare function MatrixSVD(matrix: IMatrix): TSVDDecompositionResult;
+export declare function MatrixSVD(matrix: TMatrix): TSVDDecompositionResult;
 /**
  * Solves the linear system Ax = b for the unknown vector x.
- * Uses LU decomposition internally followed by forward and back substitution.
+ * Uses LU decomposition with partial pivoting internally: decomposes A into P, L, U,
+ * applies the row permutation to b, then performs forward and back substitution.
  *
  * Given an n×n coefficient matrix A and an n-element right-hand side vector b,
  * finds x such that A × x = b.
@@ -311,16 +307,17 @@ export declare function MatrixSVD(matrix: IMatrix): TSVDDecompositionResult;
  * @throws {MatrixError} If A is not square, singular, or b has the wrong length
  *
  * @example
- * // 2x + y = 8
- * // 5x + 3y = 20
- * MatrixSolve([[2, 1], [5, 3]], [8, 20]); // [4, 0]
- *
- * @example
- * // Solve a 3×3 system
- * const A = [[1, 2, -1], [2, 1, 1], [3, -1, 2]];
- * const b = [4, 7, 2];
- * MatrixSolve(A, b); // solution vector x
+     * ```typescript
+     * // 2x + y = 8
+     * // 5x + 3y = 20
+     * MatrixSolve([[2, 1], [5, 3]], [8, 20]); // [4, 0]
+     * @example
+     * // Solve a 3×3 system
+     * const A = [[1, 2, -1], [2, 1, 1], [3, -1, 2]];
+     * const b = [4, 7, 2];
+     * MatrixSolve(A, b); // solution vector x
+     * ```
  */
-export declare function MatrixSolve(a: IMatrix, b: number[]): number[];
+export declare function MatrixSolve(a: TMatrix, b: number[]): number[];
 export {};
 //# sourceMappingURL=decompositions.d.ts.map

package/build/matrices/decompositions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decompositions.d.ts","sourceRoot":"","sources":["../../src/matrices/decompositions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAKrC;;;;;;GAMG;AACH,KAAK,yBAAyB,GAAG;IAChC,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mGAAmG;IACnG,YAAY,EAAE,OAAO,CAAC;CACtB,CAAC;AACF;;;;;;GAMG;AACH,KAAK,sBAAsB,GAAG;IAC7B,uDAAuD;IAEvD,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,oDAAoD;IAEpD,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AACF;;;;;;GAMG;AACH,KAAK,sBAAsB,GAAG;IAC7B,0CAA0C;IAE1C,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAE9B,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AACF;;;;;;;GAOG;AACH,KAAK,uBAAuB,GAAG;IAC9B,2DAA2D;IAE3D,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,qFAAqF;IAErF,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6FAA6F;IAE7F,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAoEvD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,yBAAyB,CAoHtE;AACD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,GAAE,MAAW,GAAG,yBAAyB,CA+D1G;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB,CAmGhE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,qBAAqB,UAAQ,GAAG,sBAAsB,CAiI/F;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,uBAAuB,CAkIlE;AACD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAsD7D"}
+{"version":3,"file":"decompositions.d.ts","sourceRoot":"","sources":["../../src/matrices/decompositions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAKrC;;;;;;GAMG;AACH,KAAK,yBAAyB,GAAG;IAChC,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mGAAmG;IACnG,YAAY,EAAE,OAAO,CAAC;CACtB,CAAC;AACF;;;;;;;GAOG;AACH,KAAK,sBAAsB,GAAG;IAC7B,uDAAuD;IAEvD,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,oDAAoD;IAEpD,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,iFAAiF;IAEjF,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AACF;;;;;;GAMG;AACH,KAAK,sBAAsB,GAAG;IAC7B,0CAA0C;IAE1C,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAE9B,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AACF;;;;;;;GAOG;AACH,KAAK,uBAAuB,GAAG;IAC9B,2DAA2D;IAE3D,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,qFAAqF;IAErF,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6FAA6F;IAE7F,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAoEvD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,yBAAyB,CAoHtE;AACD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,GAAE,MAAW,GAAG,yBAAyB,CA+D1G;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB,CA2EhE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,qBAAqB,UAAQ,GAAG,sBAAsB,CAiI/F;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,uBAAuB,CA2FlE;AACD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2D7D"}