@mark1russell7/highways 0.0.0-bootstrap.0 → 0.1.0

package/src/bench/quality.ts

@@ -0,0 +1,214 @@
+import {
+  bendCount,
+  dist,
+  frechet,
+  inflectionCount,
+  polylineLength,
+  segmentBoxDistance,
+  segmentsCross,
+  type Box,
+  type Point,
+} from "../geom.ts";
+import { rng } from "../fixtures.ts";
+import { Grid } from "../grid.ts";
+import { nodeIndex, type Graph, type Node, type Result } from "../model.ts";
+
+/** The quality of a result. Lower is better for each value except `clearance`. */
+export interface Quality {
+  /** The length of all drawn lines. A segment that several routes share counts one time. */
+  readonly ink: number;
+  /** The number of points where two drawn segments cross. */
+  readonly crossings: number;
+  /** This value is true when `crossings` is an estimate from a sample of the segments. */
+  readonly crossingsEstimated: boolean;
+  /** The mean number of bends of a route. */
+  readonly bends: number;
+  /** The mean number of inflections of a route. */
+  readonly inflections: number;
+  /** The mean distance from a route to the nearest node that is not one of its ends, up to `CLEARANCE_CAP`. */
+  readonly clearance: number;
+  /** The share of the routes that come closer than 4 units to a node that is not one of their ends. */
+  readonly tight: number;
+  /** The mean ratio of the length of a route to the distance between its ends. */
+  readonly detour: number;
+  /** The mean angle, in degrees, between the first or last segment of a route and the normal of the side of its node. */
+  readonly plugAngle: number;
+}
+
+/** The clearance stops at this distance. */
+export const CLEARANCE_CAP = 40;
+const TIGHT = 4;
+const EXACT_CROSSINGS = 20_000;
+const SAMPLE = 2_000;
+
+const key = (p: Point): string => `${Math.round(p.x * 8)},${Math.round(p.y * 8)}`;
+
+/** This function measures the quality of a result. */
+export function measureQuality(graph: Graph, result: Result): Quality {
+  const byId = nodeIndex(graph);
+  const nodes = new Grid<Node>(180);
+  for (const n of graph.nodes) nodes.add(n, n.box);
+
+  // The drawn segments: one for each distinct pair of ends.
+  const segs: [Point, Point][] = [];
+  const seen = new Set<string>();
+  let bends = 0;
+  let infl = 0;
+  let clear = 0;
+  let tight = 0;
+  let detour = 0;
+  let detourN = 0;
+  let angle = 0;
+  let angleN = 0;
+  for (const r of result.routes) {
+    const p = r.points;
+    for (let i = 1; i < p.length; i++) {
+      const ka = key(p[i - 1]!);
+      const kb = key(p[i]!);
+      if (ka === kb) continue;
+      const k = ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      segs.push([p[i - 1]!, p[i]!]);
+    }
+    bends += bendCount(p);
+    infl += inflectionCount(p);
+    const ends = endNodes(graph, byId, r.edge);
+    let c = CLEARANCE_CAP;
+    for (let i = 1; i < p.length; i++) {
+      const a = p[i - 1]!;
+      const b = p[i]!;
+      nodes.querySegment(a, b, c, (n) => {
+        if (n !== ends.source && n !== ends.target) c = Math.min(c, segmentBoxDistance(a, b, n.box));
+      });
+    }
+    clear += c;
+    if (c < TIGHT) tight++;
+    if (p.length >= 2) {
+      const d = dist(p[0]!, p[p.length - 1]!);
+      if (d > 1) {
+        detour += polylineLength(p) / d;
+        detourN++;
+      }
+      for (const [at, next, node] of [
+        [p[0]!, p[1]!, ends.source],
+        [p[p.length - 1]!, p[p.length - 2]!, ends.target],
+      ] as const) {
+        if (!node) continue;
+        const a = sideAngle(node.box, at, next);
+        if (a !== undefined) {
+          angle += a;
+          angleN++;
+        }
+      }
+    }
+  }
+  const n = Math.max(1, result.routes.length);
+  let ink = 0;
+  for (const [a, b] of segs) ink += dist(a, b);
+  const [crossings, crossingsEstimated] = countCrossings(segs);
+  return {
+    ink,
+    crossings,
+    crossingsEstimated,
+    bends: bends / n,
+    inflections: infl / n,
+    clearance: clear / n,
+    tight: tight / n,
+    detour: detourN ? detour / detourN : 1,
+    plugAngle: angleN ? angle / angleN : 0,
+  };
+}
+
+interface Ends {
+  readonly source: Node | undefined;
+  readonly target: Node | undefined;
+}
+
+function endNodes(graph: Graph, byId: Map<string, Node>, edgeId: string): Ends {
+  const e = edgeIndex(graph).get(edgeId);
+  return { source: e && byId.get(e.source.node), target: e && byId.get(e.target.node) };
+}
+
+const edgeIndexes = new WeakMap<Graph, Map<string, Graph["edges"][number]>>();
+function edgeIndex(graph: Graph): Map<string, Graph["edges"][number]> {
+  let m = edgeIndexes.get(graph);
+  if (!m) {
+    m = new Map();
+    for (const e of graph.edges) m.set(e.id, e);
+    edgeIndexes.set(graph, m);
+  }
+  return m;
+}
+
+/**
+ * This function gives an angle in degrees: the angle between the segment from `at` to `next` and the outward normal.
+ * The normal is the normal of the side of the box nearest to `at`. A route that starts inside the box (an interior route) gives no angle.
+ */
+export function sideAngle(box: Box, at: Point, next: Point): number | undefined {
+  const d = [
+    [Math.abs(at.y - box.y), 0, -1],
+    [Math.abs(at.x - (box.x + box.w)), 1, 0],
+    [Math.abs(at.y - (box.y + box.h)), 0, 1],
+    [Math.abs(at.x - box.x), -1, 0],
+  ].sort((a, b) => a[0]! - b[0]!)[0]!;
+  if (d[0]! > 1) return undefined;
+  const vx = next.x - at.x;
+  const vy = next.y - at.y;
+  const l = Math.hypot(vx, vy);
+  if (l === 0) return undefined;
+  const cos = Math.max(-1, Math.min(1, (vx * d[1]! + vy * d[2]!) / l));
+  return (Math.acos(cos) * 180) / Math.PI;
+}
+
+/**
+ * This function counts the crossings of a set of segments with a grid of buckets.
+ * Above 20 000 segments, it counts the crossings of a seeded sample of 2 000 segments and scales the count.
+ */
+export function countCrossings(segs: readonly (readonly [Point, Point])[]): [number, boolean] {
+  if (segs.length < 2) return [0, false];
+  const len = segs.reduce((s, [a, b]) => s + dist(a, b), 0) / segs.length;
+  const grid = new Grid<number>(Math.max(20, len));
+  segs.forEach(([a, b], i) => grid.addSegment(i, a, b));
+  const exact = segs.length <= EXACT_CROSSINGS;
+  const R = rng(segs.length);
+  const pick = exact ? segs.map((_, i) => i) : Array.from({ length: SAMPLE }, () => Math.floor(R() * segs.length));
+  let count = 0;
+  for (const i of pick) {
+    const [a, b] = segs[i]!;
+    grid.querySegment(a, b, 0, (j) => {
+      if (exact && j <= i) return;
+      if (j === i) return;
+      const [c, d] = segs[j]!;
+      if (segmentsCross(a, b, c, d)) count++;
+    });
+  }
+  return exact ? [count, false] : [Math.round((count * segs.length) / (2 * pick.length)), true];
+}
+
+/** The change between two results of the same graph: the Fréchet distance between the two routes of each edge. */
+export interface Stability {
+  readonly mean: number;
+  readonly max: number;
+  /** The share of the routes that moved more than 1 unit. */
+  readonly moved: number;
+}
+
+/** This function measures how much the routes changed between two results. */
+export function measureStability(before: Result, after: Result): Stability {
+  const prev = new Map(before.routes.map((r) => [r.edge, r.points] as const));
+  let sum = 0;
+  let max = 0;
+  let moved = 0;
+  let n = 0;
+  for (const r of after.routes) {
+    const p = prev.get(r.edge);
+    if (!p) continue;
+    const f = frechet(p, r.points);
+    sum += f;
+    max = Math.max(max, f);
+    if (f > 1) moved++;
+    n++;
+  }
+  return { mean: n ? sum / n : 0, max, moved: n ? moved / n : 0 };
+}

