@graphty/algorithms 1.7.3 → 1.8.1

package/src/indexed/dijkstra.ts

@@ -0,0 +1,134 @@
+import { type AdjacencyView, INVALID_INDEX, type NumericVector, type U32 } from "@graphty/graph-format";
+
+import { arcSourceIn } from "./structures/arc-source.js";
+import { IndexedMinHeap } from "./structures/min-heap.js";
+
+/**
+ * Single-source shortest paths, index-based (graph-format design 14.2 Port 2, line 3860).
+ * `dist` is a `NumericVector` rather than the design's `F64` because ONE declaration serves both
+ * the CPU port (which produces a `Float64Array`) and the dispatcher's decoration of an
+ * accelerator's f32 result (plan decision PD-3, departure DEP-8A-C).
+ * @public
+ */
+export interface SsspResult {
+    /** Distance per node; +Infinity for unreached nodes. */
+    readonly dist: NumericVector;
+    /** The ARC that relaxed each node; INVALID_INDEX for the source and for unreached nodes. */
+    readonly predArc: U32;
+    /**
+     * Node indices from the source to `target` inclusive; empty when `target` is unreached.
+     * @param target - The node index to walk back from
+     */
+    pathTo(target: number): U32;
+    /**
+     * LOGICAL EDGE indices along that path, one fewer than `pathTo`; this is what graphty-element's
+     * `isInPath` writes through. Empty when `target` is unreached.
+     * @param target - The node index to walk back from
+     */
+    pathEdges(target: number): U32;
+}
+
+/** Options of the index-based SSSP. @public */
+export interface SsspOptions {
+    /** Stop relaxing beyond this distance. */
+    readonly cutoff?: number | undefined;
+    /** Per-arc weight override, arcCount long -- the facade passes `expandEdges(s, shadow.data)`. */
+    readonly weights?: NumericVector | undefined;
+}
+
+/**
+ * Walk the predecessor arcs back from `target` and return the node path, source first.
+ * @param g - The adjacency the search ran on
+ * @param predArc - The search's predecessor-arc array
+ * @param source - The search's source node index
+ * @param target - The node to walk back from
+ * @returns Node indices from source to target inclusive, or an empty array when unreached
+ * @public
+ */
+export function walkPredArcs(g: AdjacencyView, predArc: U32, source: number, target: number): U32 {
+    if (target === source) {
+        return Uint32Array.of(source);
+    }
+    if (predArc[target] === INVALID_INDEX) {
+        return new Uint32Array(0);
+    }
+    const reversed: number[] = [target];
+    let node = target;
+    while (node !== source) {
+        node = arcSourceIn(g.rowPtr, predArc[node]);
+        reversed.push(node);
+    }
+    const out = new Uint32Array(reversed.length);
+    for (let i = 0; i < reversed.length; i++) {
+        out[i] = reversed[reversed.length - 1 - i];
+    }
+    return out;
+}
+
+/**
+ * Walk the predecessor arcs back from `target` and return the logical edges on the path.
+ * @param g - The adjacency the search ran on
+ * @param predArc - The search's predecessor-arc array
+ * @param source - The search's source node index
+ * @param target - The node to walk back from
+ * @returns Logical edge indices from source to target, or an empty array when unreached
+ * @public
+ */
+export function walkPredEdges(g: AdjacencyView, predArc: U32, source: number, target: number): U32 {
+    if (target === source || predArc[target] === INVALID_INDEX) {
+        return new Uint32Array(0);
+    }
+    const reversed: number[] = [];
+    let node = target;
+    while (node !== source) {
+        const arc = predArc[node];
+        reversed.push(g.arcToEdge[arc]); // the EXACT parallel edge, not a (u, v) lookup
+        node = arcSourceIn(g.rowPtr, arc);
+    }
+    const out = new Uint32Array(reversed.length);
+    for (let i = 0; i < reversed.length; i++) {
+        out[i] = reversed[reversed.length - 1 - i];
+    }
+    return out;
+}
+
+/**
+ * Dijkstra over an adjacency view, with the predecessor recorded as the relaxing ARC so a parallel
+ * edge on the path is identified exactly.
+ * @param g - The adjacency to search
+ * @param source - The node index to start from
+ * @param options - Cutoff and per-arc weight override
+ * @returns The distances, the predecessor arcs, and the two path accessors
+ * @public
+ */
+export function dijkstra(g: AdjacencyView, source: number, options: SsspOptions = {}): SsspResult {
+    const { nodeCount, rowPtr, colIdx } = g;
+    const weights: NumericVector | null = options.weights ?? g.weights;
+    const dist = new Float64Array(nodeCount).fill(Infinity);
+    const predArc = new Uint32Array(nodeCount).fill(INVALID_INDEX);
+    const heap = new IndexedMinHeap(nodeCount);
+    const cutoff = options.cutoff ?? Infinity;
+    dist[source] = 0;
+    heap.push(source, 0);
+    while (!heap.isEmpty()) {
+        const u = heap.pop();
+        const du = dist[u];
+        const end = rowPtr[u + 1];
+        for (let a = rowPtr[u]; a < end; a++) {
+            const w = weights === null ? 1 : weights[a];
+            const v = colIdx[a];
+            const dv = du + w;
+            if (dv < dist[v] && dv <= cutoff) {
+                dist[v] = dv;
+                predArc[v] = a;
+                heap.pushOrDecrease(v, dv);
+            }
+        }
+    }
+    return {
+        dist,
+        predArc,
+        pathTo: (target: number): U32 => walkPredArcs(g, predArc, source, target),
+        pathEdges: (target: number): U32 => walkPredEdges(g, predArc, source, target),
+    };
+}

