@johnhenry/math 0.2.0 → 0.3.0

package/src/EigenGeneral.ts

@@ -0,0 +1,342 @@
+import { ComplexNumber } from "./ComplexNumber.ts";
+
+/**
+ * General (non-symmetric) eigen solver: Householder reduction to upper
+ * Hessenberg form, then single-shift QR iteration (Wilkinson shifts, Givens
+ * rotations, deflation) in complex arithmetic until the matrix is the complex
+ * Schur form `A = Z·T·Zᴴ`; eigenvectors come from back-substitution on the
+ * triangular `T`. Real input with conjugate eigenvalue pairs works without a
+ * separate real-Schur code path, at the cost of doing the arithmetic in ℂ.
+ *
+ * Mirrors `scipy.linalg.eig` / `numpy.linalg.eig` (right eigenvectors,
+ * columns of `vectors`, unit 2-norm). Eigenvalues are sorted by descending
+ * real part, then descending imaginary part; each eigenvector's largest
+ * component is real and positive (LAPACK leaves that sign arbitrary).
+ */
+
+export interface GeneralEigenResult {
+  /** Eigenvalues, `values[k]` pairs with column `k` of `vectors`. */
+  values: ComplexNumber[];
+  /** `n×n` matrix whose column `k` is the unit-norm eigenvector for `values[k]`. */
+  vectors: ComplexNumber[][];
+}
+
+type CMat = { re: number[][]; im: number[][] };
+
+const zeros = (n: number): number[][] => Array.from({ length: n }, () => new Array<number>(n).fill(0));
+
+export function eigenGeneral(
+  input: ReadonlyArray<ReadonlyArray<number | ComplexNumber>>,
+  maxIterations = 60,
+): GeneralEigenResult {
+  const n = input.length;
+  if (n === 0) return { values: [], vectors: [] };
+  const H: CMat = { re: zeros(n), im: zeros(n) };
+  for (let i = 0; i < n; i++) {
+    if (input[i].length !== n) throw new Error("eigen requires a square matrix.");
+    for (let j = 0; j < n; j++) {
+      const v = input[i][j];
+      if (typeof v === "number") H.re[i][j] = v;
+      else {
+        H.re[i][j] = v.re;
+        H.im[i][j] = v.im;
+      }
+      if (!Number.isFinite(H.re[i][j]) || !Number.isFinite(H.im[i][j]))
+        throw new Error("eigen requires finite matrix entries.");
+    }
+  }
+  const Z: CMat = { re: zeros(n), im: zeros(n) };
+  for (let i = 0; i < n; i++) Z.re[i][i] = 1;
+
+  let norm = 0;
+  for (let i = 0; i < n; i++) for (let j = 0; j < n; j++) norm = Math.max(norm, Math.hypot(H.re[i][j], H.im[i][j]));
+  if (norm === 0) norm = 1;
+
+  hessenberg(H, Z, n);
+  schur(H, Z, n, norm, maxIterations);
+
+  // eigenvalues & vectors
+  const tNorm = norm * n;
+  const lam: Array<[number, number]> = [];
+  for (let k = 0; k < n; k++) lam.push([H.re[k][k], H.im[k][k]]);
+  const realTol = 1e-12 * norm;
+  const realInput = input.every((row) => row.every((v) => typeof v === "number" || v.im === 0));
+
+  const cols: Array<{ lre: number; lim: number; vre: number[]; vim: number[] }> = [];
+  for (let k = 0; k < n; k++) {
+    // back-substitute (T - λ_k I) y = 0 with y_k = 1
+    const yr = new Array<number>(n).fill(0);
+    const yi = new Array<number>(n).fill(0);
+    yr[k] = 1;
+    for (let i = k - 1; i >= 0; i--) {
+      let sr = 0;
+      let si = 0;
+      for (let j = i + 1; j <= k; j++) {
+        sr += H.re[i][j] * yr[j] - H.im[i][j] * yi[j];
+        si += H.re[i][j] * yi[j] + H.im[i][j] * yr[j];
+      }
+      let dr = H.re[i][i] - lam[k][0];
+      let di = H.im[i][i] - lam[k][1];
+      if (Math.hypot(dr, di) < Number.EPSILON * tNorm) {
+        dr = Number.EPSILON * tNorm;
+        di = 0;
+      }
+      const d2 = dr * dr + di * di;
+      yr[i] = -(sr * dr + si * di) / d2;
+      yi[i] = -(si * dr - sr * di) / d2;
+    }
+    // v = Z y
+    const vre = new Array<number>(n).fill(0);
+    const vim = new Array<number>(n).fill(0);
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j <= k; j++) {
+        vre[i] += Z.re[i][j] * yr[j] - Z.im[i][j] * yi[j];
+        vim[i] += Z.re[i][j] * yi[j] + Z.im[i][j] * yr[j];
+      }
+    }
+    // unit norm, largest component real positive
+    let nrm = 0;
+    let big = 0;
+    let bigIdx = 0;
+    for (let i = 0; i < n; i++) {
+      const m = Math.hypot(vre[i], vim[i]);
+      nrm += m * m;
+      if (m > big * (1 + 1e-12)) {
+        big = m;
+        bigIdx = i;
+      }
+    }
+    nrm = Math.sqrt(nrm);
+    const pr = vre[bigIdx] / big;
+    const pi = -vim[bigIdx] / big; // conj(phase)
+    for (let i = 0; i < n; i++) {
+      const r = (vre[i] * pr - vim[i] * pi) / nrm;
+      const m = (vre[i] * pi + vim[i] * pr) / nrm;
+      vre[i] = r;
+      vim[i] = m;
+    }
+    let lre = lam[k][0];
+    let lim = lam[k][1];
+    if (Math.abs(lim) <= realTol && realInput) {
+      lim = 0;
+      for (let i = 0; i < n; i++) if (Math.abs(vim[i]) <= 1e-10) vim[i] = 0;
+    }
+    if (lre === 0) lre = 0; // normalise -0
+    cols.push({ lre, lim, vre, vim });
+  }
+
+  cols.sort((a, b) => (Math.abs(a.lre - b.lre) <= realTol ? b.lim - a.lim : b.lre - a.lre));
+  return {
+    values: cols.map((c) => new ComplexNumber(c.lre, c.lim)),
+    vectors: Array.from({ length: n }, (_, i) => cols.map((c) => new ComplexNumber(c.vre[i], c.vim[i]))),
+  };
+}
+
+/** Householder reduction to upper Hessenberg form, accumulating the unitary Z (`A = Z H Zᴴ`). */
+function hessenberg(H: CMat, Z: CMat, n: number): void {
+  for (let k = 0; k < n - 2; k++) {
+    let alpha = 0;
+    for (let i = k + 1; i < n; i++) alpha += H.re[i][k] ** 2 + H.im[i][k] ** 2;
+    alpha = Math.sqrt(alpha);
+    if (alpha === 0) continue;
+    const x0 = Math.hypot(H.re[k + 1][k], H.im[k + 1][k]);
+    // v = x + e^{i arg(x0)} alpha e1
+    const pr = x0 === 0 ? 1 : H.re[k + 1][k] / x0;
+    const pi = x0 === 0 ? 0 : H.im[k + 1][k] / x0;
+    const vr = new Array<number>(n).fill(0);
+    const vi = new Array<number>(n).fill(0);
+    for (let i = k + 1; i < n; i++) {
+      vr[i] = H.re[i][k];
+      vi[i] = H.im[i][k];
+    }
+    vr[k + 1] += pr * alpha;
+    vi[k + 1] += pi * alpha;
+    let vv = 0;
+    for (let i = k + 1; i < n; i++) vv += vr[i] ** 2 + vi[i] ** 2;
+    if (vv === 0) continue;
+    // H <- P H, P = I - 2 v vᴴ / vᴴv   (rows k+1.., all columns)
+    for (let j = 0; j < n; j++) {
+      let sr = 0;
+      let si = 0;
+      for (let i = k + 1; i < n; i++) {
+        sr += vr[i] * H.re[i][j] + vi[i] * H.im[i][j];
+        si += vr[i] * H.im[i][j] - vi[i] * H.re[i][j];
+      }
+      sr = (2 * sr) / vv;
+      si = (2 * si) / vv;
+      for (let i = k + 1; i < n; i++) {
+        H.re[i][j] -= vr[i] * sr - vi[i] * si;
+        H.im[i][j] -= vr[i] * si + vi[i] * sr;
+      }
+    }
+    // H <- H P and Z <- Z P  (columns k+1..)
+    for (const M of [H, Z]) {
+      for (let i = 0; i < n; i++) {
+        let sr = 0;
+        let si = 0;
+        for (let j = k + 1; j < n; j++) {
+          sr += M.re[i][j] * vr[j] - M.im[i][j] * vi[j];
+          si += M.re[i][j] * vi[j] + M.im[i][j] * vr[j];
+        }
+        sr = (2 * sr) / vv;
+        si = (2 * si) / vv;
+        for (let j = k + 1; j < n; j++) {
+          M.re[i][j] -= sr * vr[j] + si * vi[j];
+          M.im[i][j] -= si * vr[j] - sr * vi[j];
+        }
+      }
+    }
+    for (let i = k + 2; i < n; i++) {
+      H.re[i][k] = 0;
+      H.im[i][k] = 0;
+    }
+  }
+}
+
+/** Shifted QR iteration on a Hessenberg matrix until upper triangular (complex Schur form). */
+function schur(H: CMat, Z: CMat, n: number, norm: number, maxIterations: number): void {
+  let hi = n - 1;
+  let iter = 0;
+  let total = 0;
+  while (hi > 0) {
+    // find the start of the active unreduced block
+    let l = hi;
+    while (l > 0) {
+      const s = Math.hypot(H.re[l - 1][l - 1], H.im[l - 1][l - 1]) + Math.hypot(H.re[l][l], H.im[l][l]);
+      const sub = Math.hypot(H.re[l][l - 1], H.im[l][l - 1]);
+      if (sub <= Number.EPSILON * (s === 0 ? norm : s)) {
+        H.re[l][l - 1] = 0;
+        H.im[l][l - 1] = 0;
+        break;
+      }
+      l--;
+    }
+    if (l === hi) {
+      hi--;
+      iter = 0;
+      continue;
+    }
+    if (++iter > maxIterations) throw new Error("eigen: QR iteration failed to converge.");
+    if (++total > 1000 * n) throw new Error("eigen: QR iteration failed to converge.");
+
+    // Wilkinson shift: eigenvalue of the trailing 2x2 closer to H[hi][hi]
+    let mur: number;
+    let mui: number;
+    if (iter % 10 === 0) {
+      // exceptional shift
+      mur = H.re[hi][hi] + Math.hypot(H.re[hi][hi - 1], H.im[hi][hi - 1]);
+      mui = H.im[hi][hi];
+    } else {
+      const ar = H.re[hi - 1][hi - 1];
+      const ai = H.im[hi - 1][hi - 1];
+      const br = H.re[hi - 1][hi];
+      const bi = H.im[hi - 1][hi];
+      const cr = H.re[hi][hi - 1];
+      const ci = H.im[hi][hi - 1];
+      const dr = H.re[hi][hi];
+      const di = H.im[hi][hi];
+      // tr/2, disc = sqrt(((a-d)/2)^2 + bc)
+      const hr = (ar - dr) / 2;
+      const hiI = (ai - di) / 2;
+      const qr = hr * hr - hiI * hiI + (br * cr - bi * ci);
+      const qi = 2 * hr * hiI + (br * ci + bi * cr);
+      const qm = Math.hypot(qr, qi);
+      const sr = Math.sqrt((qm + qr) / 2);
+      const si = (qi < 0 ? -1 : 1) * Math.sqrt(Math.max(0, (qm - qr) / 2));
+      const mr = (ar + dr) / 2;
+      const mi = (ai + di) / 2;
+      const e1r = mr + sr;
+      const e1i = mi + si;
+      const e2r = mr - sr;
+      const e2i = mi - si;
+      if (Math.hypot(e1r - dr, e1i - di) <= Math.hypot(e2r - dr, e2i - di)) {
+        mur = e1r;
+        mui = e1i;
+      } else {
+        mur = e2r;
+        mui = e2i;
+      }
+    }
+
+    for (let i = l; i <= hi; i++) {
+      H.re[i][i] -= mur;
+      H.im[i][i] -= mui;
+    }
+    const rots: Array<[number, number, number]> = []; // [c, sr, si]
+    for (let k = l; k < hi; k++) {
+      const ar = H.re[k][k];
+      const ai = H.im[k][k];
+      const br = H.re[k + 1][k];
+      const bi = H.im[k + 1][k];
+      const am = Math.hypot(ar, ai);
+      const r = Math.hypot(am, Math.hypot(br, bi));
+      let c: number;
+      let sr: number;
+      let si: number;
+      if (r === 0) {
+        c = 1;
+        sr = 0;
+        si = 0;
+      } else if (am === 0) {
+        c = 0;
+        // s = conj(b)/|b|
+        const bm = Math.hypot(br, bi);
+        sr = br / bm;
+        si = -bi / bm;
+      } else {
+        c = am / r;
+        // s = (a/|a|) conj(b) / r
+        const pr = ar / am;
+        const pi = ai / am;
+        sr = (pr * br + pi * bi) / r;
+        si = (pi * br - pr * bi) / r;
+      }
+      rots.push([c, sr, si]);
+      // rows k, k+1 over columns k..n-1: [c s; -conj(s) c]
+      for (let j = k; j < n; j++) {
+        const xr = H.re[k][j];
+        const xi = H.im[k][j];
+        const yr = H.re[k + 1][j];
+        const yi = H.im[k + 1][j];
+        H.re[k][j] = c * xr + (sr * yr - si * yi);
+        H.im[k][j] = c * xi + (sr * yi + si * yr);
+        H.re[k + 1][j] = -(sr * xr + si * xi) + c * yr;
+        H.im[k + 1][j] = -(sr * xi - si * xr) + c * yi;
+      }
+      H.re[k + 1][k] = 0;
+      H.im[k + 1][k] = 0;
+    }
+    for (let idx = 0; idx < rots.length; idx++) {
+      const k = l + idx;
+      const [c, sr, si] = rots[idx];
+      const top = Math.min(hi, k + 1);
+      // columns k, k+1 over rows 0..top (H) and all rows (Z): multiply by Gᴴ = [c -s; conj(s) c]
+      for (const [M, rowEnd] of [
+        [H, top],
+        [Z, n - 1],
+      ] as Array<[CMat, number]>) {
+        for (let i = 0; i <= rowEnd; i++) {
+          const xr = M.re[i][k];
+          const xi = M.im[i][k];
+          const yr = M.re[i][k + 1];
+          const yi = M.im[i][k + 1];
+          M.re[i][k] = c * xr + (yr * sr + yi * si);
+          M.im[i][k] = c * xi + (yi * sr - yr * si);
+          M.re[i][k + 1] = -(xr * sr - xi * si) + c * yr;
+          M.im[i][k + 1] = -(xr * si + xi * sr) + c * yi;
+        }
+      }
+    }
+    for (let i = l; i <= hi; i++) {
+      H.re[i][i] += mur;
+      H.im[i][i] += mui;
+    }
+  }
+  // clear numerical dust below the diagonal
+  for (let i = 1; i < n; i++) {
+    for (let j = 0; j < i; j++) {
+      H.re[i][j] = 0;
+      H.im[i][j] = 0;
+    }
+  }
+}