package/src/bench/run.ts

@@ -0,0 +1,103 @@
+import { makeFixture, type FixtureSpec } from "../fixtures.ts";
+import type { Graph, Result, Router } from "../model.ts";
+import { checkProperties, type Violation } from "./properties.ts";
+import { measureQuality, type Quality } from "./quality.ts";
+
+// The core runs in any host, so it reads the clock without the types of Node or the browser.
+const now = (): number => (globalThis as { performance?: { now(): number } }).performance?.now() ?? Date.now();
+
+/** One row of the benchmark: one router on one fixture. */
+export interface BenchRow {
+  readonly router: string;
+  readonly fixture: string;
+  readonly nodes: number;
+  readonly edges: number;
+  /** The median time of one run, in milliseconds. */
+  readonly ms: number;
+  /** This value is false when two runs on the same input gave different results. */
+  readonly deterministic: boolean;
+  readonly violations: number;
+  /** The first violations, for the report. */
+  readonly sample: readonly Violation[];
+  readonly quality: Quality;
+}
+
+/** The options of a benchmark run. */
+export interface BenchOptions {
+  /** The number of timed routes of each fixture by each router. The default is 3. */
+  readonly repeat?: number;
+}
+
+/** This function routes each fixture with each router, checks the hard rules and measures the quality. */
+export function runBenchmark(routers: readonly Router[], fixtures: readonly FixtureSpec[], options: BenchOptions = {}): BenchRow[] {
+  const rows: BenchRow[] = [];
+  for (const spec of fixtures) {
+    const graph = makeFixture(spec);
+    for (const router of routers) if (graph.nodes.length <= (router.maxNodes ?? Infinity)) rows.push(benchOne(router, spec.name, graph, options.repeat ?? 3));
+  }
+  return rows;
+}
+
+/**
+ * This function tells if two values hold the same data, as JSON sees it. It does not make a string,
+ * because the result of a large graph can be longer than the longest string.
+ */
+export function sameData(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const y = b as unknown[];
+    if (a.length !== y.length) return false;
+    for (let i = 0; i < a.length; i++) if (!sameData(a[i], y[i])) return false;
+    return true;
+  }
+  const x = a as Record<string, unknown>;
+  const y = b as Record<string, unknown>;
+  const kx = Object.keys(x).filter((k) => x[k] !== undefined);
+  const ky = Object.keys(y).filter((k) => y[k] !== undefined);
+  if (kx.length !== ky.length) return false;
+  for (const k of kx) if (!sameData(x[k], y[k])) return false;
+  return true;
+}
+
+/** This function routes one graph with one router and measures the result. */
+export function benchOne(router: Router, fixture: string, graph: Graph, repeat = 3): BenchRow {
+  const times: number[] = [];
+  let first: Result | undefined;
+  let deterministic = true;
+  for (let i = 0; i < Math.max(2, repeat); i++) {
+    const t0 = now();
+    const r = router.route(graph);
+    times.push(now() - t0);
+    if (!first) first = r;
+    else if (i === 1 && !sameData(r, first)) deterministic = false;
+  }
+  times.sort((a, b) => a - b);
+  const result = first!;
+  const all = checkProperties(graph, result, 1_000_000);
+  return {
+    router: router.name,
+    fixture,
+    nodes: graph.nodes.length,
+    edges: graph.edges.length,
+    ms: times[Math.floor(times.length / 2)]!,
+    deterministic,
+    violations: all.length,
+    sample: all.slice(0, 5),
+    quality: measureQuality(graph, result),
+  };
+}
+
+/** This function writes the rows as a Markdown table. */
+export function formatTable(rows: readonly BenchRow[]): string {
+  const head = "| router | fixture | nodes | edges | ms | same twice | violations | ink | crossings | bends | inflections | clearance | tight | detour | plug angle |";
+  const line = "|---|---|---:|---:|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|";
+  const f = (v: number, d = 2): string => (Number.isInteger(v) ? String(v) : v.toFixed(d));
+  const body = rows.map((r) => {
+    const q = r.quality;
+    return `| ${r.router} | ${r.fixture} | ${r.nodes} | ${r.edges} | ${f(r.ms, 1)} | ${r.deterministic ? "yes" : "NO"} | ${r.violations} | ${Math.round(q.ink)} | ${q.crossingsEstimated ? "≈" : ""}${q.crossings} | ${f(q.bends)} | ${f(q.inflections)} | ${f(q.clearance, 1)} | ${f(q.tight)} | ${f(q.detour)} | ${f(q.plugAngle, 1)} |`;
+  });
+  return [head, line, ...body].join("\n");
+}

