@danielsimonjr/mathts-matrix 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -2523,6 +2523,124 @@ interface SchurOptions {
  */
 declare function matrixSchur(A: DenseMatrix, opts?: SchurOptions): SchurResult;
 
+/**
+ * Rank-Revealing Pivoted QR Decomposition (Businger-Golub column pivoting)
+ *
+ * Computes `A[:, P] = Q · R` via Householder reflections, choosing at each
+ * step the remaining column of largest norm as the next pivot. This is the
+ * classical column-pivoted QR (LAPACK `dgeqp3`'s algorithm, simplified —
+ * exact remaining-column-norm recomputation rather than the cheaper
+ * downdating formula, since these matrices are small): it guarantees
+ * `|R[0,0]| ≥ |R[1,1]| ≥ … ≥ |R[k-1,k-1]|`, which makes `R`'s diagonal a
+ * reliable numerical-rank indicator — unlike the plain (unpivoted)
+ * Gram-Schmidt `qr()` in this directory, whose diagonal can be small for an
+ * early column purely by column order, not by rank deficiency.
+ *
+ * Reuses the Householder helpers in `./common.js` (already exercised by
+ * `svd.ts`/`schur.ts`) rather than re-deriving reflection algebra here.
+ */
+
+interface QRPivotedResult {
+    /** Orthonormal Q factor (m × k, k = min(m, n)). */
+    Q: DenseMatrix;
+    /** Upper-triangular R factor (k × n) with |diag(R)| non-increasing. */
+    R: DenseMatrix;
+    /** Column permutation: `P[j]` is the original column index now at position `j`, so `A[:, P] = Q · R`. */
+    P: number[];
+    /** Numerical rank: count of `i` with `|R[i,i]| > tolerance · |R[0,0]|`. */
+    rank: number;
+}
+interface QRPivotedOptions {
+    /** Relative rank tolerance (default `1e-10`). */
+    tolerance?: number;
+}
+/**
+ * Compute the column-pivoted rank-revealing QR decomposition of `A`.
+ *
+ * @param A    - Input matrix (m × n).
+ * @param opts - Optional rank tolerance.
+ */
+declare function qrPivoted(A: DenseMatrix, opts?: QRPivotedOptions): QRPivotedResult;
+
+/**
+ * QR-family decompositions: LQ, RQ, QL
+ *
+ * Each is derived from the existing Gram-Schmidt `qr()` primitive in this
+ * directory via the standard flip/transpose reductions (Golub & Van Loan,
+ * *Matrix Computations*, §5.2):
+ *
+ *   - **LQ** (`A = L·Q`, L lower-triangular): `qr(Aᵀ)` transposed — no flips
+ *     needed. If `Aᵀ = Q₁·R₁` then `A = R₁ᵀ·Q₁ᵀ`, so `L = R₁ᵀ`, `Q = Q₁ᵀ`.
+ *   - **RQ** (`A = R·Q`, R upper-triangular): reverse `A`'s row order,
+ *     transpose, run `qr()`, then un-flip the resulting factors.
+ *   - **QL** (`A = Q·L`, L lower-triangular): reverse `A`'s column order,
+ *     run `qr()`, then un-flip the resulting factors.
+ *
+ * All three share `qr()`'s reduced-QR convention: for an m×n input the thin
+ * factor pairing is (m×k, k×n) with k = min(m, n).
+ */
+
+interface LQResult {
+    /** Lower-triangular (trapezoidal) factor. m × k, k = min(m, n). */
+    L: DenseMatrix;
+    /** Orthonormal-row factor (Q · Qᵀ = I). k × n. */
+    Q: DenseMatrix;
+}
+interface RQResult {
+    /** Upper-triangular (trapezoidal) factor. m × k, k = min(m, n). */
+    R: DenseMatrix;
+    /** Orthonormal-row factor (Q · Qᵀ = I). k × n. */
+    Q: DenseMatrix;
+}
+interface QLResult {
+    /** Orthonormal-column factor (Qᵀ · Q = I). m × k, k = min(m, n). */
+    Q: DenseMatrix;
+    /** Lower-triangular (trapezoidal) factor. k × n. */
+    L: DenseMatrix;
+}
+/**
+ * LQ decomposition: `A = L · Q` with `L` lower-triangular and `Q` having
+ * orthonormal rows (`Q · Qᵀ = I`).
+ */
+declare function lq(A: DenseMatrix): LQResult;
+/**
+ * RQ decomposition: `A = R · Q` with `R` upper-triangular and `Q` having
+ * orthonormal rows (`Q · Qᵀ = I`).
+ */
+declare function rq(A: DenseMatrix): RQResult;
+/**
+ * QL decomposition: `A = Q · L` with `Q` having orthonormal columns
+ * (`Qᵀ · Q = I`) and `L` lower-triangular.
+ */
+declare function ql(A: DenseMatrix): QLResult;
+
+/**
+ * Condition-number ESTIMATE (Hager/Higham 1-norm power-iteration estimator)
+ *
+ * Estimates `‖A‖₁ · ‖A⁻¹‖₁` without ever forming `A⁻¹` explicitly — Hager's
+ * algorithm (Hager 1984; Higham 1988's practical refinement) needs only the
+ * ability to apply `A⁻¹` and `A⁻ᵀ` to a vector, which is done here via the
+ * existing `lu()` primitive's triangular factors (forward/back substitution,
+ * O(n²) per application vs. O(n³) to form `A⁻¹` or run the SVD-based exact
+ * `cond()` in `svd.ts`). The result is an ESTIMATE — typically a lower bound
+ * on the true `‖A⁻¹‖₁`, usually within a small constant factor — not the
+ * exact value.
+ */
+
+/**
+ * Estimate the 1-norm condition number `‖A‖₁ · ‖A⁻¹‖₁` of a square matrix.
+ *
+ * This is an ESTIMATE (Hager/Higham power iteration), not the exact
+ * condition number that `cond()` (in `svd.ts`) computes via a full SVD —
+ * `condest` is O(n²)-per-iteration and avoids forming `A⁻¹`, at the cost of
+ * being a (typically close) lower-bound estimate rather than an exact value.
+ *
+ * @param A - Square input matrix.
+ * @param p - Only the 1-norm (`p = 1`, the default) is currently implemented.
+ * @throws {Error} if `A` is not square, or `p !== 1`.
+ */
+declare function condest(A: DenseMatrix, p?: number): number;
+
 /**
  * Typed Matrix Operations
  *
@@ -2906,4 +3024,4 @@ declare function initializeParallelMatrix(): Promise<void>;
  */
 declare function terminateParallelMatrix(): Promise<void>;
 
-export { BUILTIN_SHADERS, type BackendHints, BackendManager, BackendRegistry, type BackendType, BatchExecutor, type CholeskyResult, DEFAULT_BACKEND_HINTS, DEFAULT_EXTENDED_HINTS, DenseMatrix, type EigOptions, type EigResult, type ExpmOptions, type ExtendedBackendHints, GPUBackend, type GPUBackendOptions, type GPUBackendStatus, GPUMatrixBackend, type GPUMatrixBackendConfig, JSBackend, type LUResult, type LogmOptions, Matrix, type MatrixBackend, type MatrixDimensions, type MatrixEntry, type MatrixIndex, type MatrixType, type OperationType, ParallelBackend, type ParallelBackendConfig, type PinvOptions, type QROptions, type QRResult, type SVDOptions, type SVDResult, type SchurOptions, type SchurResult, type SliceSpec, SparseMatrix, type SqrtmOptions, type SyncConfig, SyncManager, type SyncStrategy, WASMBackend, type WASMBackendConfig, type WasmFeatures, abs, add, backendManager, backendRegistry, cholesky, clearFeatureCache, column, cond, createBackendManager, createGPUMatrixBackend, createParallelBackend, createSyncManager, createWASMBackend, destroyGlobalGPUBackend, detectWasmFeatures, diag, diagonal, divide, dotMultiply, eig, eigWasm, eigvals, eigvalsWasm, exp, getCachedFeatures, getGlobalGPUBackend, gpuMatrixBackend, identity, initializeGlobalGPUBackend, initializeParallelMatrix, isAtomicsAvailable, isDenseMatrix, isMatrix, isSharedMemoryAvailable, isSparseMatrix, isWasmAvailable, jsBackend, log, lowRankApprox, lu, matrix, matrixExpm, matrixLogm, pinv as matrixPinv, matrixSchur, matrixSqrtm, max, mean, min, multiply, norm, norm2, normFro, ones, parallelBackend, parallelDiag, parallelDotMultiply, parallelIdentity, parallelMatrix, parallelMatrixAbs, parallelMatrixAdd, parallelMatrixColumn, parallelMatrixCos, parallelMatrixDiagonal, parallelMatrixDistance, parallelMatrixDivide, parallelMatrixDot, parallelMatrixExp, parallelMatrixHistogram, parallelMatrixLog, parallelMatrixMatvec, parallelMatrixMax, parallelMatrixMean, parallelMatrixMin, parallelMatrixMultiply, parallelMatrixNorm, parallelMatrixOperations, parallelMatrixOuter, parallelMatrixRow, parallelMatrixSin, parallelMatrixSize, parallelMatrixSqrt, parallelMatrixSquare, parallelMatrixStd, parallelMatrixSubset, parallelMatrixSubtract, parallelMatrixSum, parallelMatrixTan, parallelMatrixTrace, parallelMatrixTranspose, parallelMatrixVariance, parallelOnes, parallelRandom, parallelUnaryMinus, parallelZeros, pinv$1 as pinv, pow, powerIteration, qr, random, row, singularValues, size, spectralRadiusWasm, sqrt, square, subset, subtract, sum, svd, svdWasm, terminateParallelMatrix, trace, transpose, typedMatrixOperations, unaryMinus, wasmBackend, zeros };
+export { BUILTIN_SHADERS, type BackendHints, BackendManager, BackendRegistry, type BackendType, BatchExecutor, type CholeskyResult, DEFAULT_BACKEND_HINTS, DEFAULT_EXTENDED_HINTS, DenseMatrix, type EigOptions, type EigResult, type ExpmOptions, type ExtendedBackendHints, GPUBackend, type GPUBackendOptions, type GPUBackendStatus, GPUMatrixBackend, type GPUMatrixBackendConfig, JSBackend, type LQResult, type LUResult, type LogmOptions, Matrix, type MatrixBackend, type MatrixDimensions, type MatrixEntry, type MatrixIndex, type MatrixType, type OperationType, ParallelBackend, type ParallelBackendConfig, type PinvOptions, type QLResult, type QROptions, type QRPivotedOptions, type QRPivotedResult, type QRResult, type RQResult, type SVDOptions, type SVDResult, type SchurOptions, type SchurResult, type SliceSpec, SparseMatrix, type SqrtmOptions, type SyncConfig, SyncManager, type SyncStrategy, WASMBackend, type WASMBackendConfig, type WasmFeatures, abs, add, backendManager, backendRegistry, cholesky, clearFeatureCache, column, cond, condest, createBackendManager, createGPUMatrixBackend, createParallelBackend, createSyncManager, createWASMBackend, destroyGlobalGPUBackend, detectWasmFeatures, diag, diagonal, divide, dotMultiply, eig, eigWasm, eigvals, eigvalsWasm, exp, getCachedFeatures, getGlobalGPUBackend, gpuMatrixBackend, identity, initializeGlobalGPUBackend, initializeParallelMatrix, isAtomicsAvailable, isDenseMatrix, isMatrix, isSharedMemoryAvailable, isSparseMatrix, isWasmAvailable, jsBackend, log, lowRankApprox, lq, lu, matrix, matrixExpm, matrixLogm, pinv as matrixPinv, matrixSchur, matrixSqrtm, max, mean, min, multiply, norm, norm2, normFro, ones, parallelBackend, parallelDiag, parallelDotMultiply, parallelIdentity, parallelMatrix, parallelMatrixAbs, parallelMatrixAdd, parallelMatrixColumn, parallelMatrixCos, parallelMatrixDiagonal, parallelMatrixDistance, parallelMatrixDivide, parallelMatrixDot, parallelMatrixExp, parallelMatrixHistogram, parallelMatrixLog, parallelMatrixMatvec, parallelMatrixMax, parallelMatrixMean, parallelMatrixMin, parallelMatrixMultiply, parallelMatrixNorm, parallelMatrixOperations, parallelMatrixOuter, parallelMatrixRow, parallelMatrixSin, parallelMatrixSize, parallelMatrixSqrt, parallelMatrixSquare, parallelMatrixStd, parallelMatrixSubset, parallelMatrixSubtract, parallelMatrixSum, parallelMatrixTan, parallelMatrixTrace, parallelMatrixTranspose, parallelMatrixVariance, parallelOnes, parallelRandom, parallelUnaryMinus, parallelZeros, pinv$1 as pinv, pow, powerIteration, ql, qr, qrPivoted, random, row, rq, singularValues, size, spectralRadiusWasm, sqrt, square, subset, subtract, sum, svd, svdWasm, terminateParallelMatrix, trace, transpose, typedMatrixOperations, unaryMinus, wasmBackend, zeros };

package/dist/index.js

@@ -7423,6 +7423,236 @@ function isSymmetricMatrix(A, tol = 1e-8) {
   return true;
 }
 
+// src/operations/qr-pivoted.ts
+init_DenseMatrix();
+function qrPivoted(A, opts) {
+  const m = A.rows;
+  const n = A.cols;
+  const tol = opts?.tolerance ?? 1e-10;
+  const k = Math.min(m, n);
+  if (m === 0 || n === 0) {
+    return {
+      Q: DenseMatrix.identity(m),
+      R: DenseMatrix.zeros(k, n),
+      P: Array.from({ length: n }, (_, i) => i),
+      rank: 0
+    };
+  }
+  const W = A.toArray();
+  const Qacc = eye(m);
+  const perm = Array.from({ length: n }, (_, i) => i);
+  const colNormSq = new Array(n).fill(0);
+  for (let j = 0; j < n; j++) {
+    let s = 0;
+    for (let i = 0; i < m; i++) s += W[i][j] * W[i][j];
+    colNormSq[j] = s;
+  }
+  for (let c = 0; c < k; c++) {
+    let pivotCol = c;
+    let maxNorm = colNormSq[c];
+    for (let j = c + 1; j < n; j++) {
+      if (colNormSq[j] > maxNorm) {
+        maxNorm = colNormSq[j];
+        pivotCol = j;
+      }
+    }
+    if (pivotCol !== c) {
+      for (let i = 0; i < m; i++) {
+        const t = W[i][c];
+        W[i][c] = W[i][pivotCol];
+        W[i][pivotCol] = t;
+      }
+      const tn = colNormSq[c];
+      colNormSq[c] = colNormSq[pivotCol];
+      colNormSq[pivotCol] = tn;
+      const tp = perm[c];
+      perm[c] = perm[pivotCol];
+      perm[pivotCol] = tp;
+    }
+    const col = [];
+    for (let i = c; i < m; i++) col.push(W[i][c]);
+    const { v, beta } = householder(col, 2);
+    if (beta !== 0) {
+      applyHouseholderLeft(W, v, beta, c, c);
+      applyHouseholderRight(Qacc, v, beta, 0, c);
+    }
+    for (let j = c + 1; j < n; j++) {
+      let s = 0;
+      for (let i = c + 1; i < m; i++) s += W[i][j] * W[i][j];
+      colNormSq[j] = s;
+    }
+  }
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < Math.min(i, n); j++) {
+      W[i][j] = 0;
+    }
+  }
+  const rData = new Float64Array(k * n);
+  for (let i = 0; i < k; i++) {
+    for (let j = 0; j < n; j++) rData[i * n + j] = W[i][j];
+  }
+  const qData = new Float64Array(m * k);
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < k; j++) qData[i * k + j] = Qacc[i][j];
+  }
+  const r00 = Math.abs(rData[0] ?? 0);
+  let rank = 0;
+  if (r00 > 0) {
+    for (let i = 0; i < k; i++) {
+      if (Math.abs(rData[i * n + i]) > tol * r00) rank++;
+    }
+  }
+  return {
+    Q: new DenseMatrix(m, k, qData),
+    R: new DenseMatrix(k, n, rData),
+    P: perm,
+    rank
+  };
+}
+
+// src/operations/qr-family.ts
+init_DenseMatrix();
+function flipRows(M) {
+  const m = M.rows;
+  const n = M.cols;
+  const src = M.toFloat64Array();
+  const data = new Float64Array(m * n);
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      data[i * n + j] = src[(m - 1 - i) * n + j];
+    }
+  }
+  return new DenseMatrix(m, n, data);
+}
+function flipCols(M) {
+  const m = M.rows;
+  const n = M.cols;
+  const src = M.toFloat64Array();
+  const data = new Float64Array(m * n);
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      data[i * n + j] = src[i * n + (n - 1 - j)];
+    }
+  }
+  return new DenseMatrix(m, n, data);
+}
+function lq(A) {
+  const { Q: Q1, R: R1 } = qr(A.transpose(), { mode: "reduced" });
+  return { L: R1.transpose(), Q: Q1.transpose() };
+}
+function rq(A) {
+  const B2 = flipRows(A).transpose();
+  const { Q: Q1, R: R1 } = qr(B2, { mode: "reduced" });
+  const R = flipCols(flipRows(R1.transpose()));
+  const Q = flipRows(Q1.transpose());
+  return { R, Q };
+}
+function ql(A) {
+  const B2 = flipCols(A);
+  const { Q: Q1, R: R1 } = qr(B2, { mode: "reduced" });
+  const L = flipCols(flipRows(R1));
+  const Q = flipCols(Q1);
+  return { Q, L };
+}
+
+// src/operations/condest.ts
+function luSolve(L, U, perm, n, b) {
+  const pb = new Array(n);
+  for (let i = 0; i < n; i++) pb[i] = b[perm[i]];
+  const y = new Array(n);
+  for (let i = 0; i < n; i++) {
+    let s = pb[i];
+    for (let j = 0; j < i; j++) s -= L[i * n + j] * y[j];
+    y[i] = s;
+  }
+  const x = new Array(n);
+  for (let i = n - 1; i >= 0; i--) {
+    let s = y[i];
+    for (let j = i + 1; j < n; j++) s -= U[i * n + j] * x[j];
+    x[i] = s / U[i * n + i];
+  }
+  return x;
+}
+function luSolveTranspose(L, U, perm, n, b) {
+  const z = new Array(n);
+  for (let i = 0; i < n; i++) {
+    let s = b[i];
+    for (let j = 0; j < i; j++) s -= U[j * n + i] * z[j];
+    z[i] = s / U[i * n + i];
+  }
+  const w = new Array(n);
+  for (let i = n - 1; i >= 0; i--) {
+    let s = z[i];
+    for (let j = i + 1; j < n; j++) s -= L[j * n + i] * w[j];
+    w[i] = s;
+  }
+  const x = new Array(n);
+  for (let i = 0; i < n; i++) x[perm[i]] = w[i];
+  return x;
+}
+function hagerNormEstimate(applyB, applyBT, n) {
+  let x = new Array(n).fill(1 / n);
+  let gamma = 0;
+  let lastIndex = -1;
+  for (let iter = 0; iter < 5; iter++) {
+    const y = applyB(x);
+    let newGamma = 0;
+    for (const v of y) newGamma += Math.abs(v);
+    if (iter > 0 && newGamma <= gamma) break;
+    gamma = newGamma;
+    const xi = y.map((v) => v >= 0 ? 1 : -1);
+    const z = applyBT(xi);
+    let maxIndex = 0;
+    let maxAbs = Math.abs(z[0]);
+    for (let i = 1; i < n; i++) {
+      if (Math.abs(z[i]) > maxAbs) {
+        maxAbs = Math.abs(z[i]);
+        maxIndex = i;
+      }
+    }
+    if (iter > 0 && maxIndex === lastIndex) break;
+    lastIndex = maxIndex;
+    x = new Array(n).fill(0);
+    x[maxIndex] = 1;
+  }
+  return gamma;
+}
+function condest(A, p = 1) {
+  if (p !== 1) {
+    throw new Error(`condest: only the 1-norm estimator (p=1) is implemented (got p=${p})`);
+  }
+  const n = A.rows;
+  if (A.cols !== n) {
+    throw new Error(`condest: matrix must be square (got ${A.rows}\xD7${A.cols})`);
+  }
+  if (n === 0) return 0;
+  const flat2 = A.toFloat64Array();
+  let norm1A = 0;
+  for (let j = 0; j < n; j++) {
+    let colSum = 0;
+    for (let i = 0; i < n; i++) colSum += Math.abs(flat2[i * n + j]);
+    if (colSum > norm1A) norm1A = colSum;
+  }
+  if (norm1A === 0) return 0;
+  let L;
+  let U;
+  let perm;
+  try {
+    const factors = lu(A);
+    L = factors.L.toFloat64Array();
+    U = factors.U.toFloat64Array();
+    perm = factors.P;
+  } catch {
+    return Infinity;
+  }
+  const norm1Inv = hagerNormEstimate(
+    (v) => luSolve(L, U, perm, n, v),
+    (v) => luSolveTranspose(L, U, perm, n, v),
+    n
+  );
+  return norm1A * norm1Inv;
+}
+
 // src/typed-operations.ts
 init_DenseMatrix();
 import { mathTyped } from "@danielsimonjr/mathts-core";
@@ -8275,6 +8505,7 @@ export {
   clearFeatureCache,
   column,
   cond,
+  condest,
   createBackendManager,
   createGPUMatrixBackend,
   createParallelBackend,
@@ -8311,6 +8542,7 @@ export {
   jsBackend,
   log,
   lowRankApprox,
+  lq,
   lu,
   matrix,
   matrixExpm,
@@ -8370,9 +8602,12 @@ export {
   pinv,
   pow,
   powerIteration,
+  ql,
   qr,
+  qrPivoted,
   random,
   row,
+  rq,
   singularValues,
   size,
   spectralRadiusWasm,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-matrix",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Matrix operations for MathTS with WASM/WebGPU backend support",
   "author": "Daniel Simon Jr.",
   "license": "MIT",