@mark1russell7/highways 0.5.0 → 0.5.1

package/src/bench/screen/exercise.ts

@@ -0,0 +1,290 @@
+// The activation test of the screen of `highways` (ACTIVATION): the highways form of an output, the own move of each strategy,
+// the base of each strategy, and the report of the candidates that are not exercised.
+// `activation.ts` holds the functions without the types of `highways`. This file holds the parts of `highways`.
+import type { CurveSegment } from "../../curves/model.ts";
+import type { HighwayPlan } from "../../highways/model.ts";
+import type { Graph, Result } from "../../model.ts";
+import { highwayStrategies } from "../../strategies/builtins.ts";
+import type { Strategy } from "../../strategies/model.ts";
+import { exercised, outputGroups, outputHash, type OutputGroup } from "./activation.ts";
+import type { LayoutRecord } from "./forms.ts";
+import { RECORD_EPS } from "./hash.ts";
+
+const byEdge = <T extends { readonly edge: string }>(list: readonly T[]): T[] => [...list].sort((a, b) => (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : 0));
+
+/**
+ * This function gives the output hash of a result of a router, in the highways form.
+ * The form holds the routes in the order of the edge ids, and the levels, the bundles and the runs as the router gives them.
+ * Each number goes to the grid `RECORD_EPS`, as `round3` does.
+ */
+export function resultHash(result: Result): string {
+  return outputHash(resultForm(result), { grid: RECORD_EPS });
+}
+
+/** This function gives the highways form of a result of a router: the value that `resultHash` hashes. */
+export function resultForm(result: Result): object {
+  return { routes: byEdge(result.routes), levels: result.levels, bundles: result.bundles, runs: result.runs };
+}
+
+/** This function gives the output hash of the curves of the step `curve`, in the order of the edge ids. */
+export function curvesHash(edges: readonly string[], curves: readonly (readonly CurveSegment[])[]): string {
+  return outputHash(byEdge(edges.map((edge, i) => ({ edge, segments: curves[i] ?? [] }))), { grid: RECORD_EPS });
+}
+
+/**
+ * The name of the own move of each built-in highway finder. The trace of a record names the count `move.<name>`.
+ * The count is the number of highways of the plan with 2 edges or more. A finder without an entry counts `move.highway`.
+ */
+export const MOVE_NAMES: Readonly<Record<string, string>> = Object.freeze({
+  keys: "trunk",
+  "shared-ways": "sharedWay",
+  "shared-ways-all": "sharedWay",
+  corridors: "corridor",
+  quickbundles: "bundle",
+  "road-classes": "mainRoad",
+  "flow-field": "fieldLine",
+  wspd: "pair",
+  "od-cells": "cellPair",
+  select: "pick",
+  mingle: "merge",
+  spiral: "spiralTree",
+  "flow-clusters": "cluster",
+  traclus: "cluster",
+  diffusion: "channel",
+  nested: "cluster",
+  growth: "road",
+  "edge-paths": "path",
+  "soft-keys": "softKey",
+  hough: "line",
+  ridges: "ridge",
+  hdbscan: "cluster",
+  "hub-arcs": "hubArc",
+  hierarchy: "bundle",
+  fdeb: "bundle",
+  mesh: "meshRoad",
+  kdeeb: "bundle",
+  cubu: "bundle",
+  mlseb: "bundle",
+  sbeb: "bundle",
+  areas: "area",
+  confluent: "track",
+  power: "powerEdge",
+  frechet: "cluster",
+  spectral: "cluster",
+  resistance: "cluster",
+  "link-communities": "community",
+  territories: "territory",
+  consensus: "cluster",
+  "p-hub": "hubLink",
+  "scale-space": "cluster",
+});
+
+/**
+ * The highway strategies that change the plan of another strategy (`from`). Their own move is a change of that plan, so they count no move.
+ * The output against the plan `from` tells if they ran.
+ */
+export const PLAN_CHANGERS: readonly string[] = Object.freeze(["crossbars", "divided", "lanes", "level-links", "meet", "stubs", "weiszfeld", "zipper"]);
+
+const FINDERS: readonly string[] = [...new Set([...Object.keys(highwayStrategies).filter((n) => !n.includes("+")), "shared-ways-all"])].sort((a, b) => b.length - a.length);
+
+/** This function gives the name of a strategy without the prefix of a module, for example `spectral-c0.3` for `w3f:spectral-c0.3`. */
+function localName(name: string): string {
+  const colon = name.indexOf(":");
+  const local = colon >= 0 ? name.slice(colon + 1) : name;
+  // A wave can give its own variant a name with the wave, for example `w3f-nested-l1`.
+  return local.replace(/^w\d[a-z]+-/, "");
+}
+
+/**
+ * This function gives the built-in highway strategy of a name: the strategy itself, or the strategy of a variant, for example `power` for `power-near`.
+ * It gives `undefined` for a gate (a name with `+`) and for a name of another step.
+ */
+export function finderOf(name: string): string | undefined {
+  const local = localName(name);
+  if (local.includes("+")) return undefined;
+  return FINDERS.find((f) => local === f || local.startsWith(`${f}-`));
+}
+
+/**
+ * This function gives the count of the own move of a highway strategy on its plan, for example `{ "move.powerEdge": 3 }`.
+ * It gives `undefined` for a gate and for a strategy of `PLAN_CHANGERS`.
+ */
+export function planMoves(name: string, plan: HighwayPlan): Record<string, number> | undefined {
+  const finder = finderOf(name);
+  if (finder === undefined || PLAN_CHANGERS.includes(finder)) return undefined;
+  return { [`move.${MOVE_NAMES[finder] ?? "highway"}`]: plan.highways.filter((h) => h.members.length >= 2).length };
+}
+
+/** A function that gives the own move counts of a strategy on a graph, or `undefined` for a strategy without a count. */
+export type MoveCounter = (strategy: string, graph: Graph) => Readonly<Record<string, number>> | undefined;
+
+/** This function gives a `MoveCounter` for highway strategies, by the names of the records. It makes the plan of the strategy again. */
+export function highwayMoves(strategies: Readonly<Record<string, Strategy<"highway", object>>>): MoveCounter {
+  return (name, graph) => {
+    const s = strategies[name];
+    return s === undefined ? undefined : planMoves(name, s.run({ graph }, s.defaults));
+  };
+}
+
+/**
+ * This function gives the base of a strategy for the fallback test: the strategy that it falls back to or extends.
+ * - A gate `X+G` and a wrapped router `X+W` have the base `X`.
+ * - A highway finder of a module (`hw:power`, `w3e:power-near`) has the base `hw:none`, the empty plan.
+ * - A plan changer has the base of its plan `from`: `hw:shared-ways`, or `hw:corridors` and `hw:none` for a name that ends with `-corridors` and `-none`.
+ * - An option of a router (`shared-cap-3`, `shared-all-p3`, `trunks-tree-bf02`, `corners-side`) has the base `shared`, `shared-all`, `trunks` or `corners`.
+ * The function gives `undefined` when the base is not in `known`.
+ */
+export function activationBase(name: string, known: ReadonlySet<string>): string | undefined {
+  const pick = (...names: string[]): string | undefined => names.find((n) => n !== name && known.has(n));
+  const colon = name.indexOf(":");
+  if (colon >= 0) {
+    const prefix = name.slice(0, colon);
+    const local = name.slice(colon + 1);
+    if (local.includes("+")) {
+      const inner = local.slice(0, local.lastIndexOf("+"));
+      return pick(`${prefix}:${inner}`, `hw:${inner}`);
+    }
+    if (local === "none") return undefined;
+    const finder = finderOf(name);
+    if (finder !== undefined && PLAN_CHANGERS.includes(finder)) {
+      const from = local.endsWith("-corridors") ? "corridors" : local.endsWith("-none") ? "none" : "shared-ways";
+      return pick(`hw:${from}`);
+    }
+    return pick("hw:none");
+  }
+  if (name.includes("+")) return pick(name.slice(0, name.lastIndexOf("+")));
+  for (const router of ["shared-all", "shared", "trunks", "corners"]) if (name.startsWith(`${router}-`)) return pick(router);
+  return undefined;
+}
+
+/** The activation of one strategy over the decision inputs of a screen. */
+export interface ActivationRow {
+  readonly strategy: string;
+  /** The base of the fallback test, or `undefined` when the strategy has none. */
+  readonly base?: string;
+  /** The decision inputs where the strategy ran. */
+  readonly inputs: number;
+  /** The decision inputs where a move count is above 0. */
+  readonly moved: readonly string[];
+  /** The decision inputs where the output differs from the output of the base. */
+  readonly differs: readonly string[];
+  /** The sum of each move count over the decision inputs. */
+  readonly moves: Readonly<Record<string, number>>;
+  readonly verdict: "exercised" | "not-exercised";
+  /** The id of the output group of the strategy on the decision inputs. */
+  readonly group: string;
+}
+
+/** The groups of the strategies with equal output on each input of one cell (a family of boards). They are diagnostics only. */
+export interface CellGroups {
+  readonly cell: string;
+  readonly groups: readonly OutputGroup[];
+}
+
+/** The activation report of a screen. */
+export interface ActivationReport {
+  /** The decision inputs, in sorted order. */
+  readonly inputs: readonly string[];
+  readonly rows: readonly ActivationRow[];
+  /** The output groups with more than one strategy: equal output hashes on each decision input. */
+  readonly groups: readonly OutputGroup[];
+  /** The cell groups with more than one strategy, for each family of the decision inputs. */
+  readonly cells: readonly CellGroups[];
+}
+
+/** This function gives the family of an input id, for example `small-clustered` for `screen-v1/small-clustered/s0`. */
+export function familyOf(input: string): string {
+  const parts = input.split("/");
+  return parts.length >= 3 ? parts[parts.length - 2]! : input;
+}
+
+/** This function gives the move counts of a record, from its trace. */
+export function recordMoves(record: LayoutRecord): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const t of record.trace ?? []) for (const [k, v] of Object.entries(t.measures ?? {})) if (k.startsWith("move.")) out[k] = (out[k] ?? 0) + v;
+  return out;
+}
+
+/**
+ * This function gives the activation report of the records of a screen.
+ * A strategy is exercised when a move count is above 0 on a decision input.
+ * It is also exercised when its output differs from the output of its base on a decision input.
+ * The decision inputs are the inputs of the families `families`, or each input. `bases` gives the base of each strategy, or `activationBase` gives it.
+ */
+export function activationReport(
+  records: readonly LayoutRecord[],
+  options: { readonly families?: readonly string[]; readonly bases?: Readonly<Record<string, string>> } = {},
+): ActivationReport {
+  const decision = records.filter((r) => options.families?.includes(familyOf(r.input)) ?? true);
+  const inputs = [...new Set(decision.map((r) => r.input))].sort();
+  const names = [...new Set(decision.map((r) => r.strategy))];
+  const known = new Set(names);
+  const at = new Map(decision.map((r) => [`${r.strategy}\u0000${r.input}`, r]));
+  const hashOf = (strategy: string, input: string): string | undefined => {
+    const r = at.get(`${strategy}\u0000${input}`);
+    return r === undefined || r.skipped !== undefined ? undefined : r.outputHash;
+  };
+  const list = (strategy: string, of: readonly string[]): string[] => of.map((i) => hashOf(strategy, i) ?? "-");
+  const all = outputGroups(Object.fromEntries(names.map((n) => [n, list(n, inputs)])));
+  const groupOf = new Map(all.flatMap((g) => g.members.map((m) => [m, g.id] as const)));
+  const rows = names.map((strategy): ActivationRow => {
+    const base = options.bases?.[strategy] ?? activationBase(strategy, known);
+    const moved: string[] = [];
+    const differs: string[] = [];
+    const moves: Record<string, number> = {};
+    let ran = 0;
+    for (const input of inputs) {
+      const r = at.get(`${strategy}\u0000${input}`);
+      if (r === undefined || r.skipped !== undefined) continue;
+      ran++;
+      const m = recordMoves(r);
+      for (const [k, v] of Object.entries(m)) moves[k] = (moves[k] ?? 0) + v;
+      if (exercised({ moves: m })) moved.push(input);
+      const own = hashOf(strategy, input);
+      const theirs = base === undefined ? undefined : hashOf(base, input);
+      // A skipped run of the base has no hash. Then the input gives no evidence of a difference.
+      if (own !== undefined && theirs !== undefined && exercised({ hashes: [own], baseHashes: [theirs] })) differs.push(input);
+    }
+    const verdict = moved.length > 0 || differs.length > 0 ? "exercised" : "not-exercised";
+    return { strategy, ...(base === undefined ? {} : { base }), inputs: ran, moved, differs, moves, verdict, group: groupOf.get(strategy) ?? strategy };
+  });
+  const families = [...new Set(inputs.map(familyOf))].sort();
+  const cells = families.map((cell) => {
+    const of = inputs.filter((i) => familyOf(i) === cell);
+    return { cell, groups: outputGroups(Object.fromEntries(names.map((n) => [n, list(n, of)]))).filter((g) => g.members.length > 1) };
+  });
+  return { inputs, rows, groups: all.filter((g) => g.members.length > 1), cells };
+}
+
+/** This function writes the activation report as Markdown: the strategies that are not exercised, and the output groups. */
+export function formatActivation(report: ActivationReport, candidates?: ReadonlySet<string>): string {
+  const rows = report.rows.filter((r) => candidates?.has(r.strategy) ?? true);
+  const silent = rows.filter((r) => r.verdict === "not-exercised");
+  const lines = [
+    "## Activation",
+    "",
+    `${report.inputs.length} decision inputs, ${rows.length} strategies. A strategy is exercised when its own move count is above 0, or its output differs from the output of its base, on one decision input or more.`,
+    "",
+    `### Not exercised (${silent.length})`,
+    "",
+    "| strategy | base | runs | moves |",
+    "|---|---|---:|---|",
+    ...silent.map((r) => `| ${r.strategy} | ${r.base ?? "-"} | ${r.inputs} | ${Object.entries(r.moves).map(([k, v]) => `${k} ${v}`).join(", ") || "-"} |`),
+    "",
+    `### Output groups (${report.groups.length})`,
+    "",
+    "The strategies of a group have equal output on each decision input. A group counts as one candidate.",
+    "",
+    ...report.groups.map((g) => `- ${g.members.join(", ")}`),
+    "",
+    "### All strategies",
+    "",
+    "| strategy | base | runs | moved | differs | moves | verdict | group |",
+    "|---|---|---:|---:|---:|---|---|---|",
+    ...rows.map(
+      (r) =>
+        `| ${r.strategy} | ${r.base ?? "-"} | ${r.inputs} | ${r.moved.length} | ${r.differs.length} | ${Object.entries(r.moves).map(([k, v]) => `${k} ${v}`).join(", ") || "-"} | ${r.verdict} | ${r.group} |`,
+    ),
+  ];
+  return lines.join("\n") + "\n";
+}

