@mark1russell7/highways 0.4.2 → 0.5.1

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;
+}

package/src/bench/screen/hash.ts

@@ -1,14 +1,10 @@
-// The core runs in any host, so this file has its own SHA-256. It needs no API of Node or of the browser.
+// The hash, the canonical JSON and the seeded random numbers of the screen. `sha256Hex`, `canonicalJson` and `RECORD_EPS` come from
+// `@mark1russell7/layout-contract` (PORTFOLIO-FIT). The other functions have no equal in the contract, so they stay here.
+import { canonicalJson, sha256Hex } from "@mark1russell7/layout-contract";
 
-const K: readonly number[] = [
-  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
-  0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
-  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
-  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
-];
+export { canonicalJson, RECORD_EPS, sha256Hex } from "@mark1russell7/layout-contract";
 
-/** This function gives the bytes of a string in UTF-8. */
+/** This function gives the bytes of a string in UTF-8. The contract does not export its own `utf8`, so the core keeps this function. */
 export function utf8(text: string): Uint8Array {
   const out: number[] = [];
   for (const ch of text) {
@@ -21,75 +17,10 @@ export function utf8(text: string): Uint8Array {
   return Uint8Array.from(out);
 }
 
-/** This function gives the SHA-256 digest of a string, as 64 lowercase hex characters. It encodes the string in UTF-8. */
-export function sha256Hex(text: string): string {
-  const bytes = utf8(text);
-  const bits = bytes.length * 8;
-  const total = Math.ceil((bytes.length + 9) / 64) * 64;
-  const data = new Uint8Array(total);
-  data.set(bytes);
-  data[bytes.length] = 0x80;
-  const view = new DataView(data.buffer);
-  view.setUint32(total - 8, Math.floor(bits / 0x100000000));
-  view.setUint32(total - 4, bits >>> 0);
-  const h = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
-  const w = new Uint32Array(64);
-  const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
-  for (let off = 0; off < total; off += 64) {
-    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + 4 * i);
-    for (let i = 16; i < 64; i++) {
-      const a = w[i - 15]!;
-      const b = w[i - 2]!;
-      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
-      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
-      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
-    }
-    let [a, b, c, d, e, f, g, k] = h as [number, number, number, number, number, number, number, number];
-    for (let i = 0; i < 64; i++) {
-      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
-      const ch = (e & f) ^ (~e & g);
-      const t1 = (k + s1 + ch + K[i]! + w[i]!) >>> 0;
-      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
-      const maj = (a & b) ^ (a & c) ^ (b & c);
-      const t2 = (s0 + maj) >>> 0;
-      k = g;
-      g = f;
-      f = e;
-      e = (d + t1) >>> 0;
-      d = c;
-      c = b;
-      b = a;
-      a = (t1 + t2) >>> 0;
-    }
-    h[0] = (h[0]! + a) >>> 0;
-    h[1] = (h[1]! + b) >>> 0;
-    h[2] = (h[2]! + c) >>> 0;
-    h[3] = (h[3]! + d) >>> 0;
-    h[4] = (h[4]! + e) >>> 0;
-    h[5] = (h[5]! + f) >>> 0;
-    h[6] = (h[6]! + g) >>> 0;
-    h[7] = (h[7]! + k) >>> 0;
-  }
-  return h.map((x) => x.toString(16).padStart(8, "0")).join("");
-}
-
-/**
- * This function writes a value as canonical JSON: the keys of each object in sorted order, and no whitespace.
- * It drops a key whose value is `undefined`, as `JSON.stringify` does.
- */
-export function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
-  const o = value as Record<string, unknown>;
-  const keys = Object.keys(o)
-    .filter((k) => o[k] !== undefined)
-    .sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
-}
-
 /**
  * This function gives the hash of a JSON document: the first 16 hex characters of the SHA-256 of its canonical JSON.
  * The document does not include its own field `hash`. The function removes that field before it calculates the hash.
+ * The `documentHash` of the contract puts each number on a grid first, so it is not equal to this function. The hashes of the corpus files use this function.
  */
 export function documentHash(value: object): string {
   const { hash: _hash, ...rest } = value as { hash?: unknown };
@@ -122,7 +53,7 @@ export function mulberry32(seed: number): () => number {
   };
 }
 
