@graphty/algorithms 2.0.6 → 2.1.0

package/src/indexed/components.ts

@@ -15,7 +15,14 @@ export interface LabelResult {
     groups(): U32[];
 }
 
-function withGroups(labels: U32, count: number): LabelResult {
+/**
+ * Wrap a dense label array as a `LabelResult`, computing the grouping on first use. Shared with the
+ * Louvain port, whose result is a partition with a modularity attached.
+ * @param labels - Dense label per node index
+ * @param count - Number of distinct labels
+ * @returns The partition
+ */
+export function withGroups(labels: U32, count: number): LabelResult {
     let cached: U32[] | null = null;
     return {
         labels,

package/src/indexed/hits.ts

@@ -0,0 +1,126 @@
+import type { F64, GraphSnapshot } from "@graphty/graph-format";
+
+/** Options of the index-based HITS, matching the legacy `hits`. @public */
+export interface HitsOptions {
+    /** Iteration cap; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** Convergence tolerance on the largest single-node change; default 1e-6. */
+    readonly tolerance?: number | undefined;
+    /**
+     * `false` rescales both vectors so their largest entry is 1, which is what the legacy function
+     * does when normalization is switched OFF -- the iteration itself always divides by the L2
+     * norm. Default true, i.e. the L2-normalized vectors are returned unchanged.
+     */
+    readonly normalized?: boolean | undefined;
+    /** Weight a neighbour's contribution by the arc weight; default false. */
+    readonly weighted?: boolean | undefined;
+}
+
+/** Result of the index-based HITS. @public */
+export interface HitsResult {
+    /** Hub score per node index. */
+    readonly hubs: F64;
+    /** Authority score per node index. */
+    readonly authorities: F64;
+    /** Iterations actually run. */
+    readonly iterations: number;
+    /** Whether the largest single-node change fell below the tolerance. */
+    readonly converged: boolean;
+}
+
+/**
+ * Divide a vector by its L2 norm, in place; a zero vector is left alone.
+ * @param v - The vector to scale
+ */
+function l2Normalize(v: Float64Array): void {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i] * v[i];
+    }
+    const norm = Math.sqrt(sum);
+    if (norm > 0) {
+        for (let i = 0; i < v.length; i++) {
+            v[i] /= norm;
+        }
+    }
+}
+
+/**
+ * Divide a vector by its largest entry, in place; left alone when that entry is not positive.
+ * @param v - The vector to scale
+ */
+function maxNormalize(v: Float64Array): void {
+    let max = 0;
+    for (let i = 0; i < v.length; i++) {
+        if (v[i] > max) {
+            max = v[i];
+        }
+    }
+    if (max > 0) {
+        for (let i = 0; i < v.length; i++) {
+            v[i] /= max;
+        }
+    }
+}
+
+/**
+ * HITS by alternating power iteration: an authority sums the hub scores of the nodes pointing at
+ * it, a hub sums the authority scores of the nodes it points at, and both vectors are
+ * L2-normalized every round. On an undirected snapshot the two adjacencies are the same array, so
+ * the hubs and the authorities coincide.
+ * @param s - The snapshot
+ * @param o - Algorithm options
+ * @returns The two score vectors, the iteration count and the convergence flag
+ * @public
+ */
+export function hits(s: GraphSnapshot, o: HitsOptions = {}): HitsResult {
+    const n = s.nodeCount;
+    const maxIter = o.maxIterations ?? 100;
+    const tol = o.tolerance ?? 1e-6;
+    const rev = s.reverse();
+    const fwdW = o.weighted === true ? s.weights : null;
+    const revW = o.weighted === true ? rev.weights : null;
+    let hubs = new Float64Array(n).fill(n === 0 ? 0 : 1 / Math.sqrt(n));
+    let authorities = new Float64Array(n).fill(n === 0 ? 0 : 1 / Math.sqrt(n));
+    let nextHubs = new Float64Array(n);
+    let nextAuthorities = new Float64Array(n);
+    let it = 0;
+    let converged = false;
+    for (; it < maxIter && !converged; it++) {
+        for (let v = 0; v < n; v++) {
+            let auth = 0;
+            const inEnd = rev.rowPtr[v + 1];
+            for (let a = rev.rowPtr[v]; a < inEnd; a++) {
+                auth += hubs[rev.colIdx[a]] * (revW === null ? 1 : revW[a]);
+            }
+            nextAuthorities[v] = auth;
+            let hub = 0;
+            const outEnd = s.rowPtr[v + 1];
+            for (let a = s.rowPtr[v]; a < outEnd; a++) {
+                hub += authorities[s.colIdx[a]] * (fwdW === null ? 1 : fwdW[a]);
+            }
+            nextHubs[v] = hub;
+        }
+        l2Normalize(nextAuthorities);
+        l2Normalize(nextHubs);
+        let maxDiff = 0;
+        for (let v = 0; v < n; v++) {
+            const dh = Math.abs(nextHubs[v] - hubs[v]);
+            if (dh > maxDiff) {
+                maxDiff = dh;
+            }
+            const da = Math.abs(nextAuthorities[v] - authorities[v]);
+            if (da > maxDiff) {
+                maxDiff = da;
+            }
+        }
+        [hubs, nextHubs] = [nextHubs, hubs];
+        [authorities, nextAuthorities] = [nextAuthorities, authorities];
+        converged = maxDiff < tol;
+    }
+    if (o.normalized === false) {
+        maxNormalize(hubs);
+        maxNormalize(authorities);
+    }
+    return { hubs, authorities, iterations: it, converged };
+}

package/src/indexed/index.ts

@@ -16,13 +16,11 @@
 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 { dijkstra, type SsspOptions, type SsspResult, walkPredArcs, walkPredEdges } from "./dijkstra.js";
+export { hits, type HitsOptions, type HitsResult } from "./hits.js";
+export { type CorenessResult, kCoreDecomposition } from "./k-core.js";
+export { katzCentrality, type KatzOptions, type KatzResult } from "./katz.js";
+export { louvain, type LouvainOptions, type LouvainResult } from "./louvain.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/k-core.ts

@@ -0,0 +1,138 @@
+import type { GraphSnapshot, U32 } from "@graphty/graph-format";
+
+/**
+ * Result of the index-based k-core decomposition. `coreness` is the shape the accelerator seam
+ * declares (`CorenessResultLike`); `maxCore` and `cores()` are what the legacy
+ * `kCoreDecomposition` returns as `maxCore` and its `cores` map.
+ * @public
+ */
+export interface CorenessResult {
+    /** Core number per node index. */
+    readonly coreness: U32;
+    /** The largest core number present; 0 on an empty graph. */
+    readonly maxCore: number;
+    /**
+     * Node indices grouped by core number, computed once and cached: `cores()[k]` holds the nodes
+     * whose coreness is exactly k, so the array has `maxCore + 1` entries.
+     * @returns One array per core number
+     */
+    cores(): U32[];
+}
+
+/**
+ * Core number of every node, by the Batagelj-Zaversnik bucket peel: O(nodes + arcs), no priority
+ * queue and no per-node object.
+ *
+ * Core numbers are defined on a SIMPLE graph, so a parallel arc counts once (parallels are
+ * adjacent within a row, invariant I4) and a self-loop does not count at all -- which is what the
+ * legacy implementation's adjacency-of-sets also does, and what NetworkX requires of its input.
+ * @param s - An undirected snapshot
+ * @returns The core numbers, the largest of them, and the lazy grouping
+ * @public
+ */
+export function kCoreDecomposition(s: GraphSnapshot): CorenessResult {
+    if (s.directed) {
+        throw new Error("k-core requires an undirected graph. Pass s.toUndirected().snapshot.");
+    }
+    const n = s.nodeCount;
+    const { rowPtr, colIdx } = s;
+    // degree[] is peeled in place: when a node is visited its entry is already its core number.
+    const degree = new Uint32Array(n);
+    let maxDegree = 0;
+    for (let u = 0; u < n; u++) {
+        let d = 0;
+        let last = -1;
+        const end = rowPtr[u + 1];
+        for (let a = rowPtr[u]; a < end; a++) {
+            const v = colIdx[a];
+            if (v !== u && v !== last) {
+                d++;
+            }
+            last = v;
+        }
+        degree[u] = d;
+        if (d > maxDegree) {
+            maxDegree = d;
+        }
+    }
+    // Bucket sort the nodes by degree; bin[d] is the start of degree d's block in vert.
+    const bin = new Uint32Array(maxDegree + 1);
+    for (let u = 0; u < n; u++) {
+        bin[degree[u]]++;
+    }
+    let start = 0;
+    for (let d = 0; d <= maxDegree; d++) {
+        const count = bin[d];
+        bin[d] = start;
+        start += count;
+    }
+    const vert = new Uint32Array(n);
+    const pos = new Uint32Array(n);
+    for (let u = 0; u < n; u++) {
+        pos[u] = bin[degree[u]];
+        vert[pos[u]] = u;
+        bin[degree[u]]++;
+    }
+    for (let d = maxDegree; d > 0; d--) {
+        bin[d] = bin[d - 1];
+    }
+    bin[0] = 0;
+    // Peel in nondecreasing degree order. A neighbour of higher degree swaps to the front of its
+    // bucket and loses one, which keeps vert sorted without re-sorting it.
+    let maxCore = 0;
+    for (let i = 0; i < n; i++) {
+        const v = vert[i];
+        const dv = degree[v];
+        if (dv > maxCore) {
+            maxCore = dv;
+        }
+        const end = rowPtr[v + 1];
+        let last = -1;
+        for (let a = rowPtr[v]; a < end; a++) {
+            const u = colIdx[a];
+            const skip = u === v || u === last;
+            last = u;
+            if (skip) {
+                continue;
+            }
+            const du = degree[u];
+            if (du > dv) {
+                const pu = pos[u];
+                const pw = bin[du];
+                const w = vert[pw];
+                if (u !== w) {
+                    vert[pu] = w;
+                    vert[pw] = u;
+                    pos[u] = pw;
+                    pos[w] = pu;
+                }
+                bin[du]++;
+                degree[u] = du - 1;
+            }
+        }
+    }
+    let cached: U32[] | null = null;
+    return {
+        coreness: degree,
+        maxCore,
+        cores(): U32[] {
+            if (cached === null) {
+                const sizes = new Uint32Array(maxCore + 1);
+                for (let u = 0; u < n; u++) {
+                    sizes[degree[u]]++;
+                }
+                const out: U32[] = [];
+                for (let k = 0; k <= maxCore; k++) {
+                    out.push(new Uint32Array(sizes[k]));
+                }
+                const fill = new Uint32Array(maxCore + 1);
+                for (let u = 0; u < n; u++) {
+                    const k = degree[u];
+                    out[k][fill[k]++] = u;
+                }
+                cached = out;
+            }
+            return cached;
+        },
+    };
+}

package/src/indexed/katz.ts

@@ -0,0 +1,88 @@
+import type { F64, GraphSnapshot } from "@graphty/graph-format";
+
+/** Options of the index-based Katz centrality, matching the legacy `katzCentrality`. @public */
+export interface KatzOptions {
+    /** Attenuation factor applied to a neighbour's score; default 0.1. */
+    readonly alpha?: number | undefined;
+    /** Base score every node starts with and keeps; default 1. */
+    readonly beta?: number | undefined;
+    /** Iteration cap; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** Convergence tolerance on the largest single-node change; default 1e-6. */
+    readonly tolerance?: number | undefined;
+    /** Rescale the scores to [0, 1] by min-max, as the legacy function does; default true. */
+    readonly normalized?: boolean | undefined;
+    /** Weight a neighbour's contribution by the arc weight; default false. */
+    readonly weighted?: boolean | undefined;
+}
+
+/** Result of the index-based Katz centrality. @public */
+export interface KatzResult {
+    /** Score per node index. */
+    readonly scores: F64;
+    /** Iterations actually run. */
+    readonly iterations: number;
+    /** Whether the largest single-node change fell below the tolerance. */
+    readonly converged: boolean;
+}
+
+/**
+ * Katz centrality by power iteration over incoming arcs: `x[v] = alpha * sum(x[u] for u -> v) + beta`.
+ *
+ * `reverse()` supplies the in-arcs, and is the forward adjacency itself on an undirected snapshot,
+ * so one loop serves both directions exactly as the legacy function's in-neighbours / neighbours
+ * split does.
+ * @param s - The snapshot
+ * @param o - Algorithm options
+ * @returns The scores, the iteration count and the convergence flag
+ * @public
+ */
+export function katzCentrality(s: GraphSnapshot, o: KatzOptions = {}): KatzResult {
+    const n = s.nodeCount;
+    const alpha = o.alpha ?? 0.1;
+    const beta = o.beta ?? 1;
+    const maxIter = o.maxIterations ?? 100;
+    const tol = o.tolerance ?? 1e-6;
+    const rev = s.reverse();
+    const weights = o.weighted === true ? rev.weights : null;
+    let cur = new Float64Array(n).fill(beta);
+    let next = new Float64Array(n);
+    let it = 0;
+    let converged = false;
+    for (; it < maxIter && !converged; it++) {
+        let maxDiff = 0;
+        for (let v = 0; v < n; v++) {
+            let sum = 0;
+            const end = rev.rowPtr[v + 1];
+            for (let a = rev.rowPtr[v]; a < end; a++) {
+                sum += cur[rev.colIdx[a]] * (weights === null ? 1 : weights[a]);
+            }
+            next[v] = alpha * sum + beta;
+            const diff = Math.abs(next[v] - cur[v]);
+            if (diff > maxDiff) {
+                maxDiff = diff;
+            }
+        }
+        [cur, next] = [next, cur];
+        converged = maxDiff < tol;
+    }
+    if (o.normalized !== false) {
+        let min = Infinity;
+        let max = -Infinity;
+        for (let v = 0; v < n; v++) {
+            if (cur[v] < min) {
+                min = cur[v];
+            }
+            if (cur[v] > max) {
+                max = cur[v];
+            }
+        }
+        const range = max - min;
+        if (range > 0) {
+            for (let v = 0; v < n; v++) {
+                cur[v] = (cur[v] - min) / range;
+            }
+        }
+    }
+    return { scores: cur, iterations: it, converged };
+}