package/src/indexed/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Index-based implementations over `@graphty/graph-format` snapshots (graph-format design 14.1
+ * rule 2): every function takes a `GraphSnapshot` or an `AdjacencyView` first and an options object
+ * last, and returns typed arrays plus scalars. Reached as the `indexed` namespace of
+ * `@graphty/algorithms`.
+ *
+ * NOT re-exported here, deliberately (plan decision PD-9):
+ * - `./accelerator.js`, which imports this barrel -- re-exporting it would make a cycle, and its
+ *   symbols are exported FLAT from the package barrel because the GPU package must write
+ *   `import type { AlgorithmAccelerator } from "@graphty/algorithms"`.
+ * - `./to-snapshot.js`, whose parameter is a legacy `Graph`, which is not what this namespace
+ *   promises. It is exported flat too.
+ * @module
+ */
+
+export { type BfsOptions, type BfsResult, breadthFirstSearch } from "./bfs.js";
+export { type CommonNeighborsOptions, commonNeighborsScore } from "./common-neighbors.js";
+export { connectedComponents, type LabelResult, weaklyConnectedComponents } from "./components.js";
+export {
+    dijkstra,
+    type SsspOptions,
+    type SsspResult,
+    walkPredArcs,
+    walkPredEdges,
+} from "./dijkstra.js";
+export { kruskalMST, type MstOptions, type MstResult } from "./mst.js";
+export { pageRank, type PageRankOptions, type PageRankResult } from "./pagerank.js";
+export { arcSourceIn, IndexedMinHeap, IntUnionFind } from "./structures/index.js";

package/src/indexed/mst.ts