package/src/Frobenius.ts

@@ -0,0 +1,203 @@
+import { Graph } from "./Graph.ts";
+import { Rational } from "./Rational.ts";
+
+/**
+ * Two "Frobenius" normal forms.
+ *
+ * - {@link frobeniusNormalForm}: the *permutation* normal form of a square
+ *   matrix (Frobenius / Perron-Frobenius block-triangular form). Treat the
+ *   matrix as a weighted digraph (row `i` = node `i`'s out-edges, a non-zero
+ *   entry = an edge); its strongly connected components, put in
+ *   source-to-sink topological order, give a relabelling `P` for which
+ *   `Pᵀ·A·P` is block upper triangular with an irreducible diagonal block per
+ *   component. This is what mallory's matrix panel shows (`MAL-LIN-10`).
+ * - {@link rationalCanonicalForm}: the *similarity* normal form (Frobenius
+ *   normal form in the algebraic sense): `A ~ diag(C(f₁), …, C(f_k))`,
+ *   companion blocks of the invariant factors `f₁ | f₂ | … | f_k`, computed
+ *   exactly over ℚ from the Smith normal form of `xI − A`.
+ */
+
+export type NumericMatrix = ReadonlyArray<ReadonlyArray<number>>;
+
+export interface FrobeniusBlock {
+  /** The component's vertices as ORIGINAL matrix indices. */
+  component: number[];
+  /** Row/column range in `permuted` (inclusive start, exclusive end). */
+  start: number;
+  end: number;
+}
+
+export interface FrobeniusResult {
+  /** `order[i]` = the original index now at permuted position `i`. */
+  order: number[];
+  /** Permutation matrix with `Pᵀ·matrix·P === permuted`. */
+  P: number[][];
+  /** `matrix` reindexed by `order` on both axes: block upper triangular. */
+  permuted: number[][];
+  /** One entry per strongly connected component, source to sink. */
+  blocks: FrobeniusBlock[];
+  /** True when the whole matrix is a single strongly connected component. */
+  irreducible: boolean;
+}
+
+/**
+ * The block-triangular (permutation) Frobenius normal form of a square matrix.
+ * Diagonal entries are self-loops and never affect the component structure.
+ * Within a component, original index order is the (deterministic) tiebreak.
+ */
+export function frobeniusNormalForm(matrix: NumericMatrix): FrobeniusResult {
+  const n = matrix.length;
+  for (const row of matrix) {
+    if (row.length !== n)
+      throw new Error(
+        `frobeniusNormalForm requires a square matrix (got a ${n}-row matrix with a ${row.length}-entry row).`,
+      );
+  }
+  const graph = new Graph<number>(true);
+  for (let i = 0; i < n; i++) graph.addVertex(i);
+  for (let i = 0; i < n; i++) for (let j = 0; j < n; j++) if (matrix[i][j] !== 0) graph.addEdge(i, j, matrix[i][j]);
+
+  const { graph: dag, components } = graph.condensation();
+  const topo = dag.topologicalSort();
+  if (!topo) throw new Error("frobeniusNormalForm: condensation unexpectedly has a cycle.");
+
+  const order: number[] = [];
+  const blocks: FrobeniusBlock[] = [];
+  for (const c of topo) {
+    const component = [...components[c]].sort((a, b) => a - b);
+    const start = order.length;
+    order.push(...component);
+    blocks.push({ component, start, end: order.length });
+  }
+  const permuted = order.map((oi) => order.map((oj) => matrix[oi][oj]));
+  const P = Array.from({ length: n }, () => new Array<number>(n).fill(0));
+  for (let i = 0; i < n; i++) P[order[i]][i] = 1;
+  return { order, P, permuted, blocks, irreducible: components.length === 1 };
+}
+
+// ---- rational canonical form ------------------------------------------------
+
+/** A polynomial over ℚ, coefficients lowest degree first, no trailing zeros ([] is the zero polynomial). */
+type Poly = Rational[];
+
+const trim = (p: Poly): Poly => {
+  let n = p.length;
+  while (n > 0 && p[n - 1].isZero()) n--;
+  return p.slice(0, n);
+};
+const deg = (p: Poly) => p.length - 1;
+const padd = (a: Poly, b: Poly): Poly =>
+  trim(
+    Array.from({ length: Math.max(a.length, b.length) }, (_, i) => (a[i] ?? Rational.Zero).add(b[i] ?? Rational.Zero)),
+  );
+const pneg = (a: Poly): Poly => a.map((c) => c.negate());
+const pmul = (a: Poly, b: Poly): Poly => {
+  if (!a.length || !b.length) return [];
+  const out: Rational[] = Array.from({ length: a.length + b.length - 1 }, () => Rational.Zero);
+  for (let i = 0; i < a.length; i++)
+    for (let j = 0; j < b.length; j++) out[i + j] = out[i + j].add(a[i].multiply(b[j]));
+  return trim(out);
+};
+/** Polynomial division with remainder (`b` non-zero). */
+const pdivmod = (a: Poly, b: Poly): { q: Poly; r: Poly } => {
+  let r = [...a];
+  const q: Rational[] = Array.from({ length: Math.max(0, a.length - b.length + 1) }, () => Rational.Zero);
+  const lead = b[b.length - 1];
+  while (r.length >= b.length) {
+    const c = r[r.length - 1].divide(lead);
+    const d = r.length - b.length;
+    q[d] = c;
+    r = trim(r.map((x, i) => (i >= d ? x.subtract(c.multiply(b[i - d])) : x)));
+  }
+  return { q: trim(q), r };
+};
+const monic = (p: Poly): Poly => (p.length ? p.map((c) => c.divide(p[p.length - 1])) : p);
+
+/** Smith normal form diagonal of a polynomial matrix, as monic polynomials (zero entries stay zero). */
+function smithDiagonal(M: Poly[][]): Poly[] {
+  const n = M.length;
+  for (let t = 0; t < n; t++) {
+    for (;;) {
+      // pivot: non-zero entry of least degree in the trailing submatrix
+      let pi = -1;
+      let pj = -1;
+      for (let i = t; i < n; i++) {
+        for (let j = t; j < n; j++) {
+          if (M[i][j].length && (pi < 0 || deg(M[i][j]) < deg(M[pi][pj]))) {
+            pi = i;
+            pj = j;
+          }
+        }
+      }
+      if (pi < 0) return M.map((row, i) => (i < t ? monic(row[i]) : [])).concat([]);
+      [M[t], M[pi]] = [M[pi], M[t]];
+      for (const row of M) [row[t], row[pj]] = [row[pj], row[t]];
+      const p = M[t][t];
+      let dirty = false;
+      for (let i = t + 1; i < n; i++) {
+        if (!M[i][t].length) continue;
+        const { q } = pdivmod(M[i][t], p);
+        for (let j = t; j < n; j++) M[i][j] = padd(M[i][j], pneg(pmul(q, M[t][j])));
+        if (M[i][t].length) dirty = true;
+      }
+      for (let j = t + 1; j < n; j++) {
+        if (!M[t][j].length) continue;
+        const { q } = pdivmod(M[t][j], p);
+        for (let i = t; i < n; i++) M[i][j] = padd(M[i][j], pneg(pmul(q, M[i][t])));
+        if (M[t][j].length) dirty = true;
+      }
+      if (dirty) continue; // a smaller-degree remainder appeared: re-pivot
+      // pivot must divide everything left; if not, fold the offending row in
+      let bad = -1;
+      for (let i = t + 1; i < n && bad < 0; i++) {
+        for (let j = t + 1; j < n; j++) {
+          if (M[i][j].length && pdivmod(M[i][j], p).r.length) {
+            bad = i;
+            break;
+          }
+        }
+      }
+      if (bad < 0) break;
+      for (let j = t; j < n; j++) M[t][j] = padd(M[t][j], M[bad][j]);
+    }
+  }
+  return M.map((row, i) => monic(row[i]));
+}
+
+export interface RationalCanonicalResult {
+  /** Monic invariant factors `f₁ | f₂ | … | f_k` (non-constant only), each as coefficients lowest degree first. */
+  invariantFactors: Rational[][];
+  /** Block diagonal of the companion matrices of `invariantFactors` (n×n, exact). */
+  form: Rational[][];
+  /** The blocks' sizes (the degrees of the invariant factors). */
+  blockSizes: number[];
+}
+
+/**
+ * Rational canonical form (Frobenius normal form in the similarity sense) of a
+ * square matrix with integer or {@link Rational} entries, exact over ℚ.
+ * `invariantFactors` multiply to the characteristic polynomial and the last is
+ * the minimal polynomial. Each companion block `C(f)` for
+ * `f = xᵏ + c_{k-1}x^{k-1} + … + c₀` has ones on the subdiagonal and last
+ * column `(-c₀, …, -c_{k-1})ᵀ`. The similarity transform itself is not returned.
+ */
+export function rationalCanonicalForm(
+  matrix: ReadonlyArray<ReadonlyArray<number | bigint | Rational>>,
+): RationalCanonicalResult {
+  const n = matrix.length;
+  for (const row of matrix) if (row.length !== n) throw new Error("rationalCanonicalForm requires a square matrix.");
+  const A = matrix.map((row) => row.map((v) => Rational.from(v)));
+  // xI - A as a polynomial matrix
+  const M: Poly[][] = A.map((row, i) => row.map((a, j) => trim(i === j ? [a.negate(), Rational.One] : [a.negate()])));
+  const diag = smithDiagonal(M);
+  const factors = diag.filter((p) => p.length > 1);
+  const form: Rational[][] = Array.from({ length: n }, () => Array.from({ length: n }, () => Rational.Zero));
+  let off = 0;
+  for (const f of factors) {
+    const k = deg(f);
+    for (let i = 1; i < k; i++) form[off + i][off + i - 1] = Rational.One;
+    for (let i = 0; i < k; i++) form[off + i][off + k - 1] = f[i].negate();
+    off += k;
+  }
+  return { invariantFactors: factors, form, blockSizes: factors.map(deg) };
+}

