@pawells/math-extended 2.0.0 → 3.0.0

package/build/matrices/decompositions.d.ts

@@ -1,4 +1,4 @@
-import { TMatrix } from './types.js';
+import type { TMatrix } from './types.js';
 /**
  * Result of eigenvalue decomposition containing eigenvalues and their corresponding eigenvectors.
  *
@@ -6,7 +6,7 @@ import { TMatrix } from './types.js';
  * The eigenvalues represent the scaling factors, while eigenvectors represent the directions
  * that remain unchanged (up to scaling) under the linear transformation.
  */
-type TEigenDecompositionResult = {
+export 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 */
@@ -20,7 +20,7 @@ type TEigenDecompositionResult = {
  * performed during partial pivoting. This is useful for solving systems of linear equations,
  * computing determinants, and matrix inversion.
  */
-type TLUDecompositionResult = {
+export type TLUDecompositionResult = {
     /** Lower triangular matrix with 1's on the diagonal */
     readonly L: TMatrix;
     /** Upper triangular matrix containing the pivots */
@@ -35,7 +35,7 @@ type TLUDecompositionResult = {
  * and an upper triangular matrix R. This decomposition is fundamental for least squares
  * problems, eigenvalue algorithms, and solving overdetermined linear systems.
  */
-type TQRDecompositionResult = {
+export type TQRDecompositionResult = {
     /** Orthogonal matrix where Q^T × Q = I */
     readonly Q: TMatrix;
     /** Upper triangular matrix */
@@ -74,23 +74,21 @@ type TSVDDecompositionResult = {
  *
  * @param matrix - The symmetric positive definite square matrix to decompose
  * @returns Lower triangular matrix L such that A = L × L^T
- * @throws {Error} If matrix is not square, not symmetric, or not positive definite
+ * @throws {MatrixError} If matrix is not square, not symmetric, or not positive definite
  *
  * @example
-     * ```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
-     * ```
+ * ```typescript
+ * // 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: TMatrix): TMatrix;
 /**
@@ -114,25 +112,23 @@ export declare function MatrixCholesky(matrix: TMatrix): TMatrix;
  *
  * @param matrix - The square matrix to decompose
  * @returns Object containing eigenvalues and eigenvectors
- * @throws {Error} If matrix is not square, contains invalid values, or has complex eigenvalues
+ * @throws {MatrixError} If matrix is not square, contains invalid values, or has complex eigenvalues
  *
  * @example
-     * ```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
-     * ```
+ * ```typescript
+ * // 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: TMatrix): TEigenDecompositionResult;
 /**
@@ -150,9 +146,16 @@ export declare function MatrixEigen(matrix: TMatrix): TEigenDecompositionResult;
  * 4. Repeat until convergence (off-diagonal elements become small)
  * 5. Eigenvalues are the diagonal elements of the final matrix
  *
+ * **Convergence Notes:**
+ * The convergence check (examining off-diagonal elements) is optimized for symmetric
+ * inputs, which SVD provides via A^T A. For practical n×n matrices with well-conditioned
+ * symmetric inputs, convergence typically occurs within 2–5n iterations. The default
+ * maximum of 50 iterations is sufficient for matrices up to size ~10×10; larger matrices
+ * may require heuristic adjustments.
+ *
  * @private
  * @param matrix - Square matrix to compute eigenvalues for
- * @param iterations - Maximum number of QR iterations (default: 50)
+ * @param iterations - Maximum number of QR iterations (default: EIGEN_MAX_ITERATIONS = 50)
  * @returns Object containing eigenvalues and approximated eigenvectors
  *
  * @complexity O(n³) per iteration, typically converges in O(n) iterations
@@ -183,19 +186,17 @@ export declare function MatrixEigenQRIteration(matrix: TMatrix, iterations?: num
  * @throws {MatrixError} If matrix is not square, singular (zero pivot), or contains invalid values
  *
  * @example
-     * ```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
-     * ```
+ * ```typescript
+ * 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: TMatrix): TLUDecompositionResult;
 /**
@@ -219,25 +220,23 @@ export declare function MatrixLU(matrix: TMatrix): TLUDecompositionResult;
  *
  * @param matrix - Matrix to decompose (m×n where m ≥ n, must have full column rank)
  * @returns Object containing orthogonal Q and upper triangular R matrices
- * @throws {Error} If matrix has more columns than rows or columns are linearly dependent
+ * @throws {MatrixError} If matrix has more columns than rows or columns are linearly dependent
  *
  * @example
-     * ```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}
-     * ```
+ * ```typescript
+ * 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: TMatrix, allowDependentColumns?: boolean): TQRDecompositionResult;
 /**
@@ -270,27 +269,25 @@ export declare function MatrixQR(matrix: TMatrix, allowDependentColumns?: boolea
  *
  * @param matrix - Matrix to decompose (any m×n matrix)
  * @returns Object containing U, S (singular values), and VT matrices
- * @throws {Error} If matrix contains invalid values (NaN, Infinity)
+ * @throws {MatrixError} If matrix contains invalid values (NaN, Infinity)
  *
  * @example
-     * ```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}
-     * ```
+ * ```typescript
+ * 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
+ * // Note: Create diagonal matrix Sigma with S on diagonal, then: reconstructed = U × Sigma × VT
+ * const reconstructed = MatrixMultiply(MatrixMultiply(U, [[S[0], 0], [0, S[1]]]), 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: TMatrix): TSVDDecompositionResult;
 /**
@@ -307,16 +304,18 @@ export declare function MatrixSVD(matrix: TMatrix): TSVDDecompositionResult;
  * @throws {MatrixError} If A is not square, singular, or b has the wrong length
  *
  * @example
-     * ```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
-     * ```
+ * ```typescript
+ * // 2x + y = 8
+ * // 5x + 3y = 20
+ * MatrixSolve([[2, 1], [5, 3]], [8, 20]); // [4, 0]
+ * ```
+ * @example
+ * ```typescript
+ * // 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: TMatrix, b: number[]): number[];
 export {};

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;;;;;;;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"}
+{"version":3,"file":"decompositions.d.ts","sourceRoot":"","sources":["../../src/matrices/decompositions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAM1C;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACvC,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mGAAmG;IACnG,YAAY,EAAE,OAAO,CAAC;CACtB,CAAC;AACF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,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,MAAM,MAAM,sBAAsB,GAAG;IACpC,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyDvD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,yBAAyB,CAyGtE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,GAAE,MAA6B,GAAG,yBAAyB,CA2D5H;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB,CA2EhE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,qBAAqB,UAAQ,GAAG,sBAAsB,CA6G/F;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,uBAAuB,CA2FlE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAqD7D"}