@@ -0,0 +1,62 @@
+import type { GraphSnapshot, NumericVector, U32 } from "@graphty/graph-format";
+
+import { IntUnionFind } from "./structures/union-find.js";
+
+/** Options of the index-based MST. @public */
+export interface MstOptions {
+    /** Per-arc weight override, arcCount long; gathered back to per-edge through `edgeToArc`. */
+    readonly weights?: NumericVector | undefined;
+}
+
+/** Result of the index-based MST (graph-format design 14.2's result table, line 3745). @public */
+export interface MstResult {
+    /** Logical edge indices of the spanning forest, in the order they were accepted. */
+    readonly edges: U32;
+    /** Sum of the accepted edges' weights. */
+    readonly totalWeight: number;
+}
+
+/**
+ * Kruskal's minimum spanning forest over logical edges.
+ *
+ * The sort is a comparator over an f64 key array, tie-broken by edge index, rather than the
+ * design's radix sort on the f32 bit pattern (plan departure DEP-8A-D): the tie-break makes it
+ * stable by construction and it has to serve both the f32 arc array and an f64 override.
+ * @param s - The snapshot
+ * @param o - The optional per-arc weight override
+ * @returns The accepted edge indices and their total weight
+ * @public
+ */
+export function kruskalMST(s: GraphSnapshot, o: MstOptions = {}): MstResult {
+    const el = s.edgeList();
+    const m = s.edgeCount;
+    const keys = new Float64Array(m);
+    if (o.weights !== undefined) {
+        // The override is per ARC; edgeList().arc holds the arc of each edge's declared orientation.
+        for (let e = 0; e < m; e++) {
+            keys[e] = o.weights[el.arc[e]];
+        }
+    } else if (el.weights !== null) {
+        for (let e = 0; e < m; e++) {
+            keys[e] = el.weights[e];
+        }
+    } else {
+        keys.fill(1);
+    }
+    const order: number[] = new Array<number>(m);
+    for (let e = 0; e < m; e++) {
+        order[e] = e;
+    }
+    order.sort((a, b) => keys[a] - keys[b] || a - b);
+    const uf = new IntUnionFind(s.nodeCount);
+    const accepted = new Uint32Array(Math.max(s.nodeCount - 1, 0));
+    let taken = 0;
+    let totalWeight = 0;
+    for (const e of order) {
+        if (uf.union(el.src[e], el.dst[e])) {
+            accepted[taken++] = e;
+            totalWeight += keys[e];
+        }
+    }
+    return { edges: accepted.subarray(0, taken), totalWeight };
+}

package/src/indexed/pagerank.ts

@@ -0,0 +1,73 @@
+import type { F64, GraphSnapshot, NumericVector } from "@graphty/graph-format";
+
+/** Options of the index-based PageRank (graph-format design 14.2 Port 3, line 3892). @public */
+export interface PageRankOptions {
+    /** Probability of following a link; default 0.85. */
+    readonly dampingFactor?: number | undefined;
+    /** Iteration cap; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** L1 convergence tolerance; default 1e-6. */
+    readonly tolerance?: number | undefined;
+    /** Use the snapshot's arc weights; default false. */
+    readonly weighted?: boolean | undefined;
+}
+
+/** Result of the index-based PageRank. @public */
+export interface PageRankResult {
+    /** Score per node index. */
+    readonly scores: F64;
+    /** Iterations actually run. */
+    readonly iterations: number;
+    /** Whether the L1 delta fell below the tolerance. */
+    readonly converged: boolean;
+}
+
+/**
+ * PageRank by pull over `reverse()`, with the dangling mass redistributed uniformly.
+ * @param s - A DIRECTED snapshot
+ * @param o - Algorithm options
+ * @returns The scores, the iteration count and the convergence flag
+ * @public
+ */
+export function pageRank(s: GraphSnapshot, o: PageRankOptions = {}): PageRankResult {
+    if (!s.directed) {
+        throw new Error("PageRank requires a directed graph");
+    }
+    const n = s.nodeCount;
+    const d = o.dampingFactor ?? 0.85;
+    const maxIter = o.maxIterations ?? 100;
+    const tol = o.tolerance ?? 1e-6;
+    const rev = s.reverse();
+    const weighted = o.weighted === true && rev.weights !== null;
+    const outW: NumericVector = weighted ? s.weightedOutDegree() : s.outDegree();
+    let rank = new Float64Array(n).fill(1 / n);
+    let next = new Float64Array(n);
+    let it = 0;
+    let converged = false;
+    for (; it < maxIter && !converged; it++) {
+        let dangling = 0;
+        for (let u = 0; u < n; u++) {
+            if (outW[u] === 0) {
+                dangling += rank[u];
+            }
+        }
+        const base = (1 - d) / n + (d * dangling) / n;
+        let delta = 0;
+        for (let v = 0; v < n; v++) {
+            let acc = 0;
+            const end = rev.rowPtr[v + 1];
+            for (let a = rev.rowPtr[v]; a < end; a++) {
+                const u = rev.colIdx[a];
+                const ow = outW[u];
+                if (ow > 0) {
+                    acc += (rank[u] * (weighted && rev.weights !== null ? rev.weights[a] : 1)) / ow;
+                }
+            }
+            next[v] = base + d * acc;
+            delta += Math.abs(next[v] - rank[v]);
+        }
+        [rank, next] = [next, rank];
+        converged = delta < tol;
+    }
+    return { scores: rank, iterations: it, converged };
+}