-/** This function rounds a number to 3 decimals, as the files of a corpus keep it. The value `-0` becomes `0`. */
+/** This function rounds a number to 3 decimals (a step of `RECORD_EPS`), as the files of a corpus keep it. The value `-0` becomes `0`. */
 export function round3(value: number): number {
   const r = Math.round(value * 1000) / 1000;
   return r === 0 ? 0 : r;

package/src/bench/screen/index.ts

@@ -1,6 +1,12 @@
 export * from "./hash.ts";
 export * from "./forms.ts";
 export * from "./measures.ts";
+export * from "./compare.ts";
 export * from "./set.ts";
 export * from "./screen.ts";
 export * from "./generators.ts";
+export * from "./exact-set.ts";
+export * from "./gap.ts";
+export * from "./activation.ts";
+export * from "./exercise.ts";
+export * from "./portfolio-pick.ts";

package/src/bench/screen/measures.ts

@@ -1,4 +1,5 @@
 import type { Objective } from "../measures/pareto.ts";
+import type { CompareSpec, MinEffect } from "./compare.ts";
 
 /**
  * One measure of a record. `key` is the key of the measure in the values of `runSuite` and `compareStep`.
@@ -18,8 +19,55 @@ export interface MeasureInfo {
    * Then two values compare only on the same input. The value is `false` when the measure scores the routes or the curves for a fixed placement.
    */
   readonly placementDependent: boolean;
+  /**
+   * The smallest change that counts as better or worse in `compareMeasure` (WIN-RES). `MIN_EFFECTS` gives it by the unit, with its reason.
+   * A measure without this field has the threshold `RECORD_EPS`.
+   */
+  readonly minEffect?: MinEffect;
 }
 
+/** One rule of `MIN_EFFECTS`: the units, the minimum effect of a measure with one of these units, and the reason. */
+export interface MinEffectRule {
+  readonly units: readonly string[];
+  /** The minimum effect. The value `undefined` gives the threshold `RECORD_EPS`. */
+  readonly minEffect: MinEffect | undefined;
+  readonly reason: string;
+}
+
+/**
+ * The minimum effect of each measure of `MEASURES`, by the unit of the measure (WIN-RES).
+ * Each unit of `MEASURES` is in one rule. The test of the module checks it.
+ */
+export const MIN_EFFECTS: readonly MinEffectRule[] = Object.freeze([
+  {
+    units: ["0 to 1", "-1 to 1", "-0.5 to 1", "share of the gap", "0 or 1"],
+    minEffect: undefined,
+    reason: "A share or a flag of 0 or 1 has the precision of a written file. Thus the threshold is `RECORD_EPS`.",
+  },
+  {
+    units: ["ratio", "IQR over the median", "no unit", "half turns for each route", "curvature times the unit of the board"],
+    minEffect: undefined,
+    reason: "A stretch or another value without a unit has the precision of a written file. Thus the threshold is `RECORD_EPS`.",
+  },
+  {
+    units: ["count", "count for each edge", "count for each route"],
+    minEffect: 0,
+    reason: "A count or a mean of counts changes in steps. The threshold is `RECORD_EPS`, so a change of 1 counts.",
+  },
+  {
+    units: ["units", "units of the board"],
+    minEffect: { rel: 0.01 },
+    reason: "A length in pixels moves with each small move of a point. A change of 1% or less is not visible.",
+  },
+  {
+    units: ["degrees"],
+    minEffect: { rel: 0.01 },
+    reason: "An angle is a continuous value of the geometry, as a length. A change of 1% or less is not visible.",
+  },
+]);
+
+const MIN_EFFECT_BY_UNIT: ReadonlyMap<string, MinEffectRule> = new Map(MIN_EFFECTS.flatMap((r) => r.units.map((u) => [u, r] as const)));
+
 /** The text of a row of `MEASURES`: the key, the id, the name, the unit, the better side and the placement dependence. */
 type Row = readonly [key: string, id: string, name: string, unit: string, better: "lower" | "higher", placement: boolean];
 
