@graphty/algorithms 2.1.2 → 2.2.0

package/dist/src/indexed/scc.js

@@ -0,0 +1,110 @@
+import { INVALID_INDEX, } from "@graphty/graph-format";
+import { checkArcOrder } from "./bfs.js";
+import { withGroups } from "./components.js";
+/**
+ * Strongly connected components by an iterative Tarjan: roots in index order, neighbours in row
+ * order unless `options.arcOrder` gives another, and component `c` is the `c`-th to complete -- the numbering the legacy
+ * `stronglyConnectedComponents` gives its result array. Completion order is a reverse topological
+ * order of the condensation.
+ * @param g - A directed adjacency
+ * @param options - The neighbour order
+ * @returns The partition, labels in completion order
+ * @throws Error when the graph is undirected
+ * @public
+ */
+export function stronglyConnectedComponents(g, options = {}) {
+    const { labels, count } = tarjan(g, options);
+    return withGroups(labels, count);
+}
+/**
+ * The Tarjan walk behind {@link stronglyConnectedComponents}, also returning every node in the
+ * order it left the component stack. Each component leaves as one run, in label order, its members
+ * in reverse discovery order -- the order the legacy `stronglyConnectedComponents` lists them in.
+ * @param g - A directed adjacency
+ * @param options - The neighbour order
+ * @returns The labels, their count and the pop order
+ * @throws Error when the graph is undirected
+ */
+export function tarjan(g, options = {}) {
+    if (!g.directed) {
+        throw new Error("Strongly connected components require a directed graph. Use connectedComponents for an undirected one.");
+    }
+    const { nodeCount, rowPtr, colIdx } = g;
+    const arcOrder = checkArcOrder(g, options.arcOrder);
+    const index = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    const low = new Uint32Array(nodeCount);
+    const cursor = new Uint32Array(nodeCount);
+    const onStack = new Uint8Array(nodeCount);
+    const callStack = new Uint32Array(nodeCount);
+    const sccStack = new Uint32Array(nodeCount);
+    const labels = new Uint32Array(nodeCount);
+    const popped = new Uint32Array(nodeCount);
+    let poppedCount = 0;
+    let next = 0;
+    let count = 0;
+    let sp = 0;
+    let top = 0;
+    // The body of the recursive call before its loop over neighbours.
+    const enter = (u) => {
+        index[u] = next;
+        low[u] = next;
+        next++;
+        cursor[u] = rowPtr[u];
+        sccStack[sp++] = u;
+        onStack[u] = 1;
+        callStack[top++] = u;
+    };
+    for (let r = 0; r < nodeCount; r++) {
+        if (index[r] !== INVALID_INDEX) {
+            continue;
+        }
+        enter(r);
+        while (top > 0) {
+            const x = callStack[top - 1];
+            if (cursor[x] < rowPtr[x + 1]) {
+                const a = cursor[x]++;
+                const v = colIdx[arcOrder === null ? a : arcOrder[a]];
+                if (index[v] === INVALID_INDEX) {
+                    enter(v);
+                }
+                else if (onStack[v] === 1 && index[v] < low[x]) {
+                    low[x] = index[v];
+                }
+                continue;
+            }
+            // x returns: close its component if it is a root, then pass its low link to the caller.
+            top--;
+            if (low[x] === index[x]) {
+                let w;
+                do {
+                    w = sccStack[--sp];
+                    onStack[w] = 0;
+                    labels[w] = count;
+                    popped[poppedCount++] = w;
+                } while (w !== x);
+                count++;
+            }
+            if (top > 0 && low[x] < low[callStack[top - 1]]) {
+                low[callStack[top - 1]] = low[x];
+            }
+        }
+    }
+    return { labels, count, popped };
+}
+/**
+ * The condensation of a directed graph: its strongly connected components, and the DAG with one
+ * node per component that `contract()` builds from their labels. The labels already run `0..k-1`,
+ * so contract keeps them as block indices and the condensed node numbering is the component
+ * numbering.
+ * @param s - A directed snapshot
+ * @param options - The neighbour order Tarjan tries arcs in, which fixes the component numbering
+ * @returns The components and the condensed graph
+ * @throws Error when the snapshot is undirected
+ * @public
+ */
+export function condensation(s, options = {}) {
+    const components = stronglyConnectedComponents(s, options);
+    const condensed = s.contract(components.labels, { selfLoops: "drop", parallel: "merge", weights: "first" });
+    return { components, condensed };
+}
+//# sourceMappingURL=scc.js.map

