@johnhenry/math 0.0.0

package/src/Interval.ts

@@ -0,0 +1,171 @@
+const F64 = new Float64Array(1);
+const U64 = new BigUint64Array(F64.buffer);
+
+/** The next representable double strictly greater than `value` (IEEE-754 nextafter toward +Infinity) -- JS has no built-in `Math.nextafter`, so this steps the raw 64-bit pattern by one ULP via a shared scratch buffer. */
+function nextUp(value: number): number {
+  if (Number.isNaN(value) || value === Infinity) return value;
+  if (value === 0) return Number.MIN_VALUE;
+  F64[0] = value;
+  U64[0] = (U64[0] as bigint) + (value > 0 ? 1n : -1n);
+  return F64[0] as number;
+}
+
+/** The next representable double strictly less than `value` -- `-nextUp(-value)`, since stepping toward -Infinity from `x` is the mirror of stepping toward +Infinity from `-x`. */
+function nextDown(value: number): number {
+  return -nextUp(-value);
+}
+
+/**
+ * Widens `x` by one ULP on each side -- the outward-rounding every non-exact
+ * `Interval` operation below applies to its result. `Math.*` computes to
+ * the *nearest* representable double (`Math.sqrt` is correctly rounded to
+ * 0.5 ULP per IEEE-754; the other transcendentals/arithmetic are within
+ * ~1 ULP on every mainstream engine), which breaks the containment
+ * guarantee interval arithmetic exists to provide: `Interval.point(2).sqrt()`
+ * would otherwise return a degenerate `[s, s]` that provably does NOT
+ * contain the irrational `sqrt(2)`. One ULP of outward slack restores
+ * rigor, at the cost of a deliberately loose bound when a result happens
+ * to be exactly representable (e.g. `sqrt(4)` reports a width-2-ULP
+ * interval around 2 instead of the point `[2, 2]`).
+ */
+function outward(x: Interval): Interval {
+  return new Interval(nextDown(x.lo), nextUp(x.hi));
+}
+
+/**
+ * Interval — rigorous interval arithmetic `[lo, hi]`. Operations return an
+ * interval guaranteed to contain every result of the corresponding operation on
+ * any pair of members, so a final interval bounds the true answer despite
+ * rounding — useful for reliable numerics and error tracking. Every
+ * operation that isn't provably exact (`negate`/`abs`/`hull`/`intersect`
+ * only move or compare existing endpoints) outward-rounds its result by
+ * one ULP per side via `outward()` above.
+ */
+export class Interval {
+  readonly lo: number;
+  readonly hi: number;
+
+  constructor(lo: number, hi: number = lo) {
+    if (lo > hi) throw new Error(`Invalid interval: [${lo}, ${hi}]`);
+    this.lo = lo;
+    this.hi = hi;
+  }
+
+  static of(lo: number, hi: number): Interval {
+    return new Interval(lo, hi);
+  }
+
+  /** A degenerate interval `[x, x]`. */
+  static point(x: number): Interval {
+    return new Interval(x, x);
+  }
+
+  get width(): number {
+    return this.hi - this.lo;
+  }
+  get midpoint(): number {
+    return (this.lo + this.hi) / 2;
+  }
+  get radius(): number {
+    return this.width / 2;
+  }
+
+  contains(x: number): boolean {
+    return this.lo <= x && x <= this.hi;
+  }
+  overlaps(o: Interval): boolean {
+    return this.lo <= o.hi && o.lo <= this.hi;
+  }
+
+  add(o: Interval): Interval {
+    return outward(new Interval(this.lo + o.lo, this.hi + o.hi));
+  }
+  subtract(o: Interval): Interval {
+    return outward(new Interval(this.lo - o.hi, this.hi - o.lo));
+  }
+  /** Exact: IEEE-754 negation only flips the sign bit, no rounding. */
+  negate(): Interval {
+    return new Interval(-this.hi, -this.lo);
+  }
+
+  multiply(o: Interval): Interval {
+    const p = [this.lo * o.lo, this.lo * o.hi, this.hi * o.lo, this.hi * o.hi];
+    return outward(new Interval(Math.min(...p), Math.max(...p)));
+  }
+
+  divide(o: Interval): Interval {
+    if (o.contains(0)) throw new Error("Interval division by an interval containing zero.");
+    // The reciprocal bounds are themselves a rounded operation -- outward
+    // it before feeding into `multiply` (which outward-rounds its own
+    // result too), so neither step's rounding can silently eat the other's
+    // slack.
+    const reciprocal = outward(new Interval(1 / o.hi, 1 / o.lo));
+    return this.multiply(reciprocal);
+  }
+
+  /** The tightest interval containing both (the convex hull / union). */
+  hull(o: Interval): Interval {
+    return new Interval(Math.min(this.lo, o.lo), Math.max(this.hi, o.hi));
+  }
+
+  /** The overlap of two intervals, or `null` if they are disjoint. */
+  intersect(o: Interval): Interval | null {
+    const lo = Math.max(this.lo, o.lo);
+    const hi = Math.min(this.hi, o.hi);
+    return lo <= hi ? new Interval(lo, hi) : null;
+  }
+
+  abs(): Interval {
+    if (this.lo >= 0) return this;
+    if (this.hi <= 0) return this.negate();
+    return new Interval(0, Math.max(-this.lo, this.hi));
+  }
+
+  sqrt(): Interval {
+    if (this.lo < 0) throw new Error("sqrt of an interval with negative values.");
+    return outward(new Interval(Math.sqrt(this.lo), Math.sqrt(this.hi)));
+  }
+  exp(): Interval {
+    return outward(new Interval(Math.exp(this.lo), Math.exp(this.hi)));
+  }
+  log(): Interval {
+    if (this.lo <= 0) throw new Error("log of an interval with non-positive values.");
+    return outward(new Interval(Math.log(this.lo), Math.log(this.hi)));
+  }
+
+  /** Integer power (handles even powers of intervals straddling zero). Exact when `n === 0` (every interval to the 0th power is the exact point 1). */
+  pow(n: number): Interval {
+    if (!Number.isInteger(n) || n < 0) throw new Error("Interval.pow requires a non-negative integer.");
+    if (n === 0) return Interval.point(1);
+    const a = this.lo ** n;
+    const b = this.hi ** n;
+    if (n % 2 === 0 && this.contains(0)) return outward(new Interval(0, Math.max(a, b)));
+    return outward(new Interval(Math.min(a, b), Math.max(a, b)));
+  }
+
+  private extrema(f: (x: number) => number, criticalPeriodStart: number, period: number): Interval {
+    const candidates = [f(this.lo), f(this.hi)];
+    // include critical points of the form `criticalPeriodStart + k·period` in range
+    const kStart = Math.ceil((this.lo - criticalPeriodStart) / period);
+    const kEnd = Math.floor((this.hi - criticalPeriodStart) / period);
+    for (let k = kStart; k <= kEnd; k++) candidates.push(f(criticalPeriodStart + k * period));
+    return outward(new Interval(Math.min(...candidates), Math.max(...candidates)));
+  }
+
+  sin(): Interval {
+    if (this.width >= 2 * Math.PI) return new Interval(-1, 1);
+    return this.extrema(Math.sin, Math.PI / 2, Math.PI);
+  }
+  cos(): Interval {
+    if (this.width >= 2 * Math.PI) return new Interval(-1, 1);
+    return this.extrema(Math.cos, 0, Math.PI);
+  }
+
+  equals(o: Interval): boolean {
+    return this.lo === o.lo && this.hi === o.hi;
+  }
+
+  toString(): string {
+    return `[${this.lo}, ${this.hi}]`;
+  }
+}