package/src/bench/screen/forms.ts

@@ -186,6 +186,20 @@ export interface LayoutRecord {
   readonly commit?: string;
   /** The reason when the strategy did not run, for example an input over its `maxNodes`. Then the record has no measures. */
   readonly skipped?: string;
+  /**
+   * The first 16 hex characters of the SHA-256 of the output in the highways form (ACTIVATION). `resultHash` gives it for a router.
+   * Two records with the same hash have the same output, at the precision `RECORD_EPS`.
+   */
+  readonly outputHash?: string;
+  /** The facts of the stages of the run. The trace measures `move.<name>` count the own move of the strategy (ACTIVATION). */
+  readonly trace?: readonly RecordTrace[];
+}
+
+/** The facts of one stage of a run, as the `StageTrace` of the contract: its id, its time and its trace measures. */
+export interface RecordTrace {
+  readonly id: string;
+  readonly ms?: number;
+  readonly measures?: Readonly<Record<string, number>>;
 }
 
 /** The comparison of a prediction. Without it, `<=` applies to a measure where lower is better, and `>=` to the other measures. */

package/src/bench/screen/gap.ts

@@ -0,0 +1,316 @@
+import { polylineLength } from "../../geom.ts";
+import { follow } from "../../highways/follow.ts";
+import type { HighwayInput, HighwayPlan } from "../../highways/model.ts";
+import { sharedWaysPlan } from "../../highways/shared-ways/index.ts";
+import type { Graph, Result, Route } from "../../model.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { STRATEGIES } from "../../strategies/builtins.ts";
+import { asRouter, defineStrategy, getStrategy, type Strategy } from "../../strategies/model.ts";
+import { inkSaved } from "../measures/bundles.ts";
+import { quantile } from "../measures/stats.ts";
+import { exactStretch } from "../exact/index.ts";
+import { mulberry32 } from "./hash.ts";
+
+/** The rule of the exact model: `collection` lets only the edges of one collection share a link, and `all` lets each edge share a link. */
+export type GapRule = "collection" | "all";
+
+/** The rules of the gap closed, in the order of the records. */
+export const GAP_RULES: readonly GapRule[] = ["collection", "all"];
+
+/**
+ * A view of the gap closed: one rule, or `chosen`. The view `chosen` takes a rule for each run.
+ * It takes `all` when a shared segment of the run holds edges of two collections. Else it takes `collection`.
+ */
+export type GapView = GapRule | "chosen";
+
+/** The views of the gap closed, in the order of the tables. */
+export const GAP_VIEWS: readonly GapView[] = ["chosen", "collection", "all"];
+
+/** The stretch caps of the exact optima, from small to large. */
+export const GAP_CAPS: readonly number[] = [1.1, 1.25, 1.5];
+
+/** The baseline of each rule: the router `shared` for `collection`, and the plan `shared-ways-all` after `follow` for `all`. */
+export const GAP_BASELINES: Readonly<Record<GapRule, string>> = { collection: "shared", all: "shared-ways-all" };
+
+/** The parameters of the paired bootstrap of the gap closed, from `docs/PROMOTION.md`. */
+export const GAP_BOOTSTRAP: { readonly runs: number; readonly level: number; readonly seed: number } = { runs: 10_000, level: 0.95, seed: 1 };
+
+/** The optimum of the exact model on one input, for one rule and one stretch cap. The file of the optima of a set holds one for each. */
+export interface ExactOptimum {
+  /** The id of the input. */
+  readonly input: string;
+  /** The hash of the input file. The screen uses the optimum only when the hash matches. */
+  readonly hash: string;
+  /** The class of the input: its family in the set. */
+  readonly class: string;
+  readonly nodes: number;
+  readonly edges: number;
+  readonly rule: GapRule;
+  readonly cap: number;
+  /** The status of HiGHS: `optimal`, `time-limit` or another status. */
+  readonly status: string;
+  /** This value is `true` when HiGHS proved the optimum within the time limit. */
+  readonly proven: boolean;
+  /** The objective of the best solution, the dual bound and the relative MIP gap. Each one is `null` when HiGHS gives none. */
+  readonly objective: number | null;
+  readonly bound: number | null;
+  readonly mipGap: number | null;
+  /** The time of the solve, in seconds. */
+  readonly seconds: number;
+  /** The number of binary variables of the model. */
+  readonly binaries: number;
+  /** The ink saved (B1) of the routes of the best plan after `follow`. The gap closed uses this value. */
+  readonly b1: number | null;
+  /** The ink saved of the model itself, without `follow`. */
+  readonly modelB1: number | null;
+  /** The largest bundle stretch (B3) of the routes of the best plan, against the routes of `corners`. */
+  readonly b3max: number | null;
+  /** The number of highways of the best plan. */
+  readonly highways: number;
+}
+
+/** The file of the optima of a set (`exact-optima/1`). Later screens read it and do not solve again. */
+export interface ExactOptimaFile {
+  readonly schema: "exact-optima/1";
+  readonly set: string;
+  /** The time limit of each solve, in seconds. */
+  readonly seconds: number;
+  /** The commit of the code and the CI run of the solves. */
+  readonly commit?: string;
+  readonly run?: string;
+  readonly optima: readonly ExactOptimum[];
+}
+
+/** This function gives the file of the optima of a set, with the rows in the order of the input, the rule and the cap. */
+export function optimaFile(set: string, rows: readonly ExactOptimum[], at: { readonly seconds: number; readonly commit?: string; readonly run?: string }): ExactOptimaFile {
+  const order = (r: ExactOptimum): string => `${r.input}\u0000${GAP_RULES.indexOf(r.rule)}\u0000${r.cap.toFixed(3)}`;
+  const optima = [...rows].sort((a, b) => (order(a) < order(b) ? -1 : order(a) > order(b) ? 1 : 0));
+  return { schema: "exact-optima/1", set, seconds: at.seconds, ...(at.commit ? { commit: at.commit } : {}), ...(at.run ? { run: at.run } : {}), optima };
+}
+
+/** This function gives the key of an optimum in a map: the input, the rule and the cap. */
+export function optimumKey(input: string, rule: GapRule, cap: number): string {
+  return `${input}|${rule}|${cap.toFixed(3)}`;
+}
+
+/** This function gives the smallest cap that is at least the stretch, or `undefined` when the stretch is above the largest cap. */
+export function gapCap(stretch: number, caps: readonly number[] = GAP_CAPS): number | undefined {
+  return caps.find((c) => stretch <= c + 1e-9);
+}
+
+/**
+ * This function gives the gap closed: `(b1 - base) / (optimum - base)`.
+ * It gives `undefined` when the denominator is 0 or less, because then the baseline is at the optimum or above it.
+ */
+export function gapClosed(b1: number, base: number, optimum: number): number | undefined {
+  const d = optimum - base;
+  return d > 1e-9 ? (b1 - base) / d : undefined;
+}
+
+/**
+ * This function gives the largest bundle stretch of routes against base routes: the max of `L(r_e) / L(r*_e)` over the edges, as B3 counts them.
+ * An edge without a base route, or with a base route of 1 unit or less, does not count. Without such an edge, the value is 1.
+ */
+export function maxStretch(routes: readonly Route[], base: readonly Route[]): number {
+  const baseLength = new Map<string, number>();
+  for (const r of base) baseLength.set(r.edge, polylineLength(r.points));
+  let max = 1;
+  for (const r of routes) {
+    const b = baseLength.get(r.edge);
+    if (b === undefined || b <= 1 || r.points.length < 2) continue;
+    max = Math.max(max, polylineLength(r.points) / b);
+  }
+  return max;
+}
+
+/** The highway strategy `shared-ways-all`: the plan of the router `shared` without a rule. It is the baseline of the rule `all`. */
+export const sharedWaysAll: Strategy<"highway", object> = defineStrategy({
+  step: "highway",
+  name: "shared-ways-all",
+  describe: "The plan of the router `shared` without a rule.",
+  defaults: {},
+  schema: {},
+  maxNodes: 10_000,
+  run: (input: HighwayInput): HighwayPlan => sharedWaysPlan(input, {}),
+});
+
+/** This function gives the B1 of the baseline of each rule on a graph. */
+export function gapBaselines(graph: Graph): Record<GapRule, number> {
+  const shared = asRouter(getStrategy(STRATEGIES, "router", "shared")).route(graph).routes;
+  const all = follow(graph, sharedWaysAll.run({ graph }, {})).routes;
+  return { collection: inkSaved(shared), all: inkSaved(all) };
+}
+
+/** A median with its paired bootstrap interval. */
+export interface BootstrapMedian {
+  readonly median: number;
+  readonly lo: number;
+  readonly hi: number;
+}
+
+/**
+ * This function gives the median of the values and its bootstrap interval: `runs` samples of the values with replacement, from the seed `seed`.
+ * The interval is the central `level` share of the medians of the samples. Each value is the paired value of one input, so the bootstrap is paired.
+ */
+export function bootstrapMedian(values: readonly number[], o: { readonly runs?: number; readonly level?: number; readonly seed?: number } = {}): BootstrapMedian {
+  if (values.length === 0) return { median: Number.NaN, lo: Number.NaN, hi: Number.NaN };
+  const runs = o.runs ?? GAP_BOOTSTRAP.runs;
+  const level = o.level ?? GAP_BOOTSTRAP.level;
+  const r = mulberry32(o.seed ?? GAP_BOOTSTRAP.seed);
+  const medians: number[] = [];
+  const sample = new Array<number>(values.length);
+  for (let i = 0; i < runs; i++) {
+    for (let j = 0; j < values.length; j++) sample[j] = values[Math.floor(r() * values.length)]!;
+    medians.push(quantile(sample, 0.5));
+  }
+  const tail = (1 - level) / 2;
+  return { median: quantile(values, 0.5), lo: quantile(medians, tail), hi: quantile(medians, 1 - tail) };
+}
+
+/** The gap closed of one strategy and one view over the inputs of a screen. */
+export interface GapSummary {
+  readonly strategy: string;
+  readonly rule: GapView;
+  /** The number of runs, and the number of runs with a value. A run has no value above the largest cap, or without a proven optimum. */
+  readonly runs: number;
+  readonly values: number;
+  /** The median over the inputs with a value, and its paired bootstrap interval. */
+  readonly median: number;
+  readonly lo: number;
+  readonly hi: number;
+  /** The median of each class, by the family of the input. */
+  readonly byClass: Readonly<Record<string, number>>;
+  /** The number of values at each cap, by the cap. */
+  readonly caps: Readonly<Record<string, number>>;
+  /** The number of runs with some ink saved (B1 above 0): the runs where the strategy builds a shared segment. */
+  readonly builds: number;
+  /** The number of runs where a shared segment holds edges of two collections. */
+  readonly mixed: number;
+}
+
+/** The names of the measures of the gap closed in a record, for a view. */
+export function gapNames(view: GapView): { readonly gap: string; readonly cap: string } {
+  return view === "chosen" ? { gap: "route.bundle.gap-closed", cap: "route.bundle.gap-closed.cap" } : { gap: `route.bundle.gap-closed.${view}`, cap: `route.bundle.gap-closed.cap.${view}` };
+}
+
+/** This function gives the family of an input id `<set>/<family>/s<seed>`. */
+const familyOf = (input: string): string => input.split("/")[1] ?? input;
+
+/**
+ * This function gives the gap closed of each strategy and view over records.
+ * It sorts them by the view and then by the median, from high to low.
+ * A strategy with a value on fewer than half of its runs comes after the others, because its median shows only a few inputs.
+ */
+export function summarizeGap(
+  records: readonly { readonly strategy: string; readonly input: string; readonly skipped?: string; readonly measures: Readonly<Record<string, number>> }[],
+): GapSummary[] {
+  const out: GapSummary[] = [];
+  const names = [...new Set(records.map((r) => r.strategy))];
+  for (const rule of GAP_VIEWS) {
+    const key = gapNames(rule);
+    const rows: GapSummary[] = [];
+    for (const strategy of names) {
+      const ran = records.filter((r) => r.strategy === strategy && r.skipped === undefined);
+      const withValue = ran.filter((r) => r.measures[key.gap] !== undefined);
+      const values = withValue.map((r) => r.measures[key.gap]!);
+      const boot = bootstrapMedian(values);
+      const classes = [...new Set(withValue.map((r) => familyOf(r.input)))].sort();
+      const byClass = Object.fromEntries(classes.map((c) => [c, quantile(withValue.filter((r) => familyOf(r.input) === c).map((r) => r.measures[key.gap]!), 0.5)]));
+      const caps: Record<string, number> = {};
+      for (const r of withValue) {
+        const c = String(r.measures[key.cap]);
+        caps[c] = (caps[c] ?? 0) + 1;
+      }
+      const builds = ran.filter((r) => (r.measures["route.bundle.ink-saved"] ?? 0) > 1e-9).length;
+      const mixed = ran.filter((r) => r.measures["route.bundle.gap-closed.mixed"] === 1).length;
+      rows.push({ strategy, rule, runs: ran.length, values: values.length, median: boot.median, lo: boot.lo, hi: boot.hi, byClass, caps, builds, mixed });
+    }
+    const few = (r: GapSummary): number => (2 * r.values < r.runs ? 1 : 0);
+    rows.sort((a, b) => few(a) - few(b) || (Number.isNaN(b.median) ? -Infinity : b.median) - (Number.isNaN(a.median) ? -Infinity : a.median) || (a.strategy < b.strategy ? -1 : 1));
+    out.push(...rows);
+  }
+  return out;
+}
+
+/** This function writes the gap closed as Markdown: one table for each view, sorted by the median. */
+export function formatGap(rows: readonly GapSummary[]): string {
+  const f = (v: number): string => (Number.isNaN(v) ? "-" : v.toFixed(3));
+  const lines: string[] = [];
+  for (const rule of GAP_VIEWS) {
+    const mine = rows.filter((r) => r.rule === rule);
+    if (mine.length === 0) continue;
+    const classes = [...new Set(mine.flatMap((r) => Object.keys(r.byClass)))].sort();
+    lines.push(
+      "",
+      rule === "chosen"
+        ? "### The gap closed with the rule of each run (`all` when a shared segment mixes collections, else `collection`)"
+        : `### The gap closed with the rule \`${rule}\` (baseline \`${GAP_BASELINES[rule]}\`)`,
+      "",
+      "The value of an input is `(B1 - B1 of the baseline) / (the optimum B1 - B1 of the baseline)`, at the smallest cap at or above the largest stretch of the routes.",
+      "The stretch is the stretch of the exact model: the length of a route without its plug ends, divided by the shortest way in the network of the model.",
+      "The interval is the 95% paired bootstrap interval of the median, with 10000 samples.",
+      "A strategy with a value on fewer than half of its runs comes after the others. Above the largest cap, a run has no value.",
+      "",
+      `| strategy | runs | builds | mixed | values | median | interval | ${classes.join(" | ")} | caps 1.1 / 1.25 / 1.5 |`,
+      `|---|---:|---:|---:|---:|---:|---|${classes.map(() => "---:").join("|")}|---|`,
+      ...mine.map(
+        (r) =>
+          `| ${r.strategy} | ${r.runs} | ${r.builds} | ${r.mixed} | ${r.values} | ${f(r.median)} | ${f(r.lo)} to ${f(r.hi)} | ${classes.map((c) => f(r.byClass[c] ?? Number.NaN)).join(" | ")} | ${GAP_CAPS.map((c) => r.caps[String(c)] ?? 0).join(" / ")} |`,
+      ),
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+
+/** This function gives the count of the shared segments of a result (the runs and the bundles) that hold edges of two collections or more. */
+export function mixedSegments(graph: Graph, result: Result): number {
+  const key = new Map(graph.edges.map((e) => [e.id, byCollection(e) ?? `\u0000${e.id}`]));
+  const shared = [...(result.runs ?? []).map((r) => r.edges), ...(result.bundles ?? []).map((b) => b.edges)];
+  return shared.filter((edges) => new Set(edges.map((e) => key.get(e))).size > 1).length;
+}
+
+/** This function tells if a shared segment of a result (a run or a bundle) holds edges of two collections. */
+export function mixesCollections(graph: Graph, result: Result): boolean {
+  return mixedSegments(graph, result) > 0;
+}
+
+/**
+ * This function gives the gap measures of the result of one run on an input with optima, by the keys of `MEASURES`.
+ * `B3.max` is the largest stretch against the routes of `corners`. `gap.stretch` is the largest stretch as the exact model counts it (`exactStretch`).
+ * The cap is the smallest cap at or above `gap.stretch`, so both sides of the gap have the same stretch limit.
+ *
+ * `gap.<rule>` is the gap closed at the cap `gap.cap.<rule>`. `gap` is the gap closed of the rule of the run.
+ * That rule is `all` when `gap.mixed` is 1, else `collection`.
+ * A rule has no value above the largest cap or without a proven optimum at the cap.
+ * It also has no value when the hash of the optimum is not the hash of the input.
+ */
+export function gapValues(
+  input: { readonly id: string; readonly hash: string },
+  graph: Graph,
+  result: Result,
+  corners: readonly Route[],
+  baselines: Readonly<Record<GapRule, number>>,
+  optima: ReadonlyMap<string, ExactOptimum>,
+): Record<string, number> {
+  const routes = result.routes;
+  const stretch = exactStretch(graph, routes);
+  const mixed = mixesCollections(graph, result);
+  const out: Record<string, number> = { "B3.max": maxStretch(routes, corners), "gap.stretch": stretch, "gap.mixed": mixed ? 1 : 0 };
+  const cap = gapCap(stretch);
+  if (cap === undefined) return out;
+  const b1 = inkSaved(routes);
+  for (const rule of GAP_RULES) {
+    const o = optima.get(optimumKey(input.id, rule, cap));
+    if (!o || !o.proven || o.b1 === null || o.hash !== input.hash) continue;
+    const g = gapClosed(b1, baselines[rule], o.b1);
+    if (g === undefined) continue;
+    out[`gap.${rule}`] = g;
+    out[`gap.cap.${rule}`] = cap;
+  }
+  const chosen: GapRule = mixed ? "all" : "collection";
+  if (out[`gap.${chosen}`] !== undefined) {
+    out["gap"] = out[`gap.${chosen}`]!;
+    out["gap.cap"] = cap;
+  }
+  return out;
+}