@tangent.to/lina 0.1.0

package/src/index.js

@@ -0,0 +1,46 @@
+/**
+ * @tangent.to/lina - Linear algebra for JavaScript (ESM)
+ *
+ * LU, QR, Cholesky, SVD, symmetric eigendecomposition and least squares
+ * on plain nested arrays, computed on flat Float64Array storage
+ * internally. numpy/scipy.linalg-validated. MIT infrastructure of the
+ * tangent suite.
+ */
+
+export { det, inv, lu, solve } from './lu.js';
+export { cholesky, choleskySolve, isPositiveDefinite } from './cholesky.js';
+export { lstsq, qr } from './qr.js';
+export { cond, pinv, pinvSolve, rank, svd } from './svd.js';
+export { eigSym } from './eigsym.js';
+export { diag, identity, matmul, norm, trace, transpose } from './ops.js';
+
+import { det, inv, lu, solve } from './lu.js';
+import { cholesky, choleskySolve, isPositiveDefinite } from './cholesky.js';
+import { lstsq, qr } from './qr.js';
+import { cond, pinv, pinvSolve, rank, svd } from './svd.js';
+import { eigSym } from './eigsym.js';
+import { diag, identity, matmul, norm, trace, transpose } from './ops.js';
+
+export default {
+  lu,
+  solve,
+  det,
+  inv,
+  cholesky,
+  choleskySolve,
+  isPositiveDefinite,
+  qr,
+  lstsq,
+  svd,
+  pinv,
+  pinvSolve,
+  rank,
+  cond,
+  eigSym,
+  matmul,
+  transpose,
+  identity,
+  diag,
+  norm,
+  trace,
+};

package/src/lu.js