package/dist/src/indexed/scc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scc.js","sourceRoot":"","sources":["../../../src/indexed/scc.ts"],"names":[],"mappings":"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"}

package/dist/src/indexed/spectral.d.ts

@@ -0,0 +1,61 @@
+import { type GraphSnapshot, type NumericVector } from "@graphty/graph-format";
+import { type LabelResult } from "./components.js";
+/** Which graph Laplacian the embedding comes from. @public */
+export type LaplacianType = "unnormalized" | "normalized" | "randomWalk";
+/** Options of the index-based spectral clustering. @public */
+export interface SpectralOptions {
+    /** Number of clusters, a positive integer. */
+    readonly k: number;
+    /** `D - A`, `I - D^-1/2 A D^-1/2` (rows of the embedding scaled to unit length) or `I - D^-1 A`; default normalized. */
+    readonly laplacianType?: LaplacianType | undefined;
+    /** Cap on k-means rounds; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** k-means stops when no centroid moves further than this; default 1e-4. */
+    readonly tolerance?: number | undefined;
+    /** Seed of the starting block and of the k-means seeding; default 42. */
+    readonly seed?: number | undefined;
+    /** Per-arc weight override, arcCount long -- the facade passes `expandEdges(s, shadow.data)`. */
+    readonly weights?: NumericVector | undefined;
+}
+/** Result of the index-based spectral clustering. @public */
+export interface SpectralResult extends LabelResult {
+    /** The k smallest eigenvalues of the Laplacian, ascending; empty when k >= nodeCount. */
+    readonly eigenvalues: Float64Array;
+    /** One nodeCount-long eigenvector per eigenvalue; for randomWalk, of `I - D^-1 A`. */
+    readonly eigenvectors: Float64Array[];
+    /**
+     * Whether the eigenpairs met the residual tolerance. False when the iteration stopped at its
+     * round cap -- on a graph whose small eigenvalues crowd together, such as a long path -- and
+     * the eigenpairs are then approximations (the labels usually still hold). True when there
+     * were no eigenpairs to compute.
+     */
+    readonly converged: boolean;
+}
+/**
+ * Spectral clustering, the index-based port of the legacy `spectralClustering`: the k eigenvectors
+ * of the graph Laplacian with the smallest eigenvalues embed every node as a point in k dimensions,
+ * and k-means splits the points into at most k clusters.
+ *
+ * The Laplacian is applied straight from the CSR rows and never built: `D - A`
+ * (`unnormalized`), `I - D^-1/2 A D^-1/2` (`normalized`, whose embedded rows are then scaled to
+ * unit length, as Ng, Jordan and Weiss do) or `I - D^-1 A` (`randomWalk`, whose eigenvectors are
+ * `D^-1/2` times the normalized ones). A node of degree 0 has a zero row. Self-loops are ignored
+ * (they cancel in `D - A`) and a directed snapshot is read as undirected, a reciprocal pair
+ * summing. A negative, NaN or infinite weight throws. With `k >= nodeCount` every node is its own
+ * cluster.
+ *
+ * The eigenpairs come from subspace iteration with Rayleigh-Ritz, so they are the true smallest
+ * ones when `converged` is true; `converged` is false when the iteration stopped at its round cap
+ * (a small spectral gap, such as a path of hundreds of nodes), and the eigenpairs are then only
+ * approximate. The legacy function uses fixed placeholder eigenvalues for k <= 3 and plain power
+ * iteration (which finds the LARGEST eigenvectors) above that, and draws its k-means seeds from
+ * `Math.random` unless given a seed. The partitions therefore differ from the legacy function's;
+ * one `seed` gives one result. Labels are dense in first-seen order, so `count` is below k when
+ * k-means leaves a cluster empty.
+ * @param s - Any snapshot
+ * @param options - k, the Laplacian, the k-means limits, the seed and the weight override
+ * @returns The partition and the eigenpairs it came from
+ * @public
+ */
+export declare function spectralClustering(s: GraphSnapshot, options: SpectralOptions): SpectralResult;
+//# sourceMappingURL=spectral.d.ts.map

