@graphty/algorithms 2.1.1 → 2.2.0

package/src/indexed/min-cut.ts

@@ -0,0 +1,201 @@
+import {
+    type GraphSnapshot,
+    INVALID_INDEX,
+    makeMask,
+    maskSet,
+    type NodeMask,
+    type NumericVector,
+} from "@graphty/graph-format";
+
+import { crossingEdges, edgeCapacities, type MinCutResult } from "./flow.js";
+import { mulberry32 } from "./label-propagation.js";
+import { IndexedMaxHeap } from "./structures/max-heap.js";
+import { IntUnionFind } from "./structures/union-find.js";
+
+/** Options of {@link stoerWagner}. @public */
+export interface StoerWagnerOptions {
+    /** Per-arc weight override, arcCount long; without it the snapshot's weights (1 when unweighted). */
+    readonly weights?: NumericVector | undefined;
+}
+
+/** Options of {@link kargerMinCut}. @public */
+export interface KargerOptions {
+    /** Independent contraction trials; the lightest cut found wins. Default 100. */
+    readonly iterations?: number | undefined;
+    /** Seed of the edge orders; one seed gives one result, bit for bit. Default 42. */
+    readonly randomSeed?: number | undefined;
+    /** Per-arc weight override, arcCount long; without it the snapshot's weights (1 when unweighted). */
+    readonly weights?: NumericVector | undefined;
+}
+
+/**
+ * Global minimum cut by Stoer-Wagner, reading every edge as undirected (a directed snapshot's arcs
+ * count in both directions, so two opposite arcs between one pair add up).
+ *
+ * No graph is contracted (graph-format design 14.2): a representative array and member lists
+ * merge the last two nodes of each phase, and each phase's maximum-adjacency order accumulates the
+ * weights of the ORIGINAL arcs of the merged members in an {@link IndexedMaxHeap}. A phase starts
+ * from the lowest-index remaining representative and takes equal keys lowest index first, and the
+ * first phase with the lightest cut wins, which is the order the legacy implementation uses.
+ * O(n (m + n) log n).
+ * @param s - The snapshot
+ * @param options - The weight override
+ * @returns The cut value, the side holding the last node of the winning phase, and the cut edges;
+ *   with fewer than two nodes the value is 0 and every node is on `side`
+ * @public
+ */
+export function stoerWagner(s: GraphSnapshot, options: StoerWagnerOptions = {}): MinCutResult {
+    const n = s.nodeCount;
+    const capacity = edgeCapacities(s, options.weights);
+    if (n < 2) {
+        return { cutValue: 0, side: makeMask(n, true), cutEdges: new Uint32Array(0) };
+    }
+    // Incident (neighbour, edge) pairs per node, both directions of every edge.
+    const { src, dst } = s.edgeList();
+    const offset = new Uint32Array(n + 1);
+    for (let e = 0; e < s.edgeCount; e++) {
+        offset[src[e] + 1]++;
+        offset[dst[e] + 1]++;
+    }
+    for (let i = 0; i < n; i++) {
+        offset[i + 1] += offset[i];
+    }
+    const fill = offset.slice(0, n);
+    const neighbour = new Uint32Array(offset[n]);
+    const weight = new Float64Array(offset[n]);
+    for (let e = 0; e < s.edgeCount; e++) {
+        neighbour[fill[src[e]]] = dst[e];
+        weight[fill[src[e]]++] = capacity[e];
+        neighbour[fill[dst[e]]] = src[e];
+        weight[fill[dst[e]]++] = capacity[e];
+    }
+
+    const rep = new Uint32Array(n);
+    const next = new Uint32Array(n).fill(INVALID_INDEX); // member lists, one per representative
+    const tail = new Uint32Array(n);
+    for (let i = 0; i < n; i++) {
+        rep[i] = i;
+        tail[i] = i;
+    }
+    const connection = new Float64Array(n);
+    const added = new Uint8Array(n);
+    const heap = new IndexedMaxHeap(n);
+    let best = Infinity;
+    let bestSide: NodeMask = makeMask(n);
+
+    for (let active = n; active > 1; active--) {
+        let start = INVALID_INDEX;
+        for (let i = 0; i < n; i++) {
+            if (rep[i] !== i) {
+                continue;
+            }
+            added[i] = 0;
+            connection[i] = 0;
+            if (start === INVALID_INDEX) {
+                start = i;
+            } else {
+                heap.push(i, 0);
+            }
+        }
+        let prev = INVALID_INDEX;
+        let last = start;
+        for (;;) {
+            added[last] = 1;
+            for (let m = last; m !== INVALID_INDEX; m = next[m]) {
+                for (let k = offset[m]; k < offset[m + 1]; k++) {
+                    const x = rep[neighbour[k]];
+                    if (added[x] === 0) {
+                        connection[x] += weight[k];
+                        heap.pushOrIncrease(x, connection[x]);
+                    }
+                }
+            }
+            if (heap.isEmpty()) {
+                break;
+            }
+            prev = last;
+            last = heap.pop();
+        }
+        if (connection[last] < best) {
+            best = connection[last];
+            bestSide = makeMask(n);
+            for (let m = last; m !== INVALID_INDEX; m = next[m]) {
+                maskSet(bestSide, m, true);
+            }
+        }
+        // Merge the last node of the phase into the one before it.
+        for (let m = last; m !== INVALID_INDEX; m = next[m]) {
+            rep[m] = prev;
+        }
+        next[tail[prev]] = last;
+        tail[prev] = tail[last];
+    }
+    return { cutValue: best, side: bestSide, cutEdges: crossingEdges(s, bestSide, false, capacity, false) };
+}
+
+/**
+ * Global minimum cut by Karger's randomised contraction, reading every edge as undirected. Each
+ * trial unions the endpoints of the edges in a seeded random order (an {@link IntUnionFind}, no
+ * graph is contracted) until two groups remain, so every edge is equally likely to be contracted
+ * next whatever its weight; the trial's cut is the weight of the edges between the two groups.
+ * A graph with more than two components gives a cut of 0 with node 0's component on `side`.
+ * O(m alpha(n)) per trial.
+ * @param s - The snapshot
+ * @param options - Trials, seed and weight override
+ * @returns The lightest cut found; with fewer than two nodes the value is 0 and `side` is empty
+ * @throws RangeError when `randomSeed` is not an integer or `iterations` is not a positive integer
+ * @public
+ */
+export function kargerMinCut(s: GraphSnapshot, options: KargerOptions = {}): MinCutResult {
+    const iterations = options.iterations ?? 100;
+    const randomSeed = options.randomSeed ?? 42;
+    if (!Number.isInteger(iterations) || iterations < 1) {
+        throw new RangeError(`iterations must be a positive integer, got ${iterations}`);
+    }
+    if (!Number.isInteger(randomSeed)) {
+        throw new RangeError(`randomSeed must be a finite integer, got ${randomSeed}`);
+    }
+    const n = s.nodeCount;
+    const capacity = edgeCapacities(s, options.weights);
+    if (n < 2) {
+        return { cutValue: 0, side: makeMask(n), cutEdges: new Uint32Array(0) };
+    }
+    const { src, dst } = s.edgeList();
+    const rand = mulberry32(randomSeed);
+    const order = new Uint32Array(s.edgeCount);
+    let best = Infinity;
+    let bestSide: NodeMask = makeMask(n);
+    for (let trial = 0; trial < iterations; trial++) {
+        for (let e = 0; e < order.length; e++) {
+            order[e] = e;
+        }
+        for (let i = order.length - 1; i > 0; i--) {
+            const j = Math.floor(rand() * (i + 1));
+            const t = order[i];
+            order[i] = order[j];
+            order[j] = t;
+        }
+        const uf = new IntUnionFind(n);
+        let groups = n;
+        for (let i = 0; i < order.length && groups > 2; i++) {
+            if (uf.union(src[order[i]], dst[order[i]])) {
+                groups--;
+            }
+        }
+        const root = uf.find(0);
+        let cut = 0;
+        for (let e = 0; e < s.edgeCount; e++) {
+            if ((uf.find(src[e]) === root) !== (uf.find(dst[e]) === root)) {
+                cut += capacity[e];
+            }
+        }
+        if (cut < best) {
+            best = cut;
+            bestSide = makeMask(n);
+            for (let v = 0; v < n; v++) {
+                maskSet(bestSide, v, uf.find(v) === root);
+            }
+        }
+    }
+    return { cutValue: best, side: bestSide, cutEdges: crossingEdges(s, bestSide, false, capacity, false) };
+}