package/src/curves.ts

@@ -0,0 +1,89 @@
+import { dist, type Point } from "./geom.ts";
+
+/** The options of the inflection rule. */
+export interface InflectionOptions {
+  /** The half width of the axis and diagonal bands, in radians. The default is 7°. */
+  readonly tol?: number;
+  /** The number of segments of the curve. The default is 24. */
+  readonly samples?: number;
+  /** The largest angle between the tangent and the chord, in radians. The default is 1.35 (approximately 77°). */
+  readonly maxAngle?: number;
+}
+
+/**
+ * This function gives the number of inflections that the rule asks for a chord at the angle `angle` (radians).
+ * It gives 0 near an axis, 1 near a diagonal and 2 between them. The bands are `tol` wide on each side.
+ */
+export function inflectionSector(angle: number, tol: number = (7 * Math.PI) / 180): 0 | 1 | 2 {
+  const q = Math.PI / 2;
+  const mod = ((angle % q) + q) % q;
+  if (mod < tol || q - mod < tol) return 0;
+  if (Math.abs(mod - q / 2) < tol) return 1;
+  return 2;
+}
+
+/**
+ * This function draws the curve of the inflection rule from the plug `p0` to `target`.
+ * The curve leaves `p0` along `normal`. In the frame of the chord, its side offset f has f(0) = f(L) = 0 and f'(0) = tan θ.
+ * Here θ is the angle from the chord to the normal. A polynomial of degree 2, 3 or 4 gives 0, 1 or 2 inflections,
+ * at 1/2, or at 1/3 and 2/3, of the chord.
+ */
+export function inflectionCurve(p0: Point, normal: Point, target: Point, options: InflectionOptions = {}): Point[] {
+  const L = dist(p0, target);
+  if (L === 0) return [p0, target];
+  const ux = (target.x - p0.x) / L;
+  const uy = (target.y - p0.y) / L;
+  const k = inflectionSector(Math.atan2(uy, ux), options.tol);
+  const maxAngle = options.maxAngle ?? 1.35;
+  const th = -Math.atan2(normal.x * uy - normal.y * ux, normal.x * ux + normal.y * uy);
+  const d = Math.tan(Math.max(-maxAngle, Math.min(maxAngle, th)));
+  const f =
+    k === 0
+      ? (s: number): number => (-d / L) * s * s + d * s
+      : k === 1
+        ? (s: number): number => ((12 * d) / (L * L)) * (s ** 3 / 6 - (L * s * s) / 4) + d * s
+        : (s: number): number => ((-36 * d) / L ** 3) * (s ** 4 / 12 - (L * s ** 3) / 6 + (L * L * s * s) / 9) + d * s;
+  const n = Math.max(2, options.samples ?? 24);
+  const out: Point[] = [];
+  for (let i = 0; i <= n; i++) {
+    if (i === n) {
+      out.push(target);
+      break;
+    }
+    const s = (L * i) / n;
+    const o = f(s);
+    out.push({ x: p0.x + ux * s - uy * o, y: p0.y + uy * s + ux * o });
+  }
+  out[0] = p0;
+  return out;
+}
+
+/**
+ * This function rounds each inner vertex of a polyline with a quadratic Bézier curve.
+ * The curve starts and ends at most `radius` from the vertex, and at most half of each segment. The ends of the polyline stay.
+ */
+export function roundCorners(p: readonly Point[], radius: number, steps = 4): Point[] {
+  if (p.length < 3 || radius <= 0) return [...p];
+  const out: Point[] = [p[0]!];
+  for (let i = 1; i + 1 < p.length; i++) {
+    const a = p[i - 1]!;
+    const v = p[i]!;
+    const b = p[i + 1]!;
+    const la = dist(a, v);
+    const lb = dist(v, b);
+    const r = Math.min(radius, la / 2, lb / 2);
+    if (r <= 0) {
+      out.push(v);
+      continue;
+    }
+    const p1 = { x: v.x + ((a.x - v.x) * r) / la, y: v.y + ((a.y - v.y) * r) / la };
+    const p2 = { x: v.x + ((b.x - v.x) * r) / lb, y: v.y + ((b.y - v.y) * r) / lb };
+    for (let k = 0; k <= steps; k++) {
+      const t = k / steps;
+      const u = 1 - t;
+      out.push({ x: u * u * p1.x + 2 * u * t * v.x + t * t * p2.x, y: u * u * p1.y + 2 * u * t * v.y + t * t * p2.y });
+    }
+  }
+  out.push(p[p.length - 1]!);
+  return out;
+}

