@graphty/algorithms 2.1.2 → 2.2.0

package/src/indexed/bfs.ts

@@ -1,4 +1,4 @@
-import { type AdjacencyView, INVALID_INDEX, type U32 } from "@graphty/graph-format";
+import { type AdjacencyView, type GraphSnapshot, INVALID_INDEX, type U32 } from "@graphty/graph-format";
 
 /** Result of the index-based BFS (graph-format design 14.2 Port 1). @public */
 export interface BfsResult {
@@ -12,10 +12,93 @@ export interface BfsResult {
     readonly visitedCount: number;
 }
 
+/** The neighbour-order option the order-sensitive traversals share. @public */
+export interface ArcOrderOption {
+    /**
+     * A permutation of the arc indices, `arcCount` long, whose slice `[rowPtr[u], rowPtr[u + 1])`
+     * lists node `u`'s arcs in the order to try them. The default is row order (ascending neighbour
+     * index). A caller that must reproduce a traversal over another neighbour order -- a legacy
+     * `Graph` hands out neighbours in insertion order -- passes that order here.
+     */
+    readonly arcOrder?: U32 | undefined;
+}
+
 /** Options of the index-based BFS. @public */
-export interface BfsOptions {
+export interface BfsOptions extends ArcOrderOption {
     /** Stop expanding at this depth; unbounded when omitted. */
     readonly maxDepth?: number | undefined;
+    /**
+     * Stop when this node index is taken off the queue, before its neighbours are expanded. Every
+     * node discovered by then stays in `order`; the target's own position in `order` ends the
+     * prefix of nodes that were expanded.
+     * @throws RangeError when it is not a node index
+     */
+    readonly target?: number | undefined;
+}
+
+/**
+ * Check a start (or target) node index.
+ * @param g - The adjacency
+ * @param start - The node index
+ * @param what - What the index is, for the error message
+ * @throws RangeError when `start` is not a node index of `g`
+ */
+export function checkStart(g: AdjacencyView, start: number, what = "start"): void {
+    if (!Number.isInteger(start) || start < 0 || start >= g.nodeCount) {
+        throw new RangeError(`${what} node index ${String(start)} is out of range for ${String(g.nodeCount)} nodes`);
+    }
+}
+
+/**
+ * Check an optional target node index.
+ * @param g - The adjacency
+ * @param target - The option, or undefined
+ * @returns The target, or INVALID_INDEX for none
+ * @throws RangeError when `target` is set and is not a node index of `g`
+ */
+export function checkTarget(g: AdjacencyView, target: number | undefined): number {
+    if (target === undefined) {
+        return INVALID_INDEX;
+    }
+    checkStart(g, target, "target");
+    return target;
+}
+
+/**
+ * Check an `arcOrder` option: `arcCount` entries, and every row's slice a permutation of that row's
+ * arcs.
+ * @param g - The adjacency
+ * @param arcOrder - The option, or undefined
+ * @returns The order, or null for row order
+ * @throws RangeError when the order does not fit the adjacency
+ */
+export function checkArcOrder(g: AdjacencyView, arcOrder: U32 | undefined): U32 | null {
+    if (arcOrder === undefined) {
+        return null;
+    }
+    const { rowPtr, nodeCount } = g;
+    if (arcOrder.length !== g.arcCount) {
+        throw new RangeError(`arcOrder has ${String(arcOrder.length)} entries, expected ${String(g.arcCount)}`);
+    }
+    const seen = new Uint8Array(arcOrder.length);
+    for (let u = 0; u < nodeCount; u++) {
+        const begin = rowPtr[u];
+        const end = rowPtr[u + 1];
+        for (let a = begin; a < end; a++) {
+            if (arcOrder[a] < begin || arcOrder[a] >= end) {
+                throw new RangeError(
+                    `arcOrder[${String(a)}] = ${String(arcOrder[a])} is not an arc of node ${String(u)}`,
+                );
+            }
+            if (seen[arcOrder[a]] === 1) {
+                throw new RangeError(
+                    `arcOrder[${String(a)}] = ${String(arcOrder[a])} repeats an arc of node ${String(u)}`,
+                );
+            }
+            seen[arcOrder[a]] = 1;
+        }
+    }
+    return arcOrder;
 }
 
 /**
@@ -28,24 +111,30 @@ export interface BfsOptions {
  * @public
  */
 export function breadthFirstSearch(g: AdjacencyView, start: number, options: BfsOptions = {}): BfsResult {
+    checkStart(g, start);
     const { nodeCount, rowPtr, colIdx } = g;
+    const arcOrder = checkArcOrder(g, options.arcOrder);
     const parent = new Uint32Array(nodeCount).fill(INVALID_INDEX);
     const depth = new Uint32Array(nodeCount).fill(INVALID_INDEX);
     const order = new Uint32Array(nodeCount);
     const maxDepth = options.maxDepth ?? INVALID_INDEX;
+    const target = checkTarget(g, options.target);
     let head = 0;
     let tail = 0;
     order[tail++] = start;
     depth[start] = 0;
     while (head < tail) {
         const u = order[head++];
+        if (u === target) {
+            break;
+        }
         const d = depth[u];
         if (d >= maxDepth) {
             continue;
         }
         const end = rowPtr[u + 1];
         for (let a = rowPtr[u]; a < end; a++) {
-            const v = colIdx[a];
+            const v = colIdx[arcOrder === null ? a : arcOrder[a]];
             if (depth[v] === INVALID_INDEX) {
                 depth[v] = d + 1;
                 parent[v] = u;
@@ -55,3 +144,100 @@ export function breadthFirstSearch(g: AdjacencyView, start: number, options: Bfs
     }
     return { order: order.subarray(0, tail), parent, depth, visitedCount: tail };
 }
+
+/** Options of {@link directionOptimizedBfs}. @public */
+export interface DirectionOptimizedBfsOptions {
+    /**
+     * Switch from top-down to bottom-up once the frontier's out-arcs exceed the unvisited nodes'
+     * out-arcs divided by `alpha`. Default 15.
+     */
+    readonly alpha?: number | undefined;
+    /** Switch back to top-down once the frontier shrinks below `nodeCount / beta` nodes. Default 18. */
+    readonly beta?: number | undefined;
+}
+
+/**
+ * Direction-optimising breadth-first search (Beamer, Asanovic and Patterson, SC'12): a top-down
+ * step expands the frontier's out-arcs, a bottom-up step has every unvisited node look for a
+ * frontier node among its in-neighbours over `s.reverse()` (fetched only when a bottom-up step
+ * runs), and the search switches between the two
+ * by frontier size. Both steps give a node the LOWEST-index frontier node that reaches it as its
+ * parent, so the result does not depend on which steps ran: `depth` equals `breadthFirstSearch`'s,
+ * and `order` lists the visited nodes level by level, ascending within a level.
+ * @param s - The snapshot to traverse
+ * @param source - The node index to start from
+ * @param options - The switching thresholds
+ * @returns The visit order, the parent array, the depth array and the visited count
+ * @public
+ */
+export function directionOptimizedBfs(
+    s: GraphSnapshot,
+    source: number,
+    options: DirectionOptimizedBfsOptions = {},
+): BfsResult {
+    checkStart(s, source);
+    const { nodeCount, rowPtr, colIdx } = s;
+    const alpha = options.alpha ?? 15;
+    const beta = options.beta ?? 18;
+    let reverse: AdjacencyView | null = null;
+    const parent = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    const depth = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    // order[levelStart, tail) is the current frontier, sorted ascending.
+    const order = new Uint32Array(nodeCount);
+    order[0] = source;
+    depth[source] = 0;
+    let levelStart = 0;
+    let tail = 1;
+    let unexploredArcs = s.arcCount - (rowPtr[source + 1] - rowPtr[source]);
+    let bottomUp = false;
+    for (let d = 0; levelStart < tail; d++) {
+        const frontierSize = tail - levelStart;
+        if (bottomUp) {
+            bottomUp = frontierSize >= nodeCount / beta;
+        } else {
+            let frontierArcs = 0;
+            for (let i = levelStart; i < tail; i++) {
+                frontierArcs += rowPtr[order[i] + 1] - rowPtr[order[i]];
+            }
+            bottomUp = frontierArcs > unexploredArcs / alpha;
+        }
+        const levelEnd = tail;
+        if (bottomUp) {
+            reverse ??= s.reverse();
+            for (let v = 0; v < nodeCount; v++) {
+                if (depth[v] !== INVALID_INDEX) {
+                    continue;
+                }
+                const end = reverse.rowPtr[v + 1];
+                for (let a = reverse.rowPtr[v]; a < end; a++) {
+                    const u = reverse.colIdx[a];
+                    if (depth[u] === d) {
+                        parent[v] = u;
+                        depth[v] = d + 1;
+                        order[tail++] = v;
+                        break;
+                    }
+                }
+            }
+        } else {
+            for (let i = levelStart; i < levelEnd; i++) {
+                const u = order[i];
+                const end = rowPtr[u + 1];
+                for (let a = rowPtr[u]; a < end; a++) {
+                    const v = colIdx[a];
+                    if (depth[v] === INVALID_INDEX) {
+                        parent[v] = u;
+                        depth[v] = d + 1;
+                        order[tail++] = v;
+                    }
+                }
+            }
+            order.subarray(levelEnd, tail).sort();
+        }
+        for (let i = levelEnd; i < tail; i++) {
+            unexploredArcs -= rowPtr[order[i] + 1] - rowPtr[order[i]];
+        }
+        levelStart = levelEnd;
+    }
+    return { order: order.subarray(0, tail), parent, depth, visitedCount: tail };
+}

package/src/indexed/bipartite.ts

@@ -0,0 +1,77 @@
+import { type AdjacencyView, type GraphSnapshot, makeMask, maskSet, type NodeMask } from "@graphty/graph-format";
+
+/** Result of the index-based bipartiteness test. @public */
+export interface BipartiteResult {
+    /** Whether the nodes split into two sides with no arc inside a side. */
+    readonly bipartite: boolean;
+    /**
+     * The two sides as one mask: a set bit puts the node on the second side, a clear bit on the
+     * first. The lowest-index node of every component is on the first side. Null when not bipartite.
+     */
+    readonly sides: NodeMask | null;
+}
+
+/** Options of {@link isBipartite}. @public */
+export interface BipartiteOptions {
+    /**
+     * Which arcs of a directed snapshot to colour along. "both" (default) follows out- and in-arcs,
+     * which answers for the graph with direction ignored. "out" follows out-arcs only, as the legacy
+     * `bipartitePartition` does: roots are taken in index order and a node first reached through an
+     * in-arc is coloured as a new root, so the answer depends on node order. Ignored on an undirected
+     * snapshot.
+     */
+    readonly arcs?: "both" | "out" | undefined;
+}
+
+const UNSEEN = 2;
+
+/**
+ * Two-colour the graph by BFS, one BFS per component in index order. A self-loop makes a graph
+ * non-bipartite; parallel arcs change nothing. Arc direction plays no part in bipartiteness, so on
+ * a directed snapshot every node is coloured against its in-neighbours (over `s.reverse()`) as well
+ * as its out-neighbours. Following out-arcs only -- as the legacy `bipartitePartition` does -- makes
+ * the answer depend on node order: with the single arc `a -> b`, a walk that starts at `b` never
+ * meets `a`, colours it as a new root and then finds the arc inside one side. `options.arcs: "out"`
+ * gives that legacy answer.
+ * @param s - The snapshot to test
+ * @param options - Which arcs to follow on a directed snapshot
+ * @returns Whether the graph is bipartite and, when it is, its two sides
+ * @public
+ */
+export function isBipartite(s: GraphSnapshot, options: BipartiteOptions = {}): BipartiteResult {
+    const { nodeCount } = s;
+    const views: AdjacencyView[] = s.directed && options.arcs !== "out" ? [s, s.reverse()] : [s];
+    const side = new Uint8Array(nodeCount).fill(UNSEEN);
+    const queue = new Uint32Array(nodeCount);
+    for (let r = 0; r < nodeCount; r++) {
+        if (side[r] !== UNSEEN) {
+            continue;
+        }
+        side[r] = 0;
+        let head = 0;
+        let tail = 0;
+        queue[tail++] = r;
+        while (head < tail) {
+            const u = queue[head++];
+            for (const { rowPtr, colIdx } of views) {
+                const end = rowPtr[u + 1];
+                for (let a = rowPtr[u]; a < end; a++) {
+                    const v = colIdx[a];
+                    if (side[v] === UNSEEN) {
+                        side[v] = side[u] ^ 1;
+                        queue[tail++] = v;
+                    } else if (side[v] === side[u]) {
+                        return { bipartite: false, sides: null };
+                    }
+                }
+            }
+        }
+    }
+    const sides = makeMask(nodeCount);
+    for (let i = 0; i < nodeCount; i++) {
+        if (side[i] === 1) {
+            maskSet(sides, i, true);
+        }
+    }
+    return { bipartite: true, sides };
+}

package/src/indexed/closeness.ts

@@ -0,0 +1,160 @@
+import type { GraphSnapshot, NumericVector } from "@graphty/graph-format";
+
+import type { ScoresResult } from "./betweenness.js";
+import { IndexedMinHeap } from "./structures/min-heap.js";
+
+/** Options of the index-based closeness centrality, matching the legacy `closenessCentrality`. @public */
+export interface ClosenessOptions {
+    /**
+     * Scale by the fraction of other nodes reached (Wasserman and Faust), or with `harmonic` divide by
+     * `n - 1`. Default false.
+     */
+    readonly normalized?: boolean | undefined;
+    /** Sum `1 / distance` instead of taking `1 / sum(distance)`; better on disconnected graphs. Default false. */
+    readonly harmonic?: boolean | undefined;
+    /**
+     * Stop searching from nodes this far away or farther. A node past the cutoff is still counted when an edge
+     * reaches it from a node closer than the cutoff, as in the legacy functions. Default: every reachable node.
+     */
+    readonly cutoff?: number | undefined;
+    /**
+     * Measure distance by edge weight (Dijkstra) rather than by hops, as the legacy
+     * `weightedClosenessCentrality` does. Default false: weights are ignored, as the legacy
+     * `closenessCentrality` ignores them.
+     */
+    readonly weighted?: boolean | undefined;
+    /** Per-arc weight override, arcCount long, read when `weighted`; a facade passes the exact f64 weights. */
+    readonly weights?: NumericVector | undefined;
+}
+
+/** Scores one source at a time, reusing its scratch arrays across sources. */
+type Scorer = (source: number) => number;
+
+/**
+ * Build the per-source scorer: a breadth-first search, or Dijkstra when `weighted`, then the legacy formula.
+ * @param s - The snapshot
+ * @param o - The options
+ * @returns The scorer
+ */
+function scorer(s: GraphSnapshot, o: ClosenessOptions): Scorer {
+    const { nodeCount: n, rowPtr, colIdx } = s;
+    const cutoff = o.cutoff ?? Infinity;
+    const weights = o.weighted === true ? (o.weights ?? s.weights) : null;
+    const dist = new Float64Array(n).fill(Infinity);
+    const reached = new Uint32Array(n);
+    const heap = weights === null ? null : new IndexedMinHeap(n);
+    // A popped node is final, as in the legacy search: without this a negative cycle never ends.
+    const settled = new Uint8Array(n);
+
+    /**
+     * Fill `dist` from the source and list the reached nodes in `reached`.
+     * @param source - The source index
+     * @returns How many nodes were reached, the source included
+     */
+    function search(source: number): number {
+        let tail = 0;
+        dist[source] = 0;
+        reached[tail++] = source;
+        if (heap === null || weights === null) {
+            for (let head = 0; head < tail; head++) {
+                const v = reached[head];
+                if (dist[v] >= cutoff) {
+                    continue;
+                }
+                for (let a = rowPtr[v], end = rowPtr[v + 1]; a < end; a++) {
+                    const w = colIdx[a];
+                    if (dist[w] === Infinity) {
+                        dist[w] = dist[v] + 1;
+                        reached[tail++] = w;
+                    }
+                }
+            }
+            return tail;
+        }
+        heap.push(source, 0);
+        while (!heap.isEmpty()) {
+            const v = heap.pop();
+            settled[v] = 1;
+            if (dist[v] >= cutoff) {
+                continue;
+            }
+            for (let a = rowPtr[v], end = rowPtr[v + 1]; a < end; a++) {
+                const w = colIdx[a];
+                if (settled[w] === 1) {
+                    continue;
+                }
+                const d = dist[v] + weights[a];
+                if (d < dist[w]) {
+                    if (dist[w] === Infinity) {
+                        reached[tail++] = w;
+                    }
+                    dist[w] = d;
+                    heap.pushOrDecrease(w, d);
+                }
+            }
+        }
+        return tail;
+    }
+
+    return (source: number): number => {
+        const count = search(source);
+        let score = 0;
+        let total = 0;
+        for (let i = 1; i < count; i++) {
+            const d = dist[reached[i]];
+            if (o.harmonic === true) {
+                score += d > 0 ? 1 / d : 0;
+            } else {
+                total += d;
+            }
+        }
+        for (let i = 0; i < count; i++) {
+            dist[reached[i]] = Infinity;
+            settled[reached[i]] = 0;
+        }
+        if (o.harmonic === true) {
+            return o.normalized === true && n > 1 ? score / (n - 1) : score;
+        }
+        if (total <= 0) {
+            return 0;
+        }
+        return o.normalized === true && n > 1 ? (count - 1) / total / (n - 1) : 1 / total;
+    };
+}
+
+/**
+ * Closeness centrality of every node: `1 / sum(distance to each reached node)` by default, the legacy
+ * `closenessCentrality` (hops) and `weightedClosenessCentrality` (`weighted: true`) numbers. The weighted
+ * route reads the snapshot's f32 arc weights, so it matches legacy to f32 rounding; pass the f64 weights as
+ * `weights` for the exact legacy sums. As in legacy, a node's distance is final once it is searched from, so a
+ * negative weight gives the legacy (not the true shortest) distance and never loops. An unreached node adds
+ * nothing, and a node that reaches nothing scores 0.
+ * @param s - The snapshot
+ * @param options - Normalisation, harmonic form, cutoff and weights
+ * @returns One score per node index; `iterations` is the number of searches run
+ * @public
+ */
+export function closenessCentrality(s: GraphSnapshot, options: ClosenessOptions = {}): ScoresResult {
+    const score = scorer(s, options);
+    const scores = new Float64Array(s.nodeCount);
+    for (let v = 0; v < s.nodeCount; v++) {
+        scores[v] = score(v);
+    }
+    return { scores, iterations: s.nodeCount, converged: true };
+}
+
+/**
+ * Closeness centrality of one node, with one search rather than n.
+ * @param s - The snapshot
+ * @param node - The node index
+ * @param options - As {@link closenessCentrality}
+ * @returns The node's score
+ * @throws RangeError for a node index outside `[0, nodeCount)`
+ * @public
+ */
+export function nodeClosenessCentrality(s: GraphSnapshot, node: number, options: ClosenessOptions = {}): number {
+    if (!Number.isInteger(node) || node < 0 || node >= s.nodeCount) {
+        throw new RangeError(`nodeClosenessCentrality: node must be an index in [0, ${s.nodeCount}), got ${node}`);
+    }
+    return scorer(s, options)(node);
+}

package/src/indexed/common-neighbors.ts

@@ -7,32 +7,36 @@ export interface CommonNeighborsOptions {
 }
 
 /**
- * The number of distinct common neighbours of two nodes, by a merge of their sorted rows.
- * @param s - The snapshot
+ * Merge row u of `fwd` with row v of `bwd` (both sorted) and add up each DISTINCT common neighbour
+ * once: 1 per neighbour, or `weight(z)` when a weight function is given. Skipping the repeats of a
+ * match in row v gives simple-graph semantics on a multigraph; a repeat in row u is then smaller
+ * than the next entry of row v and the ordinary advance passes it.
+ * @param fwd - The view whose row u is read
+ * @param bwd - The view whose row v is read
  * @param u - A node index
  * @param v - A node index
- * @param o - Options
- * @returns The count of distinct common neighbours
- * @public
+ * @param weight - Optional weight of a common neighbour
+ * @returns The count, or the weight sum, over distinct common neighbours
  */
-export function commonNeighborsScore(s: GraphSnapshot, u: number, v: number, o: CommonNeighborsOptions = {}): number {
-    const fwd: AdjacencyView = s;
-    const bwd: AdjacencyView = o.directed === true ? s.reverse() : s;
+export function sortedRowMerge(
+    fwd: AdjacencyView,
+    bwd: AdjacencyView,
+    u: number,
+    v: number,
+    weight?: (z: number) => number,
+): number {
     let i = fwd.rowPtr[u];
     const iEnd = fwd.rowPtr[u + 1];
     let j = bwd.rowPtr[v];
     const jEnd = bwd.rowPtr[v + 1];
-    let count = 0;
+    let sum = 0;
     while (i < iEnd && j < jEnd) {
         const a = fwd.colIdx[i];
         const b = bwd.colIdx[j];
         if (a === b) {
-            count++;
+            sum += weight === undefined ? 1 : weight(a);
             i++;
             j++;
-            while (i < iEnd && fwd.colIdx[i] === a) {
-                i++;
-            }
             while (j < jEnd && bwd.colIdx[j] === b) {
                 j++;
             }
@@ -42,5 +46,18 @@ export function commonNeighborsScore(s: GraphSnapshot, u: number, v: number, o:
             j++;
         }
     }
-    return count;
+    return sum;
+}
+
+/**
+ * The number of distinct common neighbours of two nodes, by a merge of their sorted rows.
+ * @param s - The snapshot
+ * @param u - A node index
+ * @param v - A node index
+ * @param o - Options
+ * @returns The count of distinct common neighbours
+ * @public
+ */
+export function commonNeighborsScore(s: GraphSnapshot, u: number, v: number, o: CommonNeighborsOptions = {}): number {
+    return sortedRowMerge(s, o.directed === true ? s.reverse() : s, u, v);
 }

package/src/indexed/degree.ts

@@ -0,0 +1,55 @@
+import type { AdjacencyView, F64, GraphSnapshot } from "@graphty/graph-format";
+
+/** Options of the index-based degree centrality, matching the legacy `degreeCentrality`. @public */
+export interface DegreeCentralityOptions {
+    /** On a directed snapshot, which neighbours to count; ignored when undirected. Default `"total"`. */
+    readonly mode?: "in" | "out" | "total" | undefined;
+    /** Divide by `n - 1`, the most neighbours a node can have. Default false. */
+    readonly normalized?: boolean | undefined;
+}
+
+/**
+ * Add each node's number of DISTINCT neighbours in `g` to `out`: parallel edges count once and a self-loop
+ * counts once, as the legacy `Graph.degree` counts them.
+ * @param g - The adjacency
+ * @param out - Per-node totals, added to in place
+ */
+function addDistinctNeighbours(g: AdjacencyView, out: F64): void {
+    const { rowPtr, colIdx } = g;
+    for (let v = 0; v < g.nodeCount; v++) {
+        let prev = -1;
+        for (let a = rowPtr[v], end = rowPtr[v + 1]; a < end; a++) {
+            if (colIdx[a] !== prev) {
+                prev = colIdx[a];
+                out[v]++;
+            }
+        }
+    }
+}
+
+/**
+ * Degree centrality: each node's number of distinct neighbours (in, out, or both on a directed snapshot),
+ * optionally divided by `n - 1`. Equals the legacy `degreeCentrality` on every graph it can hold, and on a
+ * multigraph equals it on the same graph with each pair's parallel edges merged.
+ * @param s - The snapshot
+ * @param options - Direction and normalisation
+ * @returns One score per node index
+ * @public
+ */
+export function degreeCentrality(s: GraphSnapshot, options: DegreeCentralityOptions = {}): F64 {
+    const scores = new Float64Array(s.nodeCount);
+    const mode = s.directed ? (options.mode ?? "total") : "out";
+    if (mode !== "in") {
+        addDistinctNeighbours(s, scores);
+    }
+    if (mode !== "out") {
+        addDistinctNeighbours(s.reverse(), scores);
+    }
+    const max = s.nodeCount - 1;
+    if (options.normalized === true && max > 0) {
+        for (let v = 0; v < scores.length; v++) {
+            scores[v] /= max;
+        }
+    }
+    return scores;
+}