@pawells/math-extended 1.1.1 → 3.0.0

package/build/matrices/decompositions.d.ts

@@ -1,4 +1,4 @@
-import { IMatrix } from './types.js';
+import type { TMatrix } from './types.js';
 /**
  * Result of eigenvalue decomposition containing eigenvalues and their corresponding eigenvectors.
  *
@@ -6,11 +6,11 @@ import { IMatrix } 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 */
-    eigenvectors: IMatrix;
+    eigenvectors: TMatrix;
 };
 /**
  * Result of LU decomposition with partial pivoting where P × A = L × U.
@@ -20,11 +20,11 @@ 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: 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[];
 };
@@ -35,11 +35,11 @@ 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: IMatrix;
+    readonly Q: TMatrix;
     /** Upper triangular matrix */
-    readonly R: IMatrix;
+    readonly R: TMatrix;
 };
 /**
  * Result of Singular Value Decomposition (SVD) where A = U × Σ × V^T.
@@ -51,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,25 +74,23 @@ 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
- * ```ts
+ * ```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: IMatrix): IMatrix;
+export declare function MatrixCholesky(matrix: TMatrix): TMatrix;
 /**
  * Performs eigenvalue decomposition for square matrices to find A × v = λ × v.
  *
@@ -114,27 +112,25 @@ export declare function MatrixCholesky(matrix: IMatrix): IMatrix;
  *
  * @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
- * ```ts
+ * ```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: IMatrix): TEigenDecompositionResult;
+export declare function MatrixEigen(matrix: TMatrix): TEigenDecompositionResult;
 /**
  * Simplified QR iteration algorithm for eigenvalue computation of larger matrices.
  *
@@ -150,15 +146,22 @@ export declare function MatrixEigen(matrix: IMatrix): 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
  * @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 with partial pivoting: P × A = L × U.
  *
@@ -183,21 +186,19 @@ export declare function MatrixEigenQRIteration(matrix: IMatrix, iterations?: num
  * @throws {MatrixError} If matrix is not square, singular (zero pivot), or contains invalid values
  *
  * @example
- * ```ts
+ * ```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: IMatrix): TLUDecompositionResult;
+export declare function MatrixLU(matrix: TMatrix): TLUDecompositionResult;
 /**
  * Performs QR decomposition A = Q × R using Modified Gram-Schmidt orthogonalization.
  *
@@ -219,28 +220,25 @@ export declare function MatrixLU(matrix: IMatrix): 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
- * ```ts
+ * ```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: 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.
  *
@@ -271,31 +269,27 @@ export declare function MatrixQR(matrix: IMatrix, 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
- * ```ts
+ * ```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
- * const Sigma = Matrix_Diagonal(S);
- * const reconstructed = MatrixMultiply(MatrixMultiply(U, Sigma), VT);
- *
+ * // 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: IMatrix): TSVDDecompositionResult;
+export declare function MatrixSVD(matrix: TMatrix): TSVDDecompositionResult;
 /**
  * Solves the linear system Ax = b for the unknown vector x.
  * Uses LU decomposition with partial pivoting internally: decomposes A into P, L, U,
@@ -310,16 +304,19 @@ export declare function MatrixSVD(matrix: IMatrix): 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
+ * ```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: 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;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CA2FlE;AACD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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"}