package/src/indexed/structures/arc-source.ts

@@ -0,0 +1,25 @@
+import type { U32 } from "@graphty/graph-format";
+
+/**
+ * The source node of an arc, by binary search on `rowPtr`. `GraphSnapshot` exposes `arcSource(a)`
+ * (`graph-format/src/snapshot/graph-snapshot.ts:544`), but an `AdjacencyView` -- which is what the
+ * Port 1 and Port 2 signatures take, so that `reverse()` works as an input for free -- does not,
+ * so the predecessor walk carries its own.
+ * @param rowPtr - The view's nodeCount + 1 row offsets
+ * @param arc - An arc index in `[0, arcCount)`
+ * @returns The node index whose row contains the arc
+ * @public
+ */
+export function arcSourceIn(rowPtr: U32, arc: number): number {
+    let lo = 0;
+    let hi = rowPtr.length - 1; // nodeCount
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (rowPtr[mid + 1] <= arc) {
+            lo = mid + 1;
+        } else {
+            hi = mid;
+        }
+    }
+    return lo;
+}

package/src/indexed/structures/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Scratch structures for the index-based ports (graph-format design 14.2, section 14.6's
+ * helper-ownership sentence at `graph-format-design.md:4270`).
+ * @module
+ */
+
+export { arcSourceIn } from "./arc-source.js";
+export { IndexedMinHeap } from "./min-heap.js";
+export { IntUnionFind } from "./union-find.js";

package/src/indexed/structures/min-heap.ts

@@ -0,0 +1,122 @@
+import { type F64, INVALID_INDEX, type U32 } from "@graphty/graph-format";
+
+/**
+ * A binary min-heap over node indices with O(log n) decrease-key, keyed by `Float64Array` values
+ * (graph-format design 14.2, `graph-format-design.md:3771`). `pushOrDecrease` is the only operation
+ * Dijkstra's inner loop needs: it inserts an absent node and decreases a present one, so the heap
+ * never holds a stale duplicate and `pop()` needs no "is this entry current" check.
+ * @public
+ */
+export class IndexedMinHeap {
+    private readonly heap: U32; // slot -> node
+    private readonly slot: U32; // node -> slot, INVALID_INDEX when absent
+    private readonly key: F64; // node -> key
+    private size = 0;
+
+    /**
+     * Create an empty heap over node indices in `[0, capacity)`.
+     * @param capacity - The number of distinct node indices the heap may hold
+     */
+    constructor(capacity: number) {
+        this.heap = new Uint32Array(capacity);
+        this.slot = new Uint32Array(capacity).fill(INVALID_INDEX);
+        this.key = new Float64Array(capacity);
+    }
+
+    /**
+     * Whether the heap holds no entries.
+     * @returns True when the heap holds no entries
+     */
+    isEmpty(): boolean {
+        return this.size === 0;
+    }
+
+    /**
+     * Insert a node that is not in the heap.
+     * @param node - The node index
+     * @param key - Its key
+     */
+    push(node: number, key: number): void {
+        this.key[node] = key;
+        this.heap[this.size] = node;
+        this.slot[node] = this.size;
+        this.size++;
+        this.siftUp(this.size - 1);
+    }
+
+    /**
+     * Insert the node, or lower its key if it is already present and the new key is smaller.
+     * @param node - The node index
+     * @param key - Its candidate key
+     */
+    pushOrDecrease(node: number, key: number): void {
+        const at = this.slot[node];
+        if (at === INVALID_INDEX) {
+            this.push(node, key);
+            return;
+        }
+        if (key < this.key[node]) {
+            this.key[node] = key;
+            this.siftUp(at);
+        }
+    }
+
+    /**
+     * Remove and return the node with the smallest key. Undefined behaviour on an empty heap;
+     * callers guard with `isEmpty()`.
+     * @returns The node index
+     */
+    pop(): number {
+        const top = this.heap[0];
+        this.slot[top] = INVALID_INDEX;
+        this.size--;
+        if (this.size > 0) {
+            const moved = this.heap[this.size];
+            this.heap[0] = moved;
+            this.slot[moved] = 0;
+            this.siftDown(0);
+        }
+        return top;
+    }
+
+    private siftUp(from: number): void {
+        let at = from;
+        const node = this.heap[at];
+        const key = this.key[node];
+        while (at > 0) {
+            const parent = (at - 1) >> 1;
+            const parentNode = this.heap[parent];
+            if (this.key[parentNode] <= key) {
+                break;
+            }
+            this.heap[at] = parentNode;
+            this.slot[parentNode] = at;
+            at = parent;
+        }
+        this.heap[at] = node;
+        this.slot[node] = at;
+    }
+
+    private siftDown(from: number): void {
+        let at = from;
+        const node = this.heap[at];
+        const key = this.key[node];
+        for (;;) {
+            const left = 2 * at + 1;
+            if (left >= this.size) {
+                break;
+            }
+            const right = left + 1;
+            const child = right < this.size && this.key[this.heap[right]] < this.key[this.heap[left]] ? right : left;
+            const childNode = this.heap[child];
+            if (key <= this.key[childNode]) {
+                break;
+            }
+            this.heap[at] = childNode;
+            this.slot[childNode] = at;
+            at = child;
+        }
+        this.heap[at] = node;
+        this.slot[node] = at;
+    }
+}

