@graphty/graph-samples 0.0.1 → 0.1.2

package/dist/src/generators/erdos-renyi.js

@@ -0,0 +1,154 @@
+/**
+ * Erdos-Renyi random graphs: Gilbert's G(n, p) (every pair independently with probability p) and
+ * Erdos-Renyi's G(n, m) (m pairs uniformly without replacement).
+ */
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { bernoulliSegment, binomialBuffer, checkInt, checkProbability, EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights } from "./weights.js";
+/**
+ * Rows [start, end) of G(n, p): row u draws from stream (seed, "gnp", u) and holds the pairs
+ * (u, v), v = u + 1 .. n - 1, in ascending v. Concatenating any split of [0, n) into consecutive
+ * ranges gives exactly the whole graph's edge list.
+ * @param options - the generator's options (already checked)
+ * @param start - the first row
+ * @param end - one past the last row
+ * @param out - receives the edges
+ */
+export function erdosRenyiRows(options, start, end, out) {
+    const { n, p } = options;
+    const logQ = detLog(1 - p);
+    if (options.directed === true) {
+        directedRows(n, p, logQ, resolveSeed(options.seed), start, end, out);
+        return;
+    }
+    const stream = new RandomStream(resolveSeed(options.seed), "gnp", 0);
+    for (let u = start; u < end; u++) {
+        stream.reset(u);
+        bernoulliSegment(stream, p, logQ, u, u + 1, n, out);
+    }
+}
+/**
+ * Rows [start, end) of the directed G(n, p): row u draws from stream (seed, "gnp-directed", u)
+ * and skips over its n - 1 candidates, candidate j being the node j < u ? j : j + 1, so the arcs
+ * (u, v) come in ascending v.
+ * @param n - the node count
+ * @param p - the probability
+ * @param logQ - detLog(1 - p)
+ * @param seed - the resolved seed
+ * @param start - the first row
+ * @param end - one past the last row
+ * @param out - receives the arcs
+ */
+function directedRows(n, p, logQ, seed, start, end, out) {
+    if (p === 0) {
+        return;
+    }
+    const stream = new RandomStream(seed, "gnp-directed", 0);
+    for (let u = start; u < end; u++) {
+        stream.reset(u);
+        let j = p === 1 ? 0 : stream.nextSkip(logQ);
+        while (j < n - 1) {
+            out.push(u, j < u ? j : j + 1);
+            j += p === 1 ? 1 : 1 + stream.nextSkip(logQ);
+        }
+    }
+}
+/**
+ * Gilbert's G(n, p) in O(n + m) by geometric skipping (Batagelj and Brandes 2005). Edges are the
+ * pairs (u, v), u < v, in row-major order; row u draws from its own stream, so the graph does not
+ * depend on how the rows are split between workers. With `directed: true`, the arcs (u, v) of
+ * every ordered pair u != v, by u then v ascending, each row from stream (seed, "gnp-directed", u).
+ * @param options - n, p and seed
+ * @returns the undirected graph
+ */
+export function erdosRenyiGraph(options) {
+    const { n, p } = options;
+    checkInt("n", n, 0);
+    checkProbability("p", p);
+    resolveSeed(options.seed);
+    const directed = options.directed === true;
+    const pairs = (n * (n - 1)) / (directed ? 1 : 2);
+    const out = binomialBuffer(pairs, p);
+    erdosRenyiRows(options, 0, n, out);
+    return applyWeights(toGraph(n, out, directed), options);
+}
+/**
+ * An open-addressing set of non-negative integers below 2^53, sized for `capacity` entries.
+ */
+class NumberSet {
+    /**
+     * An empty set.
+     * @param capacity - the maximum number of entries
+     */
+    constructor(capacity) {
+        let size = 16;
+        while (size < capacity * 2) {
+            size *= 2;
+        }
+        this.slots = new Float64Array(size).fill(-1);
+        this.mask = size - 1;
+    }
+    /**
+     * Insert `x`.
+     * @param x - the value
+     * @returns false when it was already present
+     */
+    add(x) {
+        let i = Math.imul((x >>> 0) ^ Math.floor(x / 4294967296), 0x9e3779b1) & this.mask;
+        for (;;) {
+            const slot = this.slots[i];
+            if (slot === -1) {
+                this.slots[i] = x;
+                return true;
+            }
+            if (slot === x) {
+                return false;
+            }
+            i = (i + 1) & this.mask;
+        }
+    }
+}
+/**
+ * Erdos-Renyi's G(n, m): m distinct pairs chosen uniformly, by Floyd's sampling over the pair
+ * indices 0 .. n (n - 1) / 2 - 1 (exactly m draws from stream (seed, "gnm", 0), no rejection
+ * loop), in O(m log m). Edges are the pairs (u, v), u < v, in row-major order.
+ * @param options - n, m and seed
+ * @returns the undirected graph
+ */
+export function erdosRenyiGnmGraph(options) {
+    const { n, m } = options;
+    const seed = resolveSeed(options.seed);
+    // the pair indices must stay below 2^53 to be exact doubles
+    checkInt("n", n, 0, 2 ** 27);
+    const total = (n * (n - 1)) / 2;
+    checkInt("m", m, 0, Math.min(total, 2 ** 32 - 2));
+    const stream = new RandomStream(seed, "gnm", 0);
+    const chosen = new Float64Array(m);
+    const set = new NumberSet(m);
+    for (let k = 0, j = total - m; j < total; j++, k++) {
+        const t = stream.nextBelow(j + 1);
+        if (set.add(t)) {
+            chosen[k] = t;
+        }
+        else {
+            set.add(j);
+            chosen[k] = j;
+        }
+    }
+    chosen.sort();
+    const out = new EdgeBuffer(m);
+    // walk the sorted pair indices row by row: row u holds indices [rowStart, rowStart + n - u - 1)
+    let u = 0;
+    let rowStart = 0;
+    for (let k = 0; k < m; k++) {
+        const index = chosen[k];
+        while (index >= rowStart + (n - u - 1)) {
+            rowStart += n - u - 1;
+            u++;
+        }
+        out.push(u, u + 1 + (index - rowStart));
+    }
+    return applyWeights(toGraph(n, out, false), options);
+}
+//# sourceMappingURL=erdos-renyi.js.map