package/src/indexed/modularity.ts

@@ -0,0 +1,81 @@
+import { type AdjacencyView, INVALID_INDEX, type NumericVector, type U32 } from "@graphty/graph-format";
+
+/** Options of the index-based modularity. @public */
+export interface ModularityOptions {
+    /** Resolution gamma: above 1 favours smaller communities; default 1. */
+    readonly resolution?: number | undefined;
+    /** Per-arc weight override, arcCount long -- the facade passes `expandEdges(s, shadow.data)`. */
+    readonly weights?: NumericVector | undefined;
+}
+
+/**
+ * Newman's modularity of a partition: `sum_c in_c / 2m - gamma * (tot_c / 2m)^2`, where `2m` is
+ * twice the total edge weight, `in_c` counts every edge inside community c twice and `tot_c` sums
+ * its nodes' weighted degrees. Degrees follow graph-format's `weightedDegree()` convention -- a
+ * self-loop counts twice -- so `sum(tot_c) === 2m`. On a directed snapshot the direction is
+ * ignored: every arc counts as an undirected edge, and a node's degree is its in-weight plus its
+ * out-weight.
+ *
+ * On an undirected snapshot without self-loops this equals the legacy `calculateModularity`. On
+ * a directed snapshot or one with self-loops the two differ, and this one is the NetworkX value:
+ * the legacy degree counts a self-loop once and reads only out-neighbours on a directed graph, so
+ * its degrees do not sum to 2m.
+ *
+ * It is NOT the legacy `calculateMCLModularity`, in two ways. That function subtracts the null-model
+ * term `d(u) d(v) / 2m` once per edge whatever the partition: on two separate triangles it scores
+ * one community and the two triangles both 1/3, where this returns 0 and 1/2. And it ignores edge
+ * weights, where this reads the snapshot's weights by default; pass `weights` filled with 1 for
+ * the unweighted value.
+ * @param s - Any snapshot or adjacency view
+ * @param labels - Community of every node; `INVALID_INDEX` leaves a node out of every community
+ * @param options - Resolution and the weight override
+ * @returns The modularity, 0 when the snapshot has no edge weight
+ * @public
+ */
+export function modularity(s: AdjacencyView, labels: U32, options: ModularityOptions = {}): number {
+    const resolution = options.resolution ?? 1;
+    const weights = options.weights ?? s.weights;
+    if (labels.length !== s.nodeCount) {
+        throw new RangeError(`labels has ${labels.length} entries; the snapshot has ${s.nodeCount} nodes`);
+    }
+    if (weights !== null && weights.length !== s.arcCount) {
+        throw new RangeError(`weights has ${weights.length} entries; the snapshot has ${s.arcCount} arcs`);
+    }
+    const tot = new Map<number, number>();
+    const inside = new Map<number, number>();
+    const addTo = (map: Map<number, number>, label: number, w: number): void => {
+        if (label !== INVALID_INDEX) {
+            map.set(label, (map.get(label) ?? 0) + w);
+        }
+    };
+    let m2 = 0;
+    for (let u = 0; u < s.nodeCount; u++) {
+        const end = s.rowPtr[u + 1];
+        for (let a = s.rowPtr[u]; a < end; a++) {
+            const v = s.colIdx[a];
+            const w = weights === null ? 1 : weights[a];
+            // An undirected edge between two nodes is read from both rows; a self-loop and a
+            // directed arc only once, so they count double here.
+            const twice = s.directed || v === u ? 2 * w : w;
+            m2 += twice;
+            if (s.directed) {
+                addTo(tot, labels[u], w);
+                addTo(tot, labels[v], w);
+            } else {
+                addTo(tot, labels[u], twice);
+            }
+            if (labels[u] === labels[v]) {
+                addTo(inside, labels[u], twice);
+            }
+        }
+    }
+    if (m2 === 0) {
+        return 0;
+    }
+    let q = 0;
+    for (const [label, degrees] of tot) {
+        const share = degrees / m2;
+        q += (inside.get(label) ?? 0) / m2 - resolution * share * share;
+    }
+    return q;
+}

