@pawells/math-extended 2.0.0 → 3.0.0

package/build/matrices/decompositions.js

@@ -1,10 +1,11 @@
 import { AssertNumber, AssertInstanceOf, ArraySortBy } from '@pawells/typescript-common';
 import { MatrixMultiply } from './arithmetic.js';
-import { AssertMatrix, AssertMatrixRow, AssertMatrixValue, AssertMatrix1, AssertMatrix2, MatrixError } from './asserts.js';
+import { AssertMatrix, AssertMatrix1, AssertMatrix2, AssertMatrixSquare, MatrixError } from './asserts.js';
 import { MatrixSize, MatrixCreate, MatrixClone, MatrixIdentity, MatrixTranspose } from './core.js';
 import { MatrixGramSchmidt } from './linear-algebra.js';
 const MATRIX_NUMERICAL_TOLERANCE = 1e-12;
 const EIGEN_CONVERGENCE_TOLERANCE = 1e-10;
+const EIGEN_MAX_ITERATIONS = 50;
 /**
  * Performs Cholesky decomposition for symmetric positive definite matrices A = L × L^T.
  *
@@ -22,53 +23,45 @@ const EIGEN_CONVERGENCE_TOLERANCE = 1e-10;
  *
  * @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 function MatrixCholesky(matrix) {
-    AssertMatrix(matrix, { square: true });
+    AssertMatrixSquare(matrix);
     const [n] = MatrixSize(matrix);
     const L = MatrixCreate(n, n);
     // Perform Cholesky decomposition using the Cholesky-Banachiewicz algorithm
     for (let i = 0; i < n; i++) {
         const lRowI = L[i];
         const matrixRowI = matrix[i];
-        AssertMatrixRow(lRowI);
-        AssertMatrixRow(matrixRowI);
         for (let j = 0; j <= i; j++) {
             const lRowJ = L[j];
-            AssertMatrixRow(lRowJ);
             if (i === j) {
                 // Compute diagonal elements: L[i,i] = √(A[i,i] - Σ(k=0 to i-1) L[i,k]²)
                 let sum = 0;
                 // Sum of squares of elements in row i before column j
                 for (let k = 0; k < j; k++) {
                     const lVal = lRowI[k];
-                    AssertMatrixValue(lVal, { rowIndex: i, columnIndex: k });
                     sum += lVal * lVal;
                 }
                 const matrixVal = matrixRowI[j];
-                AssertMatrixValue(matrixVal, { rowIndex: i, columnIndex: j });
                 const diagonal = matrixVal - sum;
                 // Check positive definiteness - diagonal must be positive
-                if (diagonal <= 0) {
-                    throw new Error(`Matrix is not positive definite at element [${i},${j}]`);
-                }
+                if (diagonal <= 0)
+                    throw new MatrixError(`Matrix is not positive definite at element [${i},${j}]`);
                 lRowI[j] = Math.sqrt(diagonal);
             }
             else {
@@ -78,17 +71,13 @@ export function MatrixCholesky(matrix) {
                 for (let k = 0; k < j; k++) {
                     const lIVal = lRowI[k];
                     const lJVal = lRowJ[k];
-                    AssertMatrixValue(lIVal, { rowIndex: i, columnIndex: k });
-                    AssertMatrixValue(lJVal, { rowIndex: j, columnIndex: k });
                     sum += lIVal * lJVal;
                 }
                 const matrixVal = matrixRowI[j];
                 const lJDiag = lRowJ[j];
-                AssertMatrixValue(matrixVal, { rowIndex: i, columnIndex: j });
-                AssertMatrixValue(lJDiag, { rowIndex: j, columnIndex: j });
                 // Check for numerical stability - diagonal element should not be too small
                 if (Math.abs(lJDiag) < MATRIX_NUMERICAL_TOLERANCE) {
-                    throw new Error(`Zero diagonal element at [${j},${j}] - matrix not positive definite`);
+                    throw new MatrixError(`Zero diagonal element at [${j},${j}] - matrix not positive definite`);
                 }
                 lRowI[j] = (matrixVal - sum) / lJDiag;
             }
@@ -117,28 +106,26 @@ export function MatrixCholesky(matrix) {
  *
  * @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 function MatrixEigen(matrix) {
-    AssertMatrix(matrix, { square: true });
+    AssertMatrixSquare(matrix);
     const [n] = MatrixSize(matrix);
     // For small matrices, use direct analytical computation for efficiency and accuracy
     if (n === 1) {
@@ -162,7 +149,7 @@ export function MatrixEigen(matrix) {
         const discriminant = (trace * trace) - (4 * det);
         // Check for complex eigenvalues
         if (discriminant < 0) {
-            throw new Error('Complex eigenvalues not supported in this implementation');
+            throw new MatrixError('Complex eigenvalues not supported in this implementation');
         }
         const sqrtDisc = Math.sqrt(discriminant);
         const lambda1 = (trace + sqrtDisc) / 2;
@@ -175,8 +162,6 @@ export function MatrixEigen(matrix) {
             // First eigenvector: [1, 0] (for lambda1 = a)
             // Second eigenvector: [1, (lambda2 - a)/b]
             const [eigenvectorsRow0, eigenvectorsRow1] = eigenvectors;
-            AssertMatrixRow(eigenvectorsRow0);
-            AssertMatrixRow(eigenvectorsRow1);
             eigenvectorsRow0[0] = 1;
             eigenvectorsRow1[0] = 0;
             eigenvectorsRow0[1] = 1;
@@ -185,8 +170,6 @@ export function MatrixEigen(matrix) {
         else if (Math.abs(c) > MATRIX_NUMERICAL_TOLERANCE) {
             // Use the first row to find eigenvectors when c ≠ 0
             const [eigenvectorsRow0, eigenvectorsRow1] = eigenvectors;
-            AssertMatrixRow(eigenvectorsRow0);
-            AssertMatrixRow(eigenvectorsRow1);
             eigenvectorsRow0[0] = lambda1 - d;
             eigenvectorsRow1[0] = c;
             eigenvectorsRow0[1] = lambda2 - d;
@@ -195,8 +178,6 @@ export function MatrixEigen(matrix) {
         else {
             // Diagonal matrix case - eigenvectors are standard basis vectors
             const [eigenvectorsRow0, eigenvectorsRow1] = eigenvectors;
-            AssertMatrixRow(eigenvectorsRow0);
-            AssertMatrixRow(eigenvectorsRow1);
             eigenvectorsRow0[0] = 1;
             eigenvectorsRow1[0] = 0;
             eigenvectorsRow0[1] = 0;
@@ -208,7 +189,6 @@ export function MatrixEigen(matrix) {
             // Calculate the norm (length) of the eigenvector
             for (let i = 0; i < 2; i++) {
                 const eigenvectorsRowI = eigenvectors[i];
-                AssertMatrixRow(eigenvectorsRowI);
                 const val = eigenvectorsRowI[j];
                 AssertNumber(val, {}, { message: `Eigenvector[${i},${j}] Not a Number` });
                 norm += val * val;
@@ -218,9 +198,7 @@ export function MatrixEigen(matrix) {
             if (norm > MATRIX_NUMERICAL_TOLERANCE) {
                 for (let i = 0; i < 2; i++) {
                     const eigenvectorsRowI = eigenvectors[i];
-                    AssertMatrixRow(eigenvectorsRowI);
                     const val = eigenvectorsRowI[j];
-                    AssertMatrixValue(val, { rowIndex: i, columnIndex: j });
                     eigenvectorsRowI[j] = val / norm;
                 }
             }
@@ -248,15 +226,22 @@ export function MatrixEigen(matrix) {
  * 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 function MatrixEigenQRIteration(matrix, iterations = 50) {
+export function MatrixEigenQRIteration(matrix, iterations = EIGEN_MAX_ITERATIONS) {
     const [n] = MatrixSize(matrix);
     // Copy matrix for iteration to avoid modifying the original
     let A = MatrixClone(matrix);
@@ -271,7 +256,7 @@ export function MatrixEigenQRIteration(matrix, iterations = 50) {
         catch (err) {
             // If QR fails due to linear dependence, fill Q with orthonormal basis and R with zeros
             AssertInstanceOf(err, Error, { message: 'Unexpected error in QR iteration' });
-            if (err instanceof Error && typeof err.message === 'string' && err.message.includes('linearly dependent')) {
+            if (err.message.includes('linearly dependent')) {
                 Q = MatrixGramSchmidt(A);
                 R = MatrixCreate(n, n); // All zeros
             }
@@ -285,10 +270,8 @@ export function MatrixEigenQRIteration(matrix, iterations = 50) {
         let converged = true;
         for (let i = 0; i < n - 1; i++) {
             const aRowI = A[i];
-            AssertMatrixRow(aRowI);
             for (let j = i + 1; j < n; j++) {
                 const aVal = aRowI[j];
-                AssertMatrixValue(aVal, { rowIndex: i, columnIndex: j });
                 if (Math.abs(aVal) > EIGEN_CONVERGENCE_TOLERANCE) {
                     converged = false;
                     break;
@@ -304,9 +287,7 @@ export function MatrixEigenQRIteration(matrix, iterations = 50) {
     const eigenvalues = [];
     for (let i = 0; i < n; i++) {
         const aRowI = A[i];
-        AssertMatrixRow(aRowI);
         const eigenvalue = aRowI[i];
-        AssertMatrixValue(eigenvalue, { rowIndex: i, columnIndex: i });
         eigenvalues.push(eigenvalue);
     }
     return {
@@ -338,22 +319,20 @@ export function MatrixEigenQRIteration(matrix, iterations = 50) {
  * @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 function MatrixLU(matrix) {
-    AssertMatrix(matrix, { square: true });
+    AssertMatrixSquare(matrix);
     const [n] = MatrixSize(matrix);
     // Work on a mutable copy so partial pivoting can reorder rows
     const A = matrix.map((row) => [...row]);
@@ -435,32 +414,30 @@ export function MatrixLU(matrix) {
  *
  * @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 function MatrixQR(matrix, allowDependentColumns = false) {
     AssertMatrix(matrix);
     const [m, n] = MatrixSize(matrix);
     // Verify that the matrix has at least as many rows as columns
     if (m < n) {
-        throw new Error('QR decomposition requires matrix to have at least as many rows as columns');
+        throw new MatrixError('QR decomposition requires matrix to have at least as many rows as columns');
     }
     const Q = MatrixClone(matrix);
     const R = MatrixCreate(n, n);
@@ -471,16 +448,13 @@ export function MatrixQR(matrix, allowDependentColumns = false) {
             const qRow = Q[i];
             if (!qRow)
                 continue;
-            AssertMatrixRow(qRow);
             const qVal = qRow[k];
-            AssertMatrixValue(qVal, { rowIndex: i, columnIndex: k });
             norm += qVal * qVal;
         }
         norm = Math.sqrt(norm);
         if (norm < MATRIX_NUMERICAL_TOLERANCE) {
-            if (!allowDependentColumns) {
-                throw new Error(`Column ${k} is linearly dependent on previous columns`);
-            }
+            if (!allowDependentColumns)
+                throw new MatrixError(`Column ${k} is linearly dependent on previous columns`);
             // Fill Q[:,k] with an orthonormal vector not in the span of previous columns
             const candidate = Array(m).fill(0);
             candidate[k % m] = 1;
@@ -488,16 +462,12 @@ export function MatrixQR(matrix, allowDependentColumns = false) {
                 let dot = 0;
                 for (let i = 0; i < m; i++) {
                     const qRow = Q[i];
-                    AssertMatrixRow(qRow);
                     const qVal = qRow[j];
-                    AssertMatrixValue(qVal, { rowIndex: i, columnIndex: j });
                     dot += qVal * candidate[i];
                 }
                 for (let i = 0; i < m; i++) {
                     const qRow = Q[i];
-                    AssertMatrixRow(qRow);
                     const qVal = qRow[j];
-                    AssertMatrixValue(qVal, { rowIndex: i, columnIndex: j });
                     const candidateVal = candidate[i];
                     AssertNumber(candidateVal, {}, { message: `candidate[${i}] Not a Number` });
                     candidate[i] = candidateVal - (dot * qVal);
@@ -508,7 +478,7 @@ export function MatrixQR(matrix, allowDependentColumns = false) {
                 for (let i = 0; i < m; i++) {
                     const qRow = Q[i];
                     if (!Array.isArray(qRow))
-                        throw new Error(`Internal error: Q[${i}] is not an array`);
+                        throw new MatrixError(`Internal error: Q[${i}] is not an array`);
                     qRow[k] = candidate[i] / candNorm;
                 }
             }
@@ -516,53 +486,47 @@ export function MatrixQR(matrix, allowDependentColumns = false) {
                 for (let i = 0; i < m; i++) {
                     const qRow = Q[i];
                     if (!Array.isArray(qRow))
-                        throw new Error(`Internal error: Q[${i}] is not an array`);
+                        throw new MatrixError(`Internal error: Q[${i}] is not an array`);
                     qRow[k] = 0;
                 }
             }
             const rRow = R[k];
-            AssertMatrixRow(rRow);
-            for (let j = 0; j < n; j++) {
+            for (let j = 0; j < n; j++)
                 rRow[j] = 0;
-            }
             continue;
         }
         const rRow = R[k];
-        AssertMatrixRow(rRow);
         rRow[k] = norm;
         for (let i = 0; i < m; i++) {
             const qRow = Q[i];
             if (!qRow)
                 continue;
-            AssertMatrixRow(qRow);
             const qVal = qRow[k];
-            AssertMatrixValue(qVal, { rowIndex: i, columnIndex: k });
             qRow[k] = qVal / norm;
         }
+        // Extract k-th column of Q for cache-efficient access
+        const qColK = [];
+        for (let i = 0; i < m; i++) {
+            const qRow = Q[i];
+            if (qRow)
+                qColK[i] = qRow[k];
+        }
         for (let j = k + 1; j < n; j++) {
             let dot = 0;
             for (let i = 0; i < m; i++) {
                 const qRow = Q[i];
                 if (!qRow)
                     continue;
-                AssertMatrixRow(qRow);
-                const qValK = qRow[k];
                 const qValJ = qRow[j];
-                AssertMatrixValue(qValK, { rowIndex: i, columnIndex: k });
-                AssertMatrixValue(qValJ, { rowIndex: i, columnIndex: j });
-                dot += qValK * qValJ;
+                dot += qColK[i] * qValJ;
             }
             rRow[j] = dot;
             for (let i = 0; i < m; i++) {
                 const qRow = Q[i];
                 if (!qRow)
                     continue;
-                AssertMatrixRow(qRow);
-                const qValK = qRow[k];
                 const qValJ = qRow[j];
-                AssertMatrixValue(qValK, { rowIndex: i, columnIndex: k });
-                AssertMatrixValue(qValJ, { rowIndex: i, columnIndex: j });
-                qRow[j] = qValJ - (dot * qValK);
+                qRow[j] = qValJ - (dot * qColK[i]);
             }
         }
     }
@@ -598,27 +562,25 @@ export function MatrixQR(matrix, allowDependentColumns = false) {
  *
  * @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 function MatrixSVD(matrix) {
     AssertMatrix(matrix);
@@ -698,19 +660,21 @@ export function MatrixSVD(matrix) {
  * @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 function MatrixSolve(a, b) {
-    AssertMatrix(a, { square: true });
+    AssertMatrixSquare(a);
     const [n] = MatrixSize(a);
     if (b.length !== n) {
         throw new MatrixError(`Right-hand side vector length (${b.length}) must match matrix dimension (${n})`);
@@ -720,18 +684,16 @@ export function MatrixSolve(a, b) {
     const bPerm = P.map((pi) => {
         const val = b[pi];
         if (val === undefined)
-            throw new MatrixError(`b[${pi}] is undefined`);
+            throw new Error(`b[${pi}] is undefined`);
         return val;
     });
     // Forward substitution: solve Ly = b_perm (L has 1s on its diagonal)
     const y = new Array(n).fill(0);
     for (let i = 0; i < n; i++) {
         const lRow = L[i];
-        AssertMatrixRow(lRow);
         let sum = 0;
         for (let j = 0; j < i; j++) {
             const lVal = lRow[j];
-            AssertMatrixValue(lVal);
             sum += lVal * y[j];
         }
         y[i] = bPerm[i] - sum;
@@ -740,15 +702,12 @@ export function MatrixSolve(a, b) {
     const x = new Array(n).fill(0);
     for (let i = n - 1; i >= 0; i--) {
         const uRow = U[i];
-        AssertMatrixRow(uRow);
         let sum = 0;
         for (let j = i + 1; j < n; j++) {
             const uVal = uRow[j];
-            AssertMatrixValue(uVal);
             sum += uVal * x[j];
         }
         const uDiag = uRow[i];
-        AssertMatrixValue(uDiag);
         if (uDiag === 0)
             throw new MatrixError('Matrix is singular — cannot solve the linear system');
         x[i] = (y[i] - sum) / uDiag;