package/src/indexed/structures/union-find.ts

@@ -0,0 +1,74 @@
+import { renumberPartition, type U32 } from "@graphty/graph-format";
+
+/**
+ * Index-keyed union-find over `[0, size)` with union by rank and path halving. The legacy
+ * `UnionFind` (`src/data-structures/union-find.ts`) is NodeId-keyed and stays where it is.
+ * @public
+ */
+export class IntUnionFind {
+    private readonly parent: U32;
+    private readonly rank: U32;
+
+    /**
+     * Create a union-find whose every element is a singleton set.
+     * @param size - The number of elements, each initially its own singleton set
+     */
+    constructor(size: number) {
+        this.parent = new Uint32Array(size);
+        this.rank = new Uint32Array(size);
+        for (let i = 0; i < size; i++) {
+            this.parent[i] = i;
+        }
+    }
+
+    /**
+     * Find the representative of an element's set, halving the path on the way up.
+     * @param x - An element index
+     * @returns The representative of x's set
+     */
+    find(x: number): number {
+        let node = x;
+        while (this.parent[node] !== node) {
+            this.parent[node] = this.parent[this.parent[node]]; // path halving
+            node = this.parent[node];
+        }
+        return node;
+    }
+
+    /**
+     * Merge the sets of two elements, attaching the shallower tree under the deeper one.
+     * @param a - An element index
+     * @param b - An element index
+     * @returns True when the two sets were distinct and have now been merged
+     */
+    union(a: number, b: number): boolean {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra === rb) {
+            return false;
+        }
+        if (this.rank[ra] < this.rank[rb]) {
+            this.parent[ra] = rb;
+        } else if (this.rank[ra] > this.rank[rb]) {
+            this.parent[rb] = ra;
+        } else {
+            this.parent[rb] = ra;
+            this.rank[ra]++;
+        }
+        return true;
+    }
+
+    /**
+     * Dense labels in FIRST-SEEN order, which is what makes `groups()` identical to the legacy
+     * iteration order and identical to the GPU's after its own `renumberPartition` readback
+     * (design 9.7's connectedComponents row).
+     * @returns The labels and the number of distinct sets
+     */
+    toLabels(): { readonly labels: U32; readonly count: number } {
+        const roots = new Uint32Array(this.parent.length);
+        for (let i = 0; i < roots.length; i++) {
+            roots[i] = this.find(i);
+        }
+        return renumberPartition(roots);
+    }
+}

