@graphty/graph-samples 0.0.1 → 0.1.1

package/src/generators/lfr.ts

@@ -0,0 +1,227 @@
+/**
+ * The LFR community-detection benchmark: power-law degrees, power-law community sizes and a
+ * mixing parameter, with the planted communities as ground truth.
+ */
+
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { makeSumEven, pairStubs, powerLawSampler, shuffle, stubList } from "./degree-sequence.js";
+import { checkInt, checkProbability, EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** The largest LFR graph. */
+const MAX_LFR_NODES = 1_000_000;
+
+/** Options of {@link lfrGraph}. */
+export interface LfrOptions extends WeightOptions {
+    /** The node count, in [1, 1,000,000]. */
+    n: number;
+    /** The smallest degree, >= 1. */
+    minDegree: number;
+    /** The largest degree, in [minDegree, n - 1]. */
+    maxDegree: number;
+    /** The degree power-law exponent (tau1), a finite number >= 0, typically 2 to 3. */
+    degreeExponent: number;
+    /** The smallest community, >= 1. */
+    minCommunity: number;
+    /** The largest community, in [minCommunity, n]. */
+    maxCommunity: number;
+    /** The community-size power-law exponent (tau2), a finite number >= 0, typically 1 to 2. */
+    communityExponent: number;
+    /** The mixing parameter mu in [0, 1]: the share of each node's edges that leave its community. */
+    mixing: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * Community sizes from the power law on [min, max] summing to exactly n: draw sizes from stream
+ * (seed, "lfr-sizes", 0) until their sum reaches n; if k sizes of at least `min` no longer fit n,
+ * drop the last draw and grow sizes from the last one backwards (each up to max) to close the gap,
+ * otherwise shrink them from the last one backwards (each down to min) to remove the excess.
+ * @param n - the node count
+ * @param min - the smallest size
+ * @param max - the largest size
+ * @param sample - the power-law sampler
+ * @param seed - the seed
+ * @returns the sizes
+ */
+function communitySizes(
+    n: number,
+    min: number,
+    max: number,
+    sample: (stream: RandomStream) => number,
+    seed: number,
+): number[] {
+    if (Math.ceil(n / max) * min > n) {
+        throw new RangeError(`there is no partition of ${n} nodes into communities of ${min} to ${max} nodes`);
+    }
+    const stream = new RandomStream(seed, "lfr-sizes", 0);
+    const sizes: number[] = [];
+    let excess = -n;
+    while (excess < 0) {
+        const s = sample(stream);
+        sizes.push(s);
+        excess += s;
+    }
+    if (sizes.length * min > n) {
+        excess -= sizes[sizes.length - 1];
+        sizes.pop();
+    }
+    // the feasibility check above guarantees these loops close the gap exactly
+    for (let i = sizes.length - 1; i >= 0 && excess !== 0; i--) {
+        const change = excess > 0 ? -Math.min(excess, sizes[i] - min) : Math.min(-excess, max - sizes[i]);
+        sizes[i] += change;
+        excess += change;
+    }
+    return sizes;
+}
+
+/**
+ * Assign every node a community larger than its internal degree: nodes by internal degree
+ * descending (ties by index), each to a uniform choice (nextBelow of stream (seed, "lfr-assign", 0))
+ * among the communities with room whose size exceeds its internal degree. The communities that fit
+ * only grow as the internal degree falls, so this fails exactly when no assignment exists.
+ * @param internal - the internal degree of every node
+ * @param sizes - the community sizes (summing to the node count)
+ * @param seed - the seed
+ * @returns the community of every node
+ */
+function assignCommunities(internal: Uint32Array, sizes: readonly number[], seed: number): Uint32Array<ArrayBuffer> {
+    const n = internal.length;
+    const nodes = Uint32Array.from({ length: n }, (_, i) => i).sort((a, b) => internal[b] - internal[a] || a - b);
+    const bySize = Uint32Array.from(sizes, (_, i) => i).sort((a, b) => sizes[b] - sizes[a] || a - b);
+    const room = sizes.slice();
+    const open: number[] = [];
+    const community = new Uint32Array(n);
+    const stream = new RandomStream(seed, "lfr-assign", 0);
+    let next = 0;
+    for (const node of nodes) {
+        while (next < bySize.length && sizes[bySize[next]] > internal[node]) {
+            open.push(bySize[next++]);
+        }
+        if (open.length === 0) {
+            throw new RangeError(
+                `could not assign communities: node ${node} needs a community of more than ${internal[node]} nodes; ` +
+                    `raise maxCommunity or mixing, or lower maxDegree`,
+            );
+        }
+        const j = stream.nextBelow(open.length);
+        const c = open[j];
+        community[node] = c;
+        if (--room[c] === 0) {
+            open[j] = open[open.length - 1];
+            open.pop();
+        }
+    }
+    return community;
+}
+
+/**
+ * The LFR benchmark (A. Lancichinetti, S. Fortunato and F. Radicchi, "Benchmark graphs for testing
+ * community detection algorithms", Phys. Rev. E 78, 046110, 2008,
+ * doi:10.1103/PhysRevE.78.046110), built with configuration models:
+ *
+ * 1. Degrees: node i's degree is the i-th power-law draw on [minDegree, maxDegree] from stream
+ *    (seed, "lfr-degrees", 0); an odd sum is fixed on the last node as in powerLawDegreeSequence.
+ * 2. Community sizes: power law on [minCommunity, maxCommunity] summing to exactly n (stream
+ *    "lfr-sizes"); community ids are the draw order.
+ * 3. Internal degree round((1 - mu) d); assignment of nodes to communities larger than their
+ *    internal degree (stream "lfr-assign"); a RangeError when none exists.
+ * 4. Inside each community c, ascending: when its internal degrees sum to an odd number the member
+ *    with the largest (lowest index on ties) moves one stub to the outside; then a configuration
+ *    model on the members' ascending stub list shuffled with stream (seed, "lfr-internal", c).
+ * 5. Outside: a configuration model on the remaining degrees d - internal, stream
+ *    (seed, "lfr-external", 0).
+ *
+ * Self-loops and repeated pairs are erased, and so are external pairs that land inside one
+ * community, so degrees and the mixing come out approximate: the mean degree drops by up to about
+ * 10% (repeated pairs inside small communities), and the measured mixing lands within about 0.02 of
+ * mu for thousands of nodes. No edge switching repairs this. Edges: every community's internal
+ * edges (communities ascending, pair order), then the external edges. Node column `community` (u32).
+ * O(n log n + m); n at most 1,000,000.
+ * @param options - n, degree and community power laws, mixing and seed
+ * @returns the undirected graph
+ */
+export function lfrGraph(options: LfrOptions): SampleGraph {
+    const { n, minDegree, maxDegree, minCommunity, maxCommunity, mixing } = options;
+    const seed = resolveSeed(options.seed);
+    checkInt("n", n, 1, MAX_LFR_NODES);
+    checkInt("maxDegree", maxDegree, 1, n - 1);
+    checkProbability("mixing", mixing);
+    checkInt("maxCommunity", maxCommunity, 1, n);
+    const degreeOf = powerLawSampler(
+        ["degreeExponent", "minDegree", "maxDegree"],
+        options.degreeExponent,
+        minDegree,
+        maxDegree,
+    );
+    const sizeOf = powerLawSampler(
+        ["communityExponent", "minCommunity", "maxCommunity"],
+        options.communityExponent,
+        minCommunity,
+        maxCommunity,
+    );
+
+    const degree = new Uint32Array(n);
+    const degreeStream = new RandomStream(seed, "lfr-degrees", 0);
+    for (let i = 0; i < n; i++) {
+        degree[i] = degreeOf(degreeStream);
+    }
+    makeSumEven(degree, minDegree, maxDegree);
+    const sizes = communitySizes(n, minCommunity, maxCommunity, sizeOf, seed);
+    const internal = Uint32Array.from(degree, (d) => Math.round((1 - mixing) * d));
+    const community = assignCommunities(internal, sizes, seed);
+
+    // members of every community, ascending, by a counting sort
+    const start = new Uint32Array(sizes.length + 1);
+    for (let c = 0; c < sizes.length; c++) {
+        start[c + 1] = start[c] + sizes[c];
+    }
+    const fill = start.slice(0, sizes.length);
+    const members = new Uint32Array(n);
+    for (let i = 0; i < n; i++) {
+        members[fill[community[i]]++] = i;
+    }
+
+    let total = 0;
+    for (const d of degree) {
+        total += d;
+    }
+    const out = new EdgeBuffer(total / 2);
+    const stream = new RandomStream(seed, "lfr-internal", 0);
+    for (let c = 0; c < sizes.length; c++) {
+        const group = members.subarray(start[c], start[c + 1]);
+        const k = Uint32Array.from(group, (i) => internal[i]);
+        let sum = 0;
+        let largest = 0;
+        for (let j = 0; j < k.length; j++) {
+            sum += k[j];
+            if (k[j] > k[largest]) {
+                largest = j;
+            }
+        }
+        if (sum % 2 === 1) {
+            k[largest]--;
+            internal[group[largest]]--;
+            sum--;
+        }
+        const stubs = stubList(k, sum);
+        for (let j = 0; j < stubs.length; j++) {
+            stubs[j] = group[stubs[j]];
+        }
+        stream.reset(c);
+        shuffle(stubs, stream);
+        pairStubs(n, stubs, false, false, out);
+    }
+
+    const external = Uint32Array.from(degree, (d, i) => d - internal[i]);
+    let externalTotal = 0;
+    for (const d of external) {
+        externalTotal += d;
+    }
+    const stubs = stubList(external, externalTotal);
+    shuffle(stubs, new RandomStream(seed, "lfr-external", 0));
+    pairStubs(n, stubs, false, false, out, community);
+    return applyWeights(toGraph(n, out, false, { community }), options);
+}

package/src/generators/named.ts

@@ -0,0 +1,198 @@
+/**
+ * Named small graphs with well-known invariants: the teaching graphs and the platonic solids.
+ * The edge lists (node order and edge order) are those of networkx 3.1's `small.py`
+ * (A. Hagberg, D. Schult, P. Swart, "Exploring network structure, dynamics, and function using
+ * NetworkX", SciPy 2008; BSD-3-Clause), which in turn follow the literature (Krackhardt 1990,
+ * Frucht 1939, Tutte 1946, Hoffman and Singleton 1960, Sedgewick 1990). They are mathematical facts;
+ * the ordering is frozen like any other generator's. The Petersen graph is `petersenGraph()`.
+ */
+
+import { type SampleGraph } from "../types.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** The name of every graph {@link namedGraph} knows. */
+export const NAMED_GRAPH_NAMES = [
+    "bull",
+    "chvatal",
+    "cubical",
+    "desargues",
+    "diamond",
+    "dodecahedral",
+    "frucht",
+    "heawood",
+    "hoffman-singleton",
+    "house",
+    "house-x",
+    "icosahedral",
+    "krackhardt-kite",
+    "moebius-kantor",
+    "octahedral",
+    "pappus",
+    "sedgewick-maze",
+    "tetrahedral",
+    "truncated-cube",
+    "truncated-tetrahedron",
+    "tutte",
+] as const;
+
+/** A name {@link namedGraph} accepts. */
+export type NamedGraphName = (typeof NAMED_GRAPH_NAMES)[number];
+
+/** Node count and flat edge list [u0, v0, u1, v1, ...] of every named graph. */
+const GRAPHS: Readonly<Record<NamedGraphName, readonly [number, readonly number[]]>> = {
+    // a triangle with two pendant horns; 5 nodes, 5 edges
+    bull: [5, [0, 1, 0, 2, 1, 2, 1, 3, 2, 4]],
+    // the smallest triangle-free 4-regular 4-chromatic graph; 12 nodes, 24 edges
+    chvatal: [
+        12,
+        [
+            0, 1, 0, 4, 0, 6, 0, 9, 1, 2, 1, 5, 1, 7, 2, 3, 2, 6, 2, 8, 3, 4, 3, 7, 3, 9, 4, 5, 4, 8, 5, 10, 5, 11, 6,
+            10, 6, 11, 7, 8, 7, 11, 8, 10, 9, 10, 9, 11,
+        ],
+    ],
+    // the cube's skeleton (Q_3); 8 nodes, 12 edges, planar
+    cubical: [8, [0, 1, 0, 3, 0, 4, 1, 2, 1, 7, 2, 3, 2, 6, 3, 5, 4, 5, 4, 7, 5, 6, 6, 7]],
+    // the Desargues graph, 3-regular, distance-transitive; 20 nodes, 30 edges
+    desargues: [
+        20,
+        [
+            0, 1, 0, 19, 0, 5, 1, 2, 1, 16, 2, 3, 2, 11, 3, 4, 3, 14, 4, 5, 4, 9, 5, 6, 6, 7, 6, 15, 7, 8, 7, 18, 8, 9,
+            8, 13, 9, 10, 10, 11, 10, 19, 11, 12, 12, 13, 12, 17, 13, 14, 14, 15, 15, 16, 16, 17, 17, 18, 18, 19,
+        ],
+    ],
+    // K_4 minus one edge; 4 nodes, 5 edges
+    diamond: [4, [0, 1, 0, 2, 1, 2, 1, 3, 2, 3]],
+    // the dodecahedron's skeleton; 20 nodes, 30 edges, planar, 3-regular
+    dodecahedral: [
+        20,
+        [
+            0, 1, 0, 19, 0, 10, 1, 2, 1, 8, 2, 3, 2, 6, 3, 4, 3, 19, 4, 5, 4, 17, 5, 6, 5, 15, 6, 7, 7, 8, 7, 14, 8, 9,
+            9, 10, 9, 13, 10, 11, 11, 12, 11, 18, 12, 13, 12, 16, 13, 14, 14, 15, 15, 16, 16, 17, 17, 18, 18, 19,
+        ],
+    ],
+    // 3-regular with no non-trivial automorphism; 12 nodes, 18 edges
+    frucht: [
+        12,
+        [
+            0, 1, 0, 6, 0, 7, 1, 2, 1, 7, 2, 3, 2, 8, 3, 4, 3, 9, 4, 5, 4, 9, 5, 6, 5, 10, 6, 10, 7, 11, 8, 11, 8, 9,
+            10, 11,
+        ],
+    ],
+    // the (3,6)-cage, the Fano plane's incidence graph; 14 nodes, 21 edges
+    heawood: [
+        14,
+        [
+            0, 1, 0, 13, 0, 5, 1, 2, 1, 10, 2, 3, 2, 7, 3, 4, 3, 12, 4, 5, 4, 9, 5, 6, 6, 7, 6, 11, 7, 8, 8, 9, 8, 13,
+            9, 10, 10, 11, 11, 12, 12, 13,
+        ],
+    ],
+    // the (7,5)-cage, a Moore graph; 50 nodes, 175 edges
+    "hoffman-singleton": [
+        50,
+        [
+            0, 1, 0, 2, 0, 3, 0, 6, 0, 7, 0, 8, 0, 9, 1, 17, 1, 12, 1, 26, 1, 27, 1, 28, 1, 29, 2, 10, 2, 11, 2, 13, 2,
+            14, 2, 15, 2, 16, 3, 4, 3, 5, 3, 30, 3, 35, 3, 40, 3, 45, 4, 11, 4, 17, 4, 34, 4, 39, 4, 44, 4, 49, 5, 12,
+            5, 10, 5, 33, 5, 38, 5, 43, 5, 48, 6, 22, 6, 18, 6, 31, 6, 39, 6, 43, 6, 47, 7, 34, 7, 23, 7, 19, 7, 37, 7,
+            41, 7, 48, 8, 33, 8, 36, 8, 24, 8, 20, 8, 42, 8, 49, 9, 32, 9, 38, 9, 44, 9, 25, 9, 21, 9, 46, 10, 17, 10,
+            18, 10, 19, 10, 20, 10, 21, 11, 12, 11, 32, 11, 37, 11, 42, 11, 47, 12, 31, 12, 36, 12, 41, 12, 46, 13, 30,
+            13, 26, 13, 22, 13, 36, 13, 44, 13, 48, 14, 31, 14, 27, 14, 23, 14, 38, 14, 40, 14, 49, 15, 34, 15, 35, 15,
+            28, 15, 24, 15, 43, 15, 46, 16, 33, 16, 39, 16, 41, 16, 45, 16, 29, 16, 25, 17, 22, 17, 23, 17, 24, 17, 25,
+            18, 32, 18, 26, 18, 35, 18, 41, 18, 49, 19, 30, 19, 27, 19, 39, 19, 42, 19, 46, 20, 31, 20, 37, 20, 28, 20,
+            44, 20, 45, 21, 34, 21, 36, 21, 40, 21, 47, 21, 29, 22, 33, 22, 37, 22, 40, 22, 46, 23, 32, 23, 36, 23, 43,
+            23, 45, 24, 30, 24, 38, 24, 41, 24, 47, 25, 31, 25, 35, 25, 42, 25, 48, 26, 34, 26, 38, 26, 42, 26, 45, 27,
+            33, 27, 35, 27, 44, 27, 47, 28, 32, 28, 39, 28, 40, 28, 48, 29, 30, 29, 37, 29, 43, 29, 49, 30, 31, 30, 32,
+            31, 34, 32, 33, 33, 34, 35, 36, 35, 37, 36, 39, 37, 38, 38, 39, 40, 41, 40, 42, 41, 44, 42, 43, 43, 44, 45,
+            46, 45, 47, 46, 49, 47, 48, 48, 49,
+        ],
+    ],
+    // a square with a triangular roof; 5 nodes, 6 edges
+    house: [5, [0, 1, 0, 2, 1, 3, 2, 3, 2, 4, 3, 4]],
+    // the house with both diagonals of the square; 5 nodes, 8 edges
+    "house-x": [5, [0, 1, 0, 2, 0, 3, 1, 3, 1, 2, 2, 3, 2, 4, 3, 4]],
+    // the icosahedron's skeleton; 12 nodes, 30 edges, planar, 5-regular
+    icosahedral: [
+        12,
+        [
+            0, 1, 0, 5, 0, 7, 0, 8, 0, 11, 1, 2, 1, 5, 1, 6, 1, 8, 2, 3, 2, 6, 2, 8, 2, 9, 3, 4, 3, 6, 3, 9, 3, 10, 4,
+            5, 4, 6, 4, 10, 4, 11, 5, 6, 5, 11, 7, 8, 7, 9, 7, 10, 7, 11, 8, 9, 9, 10, 10, 11,
+        ],
+    ],
+    // Krackhardt's kite: degree, betweenness and closeness each crown a different node; 10 nodes, 18 edges
+    "krackhardt-kite": [
+        10,
+        [0, 1, 0, 2, 0, 3, 0, 5, 1, 3, 1, 4, 1, 6, 2, 3, 2, 5, 3, 4, 3, 5, 3, 6, 4, 6, 5, 6, 5, 7, 6, 7, 7, 8, 8, 9],
+    ],
+    // the Moebius-Kantor graph, the generalized Petersen graph GP(8, 3); 16 nodes, 24 edges
+    "moebius-kantor": [
+        16,
+        [
+            0, 1, 0, 15, 0, 5, 1, 2, 1, 12, 2, 3, 2, 7, 3, 4, 3, 14, 4, 5, 4, 9, 5, 6, 6, 7, 6, 11, 7, 8, 8, 9, 8, 13,
+            9, 10, 10, 11, 10, 15, 11, 12, 12, 13, 13, 14, 14, 15,
+        ],
+    ],
+    // the octahedron's skeleton, K_{2,2,2}; 6 nodes, 12 edges
+    octahedral: [6, [0, 1, 0, 2, 0, 3, 0, 4, 1, 2, 1, 3, 1, 5, 2, 4, 2, 5, 3, 4, 3, 5, 4, 5]],
+    // the Pappus graph, 3-regular, bipartite, distance-regular; 18 nodes, 27 edges
+    pappus: [
+        18,
+        [
+            0, 1, 0, 17, 0, 5, 1, 2, 1, 8, 2, 3, 2, 13, 3, 4, 3, 10, 4, 5, 4, 15, 5, 6, 6, 7, 6, 11, 7, 8, 7, 14, 8, 9,
+            9, 10, 9, 16, 10, 11, 11, 12, 12, 13, 12, 17, 13, 14, 14, 15, 15, 16, 16, 17,
+        ],
+    ],
+    // the small maze of Sedgewick's Algorithms in C (DFS teaching); 8 nodes, 10 edges
+    "sedgewick-maze": [8, [0, 2, 0, 7, 0, 5, 1, 7, 2, 6, 3, 4, 3, 5, 4, 5, 4, 7, 4, 6]],
+    // the tetrahedron's skeleton, K_4; 4 nodes, 6 edges
+    tetrahedral: [4, [0, 1, 0, 2, 0, 3, 1, 2, 1, 3, 2, 3]],
+    // the truncated cube's skeleton; 24 nodes, 36 edges, planar
+    "truncated-cube": [
+        24,
+        [
+            0, 1, 0, 2, 0, 4, 1, 11, 1, 14, 2, 3, 2, 4, 3, 6, 3, 8, 4, 5, 5, 16, 5, 18, 6, 7, 6, 8, 7, 10, 7, 12, 8, 9,
+            9, 17, 9, 20, 10, 11, 10, 12, 11, 14, 12, 13, 13, 21, 13, 22, 14, 15, 15, 19, 15, 23, 16, 17, 16, 18, 17,
+            20, 18, 19, 19, 23, 20, 21, 21, 22, 22, 23,
+        ],
+    ],
+    // the truncated tetrahedron's skeleton; 12 nodes, 18 edges, planar
+    "truncated-tetrahedron": [
+        12,
+        [
+            0, 1, 0, 2, 0, 9, 1, 2, 1, 6, 2, 3, 3, 4, 3, 11, 4, 5, 4, 11, 5, 6, 5, 7, 6, 7, 7, 8, 8, 9, 8, 10, 9, 10,
+            10, 11,
+        ],
+    ],
+    // Tutte's graph: 3-regular, 3-connected, planar and not Hamiltonian; 46 nodes, 69 edges
+    tutte: [
+        46,
+        [
+            0, 1, 0, 2, 0, 3, 1, 4, 1, 26, 2, 10, 2, 11, 3, 18, 3, 19, 4, 5, 4, 33, 5, 6, 5, 29, 6, 7, 6, 27, 7, 8, 7,
+            14, 8, 9, 8, 38, 9, 10, 9, 37, 10, 39, 11, 12, 11, 39, 12, 13, 12, 35, 13, 14, 13, 15, 14, 34, 15, 16, 15,
+            22, 16, 17, 16, 44, 17, 18, 17, 43, 18, 45, 19, 20, 19, 45, 20, 21, 20, 41, 21, 22, 21, 23, 22, 40, 23, 24,
+            23, 27, 24, 25, 24, 32, 25, 26, 25, 31, 26, 33, 27, 28, 28, 29, 28, 32, 29, 30, 30, 31, 30, 33, 31, 32, 34,
+            35, 34, 38, 35, 36, 36, 37, 36, 39, 37, 38, 40, 41, 40, 44, 41, 42, 42, 43, 42, 45, 43, 44,
+        ],
+    ],
+};
+
+/**
+ * A named small graph (see {@link NAMED_GRAPH_NAMES}): an undirected simple graph with networkx's
+ * node and edge order.
+ * @param name - the graph's name
+ * @param options - the common weight options
+ * @returns the graph
+ */
+export function namedGraph(name: NamedGraphName, options: WeightOptions = {}): SampleGraph {
+    const entry = Object.prototype.hasOwnProperty.call(GRAPHS, name) ? GRAPHS[name] : undefined;
+    if (entry === undefined) {
+        throw new RangeError(`unknown named graph "${name}"; see NAMED_GRAPH_NAMES`);
+    }
+    const [nodeCount, flat] = entry;
+    const m = flat.length / 2;
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    for (let e = 0; e < m; e++) {
+        src[e] = flat[2 * e];
+        dst[e] = flat[2 * e + 1];
+    }
+    return applyWeights({ directed: false, nodeCount, src, dst }, options);
+}

package/src/generators/preferential-attachment.ts

@@ -0,0 +1,188 @@
+/**
+ * Growth models: Barabasi-Albert preferential attachment with the Holme-Kim triad-formation step,
+ * and the Watts-Strogatz small world.
+ */
+
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { checkEdgeCount, checkInt, checkProbability, EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** Options of {@link barabasiAlbertGraph}. */
+export interface BarabasiAlbertOptions extends WeightOptions {
+    /** The node count, > m. */
+    n: number;
+    /** The number of edges each new node brings, >= 1. */
+    m: number;
+    /**
+     * Holme-Kim: after each preferential edge, the probability that the next of the node's m edges
+     * closes a triangle with a neighbour of that edge's target instead. 0 (the default) is plain
+     * Barabasi-Albert.
+     */
+    triadProbability?: number | undefined;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * Barabasi-Albert preferential attachment (A.-L. Barabasi and R. Albert, "Emergence of scaling in
+ * random networks", Science 286, 509-512, 1999), optionally with triad formation (P. Holme and
+ * B. J. Kim, "Growing scale-free networks with tunable clustering", Phys. Rev. E 65, 026107, 2002),
+ * in O(n m) with the repeated-endpoint list of Batagelj and Brandes (2005).
+ *
+ * The algorithm is networkx's `powerlaw_cluster_graph`, which is `barabasi_albert_graph` when the
+ * triad probability is 0: start from m isolated nodes 0 .. m - 1 whose repeated list holds each
+ * once; each new node s = m .. n - 1 draws m distinct targets uniformly from the repeated list
+ * (in draw order), then adds m edges (s, t): the first to the first target; each further one, with
+ * probability `triadProbability`, to a uniformly chosen neighbour of the previous target that s is
+ * not yet joined to, otherwise to the next unused target. Every endpoint is appended to the
+ * repeated list, s itself m times. All draws come from the single stream (seed,
+ * "barabasi-albert", 0): the process is sequential. Edges are listed by new node, in the order
+ * added. (n - m) m edges, no self-loops, no repeats.
+ * @param options - n, m, triadProbability and seed
+ * @returns the undirected graph
+ */
+export function barabasiAlbertGraph(options: BarabasiAlbertOptions): SampleGraph {
+    const { n, m } = options;
+    const triad = options.triadProbability ?? 0;
+    checkInt("m", m, 1);
+    checkInt("n", n, m + 1);
+    checkProbability("triadProbability", triad);
+    const seed = resolveSeed(options.seed);
+    const edgeCount = (n - m) * m;
+    checkEdgeCount(edgeCount);
+    const stream = new RandomStream(seed, "barabasi-albert", 0);
+    const out = new EdgeBuffer(edgeCount);
+    const repeated = new Uint32Array(m + 2 * edgeCount);
+    let length = 0;
+    for (let i = 0; i < m; i++) {
+        repeated[length++] = i;
+    }
+    // neighbour lists, only for the triad step
+    // ponytail: number[][] per node; a CSR-like growable adjacency if HK at 1M+ nodes matters
+    const adjacency: number[][] | null = triad > 0 ? Array.from({ length: n }, () => []) : null;
+    const targets = new Array<number>(m);
+    const link = (s: number, t: number): void => {
+        out.push(s, t);
+        repeated[length++] = t;
+        if (adjacency !== null) {
+            adjacency[s].push(t);
+            adjacency[t].push(s);
+        }
+    };
+    for (let s = m; s < n; s++) {
+        // m distinct targets from the repeated list, in draw order
+        let found = 0;
+        while (found < m) {
+            const t = repeated[stream.nextBelow(length)];
+            let fresh = true;
+            for (let i = 0; i < found; i++) {
+                fresh &&= targets[i] !== t;
+            }
+            if (fresh) {
+                targets[found++] = t;
+            }
+        }
+        let next = 0;
+        let target = targets[next++];
+        link(s, target);
+        for (let count = 1; count < m; count++) {
+            if (adjacency !== null && stream.nextFloat() < triad) {
+                const mine = adjacency[s];
+                const candidates = adjacency[target].filter((x) => x !== s && !mine.includes(x));
+                if (candidates.length > 0) {
+                    link(s, candidates[stream.nextBelow(candidates.length)]);
+                    continue;
+                }
+            }
+            // the next unused target (a triad step may already have joined s to it)
+            do {
+                target = targets[next++];
+            } while (adjacency !== null && adjacency[s].includes(target) && next < m);
+            if (adjacency !== null && adjacency[s].includes(target)) {
+                // every planned target is taken: fall back to a fresh preferential draw
+                do {
+                    target = repeated[stream.nextBelow(length)];
+                } while (target === s || adjacency[s].includes(target));
+            }
+            link(s, target);
+        }
+        for (let i = 0; i < m; i++) {
+            repeated[length++] = s;
+        }
+    }
+    return applyWeights(toGraph(n, out, false), options);
+}
+
+/** Options of {@link wattsStrogatzGraph}. */
+export interface WattsStrogatzOptions extends WeightOptions {
+    /** The node count, > k. */
+    n: number;
+    /** Each node's ring neighbours before rewiring, even, >= 2. */
+    k: number;
+    /** The rewiring probability of each edge, in [0, 1]. */
+    beta: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * The Watts-Strogatz small world (D. J. Watts and S. H. Strogatz, "Collective dynamics of
+ * 'small-world' networks", Nature 393, 440-442, 1998), as networkx's `watts_strogatz_graph`
+ * builds it, in O(n k).
+ *
+ * Start from the ring lattice: edge slot u k/2 + (j - 1) holds (u, (u + j) mod n) for j = 1 .. k/2.
+ * Then for j = 1 .. k/2 and u = 0 .. n - 1 in that order: draw a float; if it is below beta and u is
+ * not already joined to every other node, redraw w = nextBelow(n) until w is neither u nor a
+ * neighbour of u, and rewire the slot to (u, w). All draws come from the single stream (seed,
+ * "watts-strogatz", 0). Edges are listed in slot order.
+ * @param options - n, k, beta and seed
+ * @returns the undirected graph
+ */
+export function wattsStrogatzGraph(options: WattsStrogatzOptions): SampleGraph {
+    const { n, k, beta } = options;
+    checkInt("k", k, 2);
+    if (k % 2 !== 0) {
+        throw new RangeError(`k must be even, got ${k}`);
+    }
+    checkInt("n", n, k + 1);
+    checkProbability("beta", beta);
+    const seed = resolveSeed(options.seed);
+    const half = k / 2;
+    const m = n * half;
+    checkEdgeCount(m);
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    const degree = new Uint32Array(n).fill(k);
+    // ponytail: a Set of u * n + v keys, fine to a few million edges; a hashed typed table beyond
+    const edges = new Set<number>();
+    const key = (a: number, b: number): number => (a < b ? a * n + b : b * n + a);
+    for (let u = 0; u < n; u++) {
+        for (let j = 1; j <= half; j++) {
+            const v = (u + j) % n;
+            src[u * half + j - 1] = u;
+            dst[u * half + j - 1] = v;
+            edges.add(key(u, v));
+        }
+    }
+    const stream = new RandomStream(seed, "watts-strogatz", 0);
+    for (let j = 1; j <= half; j++) {
+        for (let u = 0; u < n; u++) {
+            if (stream.nextFloat() >= beta || degree[u] >= n - 1) {
+                continue;
+            }
+            let w = stream.nextBelow(n);
+            while (w === u || edges.has(key(u, w))) {
+                w = stream.nextBelow(n);
+            }
+            const slot = u * half + j - 1;
+            const v = dst[slot];
+            edges.delete(key(u, v));
+            edges.add(key(u, w));
+            degree[v]--;
+            degree[w]++;
+            dst[slot] = w;
+        }
+    }
+    return applyWeights({ directed: false, nodeCount: n, src, dst }, options);
+}