@graphty/algorithms 2.1.1 → 2.2.0

package/dist/src/indexed/sync.js

@@ -0,0 +1,175 @@
+import { SeededRandom } from "../utils/math-utilities.js";
+/**
+ * Euclidean distance between two rows of a row-major matrix.
+ * @param a - First matrix
+ * @param i - Row of a
+ * @param b - Second matrix
+ * @param j - Row of b
+ * @param dim - Row length
+ * @returns The distance
+ */
+function distance(a, i, b, j, dim) {
+    let sum = 0;
+    for (let k = 0; k < dim; k++) {
+        const diff = a[i * dim + k] - b[j * dim + k];
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * SynC over a snapshot: node embeddings seeded from degree and a seeded generator, pulled toward
+ * their out-neighbours by gradient steps, and clustered by k-means with k-means++ centres. The
+ * arithmetic, and the order of every random draw, are the legacy `syncClustering`'s, so for the same
+ * seed the labels and embeddings agree with it to rounding; the port draws from its own generator
+ * instead of replacing `Math.random` for the duration of the call.
+ *
+ * Weights are ignored and a parallel arc pulls once per arc. The seeding degree is legacy's: in plus
+ * out when directed, the stored arc count when undirected, so an undirected self-loop counts once.
+ * @param s - The snapshot
+ * @param options - {@link SyncClusteringOptions}
+ * @returns Assignments, embeddings and convergence
+ */
+export function syncClustering(s, options) {
+    const { numClusters, maxIterations = 100, tolerance = 1e-6, seed = 42, learningRate = 0.01, lambda = 0.1, } = options;
+    const n = s.nodeCount;
+    if (n === 0) {
+        return {
+            labels: new Uint32Array(0),
+            count: numClusters,
+            embeddings: new Float64Array(0),
+            dimensions: 0,
+            loss: 0,
+            previousLoss: Infinity,
+            iterations: 0,
+            converged: true,
+        };
+    }
+    if (!Number.isInteger(numClusters) || numClusters <= 0 || numClusters > n) {
+        throw new Error(`Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(n)}`);
+    }
+    const random = SeededRandom.createGenerator(seed);
+    const dim = Math.min(64, n);
+    const { rowPtr, colIdx } = s;
+    const emb = new Float64Array(n * dim);
+    // Legacy's degree: an undirected self-loop counts once (its single stored arc), not twice.
+    const degree = s.directed ? s.degree() : s.outDegree();
+    for (let u = 0; u < n; u++) {
+        const normalized = degree[u] / Math.max(1, n - 1);
+        for (let k = 0; k < dim; k++) {
+            emb[u * dim + k] = (random() - 0.5) * 0.1 + normalized * 0.1;
+        }
+    }
+    // k-means++: the first centre uniformly, each next one with probability proportional to the
+    // squared distance to the nearest centre so far. A draw that rounding carries past the last
+    // node adds no centre, as in legacy, so there may be fewer than numClusters.
+    const centres = new Float64Array(numClusters * dim);
+    const pick = Math.floor(random() * n);
+    centres.set(emb.subarray(pick * dim, (pick + 1) * dim), 0);
+    let centreCount = 1;
+    const weight = new Float64Array(n);
+    for (let k = 1; k < numClusters; k++) {
+        let total = 0;
+        for (let u = 0; u < n; u++) {
+            let nearest = Infinity;
+            for (let c = 0; c < centreCount; c++) {
+                nearest = Math.min(nearest, distance(emb, u, centres, c, dim));
+            }
+            weight[u] = nearest * nearest;
+            total += nearest * nearest;
+        }
+        let draw = random() * total;
+        for (let u = 0; u < n; u++) {
+            draw -= weight[u];
+            if (draw <= 0) {
+                centres.set(emb.subarray(u * dim, (u + 1) * dim), centreCount * dim);
+                centreCount++;
+                break;
+            }
+        }
+    }
+    const labels = new Uint32Array(n);
+    const assign = () => {
+        for (let u = 0; u < n; u++) {
+            let bestCentre = 0;
+            let bestDistance = Infinity;
+            for (let c = 0; c < centreCount; c++) {
+                const d = distance(emb, u, centres, c, dim);
+                if (d < bestDistance) {
+                    bestDistance = d;
+                    bestCentre = c;
+                }
+            }
+            labels[u] = bestCentre;
+        }
+    };
+    const gradient = new Float64Array(n * dim);
+    const sums = new Float64Array(numClusters * dim);
+    const sizes = new Uint32Array(numClusters);
+    let previousLoss = Infinity;
+    let loss = Infinity;
+    let iterations = 0;
+    let converged = false;
+    while (iterations < maxIterations) {
+        iterations++;
+        assign();
+        // Every gradient from the embeddings before this step, then one step for all.
+        gradient.fill(0);
+        for (let u = 0; u < n; u++) {
+            const row = u * dim;
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                const other = colIdx[a] * dim;
+                for (let k = 0; k < dim; k++) {
+                    gradient[row + k] += lambda * (emb[row + k] - emb[other + k]);
+                }
+            }
+            for (let k = 0; k < dim; k++) {
+                gradient[row + k] += lambda * emb[row + k];
+            }
+        }
+        for (let i = 0; i < emb.length; i++) {
+            emb[i] -= learningRate * gradient[i];
+        }
+        sums.fill(0);
+        sizes.fill(0);
+        for (let u = 0; u < n; u++) {
+            const c = labels[u];
+            for (let k = 0; k < dim; k++) {
+                sums[c * dim + k] += emb[u * dim + k];
+            }
+            sizes[c]++;
+        }
+        for (let c = 0; c < centreCount; c++) {
+            if (sizes[c] > 0) {
+                for (let k = 0; k < dim; k++) {
+                    centres[c * dim + k] = sums[c * dim + k] / sizes[c];
+                }
+            }
+        }
+        let clustering = 0;
+        let reconstruction = 0;
+        let regularization = 0;
+        for (let u = 0; u < n; u++) {
+            clustering += distance(emb, u, centres, labels[u], dim) ** 2;
+        }
+        for (let u = 0; u < n; u++) {
+            for (let a = rowPtr[u]; a < rowPtr[u + 1]; a++) {
+                reconstruction += distance(emb, u, emb, colIdx[a], dim) ** 2;
+            }
+        }
+        for (const value of emb) {
+            regularization += value ** 2;
+        }
+        const current = clustering + lambda * reconstruction + lambda * regularization;
+        if (iterations > 1) {
+            previousLoss = loss;
+        }
+        loss = current;
+        if (Math.abs(previousLoss - loss) < tolerance) {
+            converged = true;
+            break;
+        }
+    }
+    assign();
+    return { labels, count: numClusters, embeddings: emb, dimensions: dim, loss, previousLoss, iterations, converged };
+}
+//# sourceMappingURL=sync.js.map

package/dist/src/indexed/sync.js.map

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

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

@@ -0,0 +1,58 @@
+import { type F64, type GraphSnapshot, type U32 } from "@graphty/graph-format";
+import { type LabelResult } from "./components.js";
+/** Options of the index-based TeraHAC, matching the legacy `teraHAC`. @public */
+export interface TeraHacOptions {
+    /**
+     * How the distance between two clusters is read from their members' pairwise distances: the
+     * minimum, the maximum, the mean, or (`"ward"`) the mean of the squares; default `"average"`.
+     */
+    readonly linkage?: "single" | "complete" | "average" | "ward" | undefined;
+    /** Stop merging at this many clusters; a positive integer. Default: merge until one is left. */
+    readonly numClusters?: number | undefined;
+    /** Stop at the first merge whose linkage distance is above this. Default: no threshold. */
+    readonly distanceThreshold?: number | undefined;
+    /**
+     * Pairwise distance: hop count along out-arcs (true, the default), or 1 for an arc from the
+     * lower to the higher node index and 2 for none (false).
+     */
+    readonly useGraphDistance?: boolean | undefined;
+}
+/**
+ * Result of the index-based TeraHAC: the flat clustering plus the dendrogram. Dendrogram node
+ * `i < n` is node index i; node `n + k` is the k-th join, with children `left[k]` and `right[k]`.
+ * @public
+ */
+export interface TeraHacResult extends LabelResult {
+    /** Left child of each join (the legacy `ClusterNode.left`). */
+    readonly left: U32;
+    /** Right child of each join. */
+    readonly right: U32;
+    /** Linkage distance of each join; Infinity for the joins that tie the remaining clusters under one root. */
+    readonly distance: F64;
+    /** Node count under each join. */
+    readonly size: U32;
+    /** Joins made by distance: `distance.subarray(0, merges)` is the legacy `distances` list. */
+    readonly merges: number;
+    /** The dendrogram root: `2n - 2`, or 0 for a single node. */
+    readonly root: number;
+}
+/**
+ * TeraHAC over a snapshot: agglomerative clustering that repeatedly merges the closest pair of
+ * clusters, with the same distances, merge order and tie-breaks as the legacy `teraHAC` -- but
+ * over node indices, so the result no longer depends on what the node ids are.
+ *
+ * The linkage is kept per ordered cluster pair as an aggregate (minimum, maximum, sum of distances
+ * or sum of squared distances) and updated on each merge, instead of rescanning every member pair;
+ * the pairwise distances are integers, so the sums, and the means divided out of them, are exact.
+ * A pair's distance reads the aggregate in the orientation legacy reads it, which matters on a
+ * directed snapshot, and ties go to the pair legacy's stable sort puts first: two original nodes
+ * before any pair with a merged cluster, and among those the most recent merge last.
+ *
+ * Weights are ignored (legacy counts hops). O(n^2) memory and O(n (n + m)) for the distances; the
+ * merging keeps each cluster's closest partner and rescans a row only when that partner merges.
+ * @param s - The snapshot
+ * @param options - {@link TeraHacOptions}
+ * @returns The flat clustering and the dendrogram
+ */
+export declare function teraHAC(s: GraphSnapshot, options?: TeraHacOptions): TeraHacResult;
+//# sourceMappingURL=terahac.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terahac.d.ts","sourceRoot":"","sources":["../../../src/indexed/terahac.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAqB,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAElG,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,iBAAiB,CAAC;AAE/D,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1E,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,WAAW;IAC9C,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;IACpB,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AA8CD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CAoJrF"}

package/dist/src/indexed/terahac.js

@@ -0,0 +1,244 @@
+import { renumberPartition } from "@graphty/graph-format";
+import { withGroups } from "./components.js";
+/** The distance legacy gives an unreachable pair, so that disconnected clusters still merge last. */
+const UNREACHABLE = 100;
+/**
+ * All-pairs distances into a row-major n x n matrix: BFS hop counts along out-arcs (Infinity when
+ * unreachable) or the 1 / 2 adjacency distance.
+ * @param s - The snapshot
+ * @param useGraphDistance - Which distance
+ * @returns The matrix
+ */
+function pairwiseDistances(s, useGraphDistance) {
+    const n = s.nodeCount;
+    const d = new Float64Array(n * n);
+    if (!useGraphDistance) {
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                d[i * n + j] = d[j * n + i] = s.hasArc(i, j) ? 1 : 2;
+            }
+        }
+        return d;
+    }
+    d.fill(Infinity);
+    const queue = new Uint32Array(n);
+    for (let source = 0; source < n; source++) {
+        const row = source * n;
+        d[row + source] = 0;
+        queue[0] = source;
+        let head = 0;
+        let tail = 1;
+        while (head < tail) {
+            const u = queue[head++];
+            const next = d[row + u] + 1;
+            for (let a = s.rowPtr[u]; a < s.rowPtr[u + 1]; a++) {
+                const v = s.colIdx[a];
+                if (d[row + v] === Infinity) {
+                    d[row + v] = next;
+                    queue[tail++] = v;
+                }
+            }
+        }
+    }
+    return d;
+}
+/**
+ * TeraHAC over a snapshot: agglomerative clustering that repeatedly merges the closest pair of
+ * clusters, with the same distances, merge order and tie-breaks as the legacy `teraHAC` -- but
+ * over node indices, so the result no longer depends on what the node ids are.
+ *
+ * The linkage is kept per ordered cluster pair as an aggregate (minimum, maximum, sum of distances
+ * or sum of squared distances) and updated on each merge, instead of rescanning every member pair;
+ * the pairwise distances are integers, so the sums, and the means divided out of them, are exact.
+ * A pair's distance reads the aggregate in the orientation legacy reads it, which matters on a
+ * directed snapshot, and ties go to the pair legacy's stable sort puts first: two original nodes
+ * before any pair with a merged cluster, and among those the most recent merge last.
+ *
+ * Weights are ignored (legacy counts hops). O(n^2) memory and O(n (n + m)) for the distances; the
+ * merging keeps each cluster's closest partner and rescans a row only when that partner merges.
+ * @param s - The snapshot
+ * @param options - {@link TeraHacOptions}
+ * @returns The flat clustering and the dendrogram
+ */
+export function teraHAC(s, options = {}) {
+    const { linkage = "average", numClusters, distanceThreshold, useGraphDistance = true } = options;
+    if (numClusters !== undefined && (numClusters < 1 || !Number.isInteger(numClusters))) {
+        throw new Error("numClusters must be a positive integer");
+    }
+    const n = s.nodeCount;
+    if (n === 0) {
+        throw new Error("Cannot cluster empty graph");
+    }
+    // ponytail: dense n x n aggregate matrix, the same memory as legacy's distance matrix; a sparse
+    // candidate structure is the upgrade if graphs past ~10k nodes need this.
+    const agg = pairwiseDistances(s, useGraphDistance);
+    if (linkage === "ward") {
+        for (let i = 0; i < agg.length; i++) {
+            agg[i] *= agg[i];
+        }
+    }
+    const extremes = { single: Math.min, complete: Math.max, average: null, ward: null };
+    const extreme = extremes[linkage];
+    const joins = Math.max(0, n - 1);
+    const left = new Uint32Array(joins);
+    const right = new Uint32Array(joins);
+    const distance = new Float64Array(joins);
+    const size = new Uint32Array(joins);
+    // Slot i holds one active cluster: its dendrogram id, its size, and its closest partner.
+    const clusterId = new Uint32Array(n);
+    const members = new Uint32Array(n).fill(1);
+    const active = new Uint8Array(n).fill(1);
+    for (let i = 0; i < n; i++) {
+        clusterId[i] = i;
+    }
+    const orient = (x, y) => {
+        // true when x is the pair's first cluster: the lower id of two originals, else the newer one
+        const a = clusterId[x];
+        const b = clusterId[y];
+        return a < n && b < n ? a < b : a > b;
+    };
+    const pairDistance = (x, y) => {
+        const [p, q] = orient(x, y) ? [x, y] : [y, x];
+        let value = agg[p * n + q];
+        if (clusterId[p] < n && clusterId[q] < n) {
+            // Legacy reads two original nodes' distance straight from the matrix, unsquared even for ward.
+            value = linkage === "ward" ? Math.sqrt(value) : value;
+        }
+        else if (!extreme) {
+            value /= members[p] * members[q];
+        }
+        return value === Infinity ? UNREACHABLE : value;
+    };
+    const pairOrder = (x, y) => {
+        const a = clusterId[x];
+        const b = clusterId[y];
+        const lo = Math.min(a, b);
+        const hi = Math.max(a, b);
+        return hi < n ? lo * n + hi : n * n + hi * 2 * n + lo;
+    };
+    const best = new Int32Array(n).fill(-1);
+    const bestDistance = new Float64Array(n);
+    const bestOrder = new Float64Array(n);
+    const offer = (x, y) => {
+        const d = pairDistance(x, y);
+        const o = pairOrder(x, y);
+        if (best[x] === -1 || d < bestDistance[x] || (d === bestDistance[x] && o < bestOrder[x])) {
+            best[x] = y;
+            bestDistance[x] = d;
+            bestOrder[x] = o;
+        }
+    };
+    const rescan = (x) => {
+        best[x] = -1;
+        for (let y = 0; y < n; y++) {
+            if (active[y] && y !== x) {
+                offer(x, y);
+            }
+        }
+    };
+    for (let x = 0; x < n; x++) {
+        rescan(x);
+    }
+    let remaining = n;
+    let merges = 0;
+    while (remaining > 1 && (numClusters === undefined || remaining > numClusters)) {
+        let x = -1;
+        for (let i = 0; i < n; i++) {
+            if (active[i] &&
+                (x === -1 ||
+                    bestDistance[i] < bestDistance[x] ||
+                    (bestDistance[i] === bestDistance[x] && bestOrder[i] < bestOrder[x]))) {
+                x = i;
+            }
+        }
+        const d = bestDistance[x];
+        if (distanceThreshold !== undefined && d > distanceThreshold) {
+            break;
+        }
+        const [keep, drop] = orient(x, best[x]) ? [x, best[x]] : [best[x], x];
+        left[merges] = clusterId[keep];
+        right[merges] = clusterId[drop];
+        distance[merges] = d;
+        size[merges] = members[keep] + members[drop];
+        for (let c = 0; c < n; c++) {
+            if (active[c] && c !== keep && c !== drop) {
+                const kc = keep * n + c;
+                const dc = drop * n + c;
+                const ck = c * n + keep;
+                const cd = c * n + drop;
+                agg[kc] = extreme ? extreme(agg[kc], agg[dc]) : agg[kc] + agg[dc];
+                agg[ck] = extreme ? extreme(agg[ck], agg[cd]) : agg[ck] + agg[cd];
+            }
+        }
+        clusterId[keep] = n + merges;
+        members[keep] = size[merges];
+        active[drop] = 0;
+        merges++;
+        remaining--;
+        rescan(keep);
+        for (let c = 0; c < n; c++) {
+            if (active[c] && c !== keep) {
+                if (best[c] === keep || best[c] === drop) {
+                    rescan(c);
+                }
+                else {
+                    offer(c, keep);
+                }
+            }
+        }
+    }
+    // Tie what is left under one root, in ascending cluster id, as legacy does.
+    const rest = Array.from(clusterId.filter((_, i) => active[i] === 1)).sort((a, b) => a - b);
+    let root = rest[0];
+    const sizeOf = (c) => (c < n ? 1 : size[c - n]);
+    for (let k = 1; k < rest.length; k++) {
+        const j = merges + k - 1;
+        left[j] = root;
+        right[j] = rest[k];
+        distance[j] = Infinity;
+        size[j] = sizeOf(root) + sizeOf(rest[k]);
+        root = n + j;
+    }
+    const cut = cutDendrogram(n, left, right, root, numClusters ?? remaining);
+    const { labels, count } = renumberPartition(cut);
+    return { ...withGroups(labels, count), left, right, distance, size, merges, root };
+}
+/**
+ * Legacy's flat clustering: split dendrogram nodes breadth-first from the root until splitting the
+ * next one would exceed `k` clusters, then label every node by the cluster above it.
+ * @param n - Node count
+ * @param left - Left child of each join
+ * @param right - Right child of each join
+ * @param root - The root
+ * @param k - The cluster count asked for
+ * @returns A cluster number per node index
+ */
+function cutDendrogram(n, left, right, root, k) {
+    const kept = [];
+    const queue = [root];
+    let head = 0;
+    while (head < queue.length && kept.length < k) {
+        const c = queue[head++];
+        if (c < n || k === 1 || kept.length + (queue.length - head) + 1 >= k) {
+            kept.push(c);
+        }
+        else {
+            queue.push(left[c - n], right[c - n]);
+        }
+    }
+    const labels = new Uint32Array(n);
+    kept.forEach((top, label) => {
+        const stack = [top];
+        while (stack.length > 0) {
+            const c = stack.pop() ?? 0;
+            if (c < n) {
+                labels[c] = label;
+            }
+            else {
+                stack.push(left[c - n], right[c - n]);
+            }
+        }
+    });
+    return labels;
+}
+//# sourceMappingURL=terahac.js.map