package/src/indexed/mst.ts

@@ -1,5 +1,6 @@
-import type { GraphSnapshot, NumericVector, U32 } from "@graphty/graph-format";
+import { type GraphSnapshot, INVALID_INDEX, type NumericVector, type U32 } from "@graphty/graph-format";
 
+import { IndexedMinHeap } from "./structures/min-heap.js";
 import { IntUnionFind } from "./structures/union-find.js";
 
 /** Options of the index-based MST. @public */
@@ -60,3 +61,80 @@ export function kruskalMST(s: GraphSnapshot, o: MstOptions = {}): MstResult {
     }
     return { edges: accepted.subarray(0, taken), totalWeight };
 }
+
+/** Options of the index-based Prim. @public */
+export interface PrimOptions extends MstOptions {
+    /** The node index the (first) tree grows from; default 0. */
+    readonly start?: number | undefined;
+    /**
+     * Grow a tree in every component, rooted at `start` and then at each component's lowest node
+     * index, instead of throwing on a disconnected graph. Default false, as legacy `primMST`.
+     */
+    readonly forest?: boolean | undefined;
+}
+
+/** Result of the index-based Prim: the MST result plus each node's discovery arc. @public */
+export interface PrimResult extends MstResult {
+    /** The tree arc that reached each node, pointing at it; INVALID_INDEX for every root. */
+    readonly predArc: U32;
+}
+
+/**
+ * Prim's minimum spanning tree, grown from a start node by always taking the cheapest arc from the
+ * tree to a node outside it (an indexed heap keyed per node, so of several parallel edges the
+ * cheapest, and of equal ones the lowest-indexed, is the one taken). `edges` lists the logical
+ * edges in the order they joined the tree and `totalWeight` sums them in that order, as legacy
+ * `primMST` does. The start index is checked: one outside the graph throws a RangeError.
+ * @param s - An undirected snapshot
+ * @param o - Per-arc weight override, start node and the spanning-forest switch
+ * @returns The accepted edges, their total weight and the discovery arc per node
+ * @throws Error on a directed snapshot, and on a disconnected one unless `forest` is set
+ * @public
+ */
+export function primMST(s: GraphSnapshot, o: PrimOptions = {}): PrimResult {
+    if (s.directed) {
+        throw new Error("Prim's algorithm requires an undirected graph");
+    }
+    const { nodeCount: n, rowPtr, colIdx } = s;
+    const weights: NumericVector | null = o.weights ?? s.weights;
+    const key = new Float64Array(n).fill(Infinity);
+    const predArc = new Uint32Array(n).fill(INVALID_INDEX);
+    const inTree = new Uint8Array(n);
+    const heap = new IndexedMinHeap(n);
+    const accepted = new Uint32Array(Math.max(n - 1, 0));
+    let taken = 0;
+    let totalWeight = 0;
+    const grow = (root: number): void => {
+        heap.push(root, 0);
+        while (!heap.isEmpty()) {
+            const u = heap.pop();
+            inTree[u] = 1;
+            if (predArc[u] !== INVALID_INDEX) {
+                accepted[taken++] = s.arcToEdge[predArc[u]];
+                totalWeight += key[u];
+            }
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                const v = colIdx[a];
+                const w = weights === null ? 1 : weights[a];
+                if (inTree[v] === 0 && w < key[v]) {
+                    key[v] = w;
+                    predArc[v] = a;
+                    heap.pushOrDecrease(v, w);
+                }
+            }
+        }
+    };
+    if (n > 0) {
+        grow(o.start ?? 0);
+    }
+    if (o.forest === true) {
+        for (let root = 0; root < n; root++) {
+            if (inTree[root] === 0) {
+                grow(root);
+            }
+        }
+    } else if (taken < n - 1) {
+        throw new Error("Graph is not connected");
+    }
+    return { edges: accepted.subarray(0, taken), totalWeight, predArc };
+}