package/dist/src/generators/erdos-renyi.js.map

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

package/dist/src/generators/flow.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Maximum-flow networks: a grid (the image-segmentation shape), a random layered DAG, GENRMF and
+ * the AK network. Every one is directed, with integer capacities as its `weights`, a `role` node
+ * column and its source and sink.
+ */
+import { type SampleGraph } from "../types.js";
+import { EdgeBuffer } from "./util.js";
+/** A maximum-flow instance: a directed graph whose `weights` are integer capacities. */
+export interface FlowNetwork extends SampleGraph {
+    /** The source node. */
+    readonly source: number;
+    /** The sink node. */
+    readonly sink: number;
+}
+/** The capacity range options of the random flow networks. */
+interface CapacityOptions {
+    /** The smallest arc capacity, an integer >= 0; default 1. */
+    minCapacity?: number | undefined;
+    /** The largest arc capacity, an integer >= minCapacity; default 10. */
+    maxCapacity?: number | undefined;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+/** Options of {@link gridFlowNetwork}. */
+export interface GridFlowOptions extends CapacityOptions {
+    /** The grid's row count, >= 1. */
+    rows: number;
+    /** The grid's column count, >= 2. */
+    cols: number;
+}
+/**
+ * A grid flow network, the shape of graph-cut image segmentation: node r * cols + c for pixel
+ * (r, c), arcs to each 4-neighbour in both directions, listed by node, in the order right, down,
+ * left, up; node u draws its arcs' capacities, uniform integers in [minCapacity, maxCapacity],
+ * from stream (seed, "grid-flow", u) in that order. Then the source rows * cols with an arc to
+ * every left-column node (by row), and every right-column node with an arc to the sink
+ * rows * cols + 1 (by row), each of capacity 4 * maxCapacity. Those terminal arcs are never a
+ * minimum cut: the arcs from the first column to the second already cut the network with at most
+ * rows * maxCapacity. Node columns `x` = c and `y` = r (Float64), the source at x = -1 and the
+ * sink at x = cols, both at the middle row; `role` (u8: 0 inner, 1 source, 2 sink). O(rows cols).
+ * @param options - rows, cols, minCapacity, maxCapacity and seed
+ * @returns the flow network
+ */
+export declare function gridFlowNetwork(options: GridFlowOptions): FlowNetwork;
+/** Options of {@link layeredFlowNetwork}. */
+export interface LayeredFlowOptions extends CapacityOptions {
+    /** The width of every inner layer, >= 1 each; 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 node layout of a layered flow network. */
+interface LayeredFlowPlan {
+    /** starts[i] = the first node of inner layer i; starts[L] = the inner node count. */
+    readonly starts: readonly number[];
+    /** The inner layer of every inner node. */
+    readonly layerOf: Uint32Array;
+    /** The arc probability. */
+    readonly p: number;
+    /** The capacity range. */
+    readonly min: number;
+    /** The capacity range. */
+    readonly max: number;
+    /** The capacity of every terminal arc: max * (the widest layer). */
+    readonly terminal: number;
+    /** The resolved seed. */
+    readonly seed: number;
+}
+/**
+ * Check a layered flow network's options and lay out its nodes.
+ * @param options - the options
+ * @returns the plan
+ */
+export declare function planLayeredFlow(options: LayeredFlowOptions): LayeredFlowPlan;
+/**
+ * Rows [start, end) of the inner arcs of a layered flow network: inner node u of a layer before
+ * the last draws from stream (seed, "layered-flow", u) first its arcs to the next layer
+ * (ascending, by geometric skipping), then their capacities in the same order.
+ * @param plan - the plan
+ * @param start - the first inner node
+ * @param end - one past the last inner node
+ * @param out - receives the arcs
+ * @param capacities - receives their capacities
+ */
+export declare function layeredFlowRows(plan: LayeredFlowPlan, start: number, end: number, out: EdgeBuffer, capacities: number[]): void;
+/**
+ * A random layered flow network: inner layers as in `randomDagGraph` (arcs only from layer i to
+ * layer i + 1, each with probability p, capacities uniform integers in [minCapacity,
+ * maxCapacity]), a source feeding every node of the first layer and every node of the last layer
+ * feeding a sink. Inner nodes come first, layer by layer; the source is node N and the sink
+ * N + 1 (N inner nodes). Arcs: the inner arcs by source node (see {@link layeredFlowRows}), then
+ * source -> first-layer nodes ascending, then last-layer nodes -> sink ascending; each terminal
+ * arc has capacity maxCapacity * (the widest layer), at least what any one node can pass on.
+ * Node column `layer` (u32): inner layer i is i + 1, the source is layer 0 and the sink layer
+ * L + 1, so the column is a topological layering of the whole network; `role` (u8). O(N + m).
+ * @param options - layers, p, minCapacity, maxCapacity and seed
+ * @returns the flow network
+ */
+export declare function layeredFlowNetwork(options: LayeredFlowOptions): FlowNetwork;
+/** Options of {@link genrmfGraph}. */
+export interface GenrmfOptions {
+    /** The side of every frame (an a x a grid), >= 1. */
+    a: number;
+    /** The number of frames, >= 1. */
+    b: number;
+    /** The smallest capacity between frames, an integer >= 0. */
+    c1: number;
+    /** The largest capacity between frames, an integer >= c1; arcs inside a frame carry c2 a^2. */
+    c2: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+/**
+ * GENRMF, the max-flow family of D. Goldfarb and M. D. Grigoriadis ("A computational comparison
+ * of the Dinic and network simplex methods for maximum flow", Annals of Operations Research 13,
+ * 81-123, 1988, doi:10.1007/BF02288321) as generated by Tamas Badics's `genrmf` (1991, First
+ * DIMACS Implementation Challenge): b frames, each an a x a grid. Node f a^2 + r a + c is (r, c)
+ * of frame f. Arcs, frame by frame: the frame's grid arcs to each 4-neighbour in both directions
+ * (by node; right, down, left, up) with capacity c2 a^2; then, for f < b - 1, node j of frame f
+ * -> node perm_f(j) of frame f + 1 for j ascending, with capacity uniform in [c1, c2]. Stream
+ * (seed, "genrmf", f) first draws perm_f, a Fisher-Yates shuffle of 0 .. a^2 - 1 (for i = a^2 - 1
+ * down to 1, swap i with nextBelow(i + 1)), then the a^2 capacities in j order. The source is
+ * node 0 (the first node of the first frame), the sink the last node of the last frame. Node
+ * columns `frame` (u32) and `role` (u8). Badics's own random numbers are not reproduced; the
+ * structure is. O(a^2 b).
+ * @param options - a, b, c1, c2 and seed
+ * @returns the flow network
+ */
+export declare function genrmfGraph(options: GenrmfOptions): FlowNetwork;
+/** Options of {@link akGraph}. */
+export interface AkOptions {
+    /** The size parameter, in [1, 499998]: 4k + 6 nodes and 6k + 7 arcs. */
+    k: number;
+}
+/**
+ * The AK network of B. V. Cherkassky and A. V. Goldberg ("On implementing the push-relabel method
+ * for the maximum flow problem", Algorithmica 19, 390-410, 1997, doi:10.1007/PL00009180), built to
+ * be hard for push-relabel. Deterministic; n = 4k + 6 nodes, m = 6k + 7 arcs.
+ *
+ * Nodes: s = 0, t = 1; part A a_i = 2 + i (i = 0 .. k); a hub chain h = k + 3 .. e = 2k + 3;
+ * part B b_i = 2k + 4 + i (i = 0 .. 2k + 1). Arcs, in this order: for i = 0 .. k - 1, a_i ->
+ * a_{i+1} (capacity k + 1 - i) then a_i -> h (1); a_k -> e (1), a_k -> h (1); the chain j -> j + 1
+ * for j = h .. e - 1 (k + 1); b_i -> b_{i+1} for i = 0 .. 2k (k); the folds b_i -> b_{2k+1-i}
+ * (1) for i = 0 .. k - 1; finally s -> a_0, s -> b_0, e -> t and b_{2k+1} -> t, each 1000000.
+ * The maximum flow is 2k + 3 and the largest inner capacity k + 1, so k is capped at 499998 to
+ * keep the terminal capacity 1000000 from ever binding (every value is then exact in Float32).
+ * Node column `role` (u8). O(k).
+ * @param options - k
+ * @returns the flow network
+ */
+export declare function akGraph(options: AkOptions): FlowNetwork;
+export {};
+//# sourceMappingURL=flow.d.ts.map

package/dist/src/generators/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../../src/generators/flow.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAgE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErG,wFAAwF;AACxF,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC5C,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAOD,8DAA8D;AAC9D,UAAU,eAAe;IACrB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AA+ED,0CAA0C;AAC1C,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACpD,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CA0CrE;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACvD,kGAAkG;IAClG,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,CAAC,EAAE,MAAM,CAAC;CACb;AAED,iDAAiD;AACjD,UAAU,eAAe;IACrB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CAmB5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,EAAE,GACrB,IAAI,CAgBN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAyB3E;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC1B,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;IACV,kCAAkC;IAClC,CAAC,EAAE,MAAM,CAAC;IACV,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,+FAA+F;IAC/F,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAkD/D;AAED,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACtB,wEAAwE;IACxE,CAAC,EAAE,MAAM,CAAC;CACb;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,WAAW,CAiCvD"}

package/dist/src/generators/flow.js

@@ -0,0 +1,346 @@
+/**
+ * Maximum-flow networks: a grid (the image-segmentation shape), a random layered DAG, GENRMF and
+ * the AK network. Every one is directed, with integer capacities as its `weights`, a `role` node
+ * column and its source and sink.
+ */
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { bernoulliSegment, checkEdgeCount, checkInt, checkProbability, EdgeBuffer } from "./util.js";
+/**
+ * The largest capacity: 2^24, the last point where every integer is exact in a Float32 weight.
+ */
+const MAX_CAPACITY = 2 ** 24;
+/**
+ * The checked capacity range.
+ * @param options - the options
+ * @param terminalFactor - the terminal arcs carry terminalFactor * maxCapacity, which must stay exact
+ * @returns min and max
+ */
+function capacityRange(options, terminalFactor) {
+    const min = options.minCapacity ?? 1;
+    const max = options.maxCapacity ?? 10;
+    checkInt("minCapacity", min, 0, MAX_CAPACITY);
+    checkInt("maxCapacity", max, min, Math.floor(MAX_CAPACITY / terminalFactor));
+    return { min, max };
+}
+/**
+ * Assemble a flow network.
+ * @param n - the node count
+ * @param out - the arcs
+ * @param capacities - one capacity per arc
+ * @param source - the source
+ * @param sink - the sink
+ * @param columns - node columns besides `role`
+ * @returns the network
+ */
+function toNetwork(n, out, capacities, source, sink, columns) {
+    const { src, dst } = out.finish();
+    const role = new Uint8Array(n);
+    role[source] = 1;
+    role[sink] = 2;
+    return {
+        directed: true,
+        nodeCount: n,
+        src,
+        dst,
+        weights: Float32Array.from(capacities),
+        nodeColumns: { ...columns, role },
+        source,
+        sink,
+    };
+}
+/**
+ * Push the arcs of node (r, c) of a rows x cols grid starting at `base` to its 4-neighbours, in
+ * the order right, down, left, up.
+ * @param out - the buffer
+ * @param base - the grid's first node
+ * @param rows - the row count
+ * @param cols - the column count
+ * @param r - the row
+ * @param c - the column
+ * @returns how many arcs were pushed
+ */
+function gridArcs(out, base, rows, cols, r, c) {
+    const u = base + r * cols + c;
+    const before = out.length;
+    if (c + 1 < cols) {
+        out.push(u, u + 1);
+    }
+    if (r + 1 < rows) {
+        out.push(u, u + cols);
+    }
+    if (c > 0) {
+        out.push(u, u - 1);
+    }
+    if (r > 0) {
+        out.push(u, u - cols);
+    }
+    return out.length - before;
+}
+/**
+ * A grid flow network, the shape of graph-cut image segmentation: node r * cols + c for pixel
+ * (r, c), arcs to each 4-neighbour in both directions, listed by node, in the order right, down,
+ * left, up; node u draws its arcs' capacities, uniform integers in [minCapacity, maxCapacity],
+ * from stream (seed, "grid-flow", u) in that order. Then the source rows * cols with an arc to
+ * every left-column node (by row), and every right-column node with an arc to the sink
+ * rows * cols + 1 (by row), each of capacity 4 * maxCapacity. Those terminal arcs are never a
+ * minimum cut: the arcs from the first column to the second already cut the network with at most
+ * rows * maxCapacity. Node columns `x` = c and `y` = r (Float64), the source at x = -1 and the
+ * sink at x = cols, both at the middle row; `role` (u8: 0 inner, 1 source, 2 sink). O(rows cols).
+ * @param options - rows, cols, minCapacity, maxCapacity and seed
+ * @returns the flow network
+ */
+export function gridFlowNetwork(options) {
+    const { rows, cols } = options;
+    checkInt("rows", rows, 1);
+    checkInt("cols", cols, 2);
+    const cells = rows * cols;
+    checkInt("rows * cols + 2 (the node count)", cells + 2, 0);
+    const { min, max } = capacityRange(options, 4);
+    const seed = resolveSeed(options.seed);
+    const arcs = 2 * (rows * (cols - 1) + cols * (rows - 1)) + 2 * rows;
+    checkEdgeCount(arcs);
+    const out = new EdgeBuffer(arcs);
+    const capacities = [];
+    const stream = new RandomStream(seed, "grid-flow", 0);
+    const x = new Float64Array(cells + 2);
+    const y = new Float64Array(cells + 2);
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            const u = r * cols + c;
+            x[u] = c;
+            y[u] = r;
+            stream.reset(u);
+            const count = gridArcs(out, 0, rows, cols, r, c);
+            for (let i = 0; i < count; i++) {
+                capacities.push(min + stream.nextBelow(max - min + 1));
+            }
+        }
+    }
+    const source = cells;
+    const sink = cells + 1;
+    x[source] = -1;
+    x[sink] = cols;
+    y[source] = (rows - 1) / 2;
+    y[sink] = (rows - 1) / 2;
+    for (let r = 0; r < rows; r++) {
+        out.push(source, r * cols);
+        capacities.push(4 * max);
+    }
+    for (let r = 0; r < rows; r++) {
+        out.push(r * cols + cols - 1, sink);
+        capacities.push(4 * max);
+    }
+    return toNetwork(cells + 2, out, capacities, source, sink, { x, y });
+}
+/**
+ * Check a layered flow network's options and lay out its nodes.
+ * @param options - the options
+ * @returns the plan
+ */
+export function planLayeredFlow(options) {
+    const { layers, p } = options;
+    checkInt("layers.length", layers.length, 1);
+    checkProbability("p", p);
+    const starts = [0];
+    let widest = 0;
+    for (let i = 0; i < layers.length; i++) {
+        checkInt(`layers[${i}]`, layers[i], 1);
+        starts.push(starts[i] + layers[i]);
+        widest = Math.max(widest, layers[i]);
+    }
+    const inner = starts[layers.length];
+    checkInt("the total size + 2 (the node count)", inner + 2, 0);
+    const { min, max } = capacityRange(options, widest);
+    const layerOf = new Uint32Array(inner);
+    for (let i = 0; i < layers.length; i++) {
+        layerOf.fill(i, starts[i], starts[i + 1]);
+    }
+    return { starts, layerOf, p, min, max, terminal: max * widest, seed: resolveSeed(options.seed) };
+}
+/**
+ * Rows [start, end) of the inner arcs of a layered flow network: inner node u of a layer before
+ * the last draws from stream (seed, "layered-flow", u) first its arcs to the next layer
+ * (ascending, by geometric skipping), then their capacities in the same order.
+ * @param plan - the plan
+ * @param start - the first inner node
+ * @param end - one past the last inner node
+ * @param out - receives the arcs
+ * @param capacities - receives their capacities
+ */
+export function layeredFlowRows(plan, start, end, out, capacities) {
+    const { starts, layerOf, p, min, max } = plan;
+    const logQ = detLog(1 - p);
+    const stream = new RandomStream(plan.seed, "layered-flow", 0);
+    const last = starts.length - 2;
+    for (let u = start; u < end; u++) {
+        const layer = layerOf[u];
+        if (layer < last) {
+            stream.reset(u);
+            const before = out.length;
+            bernoulliSegment(stream, p, logQ, u, starts[layer + 1], starts[layer + 2], out);
+            for (let i = before; i < out.length; i++) {
+                capacities.push(min + stream.nextBelow(max - min + 1));
+            }
+        }
+    }
+}
+/**
+ * A random layered flow network: inner layers as in `randomDagGraph` (arcs only from layer i to
+ * layer i + 1, each with probability p, capacities uniform integers in [minCapacity,
+ * maxCapacity]), a source feeding every node of the first layer and every node of the last layer
+ * feeding a sink. Inner nodes come first, layer by layer; the source is node N and the sink
+ * N + 1 (N inner nodes). Arcs: the inner arcs by source node (see {@link layeredFlowRows}), then
+ * source -> first-layer nodes ascending, then last-layer nodes -> sink ascending; each terminal
+ * arc has capacity maxCapacity * (the widest layer), at least what any one node can pass on.
+ * Node column `layer` (u32): inner layer i is i + 1, the source is layer 0 and the sink layer
+ * L + 1, so the column is a topological layering of the whole network; `role` (u8). O(N + m).
+ * @param options - layers, p, minCapacity, maxCapacity and seed
+ * @returns the flow network
+ */
+export function layeredFlowNetwork(options) {
+    const plan = planLayeredFlow(options);
+    const { starts } = plan;
+    const L = starts.length - 1;
+    const inner = starts[L];
+    const out = new EdgeBuffer(inner);
+    const capacities = [];
+    layeredFlowRows(plan, 0, inner, out, capacities);
+    const source = inner;
+    const sink = inner + 1;
+    const { terminal } = plan;
+    for (let u = starts[0]; u < starts[1]; u++) {
+        out.push(source, u);
+        capacities.push(terminal);
+    }
+    for (let u = starts[L - 1]; u < starts[L]; u++) {
+        out.push(u, sink);
+        capacities.push(terminal);
+    }
+    const layer = new Uint32Array(inner + 2);
+    for (let u = 0; u < inner; u++) {
+        layer[u] = plan.layerOf[u] + 1;
+    }
+    layer[sink] = L + 1;
+    return toNetwork(inner + 2, out, capacities, source, sink, { layer });
+}
+/**
+ * GENRMF, the max-flow family of D. Goldfarb and M. D. Grigoriadis ("A computational comparison
+ * of the Dinic and network simplex methods for maximum flow", Annals of Operations Research 13,
+ * 81-123, 1988, doi:10.1007/BF02288321) as generated by Tamas Badics's `genrmf` (1991, First
+ * DIMACS Implementation Challenge): b frames, each an a x a grid. Node f a^2 + r a + c is (r, c)
+ * of frame f. Arcs, frame by frame: the frame's grid arcs to each 4-neighbour in both directions
+ * (by node; right, down, left, up) with capacity c2 a^2; then, for f < b - 1, node j of frame f
+ * -> node perm_f(j) of frame f + 1 for j ascending, with capacity uniform in [c1, c2]. Stream
+ * (seed, "genrmf", f) first draws perm_f, a Fisher-Yates shuffle of 0 .. a^2 - 1 (for i = a^2 - 1
+ * down to 1, swap i with nextBelow(i + 1)), then the a^2 capacities in j order. The source is
+ * node 0 (the first node of the first frame), the sink the last node of the last frame. Node
+ * columns `frame` (u32) and `role` (u8). Badics's own random numbers are not reproduced; the
+ * structure is. O(a^2 b).
+ * @param options - a, b, c1, c2 and seed
+ * @returns the flow network
+ */
+export function genrmfGraph(options) {
+    const { a, b, c1, c2 } = options;
+    checkInt("a", a, 1);
+    checkInt("b", b, 1);
+    const side = a * a;
+    checkInt("a * a * b (the node count)", side * b, 2);
+    checkInt("c1", c1, 0, MAX_CAPACITY);
+    checkInt("c2", c2, c1, MAX_CAPACITY);
+    if (c2 * side > MAX_CAPACITY) {
+        throw new RangeError(`c2 * a * a must be at most 2^24 to stay exact, got ${c2 * side}`);
+    }
+    const seed = resolveSeed(options.seed);
+    const n = side * b;
+    const arcs = b * 4 * a * (a - 1) + (b - 1) * side;
+    checkEdgeCount(arcs);
+    const out = new EdgeBuffer(arcs);
+    const capacities = [];
+    const frame = new Uint32Array(n);
+    const perm = new Uint32Array(side);
+    const stream = new RandomStream(seed, "genrmf", 0);
+    for (let f = 0; f < b; f++) {
+        const base = f * side;
+        frame.fill(f, base, base + side);
+        for (let r = 0; r < a; r++) {
+            for (let c = 0; c < a; c++) {
+                const count = gridArcs(out, base, a, a, r, c);
+                for (let i = 0; i < count; i++) {
+                    capacities.push(c2 * side);
+                }
+            }
+        }
+        if (f === b - 1) {
+            break;
+        }
+        stream.reset(f);
+        for (let i = 0; i < side; i++) {
+            perm[i] = i;
+        }
+        for (let i = side - 1; i > 0; i--) {
+            const j = stream.nextBelow(i + 1);
+            const t = perm[i];
+            perm[i] = perm[j];
+            perm[j] = t;
+        }
+        for (let j = 0; j < side; j++) {
+            out.push(base + j, base + side + perm[j]);
+            capacities.push(c1 + stream.nextBelow(c2 - c1 + 1));
+        }
+    }
+    return toNetwork(n, out, capacities, 0, n - 1, { frame });
+}
+/** The capacity of the AK network's terminal arcs, as in igraph's ak-4102.max instance. */
+const AK_BIG = 1000000;
+/**
+ * The AK network of B. V. Cherkassky and A. V. Goldberg ("On implementing the push-relabel method
+ * for the maximum flow problem", Algorithmica 19, 390-410, 1997, doi:10.1007/PL00009180), built to
+ * be hard for push-relabel. Deterministic; n = 4k + 6 nodes, m = 6k + 7 arcs.
+ *
+ * Nodes: s = 0, t = 1; part A a_i = 2 + i (i = 0 .. k); a hub chain h = k + 3 .. e = 2k + 3;
+ * part B b_i = 2k + 4 + i (i = 0 .. 2k + 1). Arcs, in this order: for i = 0 .. k - 1, a_i ->
+ * a_{i+1} (capacity k + 1 - i) then a_i -> h (1); a_k -> e (1), a_k -> h (1); the chain j -> j + 1
+ * for j = h .. e - 1 (k + 1); b_i -> b_{i+1} for i = 0 .. 2k (k); the folds b_i -> b_{2k+1-i}
+ * (1) for i = 0 .. k - 1; finally s -> a_0, s -> b_0, e -> t and b_{2k+1} -> t, each 1000000.
+ * The maximum flow is 2k + 3 and the largest inner capacity k + 1, so k is capped at 499998 to
+ * keep the terminal capacity 1000000 from ever binding (every value is then exact in Float32).
+ * Node column `role` (u8). O(k).
+ * @param options - k
+ * @returns the flow network
+ */
+export function akGraph(options) {
+    const { k } = options;
+    checkInt("k", k, 1, 499998);
+    const n = 4 * k + 6;
+    const out = new EdgeBuffer(6 * k + 7);
+    const capacities = [];
+    const arc = (u, v, capacity) => {
+        out.push(u, v);
+        capacities.push(capacity);
+    };
+    const hub = k + 3;
+    const chainEnd = 2 * k + 3;
+    const b0 = 2 * k + 4;
+    for (let i = 0; i < k; i++) {
+        arc(2 + i, 3 + i, k + 1 - i);
+        arc(2 + i, hub, 1);
+    }
+    arc(2 + k, chainEnd, 1);
+    arc(2 + k, hub, 1);
+    for (let j = hub; j < chainEnd; j++) {
+        arc(j, j + 1, k + 1);
+    }
+    for (let i = 0; i <= 2 * k; i++) {
+        arc(b0 + i, b0 + i + 1, k);
+    }
+    for (let i = 0; i < k; i++) {
+        arc(b0 + i, b0 + 2 * k + 1 - i, 1);
+    }
+    arc(0, 2, AK_BIG);
+    arc(0, b0, AK_BIG);
+    arc(chainEnd, 1, AK_BIG);
+    arc(b0 + 2 * k + 1, 1, AK_BIG);
+    return toNetwork(n, out, capacities, 0, 1, {});
+}
+//# sourceMappingURL=flow.js.map