@mark1russell7/highways 0.8.1 → 0.9.0

package/src/bench/screen/set.ts

@@ -1,7 +1,6 @@
-import { hubChainBoard, manyGroupsBoard, packedGridBoard } from "../../cases.ts";
-import { FIXTURES, makeFixture, type FixtureSpec } from "../../fixtures.ts";
+import { checkDeclared, corpusHashOf, SPLIT_SCHEMA, splitFileName, type ClaimBreak, type CorpusSplit, type DeclaredClaim, type FamilyBy, type FamilyCell } from "@mark1russell7/layout-contract";
+import { highwaysRegistry, type HighwaysBoard } from "../../families/index.ts";
 import type { Graph } from "../../model.ts";
-import { familySeed } from "../suite.ts";
 import { EXACT_V1, EXACT_V1_BOUNDS } from "./exact-set.ts";
 import { graphInput, type LayoutCell, type LayoutGenerator, type LayoutInput } from "./forms.ts";
 
@@ -20,74 +19,123 @@ export interface ScreenFamily {
   readonly cell: LayoutCell;
 }
 
+/**
+ * The key of the family of a screen input (SCREEN-WEIGHT). The map form gives the kind of the cell as the key, with no other dimension.
+ * The cells of a screen set have no `kind`, and `dense-groups` and `many-groups` have the same cell. Thus `familyCell` adds the family of the input as the kind.
+ */
+export const SCREEN_FAMILY_BY: FamilyBy = Object.freeze({ "*": Object.freeze([]) as readonly string[] });
+
+/** This function gives the cell of an input for the key `familyBy`: the cell of the input, with its family as `kind`. */
+export const familyCell = (input: { readonly family: string; readonly cell?: LayoutCell }): FamilyCell => ({ ...input.cell, kind: input.family });
+
+/** The claims of a manifest. `declared` gives the count of the inputs of each family (`docs/CORPUS-CHECKS.md` of `layout-contract`). */
+export interface CorpusClaims {
+  readonly declared: DeclaredClaim;
+}
+
 /** A screen set: a fixed list of small boards with an id. A new board or a changed board gets a new id. */
 export interface ScreenSet {
   /** The id of the set, for example `screen-v1`. The records name it in `set` and `corpus`. */
   readonly id: string;
   readonly families: readonly ScreenFamily[];
+  /** The claims of the manifest of the set. A set without claims has no field `claims` in its manifest. */
+  readonly claims?: CorpusClaims;
+  /** The member seeds of each family that the split `default` holds out. A set without them has no split file. */
+  readonly heldOut?: readonly number[];
 }
 
-const fixture = (name: string): FixtureSpec => FIXTURES.find((f) => f.name === name)!;
-const DENSE: FixtureSpec = { name: "dense-groups", kind: "clustered", nodes: 150, edgesPerNode: 2, seed: 3 };
-const PACKED = { cols: 12, rows: 8, long: 48 } as const;
+/** The registry of the screen sets (CORPUS-GEN). The screens and the site make each board with the same families. */
+const REGISTRY = highwaysRegistry();
 