package/src/Lattice.ts

@@ -0,0 +1,87 @@
+/**
+ * Lattice — axial-coordinate neighbor helpers for hexagonal and triangular
+ * grids (part of johnhenry/math#30's "lattice-geometry helpers" item,
+ * upstream for the generalized Wang tile laboratory,
+ * johnhenry/mallory#92). Both the solver (adjacency for constraint
+ * propagation) and the app (drawing) need a shared, tested "direction d's
+ * neighbor" definition per lattice — this is that definition, kept purely
+ * combinatorial (integer coordinate offsets), independent of any pixel
+ * geometry (see {@link Polygon.regular} for that side).
+ */
+
+/** One of the 6 axial directions on a hex grid, in the standard pointy-top ordering (E, NE, NW, W, SW, SE). */
+export type HexDirection = 0 | 1 | 2 | 3 | 4 | 5;
+
+/**
+ * The 6 axial-coordinate offsets, indexed by {@link HexDirection}. Opposite
+ * directions are `d` and `(d+3) % 6` — verified: `hexNeighbor` in direction
+ * `d` followed by `hexNeighbor` in direction `(d+3) % 6` returns to the
+ * start cell, for every `d`.
+ */
+export const HEX_AXIAL_DIRECTIONS: ReadonlyArray<readonly [number, number]> = [
+  [1, 0],
+  [1, -1],
+  [0, -1],
+  [-1, 0],
+  [-1, 1],
+  [0, 1],
+];
+
+/** The axial-coordinate neighbor of `(q, r)` in direction `d`. */
+export function hexNeighbor(q: number, r: number, d: HexDirection): readonly [number, number] {
+  const [dq, dr] = HEX_AXIAL_DIRECTIONS[d] as readonly [number, number];
+  return [q + dq, r + dr];
+}
+
+/** Every axial neighbor of `(q, r)`, in direction order. */
+export function hexNeighbors(q: number, r: number): Array<readonly [number, number]> {
+  return [0, 1, 2, 3, 4, 5].map((d) => hexNeighbor(q, r, d as HexDirection));
+}
+
+/**
+ * A triangular lattice cell's orientation: `(x, y)` with `x + y` even is
+ * "up" (a triangle pointing up, vertex at the top edge), odd is "down" —
+ * a lattice of alternating up/down triangles tiling the plane, indexed by
+ * integer `(x, y)` (NOT pixel coordinates; see {@link Polygon.regular} for
+ * that side).
+ */
+export type TriOrientation = "up" | "down";
+
+export function triOrientation(x: number, y: number): TriOrientation {
+  return (((x + y) % 2) + 2) % 2 === 0 ? "up" : "down";
+}
+
+/** An "up" triangle's 3 edge-sharing neighbors (all "down"): its left/right neighbors in the same row, and the one above sharing its top edge. */
+export type UpTriDirection = "left" | "right" | "top";
+/** A "down" triangle's 3 edge-sharing neighbors (all "up"): its left/right neighbors in the same row, and the one below sharing its bottom edge. */
+export type DownTriDirection = "left" | "right" | "bottom";
+export type TriDirection = UpTriDirection | DownTriDirection;
+
+/**
+ * The neighbor of triangular cell `(x, y)` in `direction` — reciprocal
+ * pairs: an "up" cell's `"right"` neighbor's `"left"` is itself, and an
+ * "up" cell's `"top"` neighbor's `"bottom"` is itself (verified before
+ * writing tests). `direction` must match `(x, y)`'s own orientation
+ * (`"top"` is only valid on an "up" cell, `"bottom"` only on "down").
+ */
+export function triNeighbor(x: number, y: number, direction: TriDirection): readonly [number, number] {
+  const orientation = triOrientation(x, y);
+  if (direction === "left") return [x - 1, y];
+  if (direction === "right") return [x + 1, y];
+  if (direction === "top") {
+    if (orientation !== "up")
+      throw new Error(`triNeighbor: "top" is only valid on an "up" cell, (${x},${y}) is "down".`);
+    return [x, y + 1];
+  }
+  if (orientation !== "down")
+    throw new Error(`triNeighbor: "bottom" is only valid on a "down" cell, (${x},${y}) is "up".`);
+  return [x, y - 1];
+}
+
+/** Every edge-sharing neighbor of triangular cell `(x, y)`, in the direction order valid for its own orientation. */
+export function triNeighbors(x: number, y: number): Array<readonly [number, number]> {
+  const orientation = triOrientation(x, y);
+  const directions: readonly TriDirection[] =
+    orientation === "up" ? ["left", "right", "top"] : ["left", "right", "bottom"];
+  return directions.map((d) => triNeighbor(x, y, d));
+}

