@graphty/graph-samples 0.0.1 → 0.1.1

package/src/generators/trees-and-dags.ts

@@ -0,0 +1,139 @@
+/**
+ * Random trees and random directed acyclic graphs.
+ */
+
+import { type U32 } from "@graphty/graph-format";
+
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { bernoulliSegment, binomialBuffer, checkInt, checkProbability, EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** Options of {@link randomTreeGraph}. */
+export interface RandomTreeOptions extends WeightOptions {
+    /** The node count, >= 1. */
+    n: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * A uniformly random labelled tree: a uniformly random Pruefer sequence (H. Pruefer, Archiv der
+ * Mathematik und Physik 27, 142-144, 1918) of n - 2 draws nextBelow(n) from stream (seed,
+ * "prufer", 0), decoded in O(n). Edge k joins the k-th removed leaf to its neighbour; the last
+ * edge is (leaf, n - 1).
+ * @param options - n and seed
+ * @returns the undirected tree
+ */
+export function randomTreeGraph(options: RandomTreeOptions): SampleGraph {
+    const { n } = options;
+    checkInt("n", n, 1);
+    const seed = resolveSeed(options.seed);
+    const out = new EdgeBuffer(n);
+    if (n === 1) {
+        return applyWeights(toGraph(1, out, false), options);
+    }
+    const stream = new RandomStream(seed, "prufer", 0);
+    const code = new Uint32Array(n - 2);
+    const degree = new Uint32Array(n).fill(1);
+    for (let i = 0; i < n - 2; i++) {
+        code[i] = stream.nextBelow(n);
+        degree[code[i]]++;
+    }
+    let ptr = 0;
+    while (degree[ptr] !== 1) {
+        ptr++;
+    }
+    let leaf = ptr;
+    for (let i = 0; i < n - 2; i++) {
+        const v = code[i];
+        out.push(leaf, v);
+        degree[v]--;
+        if (degree[v] === 1 && v < ptr) {
+            leaf = v;
+        } else {
+            ptr++;
+            while (degree[ptr] !== 1) {
+                ptr++;
+            }
+            leaf = ptr;
+        }
+    }
+    out.push(leaf, n - 1);
+    return applyWeights(toGraph(n, out, false), options);
+}
+
+/** Options of {@link randomDagGraph}. */
+export interface RandomDagOptions extends WeightOptions {
+    /** The width of every layer, top to bottom; layer i holds the next `layers[i]` node indices. */
+    layers: readonly number[];
+    /** The probability of each arc from a node to a node of the next layer. */
+    p: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * Rows [start, end) of the layered DAG: node u of layer i < L - 1 draws from stream (seed,
+ * "layered-dag", u) and holds the arcs to the chosen nodes of layer i + 1, ascending.
+ * @param starts - starts[i] = first node of layer i; starts[L] = n
+ * @param layerOf - the layer of every node
+ * @param p - the probability
+ * @param seed - the seed
+ * @param start - the first row
+ * @param end - one past the last row
+ * @param out - receives the arcs
+ */
+export function dagRows(
+    starts: readonly number[],
+    layerOf: U32,
+    p: number,
+    seed: number,
+    start: number,
+    end: number,
+    out: EdgeBuffer,
+): void {
+    const logQ = detLog(1 - p);
+    const stream = new RandomStream(seed, "layered-dag", 0);
+    const last = starts.length - 2;
+    for (let u = start; u < end; u++) {
+        const layer = layerOf[u];
+        if (layer < last) {
+            stream.reset(u);
+            bernoulliSegment(stream, p, logQ, u, starts[layer + 1], starts[layer + 2], out);
+        }
+    }
+}
+
+/**
+ * A random layered DAG: arcs only from layer i to layer i + 1, each independently with
+ * probability p, O(n + m). The standard input for layered (Sugiyama) drawing, topological sort
+ * and longest path. Arcs are listed by source node, targets ascending. Node column `layer` (u32).
+ * @param options - layers, p and seed
+ * @returns the directed graph
+ */
+export function randomDagGraph(options: RandomDagOptions): SampleGraph {
+    const { layers, p } = options;
+    checkInt("layers.length", layers.length, 1);
+    checkProbability("p", p);
+    const seed = resolveSeed(options.seed);
+    const starts = [0];
+    let pairs = 0;
+    for (let i = 0; i < layers.length; i++) {
+        checkInt(`layers[${i}]`, layers[i], 0);
+        starts.push(starts[i] + layers[i]);
+        if (i > 0) {
+            pairs += layers[i - 1] * layers[i];
+        }
+    }
+    const n = starts[layers.length];
+    checkInt("the total size", n, 0);
+    const layerOf = new Uint32Array(n);
+    for (let i = 0; i < layers.length; i++) {
+        layerOf.fill(i, starts[i], starts[i + 1]);
+    }
+    const out = binomialBuffer(pairs, p);
+    dagRows(starts, layerOf, p, seed, 0, n, out);
+    return applyWeights(toGraph(n, out, true, { layer: layerOf }), options);
+}

package/src/generators/util.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared plumbing of the generators: argument checks, the growable edge buffer and the Bernoulli
+ * row sampler every G(n, p)-style generator is built on.
+ */
+
+import { MAX_COUNT, type U32 } from "@graphty/graph-format";
+
+import { type RandomStream } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+
+/**
+ * Throw unless `value` is an integer in [min, max].
+ * @param name - the option name, for the message
+ * @param value - the value
+ * @param min - the smallest allowed value
+ * @param max - the largest allowed value
+ */
+export function checkInt(name: string, value: number, min: number, max: number = MAX_COUNT): void {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new RangeError(`${name} must be an integer in [${min}, ${max}], got ${String(value)}`);
+    }
+}
+
+/**
+ * Throw unless `value` is a probability in [0, 1].
+ * @param name - the option name, for the message
+ * @param value - the value
+ */
+export function checkProbability(name: string, value: number): void {
+    if (!(value >= 0 && value <= 1)) {
+        throw new RangeError(`${name} must be a probability in [0, 1], got ${String(value)}`);
+    }
+}
+
+/**
+ * Throw unless `count` edges fit a graph-format snapshot.
+ * @param count - the edge count
+ */
+export function checkEdgeCount(count: number): void {
+    if (count > MAX_COUNT) {
+        throw new RangeError(`the graph would have ${count} edges, above the limit of ${MAX_COUNT}`);
+    }
+}
+
+/** A growable pair of Uint32Array edge endpoint arrays. */
+export class EdgeBuffer {
+    src: U32;
+    dst: U32;
+    length = 0;
+
+    /**
+     * An empty buffer.
+     * @param capacity - the initial capacity in edges
+     */
+    constructor(capacity: number) {
+        const size = Math.max(16, Math.min(capacity, MAX_COUNT));
+        this.src = new Uint32Array(size);
+        this.dst = new Uint32Array(size);
+    }
+
+    /**
+     * Append one edge.
+     * @param u - the source index
+     * @param v - the target index
+     */
+    push(u: number, v: number): void {
+        if (this.length === this.src.length) {
+            this.grow();
+        }
+        this.src[this.length] = u;
+        this.dst[this.length] = v;
+        this.length++;
+    }
+
+    /**
+     * The edges pushed so far as exactly sized arrays (copies when the buffer has slack).
+     * @returns the endpoint arrays
+     */
+    finish(): { src: U32; dst: U32 } {
+        if (this.length === this.src.length) {
+            return { src: this.src, dst: this.dst };
+        }
+        return { src: this.src.slice(0, this.length), dst: this.dst.slice(0, this.length) };
+    }
+
+    private grow(): void {
+        checkEdgeCount(this.length + 1);
+        const size = Math.min(this.src.length * 2, MAX_COUNT);
+        const src = new Uint32Array(size);
+        const dst = new Uint32Array(size);
+        src.set(this.src);
+        dst.set(this.dst);
+        this.src = src;
+        this.dst = dst;
+    }
+}
+
+/**
+ * A buffer sized for a binomial number of edges: the mean plus six standard deviations, so it
+ * almost never grows.
+ * @param pairs - the number of candidate pairs
+ * @param p - the edge probability
+ * @returns the buffer
+ */
+export function binomialBuffer(pairs: number, p: number): EdgeBuffer {
+    const mean = pairs * p;
+    checkEdgeCount(mean);
+    return new EdgeBuffer(Math.ceil(mean + 6 * Math.sqrt(mean * (1 - p)) + 16));
+}
+
+/**
+ * Append (row, c) for every column c in [lo, hi) chosen independently with probability p, in
+ * ascending c, by geometric skipping (V. Batagelj and U. Brandes, "Efficient generation of large
+ * random networks", Phys. Rev. E 71, 036113, 2005): O(1 + selected) draws instead of hi - lo.
+ * p = 0 and p = 1 draw nothing.
+ * @param stream - the row's stream
+ * @param p - the probability
+ * @param logQ - detLog(1 - p)
+ * @param row - the row node, written as the source
+ * @param lo - the first candidate column
+ * @param hi - one past the last candidate column
+ * @param out - the buffer
+ */
+export function bernoulliSegment(
+    stream: RandomStream,
+    p: number,
+    logQ: number,
+    row: number,
+    lo: number,
+    hi: number,
+    out: EdgeBuffer,
+): void {
+    if (p === 0 || lo >= hi) {
+        return;
+    }
+    if (p === 1) {
+        for (let c = lo; c < hi; c++) {
+            out.push(row, c);
+        }
+        return;
+    }
+    let c = lo + stream.nextSkip(logQ);
+    while (c < hi) {
+        out.push(row, c);
+        c += 1 + stream.nextSkip(logQ);
+    }
+}
+
+/**
+ * Assemble an undirected or directed SampleGraph from a buffer.
+ * @param nodeCount - the node count
+ * @param edges - the edges
+ * @param directed - whether the graph is directed
+ * @param nodeColumns - ground-truth columns, if any
+ * @returns the graph
+ */
+export function toGraph(
+    nodeCount: number,
+    edges: EdgeBuffer,
+    directed: boolean,
+    nodeColumns?: SampleGraph["nodeColumns"],
+): SampleGraph {
+    const { src, dst } = edges.finish();
+    return nodeColumns === undefined
+        ? { directed, nodeCount, src, dst }
+        : { directed, nodeCount, src, dst, nodeColumns };
+}

package/src/generators/variants.ts

@@ -0,0 +1,253 @@
+/**
+ * Structural variants for testing consumers: random multigraphs, a helper that adds self-loops,
+ * parallel and anti-parallel edges to any graph, and a pack of small (and a few huge) edge-case
+ * graphs that parsers, loaders and algorithms must survive.
+ */
+
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { checkEdgeCount, checkInt } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** Options of {@link randomMultigraph}. */
+export interface RandomMultigraphOptions extends WeightOptions {
+    /** The node count, >= 1 (>= 2 without self-loops). */
+    n: number;
+    /** The edge count, >= 0. */
+    m: number;
+    /** Whether the edges are directed; default false. */
+    directed?: boolean | undefined;
+    /** Whether an edge may join a node to itself; default true. */
+    selfLoops?: boolean | undefined;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * A random multigraph: m edges, each an independent uniform ordered pair (u, v) -- drawn with
+ * replacement, so parallel edges and (when allowed) self-loops are kept. Undirected, this is the
+ * "each endpoint uniform" model: a given self-loop is half as likely as a given pair u != v. Edge e
+ * draws u = nextBelow(n) and then v = nextBelow(n), or v = nextBelow(n - 1) shifted past u when
+ * self-loops are off, from the stream (seed, "multigraph", 0); one sequential stream, since two
+ * draws per edge are cheaper than a per-edge stream derivation. O(m).
+ * @param options - n, m, directed, selfLoops and seed
+ * @returns the multigraph
+ */
+export function randomMultigraph(options: RandomMultigraphOptions): SampleGraph {
+    const { n, m } = options;
+    const loops = options.selfLoops ?? true;
+    checkInt("n", n, 1);
+    checkInt("m", m, 0);
+    if (!loops && n < 2) {
+        throw new RangeError(`selfLoops: false needs n >= 2, got ${n}`);
+    }
+    const stream = new RandomStream(resolveSeed(options.seed), "multigraph", 0);
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    for (let e = 0; e < m; e++) {
+        const u = stream.nextBelow(n);
+        let v: number;
+        if (loops) {
+            v = stream.nextBelow(n);
+        } else {
+            v = stream.nextBelow(n - 1);
+            if (v >= u) {
+                v++;
+            }
+        }
+        src[e] = u;
+        dst[e] = v;
+    }
+    return applyWeights({ directed: options.directed ?? false, nodeCount: n, src, dst }, options);
+}
+
+/** Options of {@link addPathologicalEdges}. */
+export interface PathologicalEdgeOptions {
+    /** How many self-loops to add at uniform nodes; default 0. */
+    selfLoops?: number | undefined;
+    /** How many copies of uniform existing edges to add; default 0. */
+    parallelEdges?: number | undefined;
+    /** How many reversed copies of uniform existing arcs to add (directed graphs only); default 0. */
+    antiParallelEdges?: number | undefined;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * A copy of `graph` with pathological edges appended after its own, in this order: `selfLoops`
+ * self-loops (v, v) at v = nextBelow(nodeCount); `parallelEdges` copies of edge e =
+ * nextBelow(original edge count); `antiParallelEdges` reversed copies (dst[e], src[e]) of
+ * e = nextBelow(original edge count). Copies are only ever of the original edges. Draws come from
+ * the stream (seed, "pathological", 0) in that order. A weighted graph's copies keep the copied
+ * edge's weight and a self-loop gets weight 1. `ids` and `nodeColumns` are shared, not copied.
+ * O(m + added).
+ * @param graph - the graph
+ * @param options - the counts and the seed
+ * @returns the new graph
+ */
+export function addPathologicalEdges(graph: SampleGraph, options: PathologicalEdgeOptions): SampleGraph {
+    const loops = options.selfLoops ?? 0;
+    const parallel = options.parallelEdges ?? 0;
+    const anti = options.antiParallelEdges ?? 0;
+    checkInt("selfLoops", loops, 0);
+    checkInt("parallelEdges", parallel, 0);
+    checkInt("antiParallelEdges", anti, 0);
+    if (anti > 0 && !graph.directed) {
+        throw new RangeError("antiParallelEdges needs a directed graph");
+    }
+    const m = graph.src.length;
+    if (loops > 0 && graph.nodeCount === 0) {
+        throw new RangeError("selfLoops needs a graph with at least one node");
+    }
+    if (parallel + anti > 0 && m === 0) {
+        throw new RangeError("parallelEdges and antiParallelEdges need a graph with at least one edge");
+    }
+    const total = m + loops + parallel + anti;
+    checkEdgeCount(total);
+    const stream = new RandomStream(resolveSeed(options.seed), "pathological", 0);
+    const src = new Uint32Array(total);
+    const dst = new Uint32Array(total);
+    src.set(graph.src);
+    dst.set(graph.dst);
+    const weights = graph.weights === undefined ? undefined : new Float32Array(total);
+    weights?.set(graph.weights ?? []);
+    let e = m;
+    for (let i = 0; i < loops; i++, e++) {
+        const v = stream.nextBelow(graph.nodeCount);
+        src[e] = v;
+        dst[e] = v;
+        if (weights !== undefined) {
+            weights[e] = 1;
+        }
+    }
+    for (let i = 0; i < parallel + anti; i++, e++) {
+        const f = stream.nextBelow(m);
+        const reversed = i >= parallel;
+        src[e] = reversed ? graph.dst[f] : graph.src[f];
+        dst[e] = reversed ? graph.src[f] : graph.dst[f];
+        if (weights !== undefined) {
+            weights[e] = weights[f];
+        }
+    }
+    return { ...graph, src, dst, weights };
+}
+
+/** The names of the {@link edgeCaseGraph} cases. */
+export const EDGE_CASE_NAMES = [
+    "empty",
+    "single-node",
+    "single-self-loop",
+    "isolated-nodes",
+    "disconnected",
+    "pathological-undirected",
+    "pathological-directed",
+    "zero-weights",
+    "negative-weights",
+    "negative-cycle",
+    "duplicate-heavy",
+    "max-node-index",
+    "star-100k",
+    "path-100k",
+] as const;
+
+/** One of {@link EDGE_CASE_NAMES}. */
+export type EdgeCaseName = (typeof EDGE_CASE_NAMES)[number];
+
+/**
+ * A small graph from a flat edge list.
+ * @param directed - whether the edges are directed
+ * @param nodeCount - the node count
+ * @param edges - [u, v, u, v, ...], or [u, v, w, u, v, w, ...] when weighted
+ * @param weighted - whether every edge carries a weight
+ * @returns the graph
+ */
+function build(directed: boolean, nodeCount: number, edges: readonly number[], weighted = false): SampleGraph {
+    const stride = weighted ? 3 : 2;
+    const m = edges.length / stride;
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    const weights = new Float32Array(weighted ? m : 0);
+    for (let e = 0; e < m; e++) {
+        src[e] = edges[e * stride];
+        dst[e] = edges[e * stride + 1];
+        weights[e] = weighted ? edges[e * stride + 2] : 0;
+    }
+    return weighted ? { directed, nodeCount, src, dst, weights } : { directed, nodeCount, src, dst };
+}
+
+/**
+ * A graph whose edge e is end(e) for e < m.
+ * @param nodeCount - the node count
+ * @param m - the edge count
+ * @param end - maps e to [source, target]
+ * @returns the undirected graph
+ */
+function generated(nodeCount: number, m: number, end: (e: number) => [number, number]): SampleGraph {
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    for (let e = 0; e < m; e++) {
+        [src[e], dst[e]] = end(e);
+    }
+    return { directed: false, nodeCount, src, dst };
+}
+
+const CASES: Record<EdgeCaseName, () => SampleGraph> = {
+    empty: () => build(false, 0, []),
+    "single-node": () => build(false, 1, []),
+    "single-self-loop": () => build(false, 1, [0, 0]),
+    "isolated-nodes": () => build(false, 10, []),
+    // triangle 0-1-2, path 3-4-5, edge 6-7, isolated 8 and 9
+    disconnected: () => build(false, 10, [0, 1, 1, 2, 2, 0, 3, 4, 4, 5, 6, 7]),
+    // self-loop at 0; (1, 2) three times, once written (2, 1); weights 0, negative and fractional
+    "pathological-undirected": () =>
+        build(false, 4, [0, 0, 1, 1, 2, 0, 1, 2, -2, 2, 1, 0.5, 2, 3, 2.5, 3, 0, -1], true),
+    // self-loop at 0; parallel arcs 0 -> 1; the 2-cycle 1 <-> 2 (an anti-parallel pair, one arc
+    // of weight 0); the negative cycle 2 -> 3 -> 4 -> 2 of total weight -2, reachable from 0
+    "pathological-directed": () =>
+        build(true, 5, [0, 0, 1, 0, 1, 2, 0, 1, 3, 1, 2, 1, 2, 1, 0, 2, 3, -1, 3, 4, -2, 4, 2, 1, 1, 3, 0.5], true),
+    // a 4-cycle with the chord 0-2, every weight 0: ties everywhere for Dijkstra and MST
+    "zero-weights": () => build(false, 4, [0, 1, 0, 1, 2, 0, 2, 3, 0, 3, 0, 0, 0, 2, 0], true),
+    // a DAG with negative arcs and no negative cycle; distances from 0 are [0, 4, 1, 4, 3]
+    "negative-weights": () => build(true, 5, [0, 1, 4, 0, 2, 2, 1, 2, -3, 1, 3, 2, 2, 3, 3, 3, 4, -1, 2, 4, 5], true),
+    // 0 -> 1, then the cycle 1 -> 2 -> 3 -> 1 of total weight -1
+    "negative-cycle": () => build(true, 4, [0, 1, 1, 1, 2, -1, 2, 3, -1, 3, 1, 1], true),
+    // 1,000 copies of the edge (0, 1)
+    "duplicate-heavy": () => generated(2, 1000, () => [0, 1]),
+    // 2^20 nodes, edges only at the ends: sparse index handling and large-id output
+    "max-node-index": () => build(false, 2 ** 20, [0, 1, 2 ** 20 - 2, 2 ** 20 - 1, 0, 2 ** 20 - 1]),
+    // hub 0 with 100,000 leaves
+    "star-100k": () => generated(100_001, 100_000, (e) => [0, e + 1]),
+    // the path 0 - 1 - ... - 99,999
+    "path-100k": () => generated(100_000, 99_999, (e) => [e, e + 1]),
+};
+
+/**
+ * An edge-case graph for testing parsers, loaders and algorithms. Every case loads with
+ * graph-format's `fromEdgeArrays` default options, and each call returns fresh arrays.
+ *
+ * - `empty`: 0 nodes, 0 edges.
+ * - `single-node`: 1 node, no edges.
+ * - `single-self-loop`: 1 node with a self-loop.
+ * - `isolated-nodes`: 10 nodes, no edges.
+ * - `disconnected`: a triangle, a 3-node path, one edge and 2 isolated nodes (5 components).
+ * - `pathological-undirected`: a self-loop, a triple parallel edge (one written reversed), weights
+ *   0, negative and fractional.
+ * - `pathological-directed`: a self-loop, parallel arcs, an anti-parallel pair (a 2-cycle), a
+ *   negative-weight cycle reachable from 0, zero and negative weights.
+ * - `zero-weights`: a 4-cycle plus a chord, all weights 0.
+ * - `negative-weights`: a DAG with negative weights and no negative cycle (Bellman-Ford, DAG
+ *   shortest paths); distances from 0 are [0, 4, 1, 4, 3].
+ * - `negative-cycle`: a directed cycle of total weight -1 reachable from node 0.
+ * - `duplicate-heavy`: 1,000 copies of the edge (0, 1).
+ * - `max-node-index`: 2^20 nodes, 3 edges touching nodes 0, 1, 2^20 - 2 and 2^20 - 1.
+ * - `star-100k`: a hub with 100,000 leaves (degree extremes).
+ * - `path-100k`: a 100,000-node path (deep recursion, long diameters).
+ * @param name - the case
+ * @returns the graph
+ */
+export function edgeCaseGraph(name: EdgeCaseName): SampleGraph {
+    if (!(EDGE_CASE_NAMES as readonly string[]).includes(name)) {
+        throw new RangeError(`unknown edge case "${name}"; expected one of ${EDGE_CASE_NAMES.join(", ")}`);
+    }
+    return CASES[name]();
+}