-/** This function gives a family of `makeFixture`. The member `k` has the seed `familySeed(spec, k)`, as in `runSuite`. */
-function fixtureFamily(spec: FixtureSpec, shows: string, seeds: number, cell: LayoutCell): ScreenFamily {
-  const { name, seed: _seed, ...params } = spec;
-  return {
-    name,
-    shows,
-    seeds,
-    cell,
-    make: (k) => makeFixture({ ...spec, seed: familySeed(spec, k) }),
-    generator: (k) => ({ name: "fixture", version: 1, params, seed: familySeed(spec, k) }),
+/**
+ * This function gives a screen family of a corpus family at its defaults. The member `k` has the input seed `base + 1009 * k`, the rule of `familySeed`.
+ * The family keeps the board of its last member, so `make(k)` and `generator(k)` of one member generate one time.
+ */
+function registryFamily(name: string, base: number, shows: string, seeds: number, cell: LayoutCell): ScreenFamily {
+  let last: { readonly k: number; readonly board: HighwaysBoard } | undefined;
+  const board = (k: number): HighwaysBoard => {
+    if (last?.k !== k) last = { k, board: REGISTRY.generate(name, caseSeed(base, k)) };
+    return last.board;
   };
+  return { name, shows, seeds, cell, make: (k) => board(k).graph, generator: (k) => board(k).generator };
 }
 
 /** The cell dimensions that each family of `screen-v1` shares. */
 const BASE = { containerSize: "freeAspect", containerShape: "rect", obstacles: "none", mode: "offline", groups: "none" } as const;
 
+/** This function gives the seed of the member `k` of a case board with the base seed `base`: `base + 1009 * k`, the rule of `familySeed`. */
+export function caseSeed(base: number, k: number): number {
+  return base + 1009 * k;
+}
+
+/**
+ * This function gives the 6 families of the screen. Each fixture family and `packed-grid` has `seeds` members.
+ * The case boards `hub-chain` and `many-groups` have `caseSeeds` members. The member `k` of a family has the seed of its rule for `k`.
+ * Each family is a family of `HIGHWAYS_FAMILIES` at its defaults. The base seeds are the seeds of the fixtures and the case boards of the benchmark.
+ */
+function screenFamilies(seeds: number, caseSeeds: number): ScreenFamily[] {
+  return [
+    registryFamily("tiny-uniform", 1, "A tiny board: the cost of a strategy at its start.", seeds, { ...BASE, count: "10", edgeDensity: "medium", edgeShape: "random", ports: "free" }),
+    registryFamily("small-clustered", 2, "Clusters, and fixed plugs on 20% of the nodes.", seeds, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "fixed" }),
+    registryFamily("dense-groups", 3, "Dense groups whose boxes overlap at the far view.", seeds, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "free" }),
+    registryFamily("hub-chain", 3, "A chain of hubs: routes climb away from their targets.", caseSeeds, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "hubChain", ports: "free" }),
+    registryFamily("many-groups", 7, "Many groups: level links go around the board.", caseSeeds, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "free" }),
+    registryFamily("packed-grid", 11, "A packed grid: boxes touch, with no channel for the routes.", seeds, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "longRange", ports: "free" }),
+  ];
+}
+
+const V1_FAMILIES = screenFamilies(3, 1);
+
 /**
  * The screen set `screen-v1`: 14 boards of made-up data from 10 to 150 nodes. Each family shows a known hard case.
  * The seed 0 of each family is the fixture or the case board of the benchmark. The seed `k` of a fixture family is `familySeed(spec, k)`, as in `runSuite`.
  * The generators wrap the fixtures and the case boards without a change to their output.
- * This set does not change. The tests compare it with the files in `corpus/screen-v1`.
+ *
+ * The manifest declares the inputs of each family, with `minCount` 3. The case boards `hub-chain` and `many-groups` have 1 input, so they are in `thin`.
+ * The boards of this set do not change. The tests compare it with the files in `corpus/screen-v1`.
  */
 export const SCREEN_V1: ScreenSet = {
   id: "screen-v1",
-  families: [
-    fixtureFamily(fixture("tiny-uniform"), "A tiny board: the cost of a strategy at its start.", 3, { ...BASE, count: "10", edgeDensity: "medium", edgeShape: "random", ports: "free" }),
-    fixtureFamily(fixture("small-clustered"), "Clusters, and fixed plugs on 20% of the nodes.", 3, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "fixed" }),
-    fixtureFamily(DENSE, "Dense groups whose boxes overlap at the far view.", 3, { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "free" }),
-    {
-      name: "hub-chain",
-      shows: "A chain of hubs: routes climb away from their targets.",
-      seeds: 1,
-      cell: { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "hubChain", ports: "free" },
-      make: () => hubChainBoard(),
-      generator: () => ({ name: "case.hub-chain", version: 1, params: {}, seed: 3 }),
-    },
-    {
-      name: "many-groups",
-      shows: "Many groups: level links go around the board.",
-      seeds: 1,
-      cell: { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "clustered", ports: "free" },
-      make: () => manyGroupsBoard(),
-      generator: () => ({ name: "case.many-groups", version: 1, params: {}, seed: 7 }),
-    },
-    {
-      name: "packed-grid",
-      shows: "A packed grid: boxes touch, with no channel for the routes.",
-      seeds: 3,
-      cell: { ...BASE, count: "100", edgeDensity: "medium", edgeShape: "longRange", ports: "free" },
-      make: (k) => packedGridBoard({ ...PACKED, seed: 11 + 1009 * k }),
-      generator: (k) => ({ name: "case.packed-grid", version: 1, params: PACKED, seed: 11 + 1009 * k }),
+  families: V1_FAMILIES,
+  claims: {
+    declared: {
+      minCount: 3,
+      thin: V1_FAMILIES.filter((f) => f.seeds < 3).map((f) => f.name),
+      counts: Object.fromEntries(V1_FAMILIES.map((f) => [f.name, f.seeds])),
+      familyBy: SCREEN_FAMILY_BY,
     },
-  ],
+  },
+};
+
+/** The member seeds of each family of `screen-v2` that the split `default` holds out. */
+export const SCREEN_V2_HELD_OUT: readonly number[] = [7, 8, 9];
+
+const V2_FAMILIES = screenFamilies(10, 10);
+
+/**
+ * The screen set `screen-v2` (CORPUS-SEEDS): the 6 families of `screen-v1`, each with the 10 members 0 to 9, thus 60 boards.
+ * Each family keeps the seed rule of `screen-v1`. Thus the members 0 to 2 are the boards of `screen-v1`, and the member 0 of `hub-chain` and `many-groups` is their board.
+ *
+ * The manifest declares 10 inputs for each family, and each family key has 10 inputs or more. The split `default` holds out the members 7 to 9 of each family.
+ * This set does not change. The tests compare it with the files in `corpus/screen-v2`.
+ */
+export const SCREEN_V2: ScreenSet = {
+  id: "screen-v2",
+  families: V2_FAMILIES,
+  claims: { declared: { minCount: 10, thin: [], counts: Object.fromEntries(V2_FAMILIES.map((f) => [f.name, f.seeds])), familyBy: SCREEN_FAMILY_BY, familyMin: 10 } },
+  heldOut: SCREEN_V2_HELD_OUT,
 };
 