package/src/indexed/pagerank.ts

@@ -1,15 +1,22 @@
-import type { F64, GraphSnapshot, NumericVector } from "@graphty/graph-format";
+import type { F32, F64, GraphSnapshot, NumericVector } from "@graphty/graph-format";
 
-/** Options of the index-based PageRank (graph-format design 14.2 Port 3, line 3892). @public */
+/** Options of the index-based PageRank (graph-format design 14.2 Port 3). @public */
 export interface PageRankOptions {
     /** Probability of following a link; default 0.85. */
     readonly dampingFactor?: number | undefined;
     /** Iteration cap; default 100. */
     readonly maxIterations?: number | undefined;
-    /** L1 convergence tolerance; default 1e-6. */
+    /** Convergence tolerance on the per-iteration change; default 1e-6. */
     readonly tolerance?: number | undefined;
     /** Use the snapshot's arc weights; default false. */
     readonly weighted?: boolean | undefined;
+    /** Starting rank per node index, normalised to sum 1 (when the sum is positive); default uniform. */
+    readonly initialRanks?: F32 | F64 | undefined;
+    /**
+     * How the per-iteration change is measured against `tolerance`: `"l1"` (default) sums it over
+     * all nodes, `"max"` takes the largest single-node change, the legacy `pageRank` rule.
+     */
+    readonly convergenceNorm?: "l1" | "max" | undefined;
 }
 
 /** Result of the index-based PageRank. @public */