package/src/Logic.ts

@@ -0,0 +1,38 @@
+/**
+ * Logic — boolean helper predicates.
+ *
+ * Ported from Mallory's ActionScript `Logic`. The AS3 source did not actually
+ * compile (`And(a*;b:*)` and friends are syntactically invalid); the intent is
+ * clear from the comments and reproduced here as ordinary boolean functions.
+ */
+export class Logic {
+  /** Always true, whatever the arguments. */
+  static truth(..._anything: unknown[]): boolean {
+    return true;
+  }
+
+  /** Always false, whatever the arguments. */
+  static falsehood(..._anything: unknown[]): boolean {
+    return false;
+  }
+
+  /** Logical AND. */
+  static and(a: unknown, b: unknown): boolean {
+    return Boolean(a) && Boolean(b);
+  }
+
+  /** Logical (inclusive) OR. */
+  static or(a: unknown, b: unknown): boolean {
+    return Boolean(a) || Boolean(b);
+  }
+
+  /** Logical exclusive OR. */
+  static xor(a: unknown, b: unknown): boolean {
+    return Boolean(a) !== Boolean(b);
+  }
+
+  /** Logical NOT. */
+  static not(a: unknown): boolean {
+    return !a;
+  }
+}

package/src/MatrixMath.ts

@@ -0,0 +1,326 @@
+import { Vector } from "./Vector.ts";
+import type { Matrix } from "./VectorUtils.ts";
+
+/**
+ * MatrixMath — numerical linear algebra: decompositions (LU, QR, Cholesky,
+ * eigen, SVD), direct solvers, rank/RREF/null space, least squares, the
+ * pseudo-inverse, and matrix norms. Complements the elementary matrix ops in
+ * {@link RealMath} (determinant, inverse, multiply) with the higher-level
+ * factorisations they lacked.
+ *
+ * Matrices are the library's `Matrix<number>` (a {@link Vector} of row Vectors);
+ * plain `number[][]` is also accepted as input.
+ */
+
+type Mat = Matrix<number>;
+type MatrixInput = Mat | number[][];
+
+const EPS = 1e-12;
+
+const raw = (m: MatrixInput): number[][] => [...(m as Iterable<Iterable<number>>)].map((r) => [...r]);
+const wrap = (a: number[][]): Mat => Vector.fromArray(a.map((r) => Vector.fromArray(r)));
+const vec = (a: number[]): Vector<number> => Vector.fromArray(a);
+const identity = (n: number): number[][] =>
+  Array.from({ length: n }, (_, i) => Array.from({ length: n }, (_, j) => (i === j ? 1 : 0)));
+const zeros = (m: number, n: number): number[][] => Array.from({ length: m }, () => new Array(n).fill(0));
+const transposeRaw = (a: number[][]): number[][] => a[0].map((_, j) => a.map((row) => row[j]));
+const matmul = (a: number[][], b: number[][]): number[][] => {
+  const m = a.length;
+  const n = b[0].length;
+  const k = b.length;
+  const out = zeros(m, n);
+  for (let i = 0; i < m; i++) for (let p = 0; p < k; p++) for (let j = 0; j < n; j++) out[i][j] += a[i][p] * b[p][j];
+  return out;
+};
+
+export interface LUResult {
+  L: Mat;
+  U: Mat;
+  P: Mat;
+  sign: number;
+}
+
+export interface QRResult {
+  Q: Mat;
+  R: Mat;
+}
+
+export interface EigenResult {
+  values: Vector<number>;
+  vectors: Mat;
+}
+
+export interface SVDResult {
+  U: Mat;
+  S: Vector<number>;
+  V: Mat;
+}
+
+export class MatrixMath {
+  /** LU decomposition with partial pivoting: `P·A = L·U`. */
+  static lu(A: MatrixInput): LUResult {
+    const U = raw(A);
+    const n = U.length;
+    const L = identity(n);
+    const P = identity(n);
+    let sign = 1;
+    for (let k = 0; k < n; k++) {
+      let pivot = k;
+      for (let i = k + 1; i < n; i++) if (Math.abs(U[i][k]) > Math.abs(U[pivot][k])) pivot = i;
+      if (pivot !== k) {
+        [U[k], U[pivot]] = [U[pivot], U[k]];
+        [P[k], P[pivot]] = [P[pivot], P[k]];
+        for (let j = 0; j < k; j++) [L[k][j], L[pivot][j]] = [L[pivot][j], L[k][j]];
+        sign = -sign;
+      }
+      if (Math.abs(U[k][k]) < EPS) continue; // singular column
+      for (let i = k + 1; i < n; i++) {
+        const f = U[i][k] / U[k][k];
+        L[i][k] = f;
+        for (let j = k; j < n; j++) U[i][j] -= f * U[k][j];
+      }
+    }
+    return { L: wrap(L), U: wrap(U), P: wrap(P), sign };
+  }
+
+  /** Solve the linear system `A·x = b` via LU decomposition. */
+  static solve(A: MatrixInput, b: number[] | Vector<number>): Vector<number> {
+    const a = raw(A);
+    const n = a.length;
+    const rhs = [...(b as Iterable<number>)];
+    const { L, U, P } = MatrixMath.lu(a);
+    const Lr = raw(L);
+    const Ur = raw(U);
+    const Pr = raw(P);
+    // Pb
+    const pb = Pr.map((row) => row.reduce((s, v, j) => s + v * rhs[j], 0));
+    // forward solve L y = Pb
+    const y = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+      let s = pb[i];
+      for (let j = 0; j < i; j++) s -= Lr[i][j] * y[j];
+      y[i] = s; // L has unit diagonal
+    }
+    // back solve U x = y
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+      let s = y[i];
+      for (let j = i + 1; j < n; j++) s -= Ur[i][j] * x[j];
+      x[i] = Math.abs(Ur[i][i]) < EPS ? 0 : s / Ur[i][i];
+    }
+    return vec(x);
+  }
+
+  /** Reduced row echelon form (Gauss-Jordan elimination). */
+  static rref(A: MatrixInput): Mat {
+    const a = raw(A);
+    const rows = a.length;
+    const cols = a[0].length;
+    let lead = 0;
+    for (let r = 0; r < rows && lead < cols; r++, lead++) {
+      let i = r;
+      while (lead < cols && Math.abs(a[i][lead]) < EPS) {
+        i++;
+        if (i === rows) {
+          i = r;
+          lead++;
+          if (lead === cols) return wrap(a);
+        }
+      }
+      [a[i], a[r]] = [a[r], a[i]];
+      const pivot = a[r][lead];
+      for (let j = 0; j < cols; j++) a[r][j] /= pivot;
+      for (let k = 0; k < rows; k++) {
+        if (k === r) continue;
+        const factor = a[k][lead];
+        for (let j = 0; j < cols; j++) a[k][j] -= factor * a[r][j];
+      }
+    }
+    return wrap(a);
+  }
+
+  /** Rank of a matrix (number of nonzero rows in its RREF). */
+  static rank(A: MatrixInput): number {
+    const r = raw(MatrixMath.rref(A));
+    return r.filter((row) => row.some((v) => Math.abs(v) > 1e-9)).length;
+  }
+
+  /** A basis for the null space (kernel) of `A`, as a matrix whose rows are basis vectors. */
+  static nullSpace(A: MatrixInput): Mat {
+    const R = raw(MatrixMath.rref(A));
+    const rows = R.length;
+    const cols = R[0].length;
+    const pivotCols: number[] = [];
+    for (let r = 0; r < rows; r++) {
+      const lead = R[r].findIndex((v) => Math.abs(v) > 1e-9);
+      if (lead !== -1) pivotCols.push(lead);
+    }
+    const freeCols: number[] = [];
+    for (let c = 0; c < cols; c++) if (!pivotCols.includes(c)) freeCols.push(c);
+
+    const basis: number[][] = [];
+    for (const free of freeCols) {
+      const v = new Array(cols).fill(0);
+      v[free] = 1;
+      for (let r = 0; r < pivotCols.length; r++) v[pivotCols[r]] = -R[r][free];
+      basis.push(v);
+    }
+    return wrap(basis.length ? basis : [new Array(cols).fill(0)]);
+  }
+
+  /** QR decomposition via modified Gram-Schmidt: `A = Q·R` (Q orthonormal). */
+  static qr(A: MatrixInput): QRResult {
+    const a = raw(A);
+    const m = a.length;
+    const n = a[0].length;
+    const Q = zeros(m, n);
+    const R = zeros(n, n);
+    const cols = transposeRaw(a); // columns of A
+    for (let j = 0; j < n; j++) {
+      const v = [...cols[j]];
+      for (let i = 0; i < j; i++) {
+        let dot = 0;
+        for (let r = 0; r < m; r++) dot += Q[r][i] * v[r];
+        R[i][j] = dot;
+        for (let r = 0; r < m; r++) v[r] -= dot * Q[r][i];
+      }
+      let norm = Math.hypot(...v);
+      R[j][j] = norm;
+      if (norm < EPS) norm = 1;
+      for (let r = 0; r < m; r++) Q[r][j] = v[r] / norm;
+    }
+    return { Q: wrap(Q), R: wrap(R) };
+  }
+
+  /** Cholesky decomposition of a symmetric positive-definite matrix: `A = L·Lᵀ`. */
+  static cholesky(A: MatrixInput): Mat {
+    const a = raw(A);
+    const n = a.length;
+    const L = zeros(n, n);
+    for (let j = 0; j < n; j++) {
+      let d = a[j][j];
+      for (let k = 0; k < j; k++) d -= L[j][k] * L[j][k];
+      if (d <= 0) throw new Error("Matrix is not positive-definite.");
+      L[j][j] = Math.sqrt(d);
+      for (let i = j + 1; i < n; i++) {
+        let s = a[i][j];
+        for (let k = 0; k < j; k++) s -= L[i][k] * L[j][k];
+        L[i][j] = s / L[j][j];
+      }
+    }
+    return wrap(L);
+  }
+
+  /**
+   * Eigenvalues and orthonormal eigenvectors of a symmetric matrix via the
+   * cyclic Jacobi rotation algorithm. Values are returned in descending order.
+   */
+  static eigenSymmetric(A: MatrixInput, maxSweeps = 100): EigenResult {
+    const a = raw(A);
+    const n = a.length;
+    const V = identity(n);
+    for (let sweep = 0; sweep < maxSweeps; sweep++) {
+      let off = 0;
+      for (let p = 0; p < n; p++) for (let q = p + 1; q < n; q++) off += a[p][q] * a[p][q];
+      if (off < EPS) break;
+      for (let p = 0; p < n; p++) {
+        for (let q = p + 1; q < n; q++) {
+          if (Math.abs(a[p][q]) < EPS) continue;
+          const theta = (a[q][q] - a[p][p]) / (2 * a[p][q]);
+          const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+          const c = 1 / Math.sqrt(t * t + 1);
+          const s = t * c;
+          for (let i = 0; i < n; i++) {
+            const aip = a[i][p];
+            const aiq = a[i][q];
+            a[i][p] = c * aip - s * aiq;
+            a[i][q] = s * aip + c * aiq;
+          }
+          for (let i = 0; i < n; i++) {
+            const api = a[p][i];
+            const aqi = a[q][i];
+            a[p][i] = c * api - s * aqi;
+            a[q][i] = s * api + c * aqi;
+          }
+          for (let i = 0; i < n; i++) {
+            const vip = V[i][p];
+            const viq = V[i][q];
+            V[i][p] = c * vip - s * viq;
+            V[i][q] = s * vip + c * viq;
+          }
+        }
+      }
+    }
+    const pairs = a.map((row, i) => ({ value: row[i], vec: V.map((r) => r[i]) }));
+    pairs.sort((x, y) => y.value - x.value);
+    return {
+      values: vec(pairs.map((p) => p.value)),
+      vectors: wrap(transposeRaw(pairs.map((p) => p.vec))),
+    };
+  }
+
+  /**
+   * Singular value decomposition `A = U·Σ·Vᵀ` (via the eigendecomposition of
+   * `AᵀA`). Returns `U`, the singular values `S` (descending), and `V`.
+   */
+  static svd(A: MatrixInput): SVDResult {
+    const a = raw(A);
+    const m = a.length;
+    const n = a[0].length;
+    const at = transposeRaw(a);
+    const ata = matmul(at, a); // n×n
+    const { values, vectors } = MatrixMath.eigenSymmetric(ata);
+    const V = raw(vectors); // columns are eigenvectors of AᵀA
+    const sv = [...values].map((v) => Math.sqrt(Math.max(v, 0)));
+    // U columns: A·v_i / σ_i
+    const U = zeros(m, n);
+    for (let i = 0; i < n; i++) {
+      const vi = V.map((r) => r[i]);
+      const avi = a.map((row) => row.reduce((s, val, j) => s + val * vi[j], 0));
+      const sigma = sv[i];
+      for (let r = 0; r < m; r++) U[r][i] = sigma > EPS ? avi[r] / sigma : 0;
+    }
+    return { U: wrap(U), S: vec(sv), V: wrap(V) };
+  }
+
+  /** Least-squares solution of an overdetermined system `A·x ≈ b` (normal equations). */
+  static leastSquares(A: MatrixInput, b: number[] | Vector<number>): Vector<number> {
+    const a = raw(A);
+    const at = transposeRaw(a);
+    const ata = matmul(at, a);
+    const rhs = [...(b as Iterable<number>)];
+    const atb = at.map((row) => row.reduce((s, v, j) => s + v * rhs[j], 0));
+    return MatrixMath.solve(wrap(ata), atb);
+  }
+
+  /** The Moore-Penrose pseudo-inverse `A⁺` (via SVD). */
+  static pseudoInverse(A: MatrixInput): Mat {
+    const { U, S, V } = MatrixMath.svd(A);
+    const Ur = raw(U);
+    const Vr = raw(V);
+    const s = [...S];
+    const n = s.length;
+    // A⁺ = V · Σ⁺ · Uᵀ
+    const sInv = s.map((v) => (v > 1e-9 ? 1 / v : 0));
+    const sigmaPlus = zeros(n, n);
+    for (let i = 0; i < n; i++) sigmaPlus[i][i] = sInv[i];
+    return wrap(matmul(matmul(Vr, sigmaPlus), transposeRaw(Ur)));
+  }
+
+  /** The Frobenius norm (root of the sum of squared entries). */
+  static frobeniusNorm(A: MatrixInput): number {
+    return Math.hypot(...raw(A).flat());
+  }
+
+  /** The spectral (2-)norm: the largest singular value. */
+  static spectralNorm(A: MatrixInput): number {
+    return Math.max(...MatrixMath.svd(A).S);
+  }
+
+  /** The 2-norm condition number `σ_max / σ_min`. */
+  static conditionNumber(A: MatrixInput): number {
+    const s = [...MatrixMath.svd(A).S];
+    const min = Math.min(...s);
+    return min < EPS ? Number.POSITIVE_INFINITY : Math.max(...s) / min;
+  }
+}