-/** The screen sets by id: `screen-v1`, the small boards with a known optimum `exact-v1` (MEAS2), and the larger boards with bounds `exact-v1-bounds` (EXACT-BOUNDS). */
-export const SCREEN_SETS: Readonly<Record<string, ScreenSet>> = { [SCREEN_V1.id]: SCREEN_V1, [EXACT_V1.id]: EXACT_V1, [EXACT_V1_BOUNDS.id]: EXACT_V1_BOUNDS };
+/**
+ * The screen sets by id. `screen-v1` and its larger version `screen-v2` (CORPUS-SEEDS) have the boards of the screen.
+ * `exact-v1` has small boards with a known optimum (MEAS2). `exact-v1-bounds` has larger boards with bounds (EXACT-BOUNDS).
+ */
+export const SCREEN_SETS: Readonly<Record<string, ScreenSet>> = {
+  [SCREEN_V1.id]: SCREEN_V1,
+  [SCREEN_V2.id]: SCREEN_V2,
+  [EXACT_V1.id]: EXACT_V1,
+  [EXACT_V1_BOUNDS.id]: EXACT_V1_BOUNDS,
+};
 
 /** This function gives the id of the member `seed` of a family of a set: `<set>/<family>/s<seed>`. */
 export function inputId(set: string, family: string, seed: number): string {
@@ -115,10 +163,14 @@ export interface LayoutCorpus {
   readonly corpus: string;
   readonly specs: readonly CorpusSpec[];
   readonly inputs: readonly { readonly id: string; readonly hash: string; readonly cell: LayoutCell }[];
+  readonly claims?: CorpusClaims;
 }
 
-/** This function gives the manifest of a list of inputs. The inputs of one generator, version and parameters share one spec. */
-export function corpusManifest(corpus: string, inputs: readonly LayoutInput[]): LayoutCorpus {
+/**
+ * This function gives the manifest of a list of inputs. The inputs of one generator, version and parameters share one spec.
+ * With `claims`, the manifest has the field `claims`.
+ */
+export function corpusManifest(corpus: string, inputs: readonly LayoutInput[], claims?: CorpusClaims): LayoutCorpus {
   const specs = new Map<string, { generator: string; version: number; params: Readonly<Record<string, unknown>>; seeds: number[] }>();
   for (const input of inputs) {
     const g = input.generator;
@@ -133,5 +185,60 @@ export function corpusManifest(corpus: string, inputs: readonly LayoutInput[]):
     corpus,
     specs: [...specs.values()],
     inputs: inputs.map((i) => ({ id: i.id, hash: i.hash, cell: i.cell ?? {} })),
+    ...(claims ? { claims } : {}),
+  };
+}
+
+/** This function gives the manifest of a screen set, with the claims of the set. */
+export function setManifest(set: ScreenSet, inputs: readonly LayoutInput[] = screenInputs(set)): LayoutCorpus {
+  return corpusManifest(set.id, inputs, set.claims);
+}
+
+/** The hook of the claim `declared` of a screen set: each input declares its family. */
+export const declaresFamily = (input: { readonly family: string }): readonly string[] => [input.family];
+
+/**
+ * This function checks the claim `declared` of a manifest against its inputs, with the shared check of the contract. A manifest without the claim gives no break.
+ * With `familyBy`, the check reads the cell of each input with `familyCell`.
+ */
+export function checkFamilies(manifest: LayoutCorpus, inputs: readonly LayoutInput[]): ClaimBreak[] {
+  const claim = manifest.claims?.declared;
+  return claim ? checkDeclared(inputs, declaresFamily, claim, undefined, familyCell) : [];
+}
+
+/** This function gives the hash of the corpus of a manifest with the shared function `corpusHashOf` of the contract. It reads the input ids and the input hashes. */
+export function manifestHash(manifest: LayoutCorpus): string {
+  return corpusHashOf(manifest.corpus, manifest.inputs);
+}
+
+/**
+ * This function gives the split file `corpus-split/1` of a screen set with `heldOut`. A set without `heldOut` gives `undefined`.
+ * The seeds of a split file are the seeds of the specs of the manifest. Thus each fold lists the generator seeds of its members.
+ * - The split `default` has one fold. It holds out the members `heldOut` of each family and trains on the other members.
+ * - The split `by-member` has one fold for each member `k`. The fold holds out the member `k` of each family.
+ */
+export function screenSplit(set: ScreenSet, manifest: LayoutCorpus = setManifest(set)): CorpusSplit | undefined {
+  const heldOut = set.heldOut;
+  if (!heldOut) return undefined;
+  const members = Math.max(...set.families.map((f) => f.seeds));
+  const seedsOf = (keep: (k: number) => boolean): number[] => {
+    const out = new Set<number>();
+    for (const f of set.families) for (let k = 0; k < f.seeds; k++) if (keep(k)) out.add(f.generator(k).seed);
+    return [...out].sort((a, b) => a - b);
+  };
+  const fold = (out: (k: number) => boolean) => ({ train: seedsOf((k) => !out(k)), heldOut: seedsOf(out) });
+  return {
+    schema: SPLIT_SCHEMA,
+    corpus: set.id,
+    corpusHash: manifestHash(manifest),
+    splits: {
+      default: { folds: [fold((k) => heldOut.includes(k))] },
+      "by-member": { folds: Array.from({ length: members }, (_, m) => fold((k) => k === m)) },
+    },
   };
 }
+
+/** This function gives the path of the split file of a corpus, relative to the folder of the corpora: `splits/<corpus id>.<corpus hash>.json`. */
+export function splitPath(split: CorpusSplit): string {
+  return `splits/${splitFileName(split.corpus, split.corpusHash)}`;
+}

package/src/bench/suite.ts

@@ -24,7 +24,7 @@ import { boardUnit, crossingAngles, detourSpread, drawnSegments, plugSpacing, to
 import { changeGraph, routeStability } from "./measures/stability.ts";
 import { quantile, summarize, type Spread } from "./measures/stats.ts";
 import { measureBoard } from "./room.ts";
-import { benchRun, type BenchRow } from "./run.ts";
+import { benchRun, type BenchRow, type Paired } from "./run.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();
@@ -64,6 +64,26 @@ export interface SuiteOptions {
   readonly steps?: readonly Step[];
   /** The time limit of one cell of the step `router`, in milliseconds, as `BenchOptions.cellLimit` gives it. The default is no limit. */
   readonly cellLimit?: number;
+  /**
+   * One shard of the cells of the steps `router` and `highway` (BENCH-GREEN). The default is all the cells.
+   * The strategy at place `s` of its step, on the seed `k`, belongs to the shard `(s + k) % count`, from 0.
+   * So the seeds of one strategy go to different shards, and each shard gets a similar share of the time.
+   * A shard has only these two steps and the step `curve`, because the cells of the other steps do not divide.
+   */
+  readonly shard?: { readonly index: number; readonly count: number };
+  /**
+   * The largest fixture of a strategy of the steps `router` and `highway`, in nodes, by the name of the strategy. The default is no cap.
+   * A capped strategy does not route a larger fixture. The report lists each such cell in `capped`, so the row is capped, not missing.
+   */
+  readonly caps?: Readonly<Record<string, number>>;
+  /**
+   * The name of the baseline router of the paired arm, for example `shared`. The default is no paired arm.
+   * On the first seed of each fixture, the baseline routes the same graph in turn with each strategy of the steps `router` and `highway`.
+   * The row and the bench row then get `paired`.
+   */
+  readonly pair?: string;
+  /** The paired arm routes only the fixtures up to this number of nodes. The default is 1000. */
+  readonly pairMax?: number;
   /** This function gets one line of progress for each fixture and seed. */
   readonly log?: (line: string) => void;
 }
@@ -108,6 +128,19 @@ export interface SuiteRow {
   readonly treeMs?: number;
   /** The measures, by a key that starts with the id of MEAS0, or the name of a proposed rule. */
   readonly values: Readonly<Record<string, number>>;
+  /** The time of the paired baseline arm (`SuiteOptions.pair`). Only the first seed of a fixture has it. */
+  readonly paired?: Paired;
+}
+
+/** A cell that the suite did not route, because the fixture is larger than the cap of the strategy (`SuiteOptions.caps`). */
+export interface CappedCell {
+  readonly step: Step;
+  readonly strategy: string;
+  readonly fixture: string;
+  /** The nodes of the fixture. */
+  readonly nodes: number;
+  /** The cap of the strategy, in nodes. */
+  readonly cap: number;
 }
 
 /** The spread of each measure of one strategy on one fixture family, over the seeds. */
@@ -159,16 +192,27 @@ export interface SuiteReport {
   readonly summaries: readonly SuiteSummary[];
   readonly fronts: readonly SuiteFront[];
   readonly rules: readonly RuleCount[];
+  /** The cells over the cap of their strategy, one for each strategy and fixture. A report with no cap has no such field. */
+  readonly capped?: readonly CappedCell[];
 }
 
-/** The axes of the Pareto front of each step. The note MEAS0 asks for two to four scores. */
+/** The axes of the Pareto front of a step that gives routes. */
+const ROUTE_OBJECTIVES: readonly Objective[] = [
+  { key: "R1.perEdge", better: "min" },
+  { key: "R5.median", better: "min" },
+  { key: "B1.inkSaved", better: "max" },
+  { key: "R4.turn", better: "min" },
+];
+
+/**
+ * The axes of the Pareto front of each step. The note MEAS0 asks for two to four scores.
+ * The steps `plugs`, `levels` and `whole` run as routers (`stepRouterStrategy`), so they use the axes of the step `router`.
+ */
 export const FRONT_OBJECTIVES: Readonly<Record<Step, readonly Objective[]>> = {
-  router: [
-    { key: "R1.perEdge", better: "min" },
-    { key: "R5.median", better: "min" },
-    { key: "B1.inkSaved", better: "max" },
-    { key: "R4.turn", better: "min" },
-  ],
+  router: ROUTE_OBJECTIVES,
+  plugs: ROUTE_OBJECTIVES,
+  levels: ROUTE_OBJECTIVES,
+  whole: ROUTE_OBJECTIVES,
   curve: [
     { key: "C1.share", better: "min" },
     { key: "C2.median", better: "min" },
@@ -445,6 +489,25 @@ export function runSuite(options: SuiteOptions = {}): { report: SuiteReport; ben
   const smooth = new Set(options.smoothCurves ?? ["rounded", "arc", "spline", "smooth", "clothoid", "highway"]);
   const normals = new Set(options.normalCurves ?? ["spline"]);
   const log = options.log ?? ((): void => {});
+  const shard = options.shard ?? { index: 0, count: 1 };
+  if (!Number.isInteger(shard.count) || shard.count < 1 || !Number.isInteger(shard.index) || shard.index < 0 || shard.index >= shard.count)
+    throw new Error(`The shard ${shard.index} of ${shard.count} is not valid. The index must be from 0 to count - 1.`);
+  if (shard.count > 1 && [...steps].some((s) => s !== "router" && s !== "highway" && s !== "curve"))
+    throw new Error("A shard runs only the steps router, highway and curve.");
+  const mine = (place: number, seed: number): boolean => (place + seed) % shard.count === shard.index;
+  const caps = options.caps ?? {};
+  const pairMax = options.pairMax ?? 1000;
+  const pairStrategy = options.pair === undefined ? undefined : listStrategies(registry, "router").find((s) => s.name === options.pair);
+  if (options.pair !== undefined && pairStrategy === undefined) throw new Error(`There is no baseline router "${options.pair}".`);
+  const pair = pairStrategy ? asRouter(pairStrategy) : undefined;
+  const capped: CappedCell[] = [];
+  // This function tells if the cap of a strategy stops a cell. It records the capped cell one time, on the first seed.
+  const overCap = (step: Step, strategy: string, fixture: string, nodes: number, seed: number): boolean => {
+    const cap = caps[strategy];
+    if (cap === undefined || nodes <= cap) return false;
+    if (seed === 0) capped.push({ step, strategy, fixture, nodes, cap });
+    return true;
+  };
   const fixtures = steps.has("router") || steps.has("group") || steps.has("highway") ? (options.fixtures ?? FIXTURES).filter((f) => f.nodes <= max) : [];
   const routers = steps.has("router") ? listStrategies(registry, "router").filter((s) => options.routers?.includes(s.name) ?? true) : [];
   const curves = steps.has("curve") ? listStrategies(registry, "curve") : [];
@@ -463,11 +526,14 @@ export function runSuite(options: SuiteOptions = {}): { report: SuiteReport; ben
       log(`${spec.name} seed ${k}: ${graph.nodes.length} nodes, ${graph.edges.length} edges`);
       const first = rows.length;
       // The step `router`: the hard rules and the measures of today, then the new measures.
-      for (const strategy of routers) {
+      for (const [place, strategy] of routers.entries()) {
         if (graph.nodes.length > (strategy.maxNodes ?? Infinity)) continue;
+        if (!mine(place, k)) continue;
+        if (overCap("router", strategy.name, spec.name, graph.nodes.length, k)) continue;
         const router = asRouter(strategy);
+        const paired = k === 0 && graph.nodes.length <= pairMax ? pair : undefined;
         const t0 = now();
-        const { row, result } = benchRun(router, spec.name, graph, k === 0 ? repeat : 1, cellLimit);
+        const { row, result } = benchRun(router, spec.name, graph, k === 0 ? repeat : 1, cellLimit, paired);
         const ms = now() - t0;
         if (k === 0) bench.push(row);
         const t1 = now();
@@ -494,16 +560,20 @@ export function runSuite(options: SuiteOptions = {}): { report: SuiteReport; ben
           measureMs,
           extraMs,
           values,
+          ...(row.paired ? { paired: row.paired } : {}),
         });
         if (strategy.name === curveRouter && curves.length > 0 && graph.nodes.length <= curveMax)
           rows.push(...curveRuns(graph, result, curves, { fixture: spec.name, seed: k, smooth, normals }).map((c) => c.row));
       }
       // The step `highway`: the plan of each strategy, routed with `follow`. The measures are the measures of the step `router`.
-      for (const strategy of highways) {
+      for (const [place, strategy] of highways.entries()) {
         if (graph.nodes.length > (strategy.maxNodes ?? Infinity)) continue;
+        if (!mine(place, k)) continue;
+        if (overCap("highway", strategy.name, spec.name, graph.nodes.length, k)) continue;
         const router = asRouter(strategy);
+        const paired = k === 0 && graph.nodes.length <= pairMax ? pair : undefined;
         const t0 = now();
-        const { row, result } = benchRun(router, spec.name, graph, 2, cellLimit);
+        const { row, result } = benchRun(router, spec.name, graph, 2, cellLimit, paired);
         const ms = now() - t0;
         const t1 = now();
         const values: Record<string, number> = routeMeasures(graph, result, row);
@@ -529,6 +599,7 @@ export function runSuite(options: SuiteOptions = {}): { report: SuiteReport; ben
           measureMs,
           extraMs,
           values,
+          ...(row.paired ? { paired: row.paired } : {}),
         });
       }
       // The step `group`: the router `sections` with each grouping rule, and the grouping of the changed graph (G9).
@@ -599,6 +670,7 @@ export function runSuite(options: SuiteOptions = {}): { report: SuiteReport; ben
       summaries,
       fronts: suiteFronts(summaries),
       rules: ruleCounts(rows),
+      ...(capped.length > 0 ? { capped } : {}),
     },
     bench,
   };
@@ -649,6 +721,7 @@ export function joinReports(reports: readonly SuiteReport[], options: { registry
     { ...options, curveRouter: first?.curveRouter ?? "corners" },
   );
   const summaries = summarizeRows(rows);
+  const capped = reports.flatMap((r) => r.capped ?? []);
   return {
     options: {
       max: Math.max(0, ...reports.map((r) => r.options.max)),
@@ -663,6 +736,7 @@ export function joinReports(reports: readonly SuiteReport[], options: { registry
     summaries,
     fronts: suiteFronts(summaries),
     rules: ruleCounts(rows),
+    ...(capped.length > 0 ? { capped } : {}),
   };
 }
 
@@ -762,6 +836,9 @@ export const SUITE_COLUMNS: Readonly<Record<Step, readonly string[]>> = {
   curve: ["C1.share", "C1.max", "C2.median", "C3.median", "C3.q95", "C6.length"],
   room: ["M1.area", "M4.laneThrough", "crossings", "through", "room-order"],
   group: ["Z4.farItems", "G1.modularity", "G2.cut", "G6.balance", "G8.treeCost", "G9.ari", "Z7.position", "Z8.order", "Z3.through", "treeMs"],
+  plugs: ["R1.perEdge", "R2.angle", "R2.min", "B1.inkSaved", "R5.median", "R5.q95", "R4.turn", "R11.q05", "B4.ambiguity", "Z10.moved"],
+  levels: ["R1.perEdge", "R2.angle", "R2.min", "B1.inkSaved", "R5.median", "R5.q95", "R4.turn", "R11.q05", "B4.ambiguity", "Z10.moved"],
+  whole: ["R1.perEdge", "R2.angle", "R2.min", "B1.inkSaved", "R5.median", "R5.q95", "R4.turn", "R11.q05", "B4.ambiguity", "Z10.moved"],
 };
 
 /**
@@ -837,3 +914,24 @@ export function formatMeasureTime(rows: readonly SuiteRow[], step: Step = "route
   });
   return [head, line, ...body].join("\n");
 }
+
+/** This function writes the capped cells as a Markdown table. Each line is a cell that the cap of its strategy stopped, so the row is capped, not missing. */
+export function formatCapped(capped: readonly CappedCell[]): string {
+  const head = "| step | strategy | fixture | nodes | cap | state |";
+  const line = "|---|---|---|---:|---:|---|";
+  const body = capped.map((c) => `| ${c.step} | ${c.strategy} | ${c.fixture} | ${c.nodes} | ${c.cap} | capped |`);
+  return [head, line, ...body].join("\n");
+}
+
+/**
+ * This function writes the paired arm of the rows as a Markdown table. It gives the medians of the strategy and of the baseline, and their ratio.
+ * Only the rows with `paired` count.
+ */
+export function formatPaired(rows: readonly SuiteRow[]): string {
+  const head = "| step | strategy | fixture | nodes | ms | baseline | baseline ms | ratio |";
+  const line = "|---|---|---|---:|---:|---|---:|---:|";
+  const body = rows.flatMap((r) =>
+    r.paired ? [`| ${r.step} | ${r.strategy} | ${r.fixture} | ${r.nodes} | ${r.paired.ms.toFixed(1)} | ${r.paired.base} | ${r.paired.baseMs.toFixed(1)} | ${r.paired.ratio.toFixed(3)} |`] : [],
+  );
+  return [head, line, ...body].join("\n");
+}

package/src/cases.ts

@@ -37,6 +37,12 @@ class Board {
   }
 }
 
+/** The options of a case board with a seed: `hubChainBoard` and `manyGroupsBoard`. */
+export interface CaseSeedOptions {
+  /** The seed of the random links of the board. Each board has its own default. */
+  readonly seed?: number;
+}
+
 /**
  * This function makes a dense board: 150 nodes in tight clusters. At the far view, the boxes of the groups overlap.
  * Then a level link starts or ends in a group that another group covers.
@@ -45,21 +51,38 @@ export function denseGroupsBoard(): Graph {
   return makeFixture({ name: "dense-groups", kind: "clustered", nodes: 150, edgesPerNode: 2, seed: 3 });
 }
 
+/** The options of `hubChainBoard`. Each option at its default keeps the board of today. */
+export interface HubChainOptions extends CaseSeedOptions {
+  /** The number of rows of cards. The default is 3. */
+  readonly rows?: number;
+  /** The number of cards in each row. The default is 32. */
+  readonly cols?: number;
+  /** The number of tries for a long link. The default is 40. */
+  readonly long?: number;
+  /** The free space between two cards, in units. The default is 48. */
+  readonly gap?: number;
+}
+
 /**
  * This function makes a board of three rows of 32 cards. Each card links to the next card of its row.
  * Forty long links join cards far apart. The hub of a section is near the middle of its cards.
  * So a long link climbs to hubs behind its source or past its target, and comes back.
+ *
+ * The seed changes only the long links. The rows of cards, and thus the chain of hubs, do not change.
+ * The default seed is 3. Without options, the board does not change.
+ * The default source of random numbers is `rng(seed)`. A corpus family gives the same stream from its registry.
  */
-export function hubChainBoard(): Graph {
-  const R = rng(3);
+export function hubChainBoard(options: HubChainOptions = {}, random: () => number = rng(options.seed ?? 3)): Graph {
+  const R = random;
   const b = new Board();
-  const rows = 3;
-  const cols = 32;
-  const gap = 48;
+  const rows = options.rows ?? 3;
+  const cols = options.cols ?? 32;
+  const gap = options.gap ?? 48;
+  const long = options.long ?? 40;
   const id = (r: number, c: number): string => `c${r}-${c}`;
   for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) b.node(id(r, c), c * (80 + gap), r * (36 + gap), 80, 36);
   for (let r = 0; r < rows; r++) for (let c = 0; c + 1 < cols; c++) b.link(id(r, c), id(r, c + 1));
-  for (let n = 0; n < 40; n++) {
+  for (let n = 0; n < long; n++) {
     const r = Math.floor(R() * rows);
     const c = Math.floor(R() * cols);
     const span = Math.floor(cols / 8 + (R() * cols) / 2);
@@ -68,21 +91,40 @@ export function hubChainBoard(): Graph {
   return b.graph();
 }
 
+/** The options of `manyGroupsBoard`. Each option at its default keeps the board of today. */
+export interface ManyGroupsOptions extends CaseSeedOptions {
+  /** The number of columns of groups. The default is 8. */
+  readonly groupCols?: number;
+  /** The number of rows of groups. The default is 4. */
+  readonly groupRows?: number;
+  /** The number of cards in each group. The default is 4. */
+  readonly perGroup?: number;
+  /** The number of random links between groups, for each group. The default is 3. */
+  readonly crossLinksPerGroup?: number;
+  /** The free space between two groups, in units. The default is 60. */
+  readonly groupGap?: number;
+}
+
 /**
  * This function makes a board of 32 groups in 8 columns and 4 rows. Each group has 4 cards in a square.
  * The cards of a group link in a chain, and 96 random links join cards of two groups.
  * On a level with many groups, some level links go around the outer edge of the board.
+ *
+ * The seed changes only the 96 links between groups. The 32 groups and their chains do not change.
+ * The default seed is 7. Without options, the board does not change.
+ * The default source of random numbers is `rng(seed)`. A corpus family gives the same stream from its registry.
  */
-export function manyGroupsBoard(): Graph {
-  const R = rng(7);
+export function manyGroupsBoard(options: ManyGroupsOptions = {}, random: () => number = rng(options.seed ?? 7)): Graph {
+  const R = random;
   const b = new Board();
-  const cols = 8;
-  const rows = 4;
-  const per = 4;
+  const cols = options.groupCols ?? 8;
+  const rows = options.groupRows ?? 4;
+  const per = options.perGroup ?? 4;
+  const cross = options.crossLinksPerGroup ?? 3;
   const w = 60;
   const h = 30;
   const cardGap = 12;
-  const groupGap = 60;
+  const groupGap = options.groupGap ?? 60;
   const side = Math.ceil(Math.sqrt(per));
   const gw = side * w + (side - 1) * cardGap;
   const gh = Math.ceil(per / side) * h + (Math.ceil(per / side) - 1) * cardGap;
@@ -99,7 +141,7 @@ export function manyGroupsBoard(): Graph {
     }
   for (const list of groups) for (let i = 1; i < list.length; i++) b.link(list[i - 1]!, list[i]!);
   const pick = (list: readonly string[]): string => list[Math.floor(R() * list.length)]!;
-  for (let n = 0; n < groups.length * 3; n++) b.link(pick(groups[Math.floor(R() * groups.length)]!), pick(groups[Math.floor(R() * groups.length)]!));
+  for (let n = 0; n < groups.length * cross; n++) b.link(pick(groups[Math.floor(R() * groups.length)]!), pick(groups[Math.floor(R() * groups.length)]!));
   return b.graph();
 }
 
@@ -113,6 +155,8 @@ export interface PackedGridOptions {
   readonly rows?: number;
   /** The number of long links between boxes far apart. The default is 48. */
   readonly long?: number;
+  /** The largest step, in rows and in columns, of the link of a box to a box near it. The default is 2. */
+  readonly reach?: number;
 }
 
 /**
@@ -123,18 +167,20 @@ export interface PackedGridOptions {
  *
  * The board is not in `CASES`, because the digests of the router fix the output on each board of `CASES`.
  * The options make a family of such boards for the measure suite. Without options, the board does not change.
+ * The default source of random numbers is `rng(seed)`. A corpus family gives the same stream from its registry.
  */
-export function packedGridBoard(options: PackedGridOptions = {}): Graph {
-  const R = rng(options.seed ?? 11);
+export function packedGridBoard(options: PackedGridOptions = {}, random: () => number = rng(options.seed ?? 11)): Graph {
+  const R = random;
   const b = new Board();
   const cols = options.cols ?? 12;
   const rows = options.rows ?? 8;
   const long = options.long ?? 48;
+  const reach = options.reach ?? 2;
   const w = 140;
   const h = 90;
   const id = (r: number, c: number): string => `p${r}-${c}`;
   for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) b.node(id(r, c), c * w, r * h, w, h);
-  const step = (): number => Math.floor(R() * 5) - 2;
+  const step = (): number => Math.floor(R() * (2 * reach + 1)) - reach;
   for (let r = 0; r < rows; r++)
     for (let c = 0; c < cols; c++) {
       const rr = Math.max(0, Math.min(rows - 1, r + step()));
@@ -170,6 +216,6 @@ export function nestedGridBoard(): Graph {
 /** The case boards of the benchmark. Each board has a few hundred nodes at most, so the benchmark races them on each run. */
 export const CASES: readonly CaseBoard[] = [
   { name: "case-dense-groups", defect: "Groups overlap at the far view, and level links go through other groups.", make: denseGroupsBoard },
-  { name: "case-hub-chain", defect: "A route climbs a chain of hubs away from its target and comes back.", make: hubChainBoard },
-  { name: "case-many-groups", defect: "On a level with many groups, links go around the outer edge of the board.", make: manyGroupsBoard },
+  { name: "case-hub-chain", defect: "A route climbs a chain of hubs away from its target and comes back.", make: () => hubChainBoard() },
+  { name: "case-many-groups", defect: "On a level with many groups, links go around the outer edge of the board.", make: () => manyGroupsBoard() },
 ];