@@ -0,0 +1,212 @@
+/**
+ * LU factorization with scaled partial pivoting, and LU-based solve/det/inv.
+ *
+ * Public APIs accept and return nested row-major matrices; computation runs
+ * on flat Float64Array storage (see _mat.js).
+ */
+
+import { fromNested, toNested, vecFrom } from './_mat.js';
+
+/**
+ * Factor a flat square matrix in place-of-copy with scaled partial pivoting.
+ *
+ * Returns the combined LU storage (unit-diagonal L strictly below the
+ * diagonal, U on and above), the row permutation `perm` (row k of the
+ * factored matrix is row perm[k] of the input), the permutation sign, and a
+ * singularity flag (any pivot with |pivot| <= 1e-13 * maxAbs of the input).
+ *
+ * @param {Float64Array} src - Flat row-major n*n values (not modified)
+ * @param {number} n - Dimension
+ * @returns {{a: Float64Array, perm: Int32Array, sign: number, singular: boolean}}
+ */
+function luFactor(src, n) {
+  const a = Float64Array.from(src);
+  const perm = new Int32Array(n);
+  const scale = new Float64Array(n);
+  let maxAbs = 0;
+  for (let i = 0; i < a.length; i++) maxAbs = Math.max(maxAbs, Math.abs(a[i]));
+  const tol = 1e-13 * maxAbs;
+  let sign = 1;
+  let singular = maxAbs === 0;
+
+  for (let i = 0; i < n; i++) {
+    perm[i] = i;
+    let s = 0;
+    for (let j = 0; j < n; j++) s = Math.max(s, Math.abs(a[i * n + j]));
+    scale[i] = s;
+  }
+
+  for (let k = 0; k < n; k++) {
+    // Pick the row maximizing |a[i][k]| / scale[i] among rows k..n-1.
+    let p = k;
+    let best = -1;
+    for (let i = k; i < n; i++) {
+      const v = scale[i] > 0 ? Math.abs(a[i * n + k]) / scale[i] : 0;
+      if (v > best) {
+        best = v;
+        p = i;
+      }
+    }
+    if (p !== k) {
+      for (let j = 0; j < n; j++) {
+        const t = a[k * n + j];
+        a[k * n + j] = a[p * n + j];
+        a[p * n + j] = t;
+      }
+      const ts = scale[k];
+      scale[k] = scale[p];
+      scale[p] = ts;
+      const tp = perm[k];
+      perm[k] = perm[p];
+      perm[p] = tp;
+      sign = -sign;
+    }
+    const pivot = a[k * n + k];
+    if (Math.abs(pivot) <= tol) {
+      singular = true;
+      continue;
+    }
+    for (let i = k + 1; i < n; i++) {
+      const f = a[i * n + k] / pivot;
+      a[i * n + k] = f;
+      for (let j = k + 1; j < n; j++) {
+        a[i * n + j] -= f * a[k * n + j];
+      }
+    }
+  }
+
+  return { a, perm, sign, singular };
+}
+
+/**
+ * Validate a square nested matrix and return its flat form.
+ *
+ * @param {Array<Array<number>>} A - Nested matrix
+ * @param {string} caller - Function name for error messages
+ * @returns {{data: Float64Array, m: number, n: number}}
+ */
+function squareFromNested(A, caller) {
+  const M = fromNested(A, 'A');
+  if (M.m !== M.n) {
+    throw new Error(`${caller}: matrix must be square (got ${M.m}x${M.n})`);
+  }
+  return M;
+}
+
+/**
+ * LU factorization with partial pivoting: P A = L U.
+ *
+ * @param {Array<Array<number>>} A - Square nested matrix
+ * @returns {{L: Array<Array<number>>, U: Array<Array<number>>, P: Array<Array<number>>}}
+ *   L unit lower triangular, U upper triangular, P a permutation matrix.
+ */
+export function lu(A) {
+  const { data, n } = squareFromNested(A, 'lu');
+  const { a, perm } = luFactor(data, n);
+  const L = new Float64Array(n * n);
+  const U = new Float64Array(n * n);
+  const P = new Float64Array(n * n);
+  for (let i = 0; i < n; i++) {
+    L[i * n + i] = 1;
+    P[i * n + perm[i]] = 1;
+    for (let j = 0; j < i; j++) L[i * n + j] = a[i * n + j];
+    for (let j = i; j < n; j++) U[i * n + j] = a[i * n + j];
+  }
+  return { L: toNested(L, n, n), U: toNested(U, n, n), P: toNested(P, n, n) };
+}
+
+/**
+ * Solve L U x = P b for one right-hand side, in place in `x`.
+ *
+ * @param {Float64Array} a - Combined LU storage
+ * @param {Int32Array} perm - Row permutation
+ * @param {number} n - Dimension
+ * @param {Float64Array} x - Permuted right-hand side; overwritten with the solution
+ */
+function luSolveInPlace(a, perm, n, x) {
+  // Forward substitution with unit lower triangular L.
+  for (let i = 1; i < n; i++) {
+    let s = x[i];
+    for (let j = 0; j < i; j++) s -= a[i * n + j] * x[j];
+    x[i] = s;
+  }
+  // Back substitution with U.
+  for (let i = n - 1; i >= 0; i--) {
+    let s = x[i];
+    for (let j = i + 1; j < n; j++) s -= a[i * n + j] * x[j];
+    x[i] = s / a[i * n + i];
+  }
+}
+
+/**
+ * Solve A x = b via LU factorization with partial pivoting.
+ *
+ * @param {Array<Array<number>>} A - Square nested matrix
+ * @param {Array<number>|Array<Array<number>>} b - Right-hand side vector (length n)
+ *   or nested matrix of right-hand sides (n x k, solved column by column)
+ * @returns {Array<number>|Array<Array<number>>} Solution vector, or nested n x k matrix
+ */
+export function solve(A, b) {
+  const { data, n } = squareFromNested(A, 'solve');
+  const { a, perm, singular } = luFactor(data, n);
+  if (singular) {
+    throw new Error('solve: matrix is singular (pivot below tolerance)');
+  }
+
+  const matrixRhs = Array.isArray(b) && Array.isArray(b[0]);
+  if (!matrixRhs) {
+    const bv = vecFrom(b, n, 'b');
+    const x = new Float64Array(n);
+    for (let i = 0; i < n; i++) x[i] = bv[perm[i]];
+    luSolveInPlace(a, perm, n, x);
+    return Array.from(x);
+  }
+
+  const B = fromNested(b, 'b');
+  if (B.m !== n) {
+    throw new Error(`solve: b must have ${n} rows (got ${B.m})`);
+  }
+  const k = B.n;
+  const X = new Float64Array(n * k);
+  const x = new Float64Array(n);
+  for (let c = 0; c < k; c++) {
+    for (let i = 0; i < n; i++) x[i] = B.data[perm[i] * k + c];
+    luSolveInPlace(a, perm, n, x);
+    for (let i = 0; i < n; i++) X[i * k + c] = x[i];
+  }
+  return toNested(X, n, k);
+}
+
+/**
+ * Determinant via LU factorization (permutation sign times product of pivots).
+ * Returns 0 for singular matrices instead of throwing.
+ *
+ * @param {Array<Array<number>>} A - Square nested matrix
+ * @returns {number}
+ */
+export function det(A) {
+  const { data, n } = squareFromNested(A, 'det');
+  const { a, sign, singular } = luFactor(data, n);
+  if (singular) return 0;
+  let d = sign;
+  for (let i = 0; i < n; i++) d *= a[i * n + i];
+  return d;
+}
+
+/**
+ * Matrix inverse via solve(A, I).
+ *
+ * @param {Array<Array<number>>} A - Square nested matrix
+ * @returns {Array<Array<number>>}
+ */
+export function inv(A) {
+  const M = squareFromNested(A, 'inv');
+  const n = M.n;
+  const I = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const row = new Array(n).fill(0);
+    row[i] = 1;
+    I[i] = row;
+  }
+  return solve(A, I);
+}

