@graphty/algorithms 2.1.2 → 2.2.0

package/dist/src/indexed/all-pairs.d.ts

@@ -0,0 +1,59 @@
+import { type F64, type GraphSnapshot, type NumericVector, type U32 } from "@graphty/graph-format";
+/** The default `maxNodes`: the GPU kernel's ceiling at WebGPU's 128 MiB storage binding, floor(sqrt(2^27 / 4)). */
+export declare 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;
+}
+/**
+ * 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 declare function allPairsShortestPath(s: GraphSnapshot, options?: ApspOptions): ApspResult;
+//# sourceMappingURL=all-pairs.d.ts.map

package/dist/src/indexed/all-pairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-pairs.d.ts","sourceRoot":"","sources":["../../../src/indexed/all-pairs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAiB,KAAK,aAAa,EAAE,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAMlH,mHAAmH;AACnH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,wFAAwF;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACvB,oHAAoH;IACpH,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,UAAU,GAAG,gBAAgB,CAAC;IACvD,mIAAmI;IACnI,QAAQ,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC;CAClD;AAyOD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CA6C5F"}

package/dist/src/indexed/all-pairs.js

@@ -0,0 +1,274 @@
+import { INVALID_INDEX } 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;
+/**
+ * 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, options) {
+    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 && (unit = x === 1);
+        negative || (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, w, negative, d, p) {
+    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, w) {
+    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, d, p) {
+    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, w, d, p) {
+    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, w, negative, 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, options = {}) {
+    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, target) => {
+        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),
+    };
+}
+//# sourceMappingURL=all-pairs.js.map

package/dist/src/indexed/all-pairs.js.map

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

package/dist/src/indexed/bellman-ford.d.ts

@@ -0,0 +1,25 @@
+import { type AdjacencyView } from "@graphty/graph-format";
+import { type SsspOptions, type SsspResult } 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 declare function bellmanFord(g: AdjacencyView, source: number, options?: SsspOptions): BellmanFordResult;
+//# sourceMappingURL=bellman-ford.d.ts.map

package/dist/src/indexed/bellman-ford.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bellman-ford.d.ts","sourceRoot":"","sources":["../../../src/indexed/bellman-ford.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAA+C,MAAM,uBAAuB,CAAC;AAExG,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAA+B,MAAM,eAAe,CAAC;AAE/F,oGAAoG;AACpG,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACjD;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,iBAAiB,CA6C1G"}

package/dist/src/indexed/bellman-ford.js

@@ -0,0 +1,59 @@
+import { INVALID_INDEX } from "@graphty/graph-format";
+import { walkPredArcs, walkPredEdges } from "./dijkstra.js";
+/**
+ * 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, source, options = {}) {
+    const { nodeCount, rowPtr, colIdx } = g;
+    const weights = 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 = () => {
+        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) => walkPredArcs(g, predArc, source, target),
+        pathEdges: (target) => walkPredEdges(g, predArc, source, target),
+    };
+}
+//# sourceMappingURL=bellman-ford.js.map

package/dist/src/indexed/bellman-ford.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bellman-ford.js","sourceRoot":"","sources":["../../../src/indexed/bellman-ford.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,aAAa,EAAgC,MAAM,uBAAuB,CAAC;AAExG,OAAO,EAAqC,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAY/F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,CAAgB,EAAE,MAAc,EAAE,UAAuB,EAAE;IACnF,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAyB,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEjB;;;OAGG;IACH,MAAM,KAAK,GAAG,GAAY,EAAE;QACxB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACnB,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAClB,SAAS;YACb,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;gBACpB,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACpD,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;oBAC/B,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;oBACf,OAAO,GAAG,IAAI,CAAC;gBACnB,CAAC;YACL,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC,CAAC;IAEF,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,gBAAgB,GAAG,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;IAC7C,OAAO;QACH,IAAI;QACJ,OAAO;QACP,gBAAgB;QAChB,MAAM,EAAE,CAAC,MAAc,EAAO,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;QACzE,SAAS,EAAE,CAAC,MAAc,EAAO,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;KAChF,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,85 @@
+import { type EdgeMask, type F64, type GraphSnapshot } 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 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 declare function resolveSources(n: number, sources: readonly number[] | undefined, k: number | undefined): readonly number[];
+/**
+ * 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 declare function betweennessCentrality(s: GraphSnapshot, options?: BetweennessOptions): ScoresResult;
+/**
+ * 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 declare function edgeBetweennessCentrality(s: GraphSnapshot, options?: EdgeBetweennessOptions): EdgeScoresResult;
+//# sourceMappingURL=betweenness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"betweenness.d.ts","sourceRoot":"","sources":["../../../src/indexed/betweenness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAY,MAAM,uBAAuB,CAAC;AAE9F,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACnC,wGAAwG;IACxG,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,4FAA4F;IAC5F,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACzC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IACzB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC5B;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;CACxB;AA0BD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACtC,CAAC,EAAE,MAAM,GAAG,SAAS,GACtB,SAAS,MAAM,EAAE,CAgBnB;AA2GD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,YAAY,CAQtG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,sBAA2B,GAAG,gBAAgB,CAUlH"}