package/dist/src/indexed/spectral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spectral.d.ts","sourceRoot":"","sources":["../../../src/indexed/spectral.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,aAAa,EAClB,KAAK,aAAa,EAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,iBAAiB,CAAC;AAE/D,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,YAAY,GAAG,YAAY,CAAC;AAEzE,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,wHAAwH;IACxH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAChD;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAe,SAAQ,WAAW;IAC/C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAkYD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CA+F7F"}

package/dist/src/indexed/spectral.js

@@ -0,0 +1,476 @@
+import { renumberPartition, } from "@graphty/graph-format";
+import { withGroups } from "./components.js";
+/** Relative eigenvector residual at which subspace iteration stops. */
+const RESIDUAL_TOLERANCE = 1e-11;
+/** Subspace-iteration cap; each round costs one sparse product per block vector. */
+const MAX_SUBSPACE_ROUNDS = 3000;
+/**
+ * mulberry32, the generator the label propagation port uses.
+ * @param seed - Generator seed; only its low 32 bits are used
+ * @returns The generator, output in [0, 1)
+ */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * The snapshot's adjacency made symmetric -- a directed snapshot's out-row and in-row together, so
+ * a reciprocal pair sums -- with self-loops dropped (they cancel in `D - A`) and weights checked.
+ * @param s - The snapshot
+ * @param weights - Per-arc weights, or null for all ones
+ * @returns The rows and the weighted degrees
+ */
+function symmetricRows(s, weights) {
+    const n = s.nodeCount;
+    const views = [{ view: s, arcOf: (a) => a }];
+    if (s.directed) {
+        const rev = s.reverse();
+        views.push({ view: rev, arcOf: (k) => rev.fwdArc[k] });
+    }
+    const rowPtr = new Uint32Array(n + 1);
+    for (let u = 0; u < n; u++) {
+        let kept = 0;
+        for (const { view } of views) {
+            for (let a = view.rowPtr[u]; a < view.rowPtr[u + 1]; a++) {
+                kept += view.colIdx[a] === u ? 0 : 1;
+            }
+        }
+        rowPtr[u + 1] = rowPtr[u] + kept;
+    }
+    const colIdx = new Uint32Array(rowPtr[n]);
+    const w = new Float64Array(rowPtr[n]);
+    const degree = new Float64Array(n);
+    let k = 0;
+    for (let u = 0; u < n; u++) {
+        for (const { view, arcOf } of views) {
+            for (let a = view.rowPtr[u]; a < view.rowPtr[u + 1]; a++) {
+                const weight = weights === null ? 1 : weights[arcOf(a)];
+                if (!(weight >= 0) || weight === Infinity) {
+                    throw new RangeError(`an arc has weight ${weight}; spectral clustering needs finite, non-negative weights`);
+                }
+                if (view.colIdx[a] !== u) {
+                    colIdx[k] = view.colIdx[a];
+                    w[k++] = weight;
+                    degree[u] += weight;
+                }
+            }
+        }
+    }
+    return { rowPtr, colIdx, w, degree };
+}
+/**
+ * Orthonormalise the columns of `block` in place (Gram-Schmidt, applied twice for stability). A
+ * column that collapses is replaced by a fresh random one.
+ * @param block - p columns of length n
+ * @param random - The generator for replacements
+ */
+function orthonormalise(block, random) {
+    for (let j = 0; j < block.length; j++) {
+        const v = block[j];
+        for (let attempt = 0;; attempt++) {
+            for (let pass = 0; pass < 2; pass++) {
+                for (let i = 0; i < j; i++) {
+                    const q = block[i];
+                    let dot = 0;
+                    for (let r = 0; r < v.length; r++) {
+                        dot += q[r] * v[r];
+                    }
+                    for (let r = 0; r < v.length; r++) {
+                        v[r] -= dot * q[r];
+                    }
+                }
+            }
+            let norm = 0;
+            for (let r = 0; r < v.length; r++) {
+                norm += v[r] * v[r];
+            }
+            norm = Math.sqrt(norm);
+            if (norm > 1e-10 || attempt === 3) {
+                for (let r = 0; r < v.length; r++) {
+                    v[r] = norm > 0 ? v[r] / norm : 0;
+                }
+                break;
+            }
+            for (let r = 0; r < v.length; r++) {
+                v[r] = random() - 0.5;
+            }
+        }
+    }
+}
+/**
+ * Eigen-decomposition of a small symmetric matrix by cyclic Jacobi rotations.
+ * @param a - p x p row-major, destroyed
+ * @param p - The order
+ * @returns The eigenvalues and the eigenvectors as the columns of a p x p row-major matrix
+ */
+function jacobi(a, p) {
+    const v = new Float64Array(p * p);
+    for (let i = 0; i < p; i++) {
+        v[i * p + i] = 1;
+    }
+    for (let sweep = 0; sweep < 100; sweep++) {
+        let off = 0;
+        for (let i = 0; i < p; i++) {
+            for (let j = i + 1; j < p; j++) {
+                off += a[i * p + j] * a[i * p + j];
+            }
+        }
+        if (off < 1e-30) {
+            break;
+        }
+        for (let i = 0; i < p; i++) {
+            for (let j = i + 1; j < p; j++) {
+                const aij = a[i * p + j];
+                if (aij === 0) {
+                    continue;
+                }
+                const theta = (a[j * p + j] - a[i * p + i]) / (2 * aij);
+                const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+                const c = 1 / Math.sqrt(t * t + 1);
+                const sn = t * c;
+                for (let r = 0; r < p; r++) {
+                    const ari = a[r * p + i];
+                    const arj = a[r * p + j];
+                    a[r * p + i] = c * ari - sn * arj;
+                    a[r * p + j] = sn * ari + c * arj;
+                }
+                for (let r = 0; r < p; r++) {
+                    const air = a[i * p + r];
+                    const ajr = a[j * p + r];
+                    a[i * p + r] = c * air - sn * ajr;
+                    a[j * p + r] = sn * air + c * ajr;
+                }
+                for (let r = 0; r < p; r++) {
+                    const vri = v[r * p + i];
+                    const vrj = v[r * p + j];
+                    v[r * p + i] = c * vri - sn * vrj;
+                    v[r * p + j] = sn * vri + c * vrj;
+                }
+            }
+        }
+    }
+    return { values: Float64Array.from({ length: p }, (_, i) => a[i * p + i]), vectors: v };
+}
+/**
+ * The k smallest eigenpairs of a symmetric Laplacian, by subspace iteration on `shift * I - L` (whose
+ * largest eigenpairs they are) with a Rayleigh-Ritz step, over a block a few vectors wider than k.
+ * @param apply - Writes `L x` into `out`
+ * @param n - Order
+ * @param k - Eigenpairs wanted
+ * @param shift - An upper bound on the largest eigenvalue of L
+ * @param random - The generator of the starting block
+ * @returns Eigenvalues ascending, their eigenvectors, and whether they met the tolerance
+ */
+function smallestEigenpairs(apply, n, k, shift, random) {
+    const p = Math.min(n, k + Math.max(k, 8));
+    let block = Array.from({ length: p }, () => Float64Array.from({ length: n }, () => random() - 0.5));
+    orthonormalise(block, random);
+    const lx = new Float64Array(n);
+    const shifted = (x) => {
+        apply(x, lx);
+        return x.map((xi, r) => shift * xi - lx[r]);
+    };
+    let ritz = new Float64Array(p);
+    let order = [];
+    let vectors = new Float64Array(p * p);
+    let converged = false;
+    // ponytail: plain subspace iteration converges at the ratio of neighbouring shifted eigenvalues,
+    // so a small spectral gap hits the cap; Chebyshev filtering would converge far faster there.
+    for (let round = 0; round < MAX_SUBSPACE_ROUNDS; round++) {
+        const image = block.map(shifted);
+        // Rayleigh-Ritz: the block's projection of the shifted operator, diagonalised.
+        const h = new Float64Array(p * p);
+        for (let i = 0; i < p; i++) {
+            for (let j = i; j < p; j++) {
+                let dot = 0;
+                for (let r = 0; r < n; r++) {
+                    dot += block[i][r] * image[j][r];
+                }
+                h[i * p + j] = dot;
+                h[j * p + i] = dot;
+            }
+        }
+        const eig = jacobi(h, p);
+        ({ values: ritz, vectors } = eig);
+        order = Array.from({ length: p }, (_, i) => i).sort((a, b) => ritz[b] - ritz[a]);
+        // Converged when every wanted Ritz pair (y = X q, theta) has a residual |B y - theta y|
+        // below RESIDUAL_TOLERANCE * shift; B y is the image block times q.
+        converged = order.slice(0, k).every((col) => {
+            let residual = 0;
+            for (let r = 0; r < n; r++) {
+                let diff = 0;
+                for (let i = 0; i < p; i++) {
+                    diff += vectors[i * p + col] * (image[i][r] - ritz[col] * block[i][r]);
+                }
+                residual += diff * diff;
+            }
+            return Math.sqrt(residual) <= RESIDUAL_TOLERANCE * shift;
+        });
+        if (converged || round === MAX_SUBSPACE_ROUNDS - 1) {
+            break; // at the cap the Ritz pairs of this block are the best estimate there is
+        }
+        block = image;
+        orthonormalise(block, random);
+    }
+    const values = new Float64Array(k);
+    const out = [];
+    for (let rank = 0; rank < k; rank++) {
+        const col = order[rank];
+        values[rank] = Math.max(0, shift - ritz[col]);
+        const v = new Float64Array(n);
+        for (let i = 0; i < p; i++) {
+            const c = vectors[i * p + col];
+            for (let r = 0; r < n; r++) {
+                v[r] += c * block[i][r];
+            }
+        }
+        out.push(v);
+    }
+    return { values, vectors: out, converged };
+}
+/** k-means runs per clustering; the one with the lowest inertia is kept. */
+const K_MEANS_RUNS = 10;
+/**
+ * The k-means objective: the summed squared distance of every row from its cluster's mean.
+ * @param points - n rows of length d, row-major
+ * @param assign - The cluster of every row
+ * @param n - Row count
+ * @param d - Row length
+ * @param k - Cluster count
+ * @returns The inertia
+ */
+function inertiaOf(points, assign, n, d, k) {
+    const sums = new Float64Array(k * d);
+    const sizes = new Float64Array(k);
+    for (let i = 0; i < n; i++) {
+        sizes[assign[i]]++;
+        for (let t = 0; t < d; t++) {
+            sums[assign[i] * d + t] += points[i * d + t];
+        }
+    }
+    let total = 0;
+    for (let i = 0; i < n; i++) {
+        const c = assign[i];
+        for (let t = 0; t < d; t++) {
+            total += (points[i * d + t] - sums[c * d + t] / sizes[c]) ** 2;
+        }
+    }
+    return total;
+}
+/**
+ * k-means over the rows of an n x d embedding, seeded with k-means++ and refined by Lloyd rounds.
+ * @param points - n rows of length d, row-major
+ * @param n - Row count
+ * @param d - Row length
+ * @param k - Cluster count
+ * @param maxIterations - Round cap
+ * @param tolerance - Stop when no centroid moves further than this
+ * @param random - The generator
+ * @returns The cluster of every row
+ */
+function kMeans(points, n, d, k, maxIterations, tolerance, random) {
+    const dist2 = (i, centres, c) => {
+        let sum = 0;
+        for (let t = 0; t < d; t++) {
+            const diff = points[i * d + t] - centres[c * d + t];
+            sum += diff * diff;
+        }
+        return sum;
+    };
+    const centres = new Float64Array(k * d);
+    const nearest = new Float64Array(n).fill(Infinity);
+    let pick = Math.floor(random() * n);
+    for (let c = 0; c < k; c++) {
+        centres.set(points.subarray(pick * d, pick * d + d), c * d);
+        let total = 0;
+        for (let i = 0; i < n; i++) {
+            nearest[i] = Math.min(nearest[i], dist2(i, centres, c));
+            total += nearest[i];
+        }
+        // k-means++: the next centre is a row drawn with probability proportional to its squared
+        // distance from the nearest centre so far (the first row when every row sits on a centre).
+        let target = random() * total;
+        pick = 0;
+        for (let i = 0; i < n && total > 0; i++) {
+            target -= nearest[i];
+            if (target < 0) {
+                pick = i;
+                break;
+            }
+        }
+    }
+    const assign = new Uint32Array(n);
+    for (let round = 0; round < maxIterations; round++) {
+        let changed = round === 0;
+        for (let i = 0; i < n; i++) {
+            let best = 0;
+            let bestDist = Infinity;
+            for (let c = 0; c < k; c++) {
+                const dd = dist2(i, centres, c);
+                if (dd < bestDist) {
+                    bestDist = dd;
+                    best = c;
+                }
+            }
+            changed || (changed = assign[i] !== best);
+            assign[i] = best;
+        }
+        if (!changed) {
+            break;
+        }
+        const sums = new Float64Array(k * d);
+        const sizes = new Float64Array(k);
+        for (let i = 0; i < n; i++) {
+            sizes[assign[i]]++;
+            for (let t = 0; t < d; t++) {
+                sums[assign[i] * d + t] += points[i * d + t];
+            }
+        }
+        let shift = 0;
+        for (let c = 0; c < k; c++) {
+            if (sizes[c] === 0) {
+                continue; // an emptied cluster keeps its centre
+            }
+            let moved = 0;
+            for (let t = 0; t < d; t++) {
+                const next = sums[c * d + t] / sizes[c];
+                moved += (next - centres[c * d + t]) ** 2;
+                centres[c * d + t] = next;
+            }
+            shift = Math.max(shift, Math.sqrt(moved));
+        }
+        if (shift < tolerance) {
+            break;
+        }
+    }
+    return assign;
+}
+/**
+ * Spectral clustering, the index-based port of the legacy `spectralClustering`: the k eigenvectors
+ * of the graph Laplacian with the smallest eigenvalues embed every node as a point in k dimensions,
+ * and k-means splits the points into at most k clusters.
+ *
+ * The Laplacian is applied straight from the CSR rows and never built: `D - A`
+ * (`unnormalized`), `I - D^-1/2 A D^-1/2` (`normalized`, whose embedded rows are then scaled to
+ * unit length, as Ng, Jordan and Weiss do) or `I - D^-1 A` (`randomWalk`, whose eigenvectors are
+ * `D^-1/2` times the normalized ones). A node of degree 0 has a zero row. Self-loops are ignored
+ * (they cancel in `D - A`) and a directed snapshot is read as undirected, a reciprocal pair
+ * summing. A negative, NaN or infinite weight throws. With `k >= nodeCount` every node is its own
+ * cluster.
+ *
+ * The eigenpairs come from subspace iteration with Rayleigh-Ritz, so they are the true smallest
+ * ones when `converged` is true; `converged` is false when the iteration stopped at its round cap
+ * (a small spectral gap, such as a path of hundreds of nodes), and the eigenpairs are then only
+ * approximate. The legacy function uses fixed placeholder eigenvalues for k <= 3 and plain power
+ * iteration (which finds the LARGEST eigenvectors) above that, and draws its k-means seeds from
+ * `Math.random` unless given a seed. The partitions therefore differ from the legacy function's;
+ * one `seed` gives one result. Labels are dense in first-seen order, so `count` is below k when
+ * k-means leaves a cluster empty.
+ * @param s - Any snapshot
+ * @param options - k, the Laplacian, the k-means limits, the seed and the weight override
+ * @returns The partition and the eigenpairs it came from
+ * @public
+ */
+export function spectralClustering(s, options) {
+    const { k } = options;
+    const type = options.laplacianType ?? "normalized";
+    const maxIterations = options.maxIterations ?? 100;
+    const tolerance = options.tolerance ?? 1e-4;
+    const seed = options.seed ?? 42;
+    if (!Number.isInteger(k) || k < 1) {
+        throw new RangeError(`k must be a positive integer, got ${k}`);
+    }
+    if (!["unnormalized", "normalized", "randomWalk"].includes(type)) {
+        throw new RangeError(`unknown laplacianType "${type}"`);
+    }
+    if (!Number.isInteger(maxIterations) || maxIterations < 0 || !(tolerance >= 0) || !Number.isInteger(seed)) {
+        throw new RangeError("maxIterations and seed must be integers, maxIterations and tolerance non-negative");
+    }
+    const weights = options.weights ?? s.weights;
+    if (weights !== null && weights.length !== s.arcCount) {
+        throw new RangeError(`weights has ${weights.length} entries; the snapshot has ${s.arcCount} arcs`);
+    }
+    const n = s.nodeCount;
+    if (k >= n) {
+        const labels = Uint32Array.from({ length: n }, (_, i) => i);
+        return { ...withGroups(labels, n), eigenvalues: new Float64Array(0), eigenvectors: [], converged: true };
+    }
+    const g = symmetricRows(s, weights);
+    const scale = g.degree.map((d) => (d > 0 ? 1 / Math.sqrt(d) : 0));
+    const normalised = type !== "unnormalized";
+    const apply = (x, out) => {
+        for (let u = 0; u < n; u++) {
+            let ax = 0;
+            for (let a = g.rowPtr[u]; a < g.rowPtr[u + 1]; a++) {
+                const v = g.colIdx[a];
+                ax += normalised ? g.w[a] * scale[v] * x[v] : g.w[a] * x[v];
+            }
+            if (normalised) {
+                out[u] = g.degree[u] > 0 ? x[u] - scale[u] * ax : 0;
+            }
+            else {
+                out[u] = g.degree[u] * x[u] - ax;
+            }
+        }
+    };
+    // The largest eigenvalue is at most 2 for the normalised Laplacian, and at most the largest
+    // d(u) + d(v) over the edges for D - A (Anderson and Morley, 1985).
+    let shift = 2;
+    if (!normalised) {
+        shift = 1;
+        for (let u = 0; u < n; u++) {
+            for (let a = g.rowPtr[u]; a < g.rowPtr[u + 1]; a++) {
+                shift = Math.max(shift, g.degree[u] + g.degree[g.colIdx[a]]);
+            }
+        }
+    }
+    const random = mulberry32(seed);
+    const eig = smallestEigenpairs(apply, n, k, shift, random);
+    if (type === "randomWalk") {
+        for (const v of eig.vectors) {
+            for (let i = 0; i < n; i++) {
+                v[i] *= g.degree[i] > 0 ? scale[i] : 1;
+            }
+        }
+    }
+    const points = new Float64Array(n * k);
+    for (let c = 0; c < k; c++) {
+        for (let i = 0; i < n; i++) {
+            points[i * k + c] = eig.vectors[c][i];
+        }
+    }
+    if (type === "normalized") {
+        for (let i = 0; i < n; i++) {
+            const row = points.subarray(i * k, i * k + k);
+            const norm = Math.hypot(...row);
+            if (norm > 0) {
+                row.forEach((x, c) => (row[c] = x / norm));
+            }
+        }
+    }
+    // Ten seeded k-means runs, keeping the tightest (the scikit-learn default): one run from an
+    // unlucky seeding can split a clean cluster.
+    let best = new Uint32Array(n);
+    let bestInertia = Infinity;
+    for (let run = 0; run < K_MEANS_RUNS; run++) {
+        const assign = kMeans(points, n, k, k, maxIterations, tolerance, random);
+        const inertia = inertiaOf(points, assign, n, k, k);
+        if (inertia < bestInertia) {
+            bestInertia = inertia;
+            best = assign;
+        }
+    }
+    const { labels, count } = renumberPartition(best);
+    return {
+        ...withGroups(labels, count),
+        eigenvalues: eig.values,
+        eigenvectors: eig.vectors,
+        converged: eig.converged,
+    };
+}
+//# sourceMappingURL=spectral.js.map