@@ -18,29 +25,74 @@ export interface PageRankResult {
     readonly scores: F64;
     /** Iterations actually run. */
     readonly iterations: number;
-    /** Whether the L1 delta fell below the tolerance. */
+    /** Whether the change fell below the tolerance. */
     readonly converged: boolean;
 }
 
 /**
- * PageRank by pull over `reverse()`, with the dangling mass redistributed uniformly.
- * @param s - A DIRECTED snapshot
+ * PageRank by pull over `reverse()`, with the dangling mass redistributed uniformly. On an
+ * undirected snapshot every edge carries rank both ways (a self-loop once), which is PageRank on
+ * the directed graph holding both arcs of every edge.
+ * @param s - The snapshot
  * @param o - Algorithm options
  * @returns The scores, the iteration count and the convergence flag
  * @public
  */
 export function pageRank(s: GraphSnapshot, o: PageRankOptions = {}): PageRankResult {
-    if (!s.directed) {
-        throw new Error("PageRank requires a directed graph");
-    }
+    return run(s, null, o);
+}
+
+/**
+ * Personalized PageRank, as the legacy function computes it: the personalization vector,
+ * normalised to sum 1, replaces the uniform `1 / n` in the teleport, and each node receives
+ * `d * dangling / n` of the dangling mass scaled by its personalization. That keeps only a
+ * `1 / n` share of the dangling mass, so on a graph with a dangling node the scores sum to less
+ * than 1 (networkx spreads all of it). An all-zero vector gives plain PageRank, as the legacy
+ * function does for an empty list of personal nodes.
+ * @param s - The snapshot
+ * @param personalization - One finite, non-negative mass per node index
+ * @param o - Algorithm options
+ * @returns The scores, the iteration count and the convergence flag
+ * @public
+ */
+export function personalizedPageRank(
+    s: GraphSnapshot,
+    personalization: F32 | F64,
+    o: PageRankOptions = {},
+): PageRankResult {
+    return run(s, distribution(personalization, s.nodeCount, "personalization"), o);
+}
+
+/**
+ * The shared power iteration.
+ * @param s - The snapshot
+ * @param p - The normalised personalization, or null for the uniform teleport
+ * @param o - Algorithm options
+ * @returns The scores, the iteration count and the convergence flag
+ */
+function run(s: GraphSnapshot, p: F64 | null, o: PageRankOptions): PageRankResult {
     const n = s.nodeCount;
     const d = o.dampingFactor ?? 0.85;
     const maxIter = o.maxIterations ?? 100;
     const tol = o.tolerance ?? 1e-6;
+    const useMax = o.convergenceNorm === "max";
+    if (n === 0) {
+        return { scores: new Float64Array(0), iterations: 0, converged: true };
+    }
     const rev = s.reverse();
     const weighted = o.weighted === true && rev.weights !== null;
-    const outW: NumericVector = weighted ? s.weightedOutDegree() : s.outDegree();
-    let rank = new Float64Array(n).fill(1 / n);
+    // The f64 shadow toSnapshot keeps when a weight is not f32-exact, else the f32 arc weights.
+    const shadow = weighted ? s.edges.byRole("weight") : null;
+    const exact = shadow?.dtype === "f64" ? shadow.data : null;
+    let revW: NumericVector | null = weighted ? rev.weights : null;
+    let outW: NumericVector = weighted ? s.weightedOutDegree() : s.outDegree();
+    if (exact !== null) {
+        revW = gather(exact, rev.arcToEdge);
+        outW = rowSums(s, gather(exact, s.arcToEdge));
+    }
+    let rank =
+        (o.initialRanks === undefined ? null : distribution(o.initialRanks, n, "initialRanks")) ??
+        new Float64Array(n).fill(o.initialRanks === undefined ? 1 / n : 0);
     let next = new Float64Array(n);
     let it = 0;
     let converged = false;
@@ -51,7 +103,9 @@ export function pageRank(s: GraphSnapshot, o: PageRankOptions = {}): PageRankRes
                 dangling += rank[u];
             }
         }