package/src/ops.js

@@ -0,0 +1,194 @@
+/**
+ * Basic dense matrix operations: multiply, transpose, identity, diagonal,
+ * norms, and trace.
+ *
+ * Public APIs accept and return nested row-major matrices; computation runs
+ * on flat Float64Array storage (see _mat.js).
+ */
+
+import { fromNested, toNested, vecFrom } from './_mat.js';
+
+/**
+ * Matrix product A B, or matrix-vector product A b.
+ *
+ * @param {Array<Array<number>>} A - m x n nested matrix
+ * @param {Array<Array<number>>|Array<number>} B - n x p nested matrix, or
+ *   vector of length n
+ * @returns {Array<Array<number>>|Array<number>} m x p nested matrix, or
+ *   vector of length m
+ */
+export function matmul(A, B) {
+  const Ma = fromNested(A, 'A');
+  const { data: a, m, n } = Ma;
+
+  if (Array.isArray(B) && !Array.isArray(B[0])) {
+    const x = vecFrom(B, n, 'B');
+    const y = new Float64Array(m);
+    for (let i = 0; i < m; i++) {
+      let s = 0;
+      for (let j = 0; j < n; j++) s += a[i * n + j] * x[j];
+      y[i] = s;
+    }
+    return Array.from(y);
+  }
+
+  const Mb = fromNested(B, 'B');
+  if (Mb.m !== n) {
+    throw new Error(`matmul: dimension mismatch (A is ${m}x${n}, B is ${Mb.m}x${Mb.n})`);
+  }
+  const b = Mb.data;
+  const p = Mb.n;
+  const c = new Float64Array(m * p);
+  for (let i = 0; i < m; i++) {
+    for (let k = 0; k < n; k++) {
+      const aik = a[i * n + k];
+      if (aik === 0) continue;
+      for (let j = 0; j < p; j++) {
+        c[i * p + j] += aik * b[k * p + j];
+      }
+    }
+  }
+  return toNested(c, m, p);
+}
+
+/**
+ * Matrix transpose.
+ *
+ * @param {Array<Array<number>>} A - m x n nested matrix
+ * @returns {Array<Array<number>>} n x m nested matrix
+ */
+export function transpose(A) {
+  const { data, m, n } = fromNested(A, 'A');
+  const t = new Float64Array(n * m);
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      t[j * m + i] = data[i * n + j];
+    }
+  }
+  return toNested(t, n, m);
+}
+
+/**
+ * Identity matrix of size n.
+ *
+ * @param {number} n - Dimension (positive integer)
+ * @returns {Array<Array<number>>}
+ */
+export function identity(n) {
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`identity: n must be a positive integer (got ${n})`);
+  }
+  const I = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const row = new Array(n).fill(0);
+    row[i] = 1;
+    I[i] = row;
+  }
+  return I;
+}
+
+/**
+ * Build a diagonal matrix from a vector, or extract the diagonal of a matrix.
+ *
+ * @param {Array<number>|Array<Array<number>>} x - Vector (returns an n x n
+ *   nested matrix) or nested matrix (returns its diagonal, length min(m, n))
+ * @returns {Array<Array<number>>|Array<number>}
+ */
+export function diag(x) {
+  if (!Array.isArray(x) || x.length === 0) {
+    throw new Error('diag: argument must be a non-empty vector or nested matrix');
+  }
+  if (Array.isArray(x[0])) {
+    const { data, m, n } = fromNested(x, 'A');
+    const len = Math.min(m, n);
+    const d = new Array(len);
+    for (let i = 0; i < len; i++) d[i] = data[i * n + i];
+    return d;
+  }
+  const n = x.length;
+  const D = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const row = new Array(n).fill(0);
+    row[i] = x[i];
+    D[i] = row;
+  }
+  return D;
+}
+
+/**
+ * Matrix or vector norm.
+ *
+ * For a nested matrix: 'fro' (Frobenius), 1 (max column abs sum), or
+ * Infinity (max row abs sum). For a vector: 'fro' or 2 (euclidean),
+ * 1 (abs sum), or Infinity (max abs).
+ *
+ * @param {Array<Array<number>>|Array<number>} A - Nested matrix or vector
+ * @param {'fro'|1|2|Infinity} [kind='fro'] - Norm kind
+ * @returns {number}
+ */
+export function norm(A, kind = 'fro') {
+  if (!Array.isArray(A) || A.length === 0) {
+    throw new Error('norm: argument must be a non-empty vector or nested matrix');
+  }
+
+  if (!Array.isArray(A[0])) {
+    if (kind === 'fro' || kind === 2) {
+      let s = 0;
+      for (let i = 0; i < A.length; i++) s += A[i] * A[i];
+      return Math.sqrt(s);
+    }
+    if (kind === 1) {
+      let s = 0;
+      for (let i = 0; i < A.length; i++) s += Math.abs(A[i]);
+      return s;
+    }
+    if (kind === Infinity) {
+      let s = 0;
+      for (let i = 0; i < A.length; i++) s = Math.max(s, Math.abs(A[i]));
+      return s;
+    }
+    throw new Error(`norm: unsupported vector norm kind ${String(kind)}`);
+  }
+
+  const { data, m, n } = fromNested(A, 'A');
+  if (kind === 'fro') {
+    let s = 0;
+    for (let i = 0; i < data.length; i++) s += data[i] * data[i];
+    return Math.sqrt(s);
+  }
+  if (kind === 1) {
+    let best = 0;
+    for (let j = 0; j < n; j++) {
+      let s = 0;
+      for (let i = 0; i < m; i++) s += Math.abs(data[i * n + j]);
+      best = Math.max(best, s);
+    }
+    return best;
+  }
+  if (kind === Infinity) {
+    let best = 0;
+    for (let i = 0; i < m; i++) {
+      let s = 0;
+      for (let j = 0; j < n; j++) s += Math.abs(data[i * n + j]);
+      best = Math.max(best, s);
+    }
+    return best;
+  }
+  throw new Error(`norm: unsupported matrix norm kind ${String(kind)} (use 'fro', 1, or Infinity)`);
+}
+
+/**
+ * Sum of the diagonal of a square matrix.
+ *
+ * @param {Array<Array<number>>} A - Square nested matrix
+ * @returns {number}
+ */
+export function trace(A) {
+  const { data, m, n } = fromNested(A, 'A');
+  if (m !== n) {
+    throw new Error(`trace: matrix must be square (got ${m}x${n})`);
+  }
+  let s = 0;
+  for (let i = 0; i < n; i++) s += data[i * n + i];
+  return s;
+}