package/dist/src/indexed/terahac.js.map

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

package/dist/src/indexed/to-snapshot.d.ts

@@ -5,7 +5,7 @@
  * `../core/graph.js`.
  * @module
  */
-import { type GraphSnapshot } from "@graphty/graph-format";
+import { type GraphSnapshot, type U32 } from "@graphty/graph-format";
 import type { Graph } from "../core/graph.js";
 /** Options of {@link toSnapshot}. @public */
 export interface ToSnapshotOptions {
@@ -17,7 +17,8 @@ export interface ToSnapshotOptions {
     readonly checksum?: boolean | undefined;
 }
 /**
- * Freeze a legacy `Graph` into a `GraphSnapshot`, memoised on the graph's `mutationCount`.
+ * Freeze a legacy `Graph` into a `GraphSnapshot`, memoised on the graph's `mutationCount` and its
+ * edge weights (a weight set in place does not move the counter, so a hit re-reads the weights).
  *
  * 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
@@ -35,4 +36,46 @@ export interface ToSnapshotOptions {
  * @public
  */
 export declare function toSnapshot(graph: Graph, options?: ToSnapshotOptions): GraphSnapshot;
+/**
+ * {@link toSnapshot}, or null when an edge weight is NaN: a legacy `Graph` accepts one, a snapshot
+ * does not. A facade whose legacy answer depends on how NaN compares keeps its legacy code for such
+ * a graph.
+ * @param graph - The legacy graph
+ * @param options - Conversion options
+ * @returns The snapshot, or null
+ */
+export declare function toSnapshotOrNull(graph: Graph, options?: ToSnapshotOptions): GraphSnapshot | null;
+/**
+ * A snapshot for a port that reads no weights (a traversal, the components, a clustering or link
+ * prediction that counts neighbours): {@link toSnapshot}, or,
+ * when a NaN weight stops that, the same nodes and edges frozen without weights, so a graph with a
+ * NaN weight traverses as it always did.
+ * @param graph - The legacy graph
+ * @returns The snapshot; its weights are not to be read
+ */
+export declare function toTopologySnapshot(graph: Graph): GraphSnapshot;
+/**
+ * The order a legacy `Graph` hands out each node's neighbours in, as the `arcOrder` option of the
+ * order-sensitive traversals (`depthFirstSearch`, `topologicalSort`, `stronglyConnectedComponents`,
+ * `condensation`, `breadthFirstSearch`). A snapshot row is sorted by neighbour index, while the
+ * legacy adjacency Map is in insertion order, so a traversal that must visit nodes in the legacy
+ * order -- a facade keeping its published result -- passes this.
+ * @param graph - The legacy graph
+ * @param s - A snapshot with the graph's nodes in the same order and its neighbour pairs, such as
+ *   `toSnapshot(graph)`; parallel arcs of one pair are kept together in row order
+ * @returns For every row, its arcs in legacy neighbour order
+ */
+export declare function legacyArcOrder(graph: Graph, s: GraphSnapshot): U32;
+/**
+ * Whether a facade must run its legacy code on this graph because a snapshot cannot stand in for it:
+ * - an edge weight is NaN, which the graph-format builder rejects, so `toSnapshot` would throw where
+ *   the legacy code returns a result (the unweighted functions never even read the weight);
+ * - two node ids share a spelling (the number 1 and the string "1"), so a result keyed by
+ *   `String(id)` holds one entry for both, and which value it holds depends on how the legacy code
+ *   wrote it (betweenness adds the two, others keep the last).
+ * Memoised on the graph's `mutationCount`, like {@link toSnapshot}.
+ * @param graph - The legacy graph
+ * @returns True when the facade must call its legacy implementation
+ */
+export declare function needsLegacyCode(graph: Graph): boolean;
 //# sourceMappingURL=to-snapshot.d.ts.map

package/dist/src/indexed/to-snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-snapshot.d.ts","sourceRoot":"","sources":["../../../src/indexed/to-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3C;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,iBAAsB,GAAG,aAAa,CAwBvF"}
+{"version":3,"file":"to-snapshot.d.ts","sourceRoot":"","sources":["../../../src/indexed/to-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAkC,KAAK,aAAa,EAAE,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAErG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3C;AAoCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,iBAAsB,GAAG,aAAa,CAGvF;AAkDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,iBAAsB,GAAG,aAAa,GAAG,IAAI,CASpG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,aAAa,GAAG,GAAG,CAqBlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAqBrD"}