package/src/fixtures.ts

@@ -0,0 +1,181 @@
+import type { Box, Point } from "./geom.ts";
+import { Grid } from "./grid.ts";
+import type { Edge, Graph, Node, Port, Side } from "./model.ts";
+
+/** This function gives a seeded random source with values in [0, 1) (mulberry32). */
+export function rng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * The ways a fixture puts its nodes and picks its edges. In `collections`, each cluster is one collection,
+ * and some nodes link to many nodes of one other collection (a fan-out).
+ */
+export type FixtureKind = "uniform" | "clustered" | "grid" | "hubs" | "collections";
+
+/** The parameters of a generated graph. */
+export interface FixtureSpec {
+  readonly name: string;
+  readonly kind: FixtureKind;
+  readonly nodes: number;
+  /** The number of edges is about `nodes × edgesPerNode`. */
+  readonly edgesPerNode: number;
+  readonly seed: number;
+  /** This share of the edges, from 0 to 1, joins a node near the source. */
+  readonly locality?: number;
+  /** This share of the nodes, from 0 to 1, has one fixed plug that its outgoing edges use. */
+  readonly fixedPorts?: number;
+}
+
+/** The fixtures of the benchmark, from 10 to 100 000 nodes. */
+export const FIXTURES: readonly FixtureSpec[] = [
+  { name: "tiny-uniform", kind: "uniform", nodes: 10, edgesPerNode: 1.5, seed: 1 },
+  { name: "small-clustered", kind: "clustered", nodes: 100, edgesPerNode: 2, seed: 2, fixedPorts: 0.2 },
+  { name: "grid-400", kind: "grid", nodes: 400, edgesPerNode: 2, seed: 3 },
+  { name: "mid-uniform", kind: "uniform", nodes: 1000, edgesPerNode: 2, seed: 4 },
+  { name: "mid-clustered", kind: "clustered", nodes: 1000, edgesPerNode: 3, seed: 5, fixedPorts: 0.2 },
+  { name: "mid-hubs", kind: "hubs", nodes: 1000, edgesPerNode: 2, seed: 6 },
+  { name: "mid-fanout", kind: "collections", nodes: 1000, edgesPerNode: 2, seed: 9 },
+  { name: "large-clustered", kind: "clustered", nodes: 10_000, edgesPerNode: 3, seed: 7 },
+  { name: "huge-clustered", kind: "clustered", nodes: 100_000, edgesPerNode: 2, seed: 8 },
+];
+
+const COLLECTIONS = ["users", "modes", "speeds", "scores", "teams"] as const;
+const SIDES: readonly Side[] = ["north", "east", "south", "west"];
+const GAP = 12;
+const SPACING = 90;
+
+/**
+ * This function makes the graph of a fixture. The same spec always gives the same graph.
+ * Node boxes do not overlap, and a gap of 12 units stays between them.
+ */
+export function makeFixture(spec: FixtureSpec): Graph {
+  const R = rng(spec.seed * 2654435761 + spec.nodes);
+  const gauss = (): number => Math.sqrt(-2 * Math.log(R() + 1e-12)) * Math.cos(2 * Math.PI * R());
+  const side = Math.sqrt(spec.nodes) * SPACING;
+  const grid = new Grid<Box>(SPACING);
+  const nodes: Node[] = [];
+  const clusterOf: number[] = [];
+  const free = (b: Box): boolean => {
+    let ok = true;
+    const g: Box = { x: b.x - GAP, y: b.y - GAP, w: b.w + 2 * GAP, h: b.h + 2 * GAP };
+    grid.query(g, (o) => {
+      if (ok && o.x < g.x + g.w && g.x < o.x + o.w && o.y < g.y + g.h && g.y < o.y + o.h) ok = false;
+    });
+    return ok;
+  };
+  const centers: Point[] = Array.from({ length: Math.max(3, Math.round(Math.sqrt(spec.nodes) / 3)) }, () => ({
+    x: side * (0.1 + 0.8 * R()),
+    y: side * (0.1 + 0.8 * R()),
+  }));
+  const spread = side / (2.5 * Math.sqrt(centers.length));
+  const cols = Math.ceil(Math.sqrt(spec.nodes));
+  let tries = 0;
+  while (nodes.length < spec.nodes && tries++ < spec.nodes * 200) {
+    const w = 30 + Math.floor(R() * 30);
+    const h = 18 + Math.floor(R() * 12);
+    let cx: number;
+    let cy: number;
+    let cluster = -1;
+    if (spec.kind === "grid") {
+      const i = nodes.length;
+      cx = ((i % cols) + 0.5) * SPACING;
+      cy = (Math.floor(i / cols) + 0.5) * SPACING;
+    } else if (spec.kind === "clustered" || spec.kind === "collections") {
+      cluster = Math.floor(R() * centers.length);
+      const c = centers[cluster]!;
+      cx = c.x + gauss() * spread;
+      cy = c.y + gauss() * spread;
+    } else {
+      cx = R() * side;
+      cy = R() * side;
+    }
+    const box: Box = { x: Math.round(cx - w / 2), y: Math.round(cy - h / 2), w, h };
+    if (spec.kind !== "grid" && !free(box)) continue;
+    grid.add(box, box);
+    clusterOf.push(cluster);
+    const id = `n${nodes.length}`;
+    if (R() < (spec.fixedPorts ?? 0)) {
+      const s = SIDES[Math.floor(R() * 4)]!;
+      const t = 0.2 + 0.6 * R();
+      const at: Point =
+        s === "north" ? { x: w * t, y: 0 } : s === "south" ? { x: w * t, y: h } : s === "west" ? { x: 0, y: h * t } : { x: w, y: h * t };
+      const ports: Port[] = [{ id: "out", at: { x: Math.round(at.x), y: Math.round(at.y) } }];
+      nodes.push({ id, box, ports });
+    } else nodes.push({ id, box });
+  }
+  return { nodes, edges: makeEdges(spec, nodes, clusterOf, R) };
+}
+
+function makeEdges(spec: FixtureSpec, nodes: readonly Node[], clusterOf: readonly number[], R: () => number): Edge[] {
+  const n = nodes.length;
+  if (n < 2) return [];
+  const locality = spec.locality ?? 0.65;
+  const near = new Grid<number>(SPACING * 2);
+  nodes.forEach((v, i) => near.add(i, v.box));
+  const kindOf =
+    spec.kind === "collections"
+      ? clusterOf.map((c) => `${COLLECTIONS[c % COLLECTIONS.length]!}-${c}`)
+      : nodes.map(() => COLLECTIONS[Math.floor(R() * COLLECTIONS.length)]!);
+  // Hubs: a few nodes get most of the far edges (preferential attachment by a power law).
+  const pickFar = (): number => (spec.kind === "hubs" ? Math.floor(n * R() ** 3) : Math.floor(R() * n));
+  const target = Math.round(n * spec.edgesPerNode);
+  const seen = new Set<string>();
+  const edges: Edge[] = [];
+  const add = (u: number, v: number): void => {
+    const key = u < v ? `${u}-${v}` : `${v}-${u}`;
+    if (u === v || seen.has(key)) return;
+    seen.add(key);
+    const src = nodes[u]!;
+    edges.push({
+      id: `e${edges.length}`,
+      source: src.ports ? { node: src.id, port: "out" } : { node: src.id },
+      target: { node: nodes[v]!.id },
+      data: { collection: kindOf[v]! },
+    });
+  };
+  if (spec.kind === "collections") {
+    // Six of ten edges are fan-outs: a node links to 4 to 15 nodes of one other cluster.
+    const members = new Map<number, number[]>();
+    clusterOf.forEach((c, i) => {
+      const list = members.get(c);
+      if (list) list.push(i);
+      else members.set(c, [i]);
+    });
+    const clusters = [...members.keys()].sort((a, c) => a - c);
+    let rounds = 0;
+    while (edges.length < target * 0.6 && clusters.length > 1 && rounds++ < target) {
+      const u = Math.floor(R() * n);
+      const others = clusters.filter((c) => c !== clusterOf[u]);
+      const pool = members.get(others[Math.floor(R() * others.length)]!)!;
+      const fan = 4 + Math.floor(R() * 12);
+      for (let i = 0; i < fan; i++) add(u, pool[Math.floor(R() * pool.length)]!);
+    }
+  }
+  let tries = 0;
+  while (edges.length < target && tries++ < target * 30) {
+    const u = Math.floor(R() * n);
+    let v = -1;
+    if (R() < locality) {
+      const b = nodes[u]!.box;
+      const cand: number[] = [];
+      for (let r = SPACING; cand.length < 8 && r < SPACING * 64; r *= 2) {
+        cand.length = 0;
+        near.query({ x: b.x - r, y: b.y - r, w: b.w + 2 * r, h: b.h + 2 * r }, (i) => {
+          if (i !== u) cand.push(i);
+        });
+      }
+      cand.sort((a, c) => a - c);
+      if (cand.length) v = cand[Math.floor(R() * cand.length)]!;
+    } else v = pickFar();
+    if (v >= 0) add(u, v);
+  }
+  return edges;
+}