@graphty/algorithms 2.1.2 → 2.2.0

package/src/indexed/all-pairs.ts

@@ -0,0 +1,342 @@
+import { type F64, type GraphSnapshot, INVALID_INDEX, type NumericVector, type U32 } from "@graphty/graph-format";
+
+import { PathWalkError } from "../errors.js";
+import { walkPredArcs, walkPredEdges } from "./dijkstra.js";
+import { IndexedMinHeap } from "./structures/min-heap.js";
+
+/** The default `maxNodes`: the GPU kernel's ceiling at WebGPU's 128 MiB storage binding, floor(sqrt(2^27 / 4)). */
+export const APSP_DEFAULT_MAX_NODES = 5792;
+
+/** Options of the index-based all-pairs shortest paths. @public */
+export interface ApspOptions {
+    /**
+     * Per-arc weight override, arcCount long; defaults to `s.weights` (null = 1 per arc). The
+     * snapshot's weights are f32, whose rounding can change which path is shortest; pass the exact
+     * f64 weights here to match the shipped `floydWarshall`.
+     */
+    readonly weights?: NumericVector | undefined;
+    /** `false` counts hops and ignores every weight. Default true. */
+    readonly weighted?: boolean | undefined;
+    /**
+     * Strategy override. `"auto"` (the default): BFS rows on unit weights, Floyd-Warshall on any
+     * negative weight, Dijkstra rows below arcCount n^2 / 3, Floyd-Warshall otherwise.
+     * `"floyd-warshall"` always sweeps; `"per-source"` runs BFS or Dijkstra rows and throws on a
+     * negative weight.
+     */
+    readonly method?: "auto" | "floyd-warshall" | "per-source" | undefined;
+    /** Record `predArc` so `pathTo` / `pathEdges` work; adds 4 n^2 bytes. Default false. */
+    readonly paths?: boolean | undefined;
+    /** Refuse larger graphs before allocating. Default 5,792. */
+    readonly maxNodes?: number | undefined;
+}
+
+/** All-pairs shortest paths as a dense row-major matrix. @public */
+export interface ApspResult {
+    /** dist[i * n + j] = distance from i to j; +Infinity unreachable, 0 on the diagonal, NaN under a negative cycle. */
+    readonly dist: F64;
+    /** The side of the matrix, s.nodeCount. */
+    readonly n: number;
+    /** True when a negative cycle exists; dist is then all NaN and the path accessors throw. */
+    readonly hasNegativeCycle: boolean;
+    /** The strategy that ran. */
+    readonly method: "bfs" | "dijkstra" | "floyd-warshall";
+    /** The arc ending each shortest path, row-major; INVALID_INDEX on the diagonal and when unreachable. Null unless `paths: true`. */
+    readonly predArc: U32 | null;
+    /**
+     * Node indices from `source` to `target` inclusive; empty when unreachable.
+     * @param source - The row's node index
+     * @param target - The column's node index
+     */
+    pathTo(source: number, target: number): U32;
+    /**
+     * Logical edge indices along that path; empty when unreachable or when source === target.
+     * @param source - The row's node index
+     * @param target - The column's node index
+     */
+    pathEdges(source: number, target: number): U32;
+}
+
+/**
+ * The weights in use, after the checks of design section 5.2.
+ * @param s - The snapshot
+ * @param options - The caller's options
+ * @returns The weight vector, or `null` when every weight is 1 (or weights are ignored), and whether one is negative
+ */
+function weightsInUse(s: GraphSnapshot, options: ApspOptions): { w: NumericVector | null; negative: boolean } {
+    if (options.weighted === false) {
+        return { w: null, negative: false };
+    }
+    if (options.weights !== undefined && options.weights.length !== s.arcCount) {
+        throw new RangeError(
+            `allPairsShortestPath: the weights override has ${String(options.weights.length)} entries; the snapshot has ${String(s.arcCount)} arcs`,
+        );
+    }
+    const w = options.weights ?? s.weights;
+    if (w === null) {
+        return { w: null, negative: false };
+    }
+    let unit = true;
+    let negative = false;
+    for (let a = 0; a < s.arcCount; a++) {
+        const x = w[a];
+        if (!Number.isFinite(x)) {
+            // A finite weight above 3.4e38 reaches the f32 arc column as Infinity.
+            const hint =
+                options.weights === undefined && !Number.isNaN(x)
+                    ? "; a finite weight above the f32 range (3.4e38) becomes Infinity in the snapshot's f32 arc weights -- pass the exact f64 weights through the weights override"
+                    : "";
+            throw new RangeError(
+                `allPairsShortestPath: arc ${String(a)} has weight ${String(x)}; weights must be finite${hint}`,
+            );
+        }
+        unit &&= x === 1;
+        negative ||= x < 0;
+    }
+    return { w: unit ? null : w, negative };
+}
+
+/**
+ * Floyd-Warshall in place (design section 3.1): k-i-j over the row-major matrix, row offsets
+ * hoisted, a row skipped when `d[i][k]` is +Infinity, strict `<` so the smallest pivot wins ties.
+ * With a negative weight in play the diagonal is scanned after every round and the sweep stops at
+ * the first negative entry (design section 3.3), before any value can run away.
+ * @param s - The snapshot
+ * @param w - The weights in use, or `null` for 1 per arc
+ * @param negative - Whether some weight is negative, so a cycle is possible
+ * @param d - The n x n output, overwritten
+ * @param p - The n x n predecessor arcs, filled with INVALID_INDEX, or `null` when paths are off
+ * @returns True when a negative cycle was found; `d` is then partial
+ */
+function floydWarshall(s: GraphSnapshot, w: NumericVector | null, negative: boolean, d: F64, p: U32 | null): boolean {
+    const { nodeCount: n, rowPtr, colIdx } = s;
+    d.fill(Infinity);
+    for (let u = 0; u < n; u++) {
+        const ur = u * n;
+        for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+            const v = colIdx[a];
+            const x = w === null ? 1 : w[a];
+            if (v !== u && x < d[ur + v]) {
+                d[ur + v] = x;
+                if (p !== null) {
+                    p[ur + v] = a;
+                }
+            }
+        }
+        d[ur + u] = 0;
+    }
+    for (let k = 0; k < n; k++) {
+        const kr = k * n;
+        // Row views, not d[kr + j]: 12 to 19 percent faster at every measured size (design section 12).
+        const dk = d.subarray(kr, kr + n);
+        for (let i = 0; i < n; i++) {
+            const ir = i * n;
+            const dik = d[ir + k];
+            if (dik === Infinity) {
+                continue;
+            }
+            const di = d.subarray(ir, ir + n);
+            // two copies of the j loop so the common no-paths sweep carries no per-cell branch
+            if (p === null) {
+                for (let j = 0; j < di.length; j++) {
+                    const via = dik + dk[j];
+                    if (via < di[j]) {
+                        di[j] = via;
+                    }
+                }
+            } else {
+                const pk = p.subarray(kr, kr + n);
+                const pi = p.subarray(ir, ir + n);
+                for (let j = 0; j < di.length; j++) {
+                    const via = dik + dk[j];
+                    if (via < di[j]) {
+                        di[j] = via;
+                        pi[j] = pk[j];
+                    }
+                }
+            }
+        }
+        if (negative) {
+            for (let i = 0; i < n; i++) {
+                if (d[i * n + i] < 0) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * The negative cycles the weights alone prove (design section 3.3): a negative self-loop, or any
+ * negative weight on an undirected snapshot (u-v-u).
+ * @param s - The snapshot
+ * @param w - The weights in use
+ * @returns True when such a cycle exists
+ */
+function negativeCycleFromWeights(s: GraphSnapshot, w: NumericVector): boolean {
+    for (let u = 0; u < s.nodeCount; u++) {
+        for (let a = s.rowPtr[u]; a < s.rowPtr[u + 1]; a++) {
+            if (w[a] < 0 && (!s.directed || s.colIdx[a] === u)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * One breadth-first search per source, hop counts written straight into row `src` of `d`. One
+ * queue of n entries serves every source.
+ * @param s - The snapshot
+ * @param d - The n x n output, overwritten
+ * @param p - The n x n predecessor arcs, filled with INVALID_INDEX, or `null`: the discovering arc
+ */
+function bfsRows(s: GraphSnapshot, d: F64, p: U32 | null): void {
+    const { nodeCount: n, rowPtr, colIdx } = s;
+    const queue = new Uint32Array(n);
+    d.fill(Infinity);
+    for (let src = 0; src < n; src++) {
+        const row = d.subarray(src * n, src * n + n);
+        const prow = p?.subarray(src * n, src * n + n);
+        row[src] = 0;
+        queue[0] = src;
+        let tail = 1;
+        for (let head = 0; head < tail; head++) {
+            const u = queue[head];
+            const next = row[u] + 1;
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                const v = colIdx[a];
+                if (row[v] === Infinity) {
+                    row[v] = next;
+                    if (prow !== undefined) {
+                        prow[v] = a;
+                    }
+                    queue[tail++] = v;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * One Dijkstra per source, relaxing straight into row `src` of `d`. One heap serves every source:
+ * a drained heap is empty again. Not `indexed.dijkstra` per source, which would allocate two O(n)
+ * arrays, a heap and two closures per source and then copy the row (design section 4).
+ * @param s - The snapshot
+ * @param w - The weights in use, all non-negative
+ * @param d - The n x n output, overwritten
+ * @param p - The n x n predecessor arcs, filled with INVALID_INDEX, or `null`: the relaxing arc
+ */
+function dijkstraRows(s: GraphSnapshot, w: NumericVector, d: F64, p: U32 | null): void {
+    const { nodeCount: n, rowPtr, colIdx } = s;
+    const heap = new IndexedMinHeap(n);
+    d.fill(Infinity);
+    for (let src = 0; src < n; src++) {
+        const row = d.subarray(src * n, src * n + n);
+        const prow = p?.subarray(src * n, src * n + n);
+        row[src] = 0;
+        heap.push(src, 0);
+        while (!heap.isEmpty()) {
+            const u = heap.pop();
+            const du = row[u];
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                const v = colIdx[a];
+                const dv = du + w[a];
+                if (dv < row[v]) {
+                    row[v] = dv;
+                    if (prow !== undefined) {
+                        prow[v] = a;
+                    }
+                    heap.pushOrDecrease(v, dv);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * The strategy rule of design section 4.
+ * @param s - The snapshot
+ * @param w - The weights in use, or `null` for 1 per arc
+ * @param negative - Whether some weight is negative
+ * @param method - The caller's override
+ * @returns The strategy to run
+ */
+function pickStrategy(
+    s: GraphSnapshot,
+    w: NumericVector | null,
+    negative: boolean,
+    method: ApspOptions["method"],
+): ApspResult["method"] {
+    if (method === "floyd-warshall") {
+        return "floyd-warshall";
+    }
+    if (w === null) {
+        return "bfs";
+    }
+    if (negative) {
+        if (method === "per-source") {
+            throw new Error(
+                'allPairsShortestPath: method "per-source" runs Dijkstra, which is incorrect with a negative weight; use "auto" or "floyd-warshall"',
+            );
+        }
+        return "floyd-warshall";
+    }
+    // The measured crossover (design section 12): n^2 / 3 arcs, above SciPy's n^2 / 4. Integer form, no rounding.
+    const n = s.nodeCount;
+    return method === "per-source" || 3 * s.arcCount < n * n ? "dijkstra" : "floyd-warshall";
+}
+
+/**
+ * All-pairs shortest paths over a snapshot.
+ * @param s - The snapshot
+ * @param options - Weights, strategy, paths and the size bound
+ * @returns The distance matrix and the path accessors
+ * @public
+ */
+export function allPairsShortestPath(s: GraphSnapshot, options: ApspOptions = {}): ApspResult {
+    const n = s.nodeCount;
+    const maxNodes = options.maxNodes ?? APSP_DEFAULT_MAX_NODES;
+    // Written negated so a NaN maxNodes refuses rather than switching the bound off.
+    if (!(n <= maxNodes)) {
+        const bytes = (options.paths === true ? 12 : 8) * n * n;
+        throw new RangeError(
+            `allPairsShortestPath: ${String(n)} nodes exceeds maxNodes ${String(maxNodes)}; the result would allocate ${String(bytes)} bytes. Pass a larger maxNodes to allow it.`,
+        );
+    }
+    const { w, negative } = weightsInUse(s, options);
+    const method = pickStrategy(s, w, negative, options.method);
+    const dist = new Float64Array(n * n);
+    const predArc = options.paths === true ? new Uint32Array(n * n).fill(INVALID_INDEX) : null;
+    let hasNegativeCycle = false;
+    if (method === "bfs") {
+        bfsRows(s, dist, predArc);
+    } else if (method === "dijkstra" && w !== null) {
+        dijkstraRows(s, w, dist, predArc);
+    } else {
+        hasNegativeCycle =
+            (negative && w !== null && negativeCycleFromWeights(s, w)) || floydWarshall(s, w, negative, dist, predArc);
+    }
+    if (hasNegativeCycle) {
+        dist.fill(NaN);
+    }
+    // Row i of predArc is a single-source predecessor-arc array, so the SSSP walkers apply to it.
+    const row = (source: number, target: number): U32 => {
+        if (predArc === null) {
+            throw new Error("allPairsShortestPath: pass paths: true to walk shortest paths");
+        }
+        if (hasNegativeCycle) {
+            throw new PathWalkError(source, target, "cycle");
+        }
+        return predArc.subarray(source * n, source * n + n);
+    };
+    return {
+        dist,
+        n,
+        hasNegativeCycle,
+        method,
+        predArc,
+        pathTo: (source, target) => walkPredArcs(s, row(source, target), source, target),
+        pathEdges: (source, target) => walkPredEdges(s, row(source, target), source, target),
+    };
+}

package/src/indexed/bellman-ford.ts

@@ -0,0 +1,72 @@
+import { type AdjacencyView, INVALID_INDEX, type NumericVector, type U32 } from "@graphty/graph-format";
+
+import { type SsspOptions, type SsspResult, walkPredArcs, walkPredEdges } from "./dijkstra.js";
+
+/** Result of the index-based Bellman-Ford: the SSSP result plus the negative-cycle flag. @public */
+export interface BellmanFordResult extends SsspResult {
+    /**
+     * True when a negative cycle is reachable from the source. `dist` and `predArc` then hold the
+     * state after `nodeCount - 1` rounds, which are not shortest paths, and a path accessor may throw
+     * `PathWalkError` on a predecessor chain that loops.
+     */
+    readonly hasNegativeCycle: boolean;
+}
+
+/**
+ * Bellman-Ford single-source shortest paths, index-based, for weights that may be negative. It
+ * relaxes every arc, so an undirected edge is relaxed both ways (it has an arc in each direction),
+ * and one negative undirected edge is therefore a negative cycle. Rounds stop early once one changes
+ * nothing; after `nodeCount - 1` rounds one more round decides `hasNegativeCycle`. The predecessor
+ * is the relaxing ARC, as in `dijkstra`, so a parallel edge on a path is identified exactly.
+ * @param g - The adjacency to search
+ * @param source - The node index to start from
+ * @param options - Cutoff (a relaxation beyond it is skipped) and per-arc weight override
+ * @returns The distances, the predecessor arcs, the path accessors and the negative-cycle flag
+ * @public
+ */
+export function bellmanFord(g: AdjacencyView, source: number, options: SsspOptions = {}): BellmanFordResult {
+    const { nodeCount, rowPtr, colIdx } = g;
+    const weights: NumericVector | null = options.weights ?? g.weights;
+    const cutoff = options.cutoff ?? Infinity;
+    const dist = new Float64Array(nodeCount).fill(Infinity);
+    const predArc = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    dist[source] = 0;
+
+    /**
+     * One pass over every arc leaving a reached node.
+     * @returns True when any distance dropped
+     */
+    const round = (): boolean => {
+        let changed = false;
+        for (let u = 0; u < nodeCount; u++) {
+            const du = dist[u];
+            if (du === Infinity) {
+                continue;
+            }
+            const end = rowPtr[u + 1];
+            for (let a = rowPtr[u]; a < end; a++) {
+                const v = colIdx[a];
+                const dv = du + (weights === null ? 1 : weights[a]);
+                if (dv < dist[v] && dv <= cutoff) {
+                    dist[v] = dv;
+                    predArc[v] = a;
+                    changed = true;
+                }
+            }
+        }
+        return changed;
+    };
+
+    let settled = false;
+    for (let i = 0; i < nodeCount - 1 && !settled; i++) {
+        settled = !round();
+    }
+    const hasNegativeCycle = !settled && round();
+    return {
+        dist,
+        predArc,
+        hasNegativeCycle,
+        pathTo: (target: number): U32 => walkPredArcs(g, predArc, source, target),
+        pathEdges: (target: number): U32 => walkPredEdges(g, predArc, source, target),
+    };
+}

package/src/indexed/betweenness.ts

@@ -0,0 +1,258 @@
+import { type EdgeMask, type F64, type GraphSnapshot, maskTest } from "@graphty/graph-format";
+
+/** Options of the index-based node betweenness. @public */
+export interface BetweennessOptions {
+    /**
+     * Divide by the number of ordered pairs a node can sit between: `(n - 1)(n - 2)` directed, half that
+     * undirected; with `endpoints`, `n (n - 1)` and half that. Default false.
+     */
+    readonly normalized?: boolean | undefined;
+    /**
+     * Count a path's two ends as lying on it, as NetworkX's `endpoints=True` does. Default false. The legacy
+     * `betweennessCentrality` accepts this option and ignores it.
+     */
+    readonly endpoints?: boolean | undefined;
+    /** Sampled betweenness: the source node indices to run from. Duplicates run twice. */
+    readonly sources?: readonly number[] | undefined;
+    /**
+     * Sampled betweenness: how many distinct sources to draw when `sources` is not given. The draw is
+     * deterministic -- the same `(n, k)` draws the same sources every time, and the dispatcher hands an
+     * accelerator the drawn sources, so both paths run the same ones. With `sources` it must equal `sources.length`.
+     */
+    readonly k?: number | undefined;
+}
+
+/** Options of the index-based edge betweenness. @public */
+export interface EdgeBetweennessOptions {
+    /** Divide by `(n - 1)(n - 2)` directed, half that undirected, as the node scores are. Default false. */
+    readonly normalized?: boolean | undefined;
+    /** Sampled edge betweenness: the source node indices to run from. */
+    readonly sources?: readonly number[] | undefined;
+    /** Sampled edge betweenness: how many sources to draw; see {@link BetweennessOptions.k}. */
+    readonly k?: number | undefined;
+    /**
+     * Logical edges to keep, as a packed mask over `edgeCount`; a cleared edge is treated as deleted and scores
+     * 0. Girvan-Newman removes edges this way without building a new snapshot.
+     */
+    readonly alive?: EdgeMask | undefined;
+}
+
+/** Scores per node index from an exact, non-iterative computation. @public */
+export interface ScoresResult {
+    /** One score per node index. */
+    readonly scores: F64;
+    /** The number of breadth-first searches or shortest-path searches run: one per source. */
+    readonly iterations: number;
+    /** Always true: nothing here iterates to a tolerance. */
+    readonly converged: true;
+}
+
+/** Scores per logical edge index. @public */
+export interface EdgeScoresResult {
+    /** One score per logical edge. */
+    readonly scores: F64;
+}
+
+/** The seed of the `k` draw. Any fixed value works: the draw only has to repeat. */
+const SAMPLE_SEED = 0x9e3779b9;
+
+/**
+ * `k` distinct node indices by a partial Fisher-Yates shuffle over a fixed-seed mulberry32 stream, so the same
+ * `(n, k)` draws the same sources every time.
+ * @param n - The node count
+ * @param k - How many to draw, at most n
+ * @returns The sources
+ */
+function drawSources(n: number, k: number): number[] {
+    const pool = Array.from({ length: n }, (_, i) => i);
+    let state = SAMPLE_SEED;
+    for (let i = 0; i < k; i++) {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(state ^ (state >>> 15), state | 1);
+        t = (t + Math.imul(t ^ (t >>> 7), t | 61)) ^ t;
+        const unit = ((t ^ (t >>> 14)) >>> 0) / 2 ** 32;
+        const j = i + Math.floor(unit * (n - i));
+        [pool[i], pool[j]] = [pool[j], pool[i]];
+    }
+    return pool.slice(0, k);
+}
+
+/**
+ * The sources a call runs: `sources` as given, else `k` drawn, else every node.
+ * @param n - The node count
+ * @param sources - The caller's list
+ * @param k - The caller's count
+ * @returns The sources
+ * @throws RangeError for a source outside `[0, n)`, a `k` outside `[0, n]`, or a `k` that disagrees with the list
+ */
+export function resolveSources(
+    n: number,
+    sources: readonly number[] | undefined,
+    k: number | undefined,
+): readonly number[] {
+    if (k !== undefined && (!Number.isInteger(k) || k < 0 || k > n)) {
+        throw new RangeError(`betweenness: k must be an integer in [0, ${n}], got ${k}`);
+    }
+    if (sources !== undefined) {
+        for (const v of sources) {
+            if (!Number.isInteger(v) || v < 0 || v >= n) {
+                throw new RangeError(`betweenness: sources must be node indices in [0, ${n}), got ${v}`);
+            }
+        }
+        if (k !== undefined && k !== sources.length) {
+            throw new RangeError(`betweenness: k (${k}) must be absent or equal sources.length (${sources.length})`);
+        }
+        return sources;
+    }
+    return k === undefined ? Array.from({ length: n }, (_, i) => i) : drawSources(n, k);
+}
+
+/**
+ * Brandes' accumulation from every source, into `node` and/or `edge` (raw sums, before halving or
+ * normalising).
+ *
+ * A pair joined by parallel edges is ONE neighbour relation (graph-format design 3.5, the adjacent-skip idiom),
+ * so path counts are the simple graph's and equal the legacy function's. The pair's share of an edge score goes
+ * to the first alive parallel edge in row order; the others score 0. Removing that edge hands the whole share to
+ * the next parallel, so the scores of a pair's parallels always sum to the simple graph's edge score.
+ * Dependencies are pulled over OUT-arcs from the deepest level up, so no reverse adjacency is built.
+ * @param s - The snapshot
+ * @param sources - Source node indices
+ * @param node - Node sums, or null
+ * @param edge - Edge sums, or null
+ * @param alive - Kept edges, or null for all
+ * @param endpoints - Count path ends on the path (node sums only)
+ */
+function accumulate(
+    s: GraphSnapshot,
+    sources: readonly number[],
+    node: F64 | null,
+    edge: F64 | null,
+    alive: EdgeMask | null,
+    endpoints: boolean,
+): void {
+    const { nodeCount: n, rowPtr, colIdx, arcToEdge } = s;
+    const depth = new Int32Array(n).fill(-1);
+    const sigma = new Float64Array(n);
+    const delta = new Float64Array(n);
+    const order = new Uint32Array(n);
+    for (const source of sources) {
+        let head = 0;
+        let tail = 0;
+        depth[source] = 0;
+        sigma[source] = 1;
+        order[tail++] = source;
+        while (head < tail) {
+            const v = order[head++];
+            const next = depth[v] + 1;
+            let prev = -1;
+            for (let a = rowPtr[v], end = rowPtr[v + 1]; a < end; a++) {
+                const w = colIdx[a];
+                if (w === prev || (alive !== null && !maskTest(alive, arcToEdge[a]))) {
+                    continue;
+                }
+                prev = w;
+                if (depth[w] < 0) {
+                    depth[w] = next;
+                    order[tail++] = w;
+                }
+                if (depth[w] === next) {
+                    sigma[w] += sigma[v];
+                }
+            }
+        }
+        for (let i = tail - 1; i >= 0; i--) {
+            const v = order[i];
+            const next = depth[v] + 1;
+            let prev = -1;
+            for (let a = rowPtr[v], end = rowPtr[v + 1]; a < end; a++) {
+                const w = colIdx[a];
+                if (w === prev || (alive !== null && !maskTest(alive, arcToEdge[a]))) {
+                    continue;
+                }
+                prev = w;
+                if (depth[w] === next) {
+                    const c = (sigma[v] / sigma[w]) * (1 + delta[w]);
+                    delta[v] += c;
+                    if (edge !== null) {
+                        edge[arcToEdge[a]] += c;
+                    }
+                }
+            }
+            if (node !== null && v !== source) {
+                node[v] += endpoints ? delta[v] + 1 : delta[v];
+            }
+        }
+        if (node !== null && endpoints) {
+            node[source] += tail - 1;
+        }
+        for (let i = 0; i < tail; i++) {
+            const v = order[i];
+            depth[v] = -1;
+            sigma[v] = 0;
+            delta[v] = 0;
+        }
+    }
+}
+
+/**
+ * Halve on an undirected snapshot (each unordered pair was counted from both ends) and divide by `factor` when
+ * normalising and it is positive.
+ * @param s - The snapshot
+ * @param scores - The raw sums, scaled in place
+ * @param normalized - Whether to normalise
+ * @param factor - The directed pair count to normalise by
+ */
+function scale(s: GraphSnapshot, scores: F64, normalized: boolean | undefined, factor: number): void {
+    // Undirected: halving and then dividing by half the directed pair count is dividing by the whole count.
+    const halve = s.directed ? 1 : 2;
+    const divisor = normalized === true && factor > 0 ? factor : halve;
+    for (let i = 0; i < scores.length; i++) {
+        scores[i] /= divisor;
+    }
+}
+
+/**
+ * Node betweenness centrality by Brandes' algorithm: breadth-first, so weights are ignored, as in the legacy
+ * `betweennessCentrality`, whose scores this equals on every graph it can hold. A sampled run (`sources` or `k`)
+ * is the UNSCALED sum over the sources run, as the WebGPU accelerator reports it.
+ * @param s - The snapshot
+ * @param options - Normalisation, endpoints and sampling
+ * @returns One score per node index; `iterations` is the number of sources run
+ * @throws RangeError for a bad `sources` or `k`
+ * @public
+ */
+export function betweennessCentrality(s: GraphSnapshot, options: BetweennessOptions = {}): ScoresResult {
+    const n = s.nodeCount;
+    const sources = resolveSources(n, options.sources, options.k);
+    const scores = new Float64Array(n);
+    const endpoints = options.endpoints === true;
+    accumulate(s, sources, scores, null, null, endpoints);
+    scale(s, scores, options.normalized, endpoints ? n * (n - 1) : (n - 1) * (n - 2));
+    return { scores, iterations: sources.length, converged: true };
+}
+
+/**
+ * Edge betweenness centrality by Brandes' algorithm, one score per logical edge.
+ *
+ * On a directed snapshot an edge's score equals the legacy `edgeBetweennessCentrality` value keyed
+ * `"source-target"`. On an undirected one it is the number of pairs whose shortest paths cross the edge in
+ * either direction, which is the SUM of the two values the legacy function reports under `"u-v"` and `"v-u"`
+ * (each of those holds half), and is the score the WebGPU accelerator returns.
+ * @param s - The snapshot
+ * @param options - Normalisation, sampling and the alive-edge mask
+ * @returns One score per logical edge
+ * @throws RangeError for a bad `sources` or `k`, or an `alive` mask shorter than the edge count
+ * @public
+ */
+export function edgeBetweennessCentrality(s: GraphSnapshot, options: EdgeBetweennessOptions = {}): EdgeScoresResult {
+    const n = s.nodeCount;
+    const alive = options.alive ?? null;
+    if (alive !== null && alive.length < Math.ceil(s.edgeCount / 32)) {
+        throw new RangeError(`edgeBetweennessCentrality: alive covers fewer than ${s.edgeCount} edges`);
+    }
+    const scores = new Float64Array(s.edgeCount);
+    accumulate(s, resolveSources(n, options.sources, options.k), null, scores, alive, false);
+    scale(s, scores, options.normalized, (n - 1) * (n - 2));
+    return { scores };
+}