@graphty/algorithms 2.1.2 → 2.2.0

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

@@ -0,0 +1,120 @@
+import { type GraphSnapshot, type NodeId, type NodeMask, type NumericVector, type U32 } from "@graphty/graph-format";
+/** Options of {@link maxFlow} and {@link minSTCut}. @public */
+export interface MaxFlowOptions {
+    /**
+     * How augmenting paths are found: `"edmonds-karp"` (breadth-first, shortest paths first,
+     * O(V E^2)) or `"ford-fulkerson"` (depth-first, O(E f)). Default `"edmonds-karp"` for
+     * {@link maxFlow} and `"ford-fulkerson"` for {@link minSTCut}. Both give the same source side
+     * and the same flow value up to floating-point rounding; the per-edge flows can differ where
+     * the maximum flow is not unique.
+     */
+    readonly algorithm?: "edmonds-karp" | "ford-fulkerson" | undefined;
+    /**
+     * Per-arc capacity override, arcCount long -- the facade passes `expandEdges(s, shadow.data)`
+     * for exact f64 capacities. Without it the snapshot's arc weights are the capacities, and an
+     * unweighted snapshot gives every edge capacity 1.
+     */
+    readonly weights?: NumericVector | undefined;
+}
+/** Result of {@link maxFlow}. @public */
+export interface MaxFlowResult {
+    /** The value of the maximum flow. */
+    readonly maxFlow: number;
+    /**
+     * Net flow per logical edge in its declared orientation. On an undirected snapshot a negative
+     * value is flow from the declared target to the declared source.
+     */
+    readonly flow: Float64Array;
+    /** The nodes reachable from the source in the final residual graph: the source side of a minimum cut. */
+    readonly sourceSide: NodeMask;
+    /**
+     * Logical edges with positive capacity that cross the cut, in edge order: from the source side
+     * to the other on a directed snapshot, with exactly one endpoint on the source side on an
+     * undirected one.
+     */
+    readonly cutEdges: U32;
+}
+/** Result of the index-based minimum cuts ({@link minSTCut}, `stoerWagner`, `kargerMinCut`). @public */
+export interface MinCutResult {
+    /** The total weight of the cut. */
+    readonly cutValue: number;
+    /** One side of the cut; every other node is on the other side. */
+    readonly side: NodeMask;
+    /** Logical edges with one endpoint on each side, in edge order. */
+    readonly cutEdges: U32;
+}
+/**
+ * The capacity of every logical edge: the override's value at the edge's declared arc, else the
+ * snapshot's per-edge weight, else 1.
+ * @param s - The snapshot
+ * @param weights - The optional per-arc override
+ * @returns One capacity per logical edge
+ */
+export declare function edgeCapacities(s: GraphSnapshot, weights: NumericVector | undefined): Float64Array;
+/**
+ * The logical edges whose endpoints lie on different sides of `side` -- leaving it, when
+ * `directed` -- with positive capacity when `positiveOnly` is set.
+ * @param s - The snapshot
+ * @param side - One side of the cut
+ * @param directed - Whether only edges from `side` to the other side count
+ * @param capacity - Per-edge capacities, consulted only with `positiveOnly`
+ * @param positiveOnly - Whether to leave out edges of capacity zero or less
+ * @returns Edge indices in edge order
+ */
+export declare function crossingEdges(s: GraphSnapshot, side: NodeMask, directed: boolean, capacity: Float64Array, positiveOnly: boolean): U32;
+/**
+ * Maximum flow from `source` to `sink` by augmenting paths.
+ *
+ * Paths, bottlenecks and per-edge flows equal the legacy `edmondsKarp` / `fordFulkerson` on a
+ * graph with no parallel edges and no two opposite directed edges: the residual is kept per node
+ * pair and searched in the legacy row order (see {@link buildResidual}). Where two opposite
+ * directed edges carry flow, legacy records every push on the edge in the push's direction, so
+ * one edge can show more flow than its capacity; this port reports the net flow of the pair on
+ * the edges in its direction instead, each within its capacity.
+ * @param s - The snapshot
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param options - The path search and the capacity override
+ * @returns The flow value, the per-edge flows, the source side and the cut edges
+ * @throws RangeError when `source` or `sink` is not a node index, or they are the same node
+ * @public
+ */
+export declare function maxFlow(s: GraphSnapshot, source: number, sink: number, options?: MaxFlowOptions): MaxFlowResult;
+/**
+ * Minimum s-t cut: the source side and value of a maximum flow (max-flow min-cut theorem). The
+ * side is the set reachable from the source in the final residual graph, which is the same for
+ * every maximum flow, so the path search does not change it. The search defaults to
+ * `"ford-fulkerson"`, as the legacy `minSTCut` uses: on weights that are not binary fractions
+ * another search adds the bottlenecks in another order and the value can differ in its last bits.
+ * @param s - The snapshot
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param options - The path search and the capacity override
+ * @returns The cut value, the source side and the cut edges
+ * @throws RangeError as {@link maxFlow} does
+ * @public
+ */
+export declare function minSTCut(s: GraphSnapshot, source: number, sink: number, options?: MaxFlowOptions): MinCutResult;
+/** Result of {@link bipartiteFlowNetwork}. @public */
+export interface BipartiteFlowNetwork {
+    /** The directed, unit-capacity (unweighted) flow network. */
+    readonly snapshot: GraphSnapshot;
+    /** The index of the added source node, id `"__source__"`. */
+    readonly source: number;
+    /** The index of the added sink node, id `"__sink__"`. */
+    readonly sink: number;
+}
+/**
+ * The unit-capacity flow network whose maximum flow is a maximum bipartite matching: a source with
+ * an edge to every left node, every given left-right edge, and an edge from every right node to a
+ * sink. Nodes are numbered source, left nodes, left endpoints of `edges` not already listed, right
+ * nodes, right endpoints not already listed, sink; a repeated edge is kept once.
+ * @param left - The left side's node ids
+ * @param right - The right side's node ids
+ * @param edges - Left-to-right edges as `[left id, right id]`
+ * @returns The network and the indices of its source and sink
+ * @throws RangeError when a given id is `"__source__"` or `"__sink__"`
+ * @public
+ */
+export declare function bipartiteFlowNetwork(left: readonly NodeId[], right: readonly NodeId[], edges: readonly (readonly [NodeId, NodeId])[]): BipartiteFlowNetwork;
+//# sourceMappingURL=flow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../../src/indexed/flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,aAAa,EAKlB,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,GAAG,EACX,MAAM,uBAAuB,CAAC;AAE/B,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACnE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAChD;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,yGAAyG;IACzG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC;CAC1B;AAED,wGAAwG;AACxG,MAAM,WAAW,YAAY;IACzB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,YAAY,CAOjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CACzB,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,OAAO,GACtB,GAAG,CAWL;AAkGD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CAgDnH;AAqDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,YAAY,CAGnH;AA6GD,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,GAC9C,oBAAoB,CAwBtB"}