@@ -45,6 +93,9 @@ const ROWS: readonly Row[] = [
   ["R11.q05", "R11", "route.plug-spacing.q05", "0 to 1", "higher", true],
   ["R13.outside", "R13", "route.outside", "count", "lower", false],
   ["R15.inflections", "R15", "route.inflections", "count for each route", "lower", false],
+  // MEAS3A, for the steps `router` and `highway`. R12 is the share of the ink near a parallel leg of other edges. A narrow channel between boxes moves it.
+  ["R12.share", "R12", "route.lane.separation", "0 to 1", "lower", true],
+  ["R14.share", "R14", "route.orthogonality", "0 to 1", "higher", false],
   ["ink", "R1", "route.ink", "units", "lower", true],
   // The bundles.
   ["B1.inkSaved", "B1", "route.bundle.ink-saved", "0 to 1", "higher", false],
@@ -54,6 +105,28 @@ const ROWS: readonly Row[] = [
   ["B3.median", "B3", "route.bundle.stretch.median", "ratio", "lower", false],
   ["B3.q95", "B3", "route.bundle.stretch.q95", "ratio", "lower", false],
   ["B6.max", "B6", "route.bundle.merge-angle.max", "degrees", "lower", false],
+  // MEAS2, on the inputs of `exact-v1`: the largest B3, the largest stretch of the exact model, and the gap closed (B10) to the exact optimum at the smallest cap at or above that stretch.
+  ["B3.max", "B3", "route.bundle.stretch.max", "ratio", "lower", false],
+  ["gap.stretch", "B3", "route.bundle.stretch.model.max", "ratio", "lower", false],
+  ["gap.mixed", "B10", "route.bundle.gap-closed.mixed", "0 or 1", "lower", false],
+  ["gap", "B10", "route.bundle.gap-closed", "share of the gap", "higher", false],
+  ["gap.cap", "B10", "route.bundle.gap-closed.cap", "ratio", "lower", false],
+  ["gap.collection", "B10", "route.bundle.gap-closed.collection", "share of the gap", "higher", false],
+  ["gap.cap.collection", "B10", "route.bundle.gap-closed.cap.collection", "ratio", "lower", false],
+  ["gap.all", "B10", "route.bundle.gap-closed.all", "share of the gap", "higher", false],
+  ["gap.cap.all", "B10", "route.bundle.gap-closed.cap.all", "ratio", "lower", false],
+  // MEAS3A, for the steps `router` and `highway`. B5, B8 and B9 read the runs and the trunks of the result. B8 is good or bad only in context, as B2.
+  ["B5.crossings", "B5", "route.bundle.lane-crossings", "count", "lower", false],
+  ["B7.ratio", "B7", "route.bundle.occupied-area", "ratio", "lower", false],
+  ["B8.runs", "B8", "route.bundle.runs", "count", "lower", false],
+  ["B8.median", "B8", "route.bundle.run-edges.median", "count", "higher", false],
+  ["B8.max", "B8", "route.bundle.run-edges.max", "count", "higher", false],
+  ["B9.median", "B9", "route.bundle.lane-fidelity.median", "ratio", "lower", false],
+  ["B9.max", "B9", "route.bundle.lane-fidelity.max", "ratio", "lower", false],
+  // M1 and M4 of the room, for the steps `router` and `highway`: the lanes of each shared segment open at `MEASURE_LANE_WIDTH`.
+  // The step `room` of `runSuite` gives the same keys for the boards that a room strategy opens.
+  ["M1.area", "M1", "route.lane.area", "ratio", "lower", false],
+  ["M4.laneThrough", "M4", "route.lane.through", "count", "lower", true],
   // The order fragility (W3 of MEAS3, from WILD-056): the spread of a measure over random orders of the edges. The placement can move it.
   ["W3.crossings", "W3", "route.order.crossings", "IQR over the median", "lower", true],
   ["W3.detour", "W3", "route.order.detour", "IQR over the median", "lower", true],
@@ -75,6 +148,9 @@ const ROWS: readonly Row[] = [
   ["Z10.ids", "Z10", "route.stability.highway-ids", "0 to 1", "higher", false],
   // The zoom levels and the groups. The default grouping rule reads the positions, so most of these measures depend on the placement.
   ["level-nesting", "Z6", "route.level.nesting", "count", "lower", false],
+  // MEAS3A, for the steps `router`, `highway` and `group`. Z2 is the count of the hard rule `link-ends`. Z9 needs a result with zoom levels.
+  ["Z2.linkEnds", "Z2", "route.level.link-ends", "count", "lower", false],
+  ["Z9.mean", "Z9", "route.level.link-agreement", "no unit", "lower", true],
   ["Z3.through", "Z3", "route.level.through", "count", "lower", true],
   ["Z3.length", "Z3", "route.level.link-length", "units", "lower", true],
   ["Z4.farItems", "Z4", "route.level.far-items", "count", "lower", true],
@@ -105,7 +181,19 @@ const ROWS: readonly Row[] = [
  * A joint harness that moves the boxes and routes the edges reads `placementDependent`.
  * It compares a measure with the value `true` only between runs on the same input.
  */
-export const MEASURES: readonly MeasureInfo[] = Object.freeze(ROWS.map(([key, id, name, unit, better, placementDependent]) => Object.freeze({ key, id, name, unit, better, placementDependent })));
+export const MEASURES: readonly MeasureInfo[] = Object.freeze(
+  ROWS.map(([key, id, name, unit, better, placementDependent]) => {
+    const rule = MIN_EFFECT_BY_UNIT.get(unit);
+    if (!rule) throw new Error(`MEASURES: the unit "${unit}" of ${key} has no rule in MIN_EFFECTS`);
+    const info: MeasureInfo = { key, id, name, unit, better, placementDependent };
+    return Object.freeze(rule.minEffect === undefined ? info : { ...info, minEffect: rule.minEffect });
+  }),
+);
+
+/** This function gives the spec of a compare of a measure: its better side and its minimum effect. */
+export function compareSpec(info: MeasureInfo): CompareSpec {
+  return info.minEffect === undefined ? { direction: info.better } : { direction: info.better, minEffect: info.minEffect };
+}
 
 const BY_KEY: ReadonlyMap<string, MeasureInfo> = new Map(MEASURES.map((m) => [m.key, m]));
 const BY_NAME: ReadonlyMap<string, MeasureInfo> = new Map(MEASURES.map((m) => [m.name, m]));

package/src/bench/screen/portfolio-pick.ts

@@ -0,0 +1,20 @@
+// The portfolio combinator (PORTFOLIO-API): `portfolio`, `selectBest` and `pickMoves` come from `@mark1russell7/layout-contract` 0.2.6 (PORTFOLIO-FIT).
+// The rules of the pick, the time limit and the trace are in `docs/PORTFOLIO.md` of the contract.
+export {
+  pickMoves,
+  portfolio,
+  selectBest,
+  type Member,
+  type MemberStatus,
+  type MemberTrace,
+  type PickSpec,
+  type Portfolio,
+  type PortfolioKey,
+  type PortfolioLevel,
+  type PortfolioOptions,
+  type PortfolioPick,
+  type PortfolioTrace,
+  type SelectCandidate,
+  type SelectLevel,
+  type Selection,
+} from "@mark1russell7/layout-contract";