package/src/qr.js

@@ -0,0 +1,178 @@
+/**
+ * QR decomposition via Householder reflections, and least squares on top of it.
+ *
+ * Public APIs take and return nested row-major matrices (Array<Array<number>>)
+ * and plain vectors (Array<number>); computation runs on flat Float64Array
+ * storage via the helpers in _mat.js.
+ */
+
+import { fromNested, toNested, vecFrom } from './_mat.js';
+
+/**
+ * Factor a flat matrix in place with Householder reflectors.
+ *
+ * After the call, `data` holds R in its upper triangle (subdiagonal entries of
+ * the processed columns are set to exact zeros). The reflectors H_j =
+ * I - beta_j v_j v_j^T (with v_j supported on rows j..m-1) satisfy
+ * H_{k-1} ... H_0 A = R, i.e. A = H_0 ... H_{k-1} R.
+ *
+ * Uses the standard stable sign choice v = x + sign(x0) ||x|| e1.
+ *
+ * @param {Float64Array} data - Row-major m*n storage, overwritten with R
+ * @param {number} m - Rows
+ * @param {number} n - Columns
+ * @returns {{vs: Array<Float64Array>, betas: Float64Array, k: number}}
+ */
+function householderFactor(data, m, n) {
+  const k = Math.min(m, n);
+  const vs = new Array(k);
+  const betas = new Float64Array(k);
+  for (let j = 0; j < k; j++) {
+    let norm = 0;
+    for (let i = j; i < m; i++) {
+      const t = data[i * n + j];
+      norm += t * t;
+    }
+    norm = Math.sqrt(norm);
+    const v = new Float64Array(m - j);
+    vs[j] = v;
+    if (norm === 0) {
+      betas[j] = 0;
+      continue;
+    }
+    const x0 = data[j * n + j];
+    const sign = x0 >= 0 ? 1 : -1;
+    v[0] = x0 + sign * norm;
+    for (let i = j + 1; i < m; i++) v[i - j] = data[i * n + j];
+    let vv = 0;
+    for (let t = 0; t < v.length; t++) vv += v[t] * v[t];
+    const beta = 2 / vv;
+    betas[j] = beta;
+    // Apply H_j to the trailing columns.
+    for (let c = j + 1; c < n; c++) {
+      let s = 0;
+      for (let i = j; i < m; i++) s += v[i - j] * data[i * n + c];
+      s *= beta;
+      for (let i = j; i < m; i++) data[i * n + c] -= s * v[i - j];
+    }
+    // Column j maps exactly to -sign * norm * e1.
+    data[j * n + j] = -sign * norm;
+    for (let i = j + 1; i < m; i++) data[i * n + j] = 0;
+  }
+  return { vs, betas, k };
+}
+
+/**
+ * Accumulate Q = H_0 H_1 ... H_{k-1} applied to the first qCols columns of I.
+ *
+ * @param {Array<Float64Array>} vs - Reflector vectors
+ * @param {Float64Array} betas - Reflector scalings
+ * @param {number} m - Rows of Q
+ * @param {number} qCols - Columns of Q (min(m, n) for reduced, m for full)
+ * @returns {Float64Array} Row-major m*qCols storage of Q
+ */
+function accumulateQ(vs, betas, m, qCols) {
+  const Q = new Float64Array(m * qCols);
+  for (let i = 0; i < qCols; i++) Q[i * qCols + i] = 1;
+  for (let j = vs.length - 1; j >= 0; j--) {
+    const v = vs[j];
+    const beta = betas[j];
+    if (beta === 0) continue;
+    for (let c = 0; c < qCols; c++) {
+      let s = 0;
+      for (let i = j; i < m; i++) s += v[i - j] * Q[i * qCols + c];
+      s *= beta;
+      for (let i = j; i < m; i++) Q[i * qCols + c] -= s * v[i - j];
+    }
+  }
+  return Q;
+}
+
+/**
+ * QR decomposition A = Q R via Householder reflections.
+ *
+ * Works for any shape: m >= n and m < n alike.
+ *
+ * @param {Array<Array<number>>} A - m x n matrix
+ * @param {Object} [options]
+ * @param {string} [options.mode='reduced'] - 'reduced' (Q is m x min(m,n),
+ *   R is min(m,n) x n) or 'full' (Q is m x m, R is m x n)
+ * @returns {{Q: Array<Array<number>>, R: Array<Array<number>>}}
+ */
+export function qr(A, options = {}) {
+  const { data, m, n } = fromNested(A, 'A');
+  const mode = options.mode !== undefined ? options.mode : 'reduced';
+  if (mode !== 'reduced' && mode !== 'full') {
+    throw new Error(`qr: options.mode must be 'reduced' or 'full' (got '${mode}')`);
+  }
+  const { vs, betas, k } = householderFactor(data, m, n);
+  const qCols = mode === 'full' ? m : k;
+  const Qflat = accumulateQ(vs, betas, m, qCols);
+  const rRows = mode === 'full' ? m : k;
+  return {
+    Q: toNested(Qflat, m, qCols),
+    R: toNested(data.subarray(0, rRows * n), rRows, n),
+  };
+}
+
+/**
+ * Least-squares solution of A x ≈ b via reduced QR.
+ *
+ * Requires m >= n and full column rank: solves R x = Q^T b by back
+ * substitution. Throws for rank-deficient R.
+ *
+ * @param {Array<Array<number>>} A - m x n matrix with m >= n
+ * @param {Array<number>} b - Right-hand side of length m
+ * @returns {{x: Array<number>, residualNorm: number}} residualNorm = ||A x - b||_2
+ */
+export function lstsq(A, b) {
+  const { data, m, n } = fromNested(A, 'A');
+  if (m < n) {
+    throw new Error(`lstsq: A must have at least as many rows as columns (got ${m}x${n})`);
+  }
+  const bv = vecFrom(b, m, 'b');
+  const original = data.slice();
+  const { vs, betas, k } = householderFactor(data, m, n);
+
+  // Rank check on the diagonal of R against its largest entry.
+  let maxR = 0;
+  for (let i = 0; i < k; i++) {
+    for (let j = i; j < n; j++) maxR = Math.max(maxR, Math.abs(data[i * n + j]));
+  }
+  for (let i = 0; i < n; i++) {
+    if (Math.abs(data[i * n + i]) < 1e-12 * maxR || maxR === 0) {
+      throw new Error(
+        `lstsq: A is rank deficient (R[${i}][${i}] is negligible); ` +
+        'use pinv for a minimum-norm solution'
+      );
+    }
+  }
+
+  // Compute Q^T b = H_{k-1} ... H_0 b in place.
+  for (let j = 0; j < k; j++) {
+    const v = vs[j];
+    const beta = betas[j];
+    if (beta === 0) continue;
+    let s = 0;
+    for (let i = j; i < m; i++) s += v[i - j] * bv[i];
+    s *= beta;
+    for (let i = j; i < m; i++) bv[i] -= s * v[i - j];
+  }
+
+  // Back substitution: R x = (Q^T b)[0..n-1].
+  const x = new Array(n).fill(0);
+  for (let i = n - 1; i >= 0; i--) {
+    let s = bv[i];
+    for (let j = i + 1; j < n; j++) s -= data[i * n + j] * x[j];
+    x[i] = s / data[i * n + i];
+  }
+
+  // Residual norm from the original A.
+  let rr = 0;
+  for (let i = 0; i < m; i++) {
+    let s = -b[i];
+    for (let j = 0; j < n; j++) s += original[i * n + j] * x[j];
+    rr += s * s;
+  }
+  return { x, residualNorm: Math.sqrt(rr) };
+}