package/dist/src/indexed/flow.js

@@ -0,0 +1,377 @@
+import { fromEdgeArrays, GraphBuilder, INVALID_INDEX, makeMask, maskSet, maskTest, } from "@graphty/graph-format";
+/**
+ * The capacity of every logical edge: the override's value at the edge's declared arc, else the
+ * snapshot's per-edge weight, else 1.
+ * @param s - The snapshot
+ * @param weights - The optional per-arc override
+ * @returns One capacity per logical edge
+ */
+export function edgeCapacities(s, weights) {
+    const el = s.edgeList();
+    const out = new Float64Array(s.edgeCount);
+    for (let e = 0; e < s.edgeCount; e++) {
+        out[e] = weights !== undefined ? weights[el.arc[e]] : (el.weights?.[e] ?? 1);
+    }
+    return out;
+}
+/**
+ * The logical edges whose endpoints lie on different sides of `side` -- leaving it, when
+ * `directed` -- with positive capacity when `positiveOnly` is set.
+ * @param s - The snapshot
+ * @param side - One side of the cut
+ * @param directed - Whether only edges from `side` to the other side count
+ * @param capacity - Per-edge capacities, consulted only with `positiveOnly`
+ * @param positiveOnly - Whether to leave out edges of capacity zero or less
+ * @returns Edge indices in edge order
+ */
+export function crossingEdges(s, side, directed, capacity, positiveOnly) {
+    const { src, dst } = s.edgeList();
+    const out = [];
+    for (let e = 0; e < s.edgeCount; e++) {
+        const inSrc = maskTest(side, src[e]);
+        const crosses = directed ? inSrc && !maskTest(side, dst[e]) : inSrc !== maskTest(side, dst[e]);
+        if (crosses && (!positiveOnly || capacity[e] > 0)) {
+            out.push(e);
+        }
+    }
+    return Uint32Array.from(out);
+}
+/**
+ * Build the pair-keyed residual graph of `s`. The visiting order starts as the legacy
+ * `graphToMap` row order -- each neighbour at the first edge that joins it -- and a group with no
+ * real arc is appended to its row when flow first reaches it, where the legacy residual Map
+ * inserts the key.
+ * @param s - The snapshot
+ * @param capacity - Per-edge capacities
+ * @returns The residual graph
+ */
+function buildResidual(s, capacity) {
+    const n = s.nodeCount;
+    const E = s.edgeCount;
+    const { src, dst } = s.edgeList();
+    const rSrc = new Uint32Array(2 * E);
+    const rDst = new Uint32Array(2 * E);
+    rSrc.set(src);
+    rSrc.set(dst, E);
+    rDst.set(dst);
+    rDst.set(src, E);
+    const r = fromEdgeArrays({ directed: true, nodeCount: n, src: rSrc, dst: rDst });
+    const { rowPtr, colIdx, arcToEdge, edgeToArc } = r;
+    const A = r.arcCount;
+    const residual = new Float64Array(A);
+    const groupOf = new Uint32Array(A);
+    const real = new Uint8Array(A);
+    for (let u = 0; u < n; u++) {
+        for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+            const g = a > rowPtr[u] && colIdx[a] === colIdx[a - 1] ? groupOf[a - 1] : a;
+            groupOf[a] = g;
+            const re = arcToEdge[a];
+            if (re < E || !s.directed) {
+                real[g] = 1;
+                residual[g] += Math.max(capacity[re < E ? re : re - E], 0);
+            }
+        }
+    }
+    const twin = new Uint32Array(A);
+    for (let a = 0; a < A; a++) {
+        if (groupOf[a] === a) {
+            const re = arcToEdge[a];
+            twin[a] = groupOf[edgeToArc[re < E ? re + E : re - E]];
+        }
+    }
+    const order = new Uint32Array(A);
+    const placed = new Uint32Array(n);
+    const inOrder = new Uint8Array(A);
+    const place = (u, g) => {
+        if (inOrder[g] === 0) {
+            inOrder[g] = 1;
+            order[rowPtr[u] + placed[u]++] = g;
+        }
+    };
+    for (let e = 0; e < E; e++) {
+        place(src[e], groupOf[edgeToArc[e]]);
+        if (!s.directed) {
+            place(dst[e], groupOf[edgeToArc[e + E]]);
+        }
+    }
+    return { rowPtr, colIdx, arcToEdge, capacity: residual, groupOf, twin, order, placed, inOrder, real };
+}
+/**
+ * Maximum flow from `source` to `sink` by augmenting paths.
+ *
+ * Paths, bottlenecks and per-edge flows equal the legacy `edmondsKarp` / `fordFulkerson` on a
+ * graph with no parallel edges and no two opposite directed edges: the residual is kept per node
+ * pair and searched in the legacy row order (see {@link buildResidual}). Where two opposite
+ * directed edges carry flow, legacy records every push on the edge in the push's direction, so
+ * one edge can show more flow than its capacity; this port reports the net flow of the pair on
+ * the edges in its direction instead, each within its capacity.
+ * @param s - The snapshot
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param options - The path search and the capacity override
+ * @returns The flow value, the per-edge flows, the source side and the cut edges
+ * @throws RangeError when `source` or `sink` is not a node index, or they are the same node
+ * @public
+ */
+export function maxFlow(s, source, sink, options = {}) {
+    const n = s.nodeCount;
+    if (!(Number.isInteger(source) && source >= 0 && source < n && Number.isInteger(sink) && sink >= 0 && sink < n)) {
+        throw new RangeError(`source ${String(source)} and sink ${String(sink)} must be node indices below ${n}`);
+    }
+    if (source === sink) {
+        throw new RangeError(`source and sink are the same node (${source})`);
+    }
+    const capacity = edgeCapacities(s, options.weights);
+    const r = buildResidual(s, capacity);
+    const { colIdx, twin } = r;
+    // Flow pushed per real group, accumulated as the legacy flow Map accumulates it: a push along
+    // a pair with a real arc adds to that pair, a push along a reverse-only pair subtracts from
+    // the opposite one.
+    const pushed = new Float64Array(colIdx.length);
+    const predGroup = new Uint32Array(n);
+    const findPath = options.algorithm === "ford-fulkerson" ? depthFirstPath : breadthFirstPath;
+    let total = 0;
+    while (findPath(r, source, sink, predGroup)) {
+        let bottleneck = Infinity;
+        for (let v = sink; v !== source; v = colIdx[twin[predGroup[v]]]) {
+            bottleneck = Math.min(bottleneck, r.capacity[predGroup[v]]);
+        }
+        for (let v = sink; v !== source;) {
+            const g = predGroup[v];
+            const t = twin[g];
+            r.capacity[g] -= bottleneck;
+            r.capacity[t] += bottleneck;
+            if (r.inOrder[t] === 0) {
+                r.inOrder[t] = 1;
+                r.order[r.rowPtr[v] + r.placed[v]++] = t;
+            }
+            if (r.real[g] === 1) {
+                pushed[g] += bottleneck;
+            }
+            else {
+                pushed[t] -= bottleneck;
+            }
+            v = colIdx[t];
+        }
+        total += bottleneck;
+    }
+    const sourceSide = reachable(r, source);
+    return {
+        maxFlow: total,
+        flow: edgeFlows(s, r, capacity, pushed),
+        sourceSide,
+        cutEdges: crossingEdges(s, sourceSide, s.directed, capacity, true),
+    };
+}
+/**
+ * Spread each pair's net flow over its logical edges: all of it on the pair's only edge in the
+ * flow's direction, and in arc order up to capacity where there are several (the last one takes
+ * the remainder, so rounding never drops flow).
+ * @param s - The snapshot
+ * @param r - The residual graph after the last augmentation
+ * @param capacity - Per-edge capacities
+ * @param pushed - Flow pushed per real group
+ * @returns Net flow per logical edge in its declared orientation
+ */
+function edgeFlows(s, r, capacity, pushed) {
+    const E = s.edgeCount;
+    const flow = new Float64Array(E);
+    const { rowPtr, colIdx, arcToEdge, groupOf } = r;
+    for (let u = 0; u < s.nodeCount; u++) {
+        for (let g = rowPtr[u]; g < rowPtr[u + 1]; g++) {
+            const v = colIdx[g];
+            if (groupOf[g] !== g || v <= u) {
+                continue;
+            }
+            const net = pushed[g] - pushed[r.twin[g]];
+            if (net === 0) {
+                continue;
+            }
+            // Walk the arcs of the group the flow runs along: u to v, or v to u.
+            const along = net > 0 ? g : r.twin[g];
+            const end = rowPtr[colIdx[r.twin[along]] + 1];
+            let remaining = Math.abs(net);
+            let lastEdge = -1;
+            let lastSign = 1;
+            for (let a = along; a < end && groupOf[a] === along; a++) {
+                const re = arcToEdge[a];
+                if (re >= E && s.directed) {
+                    continue; // a reverse arc carries no edge
+                }
+                if (lastEdge >= 0) {
+                    const x = Math.min(remaining, Math.max(capacity[lastEdge], 0));
+                    flow[lastEdge] += lastSign * x;
+                    remaining -= x;
+                }
+                lastEdge = re < E ? re : re - E;
+                lastSign = re < E ? 1 : -1;
+            }
+            if (lastEdge >= 0) {
+                flow[lastEdge] += lastSign * remaining;
+            }
+        }
+    }
+    return flow;
+}
+/**
+ * Minimum s-t cut: the source side and value of a maximum flow (max-flow min-cut theorem). The
+ * side is the set reachable from the source in the final residual graph, which is the same for
+ * every maximum flow, so the path search does not change it. The search defaults to
+ * `"ford-fulkerson"`, as the legacy `minSTCut` uses: on weights that are not binary fractions
+ * another search adds the bottlenecks in another order and the value can differ in its last bits.
+ * @param s - The snapshot
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param options - The path search and the capacity override
+ * @returns The cut value, the source side and the cut edges
+ * @throws RangeError as {@link maxFlow} does
+ * @public
+ */
+export function minSTCut(s, source, sink, options = {}) {
+    const r = maxFlow(s, source, sink, { ...options, algorithm: options.algorithm ?? "ford-fulkerson" });
+    return { cutValue: r.maxFlow, side: r.sourceSide, cutEdges: r.cutEdges };
+}
+/**
+ * Breadth-first search for a source-to-sink path over groups with residual capacity, stopping when
+ * the sink is discovered (its parent is fixed then, as in the legacy search that stops when it
+ * dequeues the sink).
+ * @param r - The residual graph
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param predGroup - Receives the group that discovered each node on the path
+ * @returns Whether the sink was reached
+ */
+function breadthFirstPath(r, source, sink, predGroup) {
+    const { rowPtr, colIdx, order, placed, capacity } = r;
+    predGroup.fill(INVALID_INDEX);
+    const queue = new Uint32Array(predGroup.length);
+    let head = 0;
+    let tail = 0;
+    queue[tail++] = source;
+    while (head < tail) {
+        const u = queue[head++];
+        const end = rowPtr[u] + placed[u];
+        for (let k = rowPtr[u]; k < end; k++) {
+            const g = order[k];
+            const v = colIdx[g];
+            if (capacity[g] > 0 && v !== source && predGroup[v] === INVALID_INDEX) {
+                predGroup[v] = g;
+                if (v === sink) {
+                    return true;
+                }
+                queue[tail++] = v;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Depth-first search for a source-to-sink path over groups with residual capacity, in the order a
+ * recursive search takes: the first group with capacity to an unvisited node is followed to its
+ * end before the next is tried.
+ * @param r - The residual graph
+ * @param source - The source node index
+ * @param sink - The sink node index
+ * @param predGroup - Receives the group that entered each node on the path
+ * @returns Whether the sink was reached
+ */
+function depthFirstPath(r, source, sink, predGroup) {
+    const { rowPtr, colIdx, order, placed, capacity } = r;
+    const n = predGroup.length;
+    predGroup.fill(INVALID_INDEX);
+    const visited = new Uint8Array(n);
+    const stack = new Uint32Array(n);
+    const cursor = new Uint32Array(n);
+    let depth = 0;
+    stack[depth++] = source;
+    visited[source] = 1;
+    cursor[source] = rowPtr[source];
+    while (depth > 0) {
+        const u = stack[depth - 1];
+        const k = cursor[u]++;
+        if (k >= rowPtr[u] + placed[u]) {
+            depth--;
+            continue;
+        }
+        const g = order[k];
+        const v = colIdx[g];
+        if (capacity[g] > 0 && visited[v] === 0) {
+            predGroup[v] = g;
+            if (v === sink) {
+                return true;
+            }
+            visited[v] = 1;
+            cursor[v] = rowPtr[v];
+            stack[depth++] = v;
+        }
+    }
+    return false;
+}
+/**
+ * The nodes reachable from `source` over groups with residual capacity.
+ * @param r - The residual graph
+ * @param source - The source node index
+ * @returns The reachable set as a node mask
+ */
+function reachable(r, source) {
+    const { rowPtr, colIdx, order, placed, capacity } = r;
+    const n = rowPtr.length - 1;
+    const mask = makeMask(n);
+    const queue = new Uint32Array(n);
+    let head = 0;
+    let tail = 0;
+    queue[tail++] = source;
+    maskSet(mask, source, true);
+    while (head < tail) {
+        const u = queue[head++];
+        const end = rowPtr[u] + placed[u];
+        for (let k = rowPtr[u]; k < end; k++) {
+            const v = colIdx[order[k]];
+            if (capacity[order[k]] > 0 && !maskTest(mask, v)) {
+                maskSet(mask, v, true);
+                queue[tail++] = v;
+            }
+        }
+    }
+    return mask;
+}
+const SOURCE_ID = "__source__";
+const SINK_ID = "__sink__";
+/**
+ * The unit-capacity flow network whose maximum flow is a maximum bipartite matching: a source with
+ * an edge to every left node, every given left-right edge, and an edge from every right node to a
+ * sink. Nodes are numbered source, left nodes, left endpoints of `edges` not already listed, right
+ * nodes, right endpoints not already listed, sink; a repeated edge is kept once.
+ * @param left - The left side's node ids
+ * @param right - The right side's node ids
+ * @param edges - Left-to-right edges as `[left id, right id]`
+ * @returns The network and the indices of its source and sink
+ * @throws RangeError when a given id is `"__source__"` or `"__sink__"`
+ * @public
+ */
+export function bipartiteFlowNetwork(left, right, edges) {
+    const b = new GraphBuilder({ directed: true, duplicateEdges: "first" });
+    const add = (id) => {
+        if (id === SOURCE_ID || id === SINK_ID) {
+            throw new RangeError(`node id "${id}" is reserved for the flow network's source or sink`);
+        }
+        return b.addNode(id);
+    };
+    const source = b.addNode(SOURCE_ID);
+    const leftIndex = left.map(add);
+    const edgeLeft = edges.map(([u]) => add(u));
+    const rightIndex = right.map(add);
+    const edgeRight = edges.map(([, v]) => add(v));
+    const sink = b.addNode(SINK_ID);
+    for (const u of leftIndex) {
+        b.addEdgeByIndex(source, u);
+    }
+    for (let e = 0; e < edges.length; e++) {
+        b.addEdgeByIndex(edgeLeft[e], edgeRight[e]);
+    }
+    for (const v of rightIndex) {
+        b.addEdgeByIndex(v, sink);
+    }
+    return { snapshot: b.freeze({ label: "algorithms.bipartiteFlowNetwork" }), source, sink };
+}
+//# sourceMappingURL=flow.js.map

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

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

package/dist/src/indexed/girvan-newman.d.ts

@@ -0,0 +1,42 @@
+import { type F64, type GraphSnapshot, type U32 } from "@graphty/graph-format";
+/** Options of the index-based Girvan-Newman, matching the legacy `girvanNewman`. @public */
+export interface GirvanNewmanOptions {
+    /** Stop once a level has at least this many communities of `minCommunitySize` or more nodes. */
+    readonly maxCommunities?: number | undefined;
+    /** Communities smaller than this do not count towards `maxCommunities`; default 1. */
+    readonly minCommunitySize?: number | undefined;
+    /** Cap on rounds of edge removal; default 100. */
+    readonly maxIterations?: number | undefined;
+}
+/** The Girvan-Newman dendrogram: one partition per level, the uncut graph first. @public */
+export interface GirvanNewmanResult {
+    /** Dense community label per node index at each level, in first-seen order. */
+    readonly levels: U32[];
+    /** Modularity of each level's partition over the original graph. */
+    readonly modularity: F64;
+}
+/**
+ * Girvan-Newman divisive community detection (PNAS 99:7821, 2002) over an undirected snapshot:
+ * repeatedly delete every edge whose betweenness is the maximum (within 1e-10), recording the
+ * connected components after each round as one level of a dendrogram.
+ *
+ * Edges are deleted by clearing bits of an alive mask over logical edges that the edge betweenness
+ * reads, so no graph is rebuilt. Betweenness is unweighted, as in the legacy function; a pair of
+ * nodes joined by parallel edges is one neighbour relation whose share goes to the first alive
+ * parallel, so the parallels are deleted one round at a time. Modularity reads the edge weights,
+ * the exact f64 ones when the snapshot keeps them, with graph-format's `weightedDegree()` rule (a
+ * self-loop counts twice); on a graph without self-loops it equals the legacy function's.
+ *
+ * The run stops when no edge is left, after `maxIterations` rounds, when a level has
+ * `maxCommunities` communities of at least `minCommunitySize` nodes, or when that count reaches
+ * the node count. Every level is returned whole: the legacy function drops communities below
+ * `minCommunitySize` from the lists it returns, which a caller does with `levels[i]` and a size
+ * count.
+ * @param s - An undirected snapshot
+ * @param options - Stopping rules
+ * @returns The levels and their modularity
+ * @throws Error on a directed snapshot
+ * @public
+ */
+export declare function girvanNewman(s: GraphSnapshot, options?: GirvanNewmanOptions): GirvanNewmanResult;
+//# sourceMappingURL=girvan-newman.d.ts.map

package/dist/src/indexed/girvan-newman.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"girvan-newman.d.ts","sourceRoot":"","sources":["../../../src/indexed/girvan-newman.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,GAAG,EACR,KAAK,aAAa,EAKlB,KAAK,GAAG,EACX,MAAM,uBAAuB,CAAC;AAO/B,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAChC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,kDAAkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;CAC5B;AAsBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA0CpG"}

package/dist/src/indexed/girvan-newman.js

@@ -0,0 +1,90 @@
+import { makeMask, maskCount, maskSet, maskTest, } from "@graphty/graph-format";
+import { edgeBetweennessCentrality } from "./betweenness.js";
+import { arcWeightsOf, exactEdgeWeights } from "./label-propagation.js";
+import { modularity } from "./modularity.js";
+import { IntUnionFind } from "./structures/union-find.js";
+/** Scores this close to the maximum are removed together, as the legacy function does. */
+const TIE = 1e-10;
+/**
+ * Connected components over the edges still alive.
+ * @param s - The snapshot
+ * @param alive - Kept edges
+ * @returns Dense labels and their count
+ */
+function aliveComponents(s, alive) {
+    const uf = new IntUnionFind(s.nodeCount);
+    const el = s.edgeList();
+    for (let e = 0; e < s.edgeCount; e++) {
+        if (maskTest(alive, e)) {
+            uf.union(el.src[e], el.dst[e]);
+        }
+    }
+    return uf.toLabels();
+}
+/**
+ * Girvan-Newman divisive community detection (PNAS 99:7821, 2002) over an undirected snapshot:
+ * repeatedly delete every edge whose betweenness is the maximum (within 1e-10), recording the
+ * connected components after each round as one level of a dendrogram.
+ *
+ * Edges are deleted by clearing bits of an alive mask over logical edges that the edge betweenness
+ * reads, so no graph is rebuilt. Betweenness is unweighted, as in the legacy function; a pair of
+ * nodes joined by parallel edges is one neighbour relation whose share goes to the first alive
+ * parallel, so the parallels are deleted one round at a time. Modularity reads the edge weights,
+ * the exact f64 ones when the snapshot keeps them, with graph-format's `weightedDegree()` rule (a
+ * self-loop counts twice); on a graph without self-loops it equals the legacy function's.
+ *
+ * The run stops when no edge is left, after `maxIterations` rounds, when a level has
+ * `maxCommunities` communities of at least `minCommunitySize` nodes, or when that count reaches
+ * the node count. Every level is returned whole: the legacy function drops communities below
+ * `minCommunitySize` from the lists it returns, which a caller does with `levels[i]` and a size
+ * count.
+ * @param s - An undirected snapshot
+ * @param options - Stopping rules
+ * @returns The levels and their modularity
+ * @throws Error on a directed snapshot
+ * @public
+ */
+export function girvanNewman(s, options = {}) {
+    if (s.directed) {
+        throw new Error("Girvan-Newman requires an undirected graph. Pass s.toUndirected().snapshot.");
+    }
+    const maxCommunities = options.maxCommunities ?? 0;
+    const minCommunitySize = options.minCommunitySize ?? 1;
+    const maxIterations = options.maxIterations ?? 100;
+    const { nodeCount: n, edgeCount } = s;
+    const weights = arcWeightsOf(s, exactEdgeWeights(s));
+    const alive = makeMask(edgeCount, true);
+    const levels = [];
+    const scores = [];
+    const record = () => {
+        const { labels, count } = aliveComponents(s, alive);
+        levels.push(labels);
+        scores.push(modularity(s, labels, weights === null ? {} : { weights }));
+        const sizes = new Uint32Array(count);
+        for (let u = 0; u < n; u++) {
+            sizes[labels[u]]++;
+        }
+        return sizes.filter((size) => size >= minCommunitySize).length;
+    };
+    record();
+    for (let round = 0; round < maxIterations && maskCount(alive, edgeCount) > 0; round++) {
+        const betweenness = edgeBetweennessCentrality(s, { alive }).scores;
+        let max = -Infinity;
+        for (let e = 0; e < edgeCount; e++) {
+            if (maskTest(alive, e) && betweenness[e] > max) {
+                max = betweenness[e];
+            }
+        }
+        for (let e = 0; e < edgeCount; e++) {
+            if (maskTest(alive, e) && Math.abs(betweenness[e] - max) < TIE) {
+                maskSet(alive, e, false);
+            }
+        }
+        const valid = record();
+        if ((maxCommunities > 0 && valid >= maxCommunities) || valid === n) {
+            break;
+        }
+    }
+    return { levels, modularity: Float64Array.from(scores) };
+}
+//# sourceMappingURL=girvan-newman.js.map