-        const base = (1 - d) / n + (d * dangling) / n;
+        // Teleport (1 - d) spread by p or uniformly; the dangling mass d * dangling spread uniformly,
+        // and with p scaled by p[v] on top of the uniform 1 / n, as the legacy function does.
+        const spread = 1 - d + d * dangling * (p === null ? 1 : 1 / n);
         let delta = 0;
         for (let v = 0; v < n; v++) {
             let acc = 0;
@@ -60,14 +114,73 @@ export function pageRank(s: GraphSnapshot, o: PageRankOptions = {}): PageRankRes
                 const u = rev.colIdx[a];
                 const ow = outW[u];
                 if (ow > 0) {
-                    acc += (rank[u] * (weighted && rev.weights !== null ? rev.weights[a] : 1)) / ow;
+                    acc += (rank[u] * (revW === null ? 1 : revW[a])) / ow;
                 }
             }
-            next[v] = base + d * acc;
-            delta += Math.abs(next[v] - rank[v]);
+            next[v] = spread * (p === null ? 1 / n : p[v]) + d * acc;
+            const change = Math.abs(next[v] - rank[v]);
+            delta = useMax ? Math.max(delta, change) : delta + change;
         }
         [rank, next] = [next, rank];
         converged = delta < tol;
     }
     return { scores: rank, iterations: it, converged };
 }
+
+/**
+ * One value per arc, read through the arc's logical edge.
+ * @param perEdge - One value per logical edge
+ * @param arcToEdge - The logical edge of every arc
+ * @returns One value per arc
+ */
+function gather(perEdge: F64, arcToEdge: Uint32Array): F64 {
+    const out = new Float64Array(arcToEdge.length);
+    for (let a = 0; a < out.length; a++) {
+        out[a] = perEdge[arcToEdge[a]];
+    }
+    return out;
+}
+
+/**
+ * The sum of each node's out-arc values.
+ * @param s - The snapshot
+ * @param perArc - One value per forward arc
+ * @returns One sum per node
+ */
+function rowSums(s: GraphSnapshot, perArc: F64): F64 {
+    const out = new Float64Array(s.nodeCount);
+    for (let u = 0; u < s.nodeCount; u++) {
+        for (let a = s.rowPtr[u]; a < s.rowPtr[u + 1]; a++) {
+            out[u] += perArc[a];
+        }
+    }
+    return out;
+}
+
+/**
+ * Check a per-node mass vector and normalise it to sum 1.
+ * @param v - The caller's vector
+ * @param n - The node count
+ * @param name - The option's name, for the message
+ * @returns A normalised copy, or null when every entry is 0
+ */
+function distribution(v: F32 | F64, n: number, name: string): F64 | null {
+    if (v.length !== n) {
+        throw new Error(`PageRank: ${name} has ${String(v.length)} entries for ${String(n)} nodes`);
+    }
+    let total = 0;
+    for (const mass of v) {
+        if (!Number.isFinite(mass) || mass < 0) {
+            throw new Error(`PageRank: ${name} must be finite and non-negative, got ${String(mass)}`);
+        }
+        total += mass;
+    }
+    if (total === 0) {
+        return null;
+    }
+    const out = new Float64Array(n);
+    for (let u = 0; u < n; u++) {
+        out[u] = v[u] / total;
+    }
+    return out;
+}