package/src/Graph.ts

@@ -260,6 +260,74 @@ export class Graph<T = string | number> {
     return mst;
   }
 
+  /**
+   * Minimum spanning tree (or forest, when the graph is disconnected) with
+   * its total weight and the number of connected components. Edge direction
+   * is ignored. `algorithm` picks Kruskal (default, sort + union-find) or
+   * Prim (heap-based, grown from each unvisited vertex in turn); both give
+   * the same total weight, though tie-broken edge choices may differ.
+   */
+  mst(algorithm: "kruskal" | "prim" = "kruskal"): { edges: Array<Edge<T>>; totalWeight: number; components: number } {
+    const n = this.vertices().length;
+    let edges: Array<Edge<T>>;
+    if (algorithm === "kruskal") edges = this.minimumSpanningTree();
+    else {
+      edges = [];
+      const nbrs = new Map<T, Array<Edge<T>>>();
+      for (const v of this.vertices()) nbrs.set(v, []);
+      for (const e of this.edges()) {
+        (nbrs.get(e.from) as Array<Edge<T>>).push(e);
+        (nbrs.get(e.to) as Array<Edge<T>>).push(e);
+      }
+      const seen = new Set<T>();
+      for (const root of this.vertices()) {
+        if (seen.has(root)) continue;
+        seen.add(root);
+        const heap = new MinHeap<Edge<T>>();
+        for (const e of nbrs.get(root) as Array<Edge<T>>) heap.push(e, e.weight);
+        for (let top = heap.pop(); top; top = heap.pop()) {
+          const e = top.value;
+          const next = seen.has(e.from) ? e.to : e.from;
+          if (seen.has(next)) continue;
+          seen.add(next);
+          edges.push(e);
+          for (const f of nbrs.get(next) as Array<Edge<T>>)
+            if (!seen.has(f.from) || !seen.has(f.to)) heap.push(f, f.weight);
+        }
+      }
+    }
+    return { edges, totalWeight: edges.reduce((s, e) => s + e.weight, 0), components: n - edges.length };
+  }
+
+  /** Alias of {@link stronglyConnectedComponents} (Tarjan; components in reverse topological order). */
+  scc(): T[][] {
+    return this.stronglyConnectedComponents();
+  }
+
+  /**
+   * The condensation: one vertex per strongly connected component (numbered
+   * by position in {@link scc}'s output), with one weight-1 edge `i -> j`
+   * wherever the original graph has any edge from a member of `i` to a
+   * member of `j`. Always a DAG. Also returns the `components` and the
+   * `componentOf` vertex-to-index map.
+   */
+  condensation(): { graph: Graph<number>; components: T[][]; componentOf: Map<T, number> } {
+    const components = this.scc();
+    const componentOf = new Map<T, number>();
+    components.forEach((c, i) => {
+      for (const v of c) componentOf.set(v, i);
+    });
+    const graph = new Graph<number>(true);
+    for (let i = 0; i < components.length; i++) graph.addVertex(i);
+    for (const e of this.edges()) {
+      const a = componentOf.get(e.from) as number;
+      const b = componentOf.get(e.to) as number;
+      if (a !== b) graph.addEdge(a, b, 1);
+      if (!this.directed && a !== b) graph.addEdge(b, a, 1);
+    }
+    return { graph, components, componentOf };
+  }
+
   /** Adjacency matrix (rows/cols follow the returned `order`; `Infinity` = no edge). */
   toAdjacencyMatrix(): { matrix: number[][]; order: T[] } {
     const order = this.vertices();

package/src/MatrixMath.ts

@@ -1,3 +1,5 @@
+import type { ComplexNumber } from "./ComplexNumber.ts";
+import { eigenGeneral, type GeneralEigenResult } from "./EigenGeneral.ts";
 import { Vector } from "./Vector.ts";
 import type { Matrix } from "./VectorUtils.ts";
 
@@ -259,6 +261,17 @@ export class MatrixMath {
     };
   }
 
+  /**
+   * Eigenvalues and right eigenvectors of any square matrix (real or complex
+   * entries), as `scipy.linalg.eig`: Hessenberg reduction plus shifted QR.
+   * Eigenvalues may be complex; `vectors[i][k]` is component `i` of the unit
+   * eigenvector for `values[k]`. For symmetric input prefer
+   * {@link MatrixMath.eigenSymmetric} (real, orthonormal, faster).
+   */
+  static eigen(A: MatrixInput | ComplexNumber[][]): GeneralEigenResult {
+    return eigenGeneral([...(A as Iterable<Iterable<number | ComplexNumber>>)].map((r) => [...r]));
+  }
+
   /**
    * Singular value decomposition `A = U·Σ·Vᵀ` (via the eigendecomposition of
    * `AᵀA`). Returns `U`, the singular values `S` (descending), and `V`.