package/src/indexed/to-snapshot.ts

@@ -0,0 +1,78 @@
+/**
+ * Conversion from the legacy `Graph` class to a frozen graph-format snapshot
+ * (graph-format design 14.1 rule 4, 14.6 row A1). This is the ONLY bridge between the legacy
+ * Map-of-Maps surface and `indexed.*`; nothing under `src/indexed/` other than this file imports
+ * `../core/graph.js`.
+ * @module
+ */
+
+import { GraphBuilder, type GraphSnapshot } from "@graphty/graph-format";
+
+import type { Graph } from "../core/graph.js";
+
+/** Options of {@link toSnapshot}. @public */
+export interface ToSnapshotOptions {
+    /**
+     * Record FNV-1a checksums at freeze so a caller can assert `snapshot.validate({ checksum: true })`
+     * (graph-format design 14.2's first port rule: views are shared, so a port that writes into one
+     * has to fail a test rather than corrupt the next call). Default false; the test suites set it.
+     */
+    readonly checksum?: boolean | undefined;
+}
+
+interface CacheEntry {
+    readonly mutationCount: number;
+    readonly checksum: boolean;
+    readonly snapshot: GraphSnapshot;
+}
+
+/**
+ * One entry per graph, REPLACED rather than appended to on a mutation. The entry holds the
+ * mutationCount it was built at, which is what makes a stale hit impossible -- the bug the old
+ * `WeakMap<Graph, CSRGraph>` cache had (graph-format design 14.1 rule 4).
+ */
+const SNAPSHOT_CACHE = new WeakMap<Graph, CacheEntry>();
+
+/**
+ * Freeze a legacy `Graph` into a `GraphSnapshot`, memoised on the graph's `mutationCount`.
+ *
+ * The builder is created with `weightDtype: "f64"` so a legacy graph's double weights survive
+ * exactly: at freeze, graph-format keeps the original values in an f64 edge column with role
+ * `weight` (the "shadow") whenever at least one of them is not f32-exact, and costs nothing when
+ * they all are (graph-format design section 3.7, `graph-format/src/builder/freeze.ts:332-360`).
+ * A weighted `indexed.*` port reproduces legacy f64 results by passing
+ * `expandEdges(s, shadow.data)` as its per-arc `weights` override.
+ *
+ * Every legacy edge carries a weight (`Graph.addEdge` defaults it to 1), so the builder's
+ * `weighted: "auto"` always allocates the arc weight array -- 4 bytes per arc. That is truthful
+ * rather than wasteful: the legacy graph really does store the value.
+ * @param graph - The legacy graph to convert
+ * @param options - Conversion options
+ * @returns A frozen snapshot of the graph's current topology and weights
+ * @public
+ */
+export function toSnapshot(graph: Graph, options: ToSnapshotOptions = {}): GraphSnapshot {
+    const checksum = options.checksum === true;
+    const cached = SNAPSHOT_CACHE.get(graph);
+    // A checksummed snapshot answers a plain request; a plain one cannot answer a checksummed
+    // request -- validate({ checksum: true }) throws E_INVALID_SNAPSHOT ("no-checksum") when none
+    // were recorded (graph-format/src/types/snapshot.ts:401-405).
+    if (cached !== undefined && cached.mutationCount === graph.mutationCount && (cached.checksum || !checksum)) {
+        return cached.snapshot;
+    }
+    const builder = new GraphBuilder({
+        directed: graph.isDirected,
+        weightDtype: "f64",
+        expectedNodes: graph.nodeCount,
+        expectedEdges: graph.totalEdgeCount,
+    });
+    for (const node of graph.nodes()) {
+        builder.addNode(node.id);
+    }
+    for (const edge of graph.edges()) {
+        builder.addEdge(edge.source, edge.target, edge.weight);
+    }
+    const snapshot = builder.freeze({ label: "algorithms.toSnapshot", checksum });
+    SNAPSHOT_CACHE.set(graph, { mutationCount: graph.mutationCount, checksum, snapshot });
+    return snapshot;
+}