@mark1russell7/highways 0.5.0 → 0.5.1

package/src/bench/exact/solve.ts

@@ -0,0 +1,129 @@
+import { follow } from "../../highways/follow.ts";
+import type { HighwayPlan } from "../../highways/model.ts";
+import type { Graph, Route } from "../../model.ts";
+import { STRATEGIES } from "../../strategies/builtins.ts";
+import { asRouter, getStrategy } from "../../strategies/model.ts";
+import { inkSaved } from "../measures/bundles.ts";
+import { maxStretch } from "../screen/gap.ts";
+import { exactModel, type ExactRule } from "./index.ts";
+
+/**
+ * The part of a persistent model of the package `highs` that `solveExact` uses.
+ * The library does not import `highs`. The caller gives the loaded runtime, so `highs` stays a devDependency.
+ */
+export interface HighsModelLike {
+  readonly options: { set(values: Readonly<Record<string, string | number | boolean>>): unknown };
+  readonly info: { get(name: string): number | bigint };
+  run(): unknown;
+  getModelStatus(): number;
+  getObjectiveValue(): number;
+  getSolution(): { readonly colValue: ArrayLike<number> };
+  getDimensions(): { readonly numCols: number };
+  getColName(index: number): string;
+  dispose(): void;
+}
+
+/** The part of the loaded runtime of the package `highs` that `solveExact` uses. */
+export interface HighsLike {
+  createModel(source: { readonly format: "lp"; readonly data: string }): HighsModelLike;
+  readonly constants: { readonly modelStatus: { readonly optimal: number; readonly timeLimit: number } };
+}
+
+/** The result of one solve of the exact model. */
+export interface ExactSolve {
+  /** The model status of HiGHS, for example `optimal` or `time-limit`. */
+  readonly status: string;
+  /** This value is `true` when HiGHS proved the optimum, with a relative MIP gap of 0. */
+  readonly proven: boolean;
+  /** The objective of the best solution, or `null` without a solution. */
+  readonly objective: number | null;
+  /** The dual bound of HiGHS at the end of the solve, or `null` when HiGHS gives none. */
+  readonly bound: number | null;
+  /** The relative MIP gap of HiGHS at the end of the solve: `|objective - bound| / |objective|`. It is `null` without a solution. */
+  readonly mipGap: number | null;
+  /** The time of the solve, in seconds, without the time to make the model. */
+  readonly seconds: number;
+  /** The size of the model: the edges with a way in the stretch limit, the binary variables and the constraints. */
+  readonly edges: number;
+  readonly binaries: number;
+  readonly rows: number;
+  /** The plan of the best solution. It is empty without a solution. */
+  readonly plan: HighwayPlan;
+  /** The ink saved (B1) of the model itself: `1 - (the ink of the open links) / (the length of the ways)`. It is `null` without a solution. */
+  readonly modelB1: number | null;
+}
+
+/** This function gives a finite number of the info of HiGHS, or `null`. */
+function infoNumber(model: HighsModelLike, name: string): number | null {
+  try {
+    const v = Number(model.info.get(name));
+    return Number.isFinite(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This function makes the exact model of a graph and solves it with HiGHS.
+ * The relative MIP gap is 0, and the time limit is `seconds`.
+ * It gives the status, the proof, the bound, the gap, the time and the plan of the best solution.
+ */
+export function solveExact(highs: HighsLike, graph: Graph, o: { readonly stretch: number; readonly rule: ExactRule; readonly seconds: number }): ExactSolve {
+  const model = exactModel(graph, { stretch: o.stretch, rule: o.rule });
+  const size = { edges: model.edges, binaries: model.columns, rows: model.rows };
+  const m = highs.createModel({ format: "lp", data: model.lp });
+  try {
+    m.options.set({ time_limit: o.seconds, output_flag: false, mip_rel_gap: 0 });
+    const start = Date.now();
+    m.run();
+    const seconds = (Date.now() - start) / 1000;
+    const code = m.getModelStatus();
+    const statuses = highs.constants.modelStatus;
+    const status = code === statuses.optimal ? "optimal" : code === statuses.timeLimit ? "time-limit" : `status-${code}`;
+    // The value 2 of `primal_solution_status` is a feasible solution.
+    const found = infoNumber(m, "primal_solution_status") === 2;
+    if (!found) return { status, proven: false, objective: null, bound: infoNumber(m, "mip_dual_bound"), mipGap: null, seconds, ...size, plan: { highways: [] }, modelB1: null };
+    const values = m.getSolution().colValue;
+    const byName = new Map<string, number>();
+    const cols = m.getDimensions().numCols;
+    for (let i = 0; i < cols; i++) byName.set(m.getColName(i), values[i]!);
+    const value = (name: string): number => byName.get(name) ?? 0;
+    const plan = model.decode(value);
+    // The ink is the sum of the lengths of the open links (`y`), and the length of the ways is the sum of the lengths of the arcs (`x`).
+    let ink = 0;
+    let ways = 0;
+    for (const [name, len] of model.lengths) {
+      if (value(name) <= 0.5) continue;
+      if (name.startsWith("y")) ink += len;
+      else ways += len;
+    }
+    const mipGap = infoNumber(m, "mip_gap");
+    return {
+      status,
+      proven: code === statuses.optimal,
+      objective: m.getObjectiveValue(),
+      bound: infoNumber(m, "mip_dual_bound"),
+      mipGap: code === statuses.optimal ? (mipGap ?? 0) : mipGap,
+      seconds,
+      ...size,
+      plan,
+      modelB1: ways > 0 ? Math.max(0, 1 - ink / ways) : 0,
+    };
+  } finally {
+    m.dispose();
+  }
+}
+
+/** The routes of a plan after `follow`, with the ink saved (B1) and the largest bundle stretch (B3) against the routes of `corners`. */
+export interface PlanMeasures {
+  readonly routes: readonly Route[];
+  readonly b1: number;
+  readonly b3max: number;
+}
+
+/** This function routes a plan with `follow`, and gives B1 and the largest B3 of the routes. The base of B3 is the router `corners`. */
+export function planMeasures(graph: Graph, plan: HighwayPlan): PlanMeasures {
+  const routes = follow(graph, plan).routes;
+  const corners = asRouter(getStrategy(STRATEGIES, "router", "corners")).route(graph).routes;
+  return { routes, b1: inkSaved(routes), b3max: maxStretch(routes, corners) };
+}

package/src/bench/screen/activation.ts

@@ -0,0 +1,3 @@
+// The activation test of a screen (ACTIVATION): did the idea of a candidate run on the input?
+// `outputHash`, `outputGroups` and `exercised` come from `@mark1russell7/layout-contract` (PORTFOLIO-FIT). `docs/PROMOTION.md` gives the rules.
+export { exercised, outputGroups, outputHash, type ExerciseEvidence, type HashOptions, type OutputGroup } from "@mark1russell7/layout-contract";

package/src/bench/screen/bounds.ts

@@ -0,0 +1,140 @@
+import { quantile } from "../measures/stats.ts";
+import { GAP_BASELINES, type ExactOptimum, type GapRule } from "./gap.ts";
+
+/**
+ * The interval of the optimum B1 of one solve (EXACT-BOUNDS). The low end is the B1 of the best solution of HiGHS.
+ * The high end comes from the dual bound. For a proven optimum, the two ends are equal.
+ */
+export interface OptimumInterval {
+  readonly lo: number;
+  readonly hi: number;
+  readonly proven: boolean;
+}
+
+/**
+ * This function gives the interval of the optimum B1 of a solve, or `undefined` without a solution.
+ * The high end is `1 - (1 - b1) × bound / objective`. It supposes that the ink of the optimum is at least `bound / objective` times the ink of the best solution,
+ * with routes of the same length. The objective of the model is the ink plus a small cost of the length, so the ratio is a ratio of the ink.
+ * Without a positive bound, the high end is 1.
+ */
+export function optimumInterval(o: ExactOptimum): OptimumInterval | undefined {
+  if (o.b1 === null || o.objective === null) return undefined;
+  if (o.proven) return { lo: o.b1, hi: o.b1, proven: true };
+  const ratio = o.bound !== null && o.bound > 0 && o.objective > 0 ? Math.min(1, o.bound / o.objective) : 0;
+  return { lo: o.b1, hi: Math.min(1, Math.max(o.b1, 1 - (1 - o.b1) * ratio)), proven: false };
+}
+
+/** The interval of the gap closed of one run against an interval of the optimum. */
+export interface GapInterval {
+  readonly lo: number;
+  readonly hi: number;
+  readonly mid: number;
+  readonly width: number;
+}
+
+/**
+ * This function gives the interval of the gap closed `(b1 - base) / (optimum - base)` over the interval of the optimum.
+ * For a run above the baseline, the high end of the optimum gives the low end of the gap closed. The low end of the optimum gives the high end.
+ * It gives `undefined` when the low end of the optimum is at the baseline or below it, because then the gap closed has no limit.
+ */
+export function gapInterval(b1: number, base: number, optimum: { readonly lo: number; readonly hi: number }): GapInterval | undefined {
+  const dLo = optimum.lo - base;
+  const dHi = optimum.hi - base;
+  if (!(dLo > 1e-9)) return undefined;
+  const a = (b1 - base) / dHi;
+  const b = (b1 - base) / dLo;
+  const lo = Math.min(a, b);
+  const hi = Math.max(a, b);
+  return { lo, hi, mid: (lo + hi) / 2, width: hi - lo };
+}
+
+/** The values of one run that the bounds read: B1, the largest stretch of the model and the flag of mixed collections. */
+export interface BoundsRun {
+  readonly b1: number;
+  readonly stretch: number;
+  readonly mixed: boolean;
+}
+
+/** The gap closed of one strategy at one size, one rule and one cap, over the inputs. */
+export interface BoundsRow {
+  readonly strategy: string;
+  /** The number of inputs, and the number of inputs where the run has a value. */
+  readonly inputs: number;
+  readonly values: number;
+  /** The medians over the inputs with a value: the midpoint, the low end, the high end and the width of the interval. */
+  readonly mid: number;
+  readonly lo: number;
+  readonly hi: number;
+  readonly width: number;
+}
+
+/** The gap closed of each strategy at one size, one rule and one cap, sorted by the median of the midpoint. */
+export interface BoundsCell {
+  readonly nodes: number;
+  readonly rule: GapRule;
+  readonly cap: number;
+  /** The counts of the solves: the inputs, the proven optima, the solves with a bound only, and the solves without a solution. */
+  readonly inputs: number;
+  readonly proven: number;
+  readonly bounded: number;
+  readonly none: number;
+  /** The median width of the interval of the optimum B1, over the solves with a solution. */
+  readonly optimumWidth: number;
+  readonly rows: readonly BoundsRow[];
+}
+
+/**
+ * This function gives the gap closed of each strategy for each size, rule and cap of the optima.
+ * A run has a value when it obeys the rule and when its stretch is at or below the cap. The solve must also have a solution.
+ * The rule `collection` refuses a run with a shared segment that holds edges of two collections.
+ * The baseline of each rule is the run of `GAP_BASELINES` on the same input, with the prefix `hw:` for a highway strategy.
+ * The rows sort by the median of the midpoint, from high to low. A strategy with a value on fewer than half of the inputs comes after the others.
+ */
+export function boundsCells(runs: ReadonlyMap<string, ReadonlyMap<string, BoundsRun>>, optima: readonly ExactOptimum[]): BoundsCell[] {
+  const keys = [...new Set(optima.map((o) => `${o.nodes}|${o.rule}|${o.cap}`))];
+  const cells: BoundsCell[] = [];
+  const baseName = (rule: GapRule): string => (rule === "all" ? `hw:${GAP_BASELINES.all}` : GAP_BASELINES.collection);
+  for (const key of keys) {
+    const [n, rule, c] = key.split("|") as [string, GapRule, string];
+    const nodes = Number(n);
+    const cap = Number(c);
+    const mine = optima.filter((o) => o.nodes === nodes && o.rule === rule && o.cap === cap && runs.has(o.input));
+    const intervals = new Map(mine.flatMap((o) => (optimumInterval(o) ? [[o.input, optimumInterval(o)!] as const] : [])));
+    const names = [...new Set(mine.flatMap((o) => [...runs.get(o.input)!.keys()]))].sort();
+    const rows: BoundsRow[] = names.map((strategy) => {
+      const vs: GapInterval[] = [];
+      for (const o of mine) {
+        const row = runs.get(o.input)!;
+        const r = row.get(strategy);
+        const base = row.get(baseName(rule));
+        const opt = intervals.get(o.input);
+        if (r === undefined || base === undefined || opt === undefined) continue;
+        if ((rule === "collection" && r.mixed) || r.stretch > cap + 1e-9) continue;
+        const g = gapInterval(r.b1, base.b1, opt);
+        if (g !== undefined) vs.push(g);
+      }
+      const med = (f: (g: GapInterval) => number): number => quantile(vs.map(f), 0.5);
+      return { strategy, inputs: mine.length, values: vs.length, mid: med((g) => g.mid), lo: med((g) => g.lo), hi: med((g) => g.hi), width: med((g) => g.width) };
+    });
+    const few = (r: BoundsRow): number => (2 * r.values < r.inputs || r.values === 0 ? 1 : 0);
+    rows.sort((a, b) => few(a) - few(b) || (Number.isNaN(b.mid) ? -Infinity : b.mid) - (Number.isNaN(a.mid) ? -Infinity : a.mid) || (a.strategy < b.strategy ? -1 : 1));
+    const widths = [...intervals.values()].map((i) => i.hi - i.lo);
+    cells.push({
+      nodes,
+      rule,
+      cap,
+      inputs: mine.length,
+      proven: mine.filter((o) => o.proven).length,
+      bounded: mine.filter((o) => !o.proven && intervals.has(o.input)).length,
+      none: mine.filter((o) => !intervals.has(o.input)).length,
+      optimumWidth: quantile(widths, 0.5),
+      rows,
+    });
+  }
+  return cells.sort((a, b) => a.nodes - b.nodes || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0) || a.cap - b.cap);
+}
+
+/** This function gives the strategies that rank in a cell: the first `k` rows with a value on at least half of the inputs. */
+export function topOf(cell: BoundsCell, k = 5): BoundsRow[] {
+  return cell.rows.filter((r) => r.values > 0 && 2 * r.values >= r.inputs).slice(0, k);
+}

package/src/bench/screen/compare.ts

@@ -0,0 +1,26 @@
+// The compare of one measure (WIN-RES). `compareMeasure` and `minEffectOf` come from `@mark1russell7/layout-contract` (PORTFOLIO-FIT).
+// `docs/PROMOTION.md` gives the rule. The test `compare.test.ts` checks that the functions agree with the note.
+import type { MeasureSpec, Verdict } from "@mark1russell7/layout-contract";
+
+export { compareMeasure, minEffectOf } from "@mark1russell7/layout-contract";
+
+/**
+ * The smallest change of a measure that counts as better or worse (WIN-RES).
+ * A number is an absolute change. `{ rel }` is a share of the larger of the two absolute values.
+ * The threshold is not less than `RECORD_EPS` at any time.
+ */
+export type MinEffect = NonNullable<MeasureSpec["minEffect"]>;
+
+/** The result of a compare of a candidate with a baseline on one measure. A tie is not a win. It is the `Verdict` of the contract. */
+export type MeasureCompare = Verdict;
+
+/** The part of a measure that a compare reads: the better side and the minimum effect. */
+export type CompareSpec = Pick<MeasureSpec, "direction" | "minEffect">;
+
+/**
+ * This function applies the wave rule to the compares of one board, for example of `B1` and of the `B3` q95.
+ * The board is a win only when no compare is `worse` and one or more compares are `better`. Thus a board of ties is not a win.
+ */
+export function boardWins(compares: readonly MeasureCompare[]): boolean {
+  return !compares.includes("worse") && compares.includes("better");
+}

package/src/bench/screen/exact-set.ts

@@ -0,0 +1,100 @@
+import { makeFixture, type FixtureKind } from "../../fixtures.ts";
+import type { Graph } from "../../model.ts";
+import type { LayoutCell, LayoutGenerator } from "./forms.ts";
+import type { ScreenFamily, ScreenSet } from "./set.ts";
+
+/** The board classes of the small boards with a known optimum (MEAS2). */
+export type ExactClass = "uniform" | "clustered" | "hubs" | "fanout";
+
+/** The board classes of `EXACT_V1`, in the order of the set. */
+export const EXACT_CLASSES: readonly ExactClass[] = ["uniform", "clustered", "hubs", "fanout"];
+
+/** The edges of each node of a small board with a known optimum. */
+export const EXACT_EDGES_PER_NODE = 1.5;
+
+/** The fixture kind of each class. The class `fanout` is the kind `collections`: each cluster is one collection, with fan-outs. */
+const KINDS: Readonly<Record<ExactClass, FixtureKind>> = { uniform: "uniform", clustered: "clustered", hubs: "hubs", fanout: "collections" };
+
+/** The cell of each class in the taxonomy of the corpus. */
+const CELLS: Readonly<Record<ExactClass, LayoutCell>> = {
+  uniform: { edgeShape: "random" },
+  clustered: { edgeShape: "clustered" },
+  hubs: { edgeShape: "hubChain" },
+  fanout: { edgeShape: "bundled" },
+};
+
+/** This function gives the seed of the fixture of the member `k` of a class: `100 × (the index of the class + 1) + k`. */
+export function exactSeed(cls: ExactClass, k: number): number {
+  return 100 * (EXACT_CLASSES.indexOf(cls) + 1) + k;
+}
+
+/** This function gives the generator of a small board: the generator `fixture` with the kind of the class, `nodes` and the seed of `exactSeed`. */
+export function exactGenerator(cls: ExactClass, nodes: number, k: number): LayoutGenerator {
+  return { name: "fixture", version: 1, params: { kind: KINDS[cls], nodes, edgesPerNode: EXACT_EDGES_PER_NODE }, seed: exactSeed(cls, k) };
+}
+
+/** This function makes the small board of a class with `nodes` nodes and the member `k`. The same values always give the same graph. */
+export function exactBoard(cls: ExactClass, nodes: number, k: number): Graph {
+  return makeFixture({ name: cls, kind: KINDS[cls], nodes, edgesPerNode: EXACT_EDGES_PER_NODE, seed: exactSeed(cls, k) });
+}
+
+/**
+ * This function gives a family of small boards of one class. The member `k` has `sizes[k mod sizes.length]` nodes.
+ * The count of the cell is `10`, because each board has fewer than 100 nodes.
+ */
+export function exactFamily(cls: ExactClass, sizes: readonly number[], seeds: number): ScreenFamily {
+  const nodes = (k: number): number => sizes[k % sizes.length]!;
+  return {
+    name: cls,
+    shows: `Small boards of the class ${cls} with ${sizes.join(", ")} nodes and a known optimum.`,
+    seeds,
+    cell: { containerSize: "freeAspect", containerShape: "rect", obstacles: "none", mode: "offline", groups: "none", count: "10", edgeDensity: "medium", ports: "free", ...CELLS[cls] },
+    make: (k) => exactBoard(cls, nodes(k), k),
+    generator: (k) => exactGenerator(cls, nodes(k), k),
+  };
+}
+
+/**
+ * The node counts of the boards of `EXACT_V1`. The member `k` of each class has `EXACT_V1_SIZES[k mod length]` nodes.
+ * The size ladder of MEAS2 (CI run 40613531631) proved each optimum at 10 nodes within 300 s, for each class, both rules and the cap 1.5.
+ * At 14 nodes, 4 of 24 solves stopped at the time limit.
+ */
+export const EXACT_V1_SIZES: readonly number[] = [10];
+
+/** The number of seeds of each class of `EXACT_V1`. It is `cellMin` of the promotion rule. */
+export const EXACT_V1_SEEDS = 10;
+
+/**
+ * The screen set `exact-v1` (MEAS2): small boards of made-up data with a known optimum of the exact model.
+ * It has 4 classes of 10 seeds. The file `optima-exact-v1.json` of `bench/exact` keeps the optimum of each input, each rule and each cap.
+ * This set does not change. The tests compare it with the files in `corpus/exact-v1`.
+ */
+export const EXACT_V1: ScreenSet = {
+  id: "exact-v1",
+  families: EXACT_CLASSES.map((cls) => exactFamily(cls, EXACT_V1_SIZES, EXACT_V1_SEEDS)),
+};
+
+/** The node counts of the boards of `EXACT_V1_BOUNDS`. HiGHS proves few optima at these sizes within 300 s, so the set keeps bounds (EXACT-BOUNDS). */
+export const EXACT_V1_BOUNDS_SIZES: readonly number[] = [18, 24, 40];
+
+/** This function gives the name of the family of a class at a size in `EXACT_V1_BOUNDS`: `<class>-n<nodes>`. */
+export function boundsFamilyName(cls: ExactClass, nodes: number): string {
+  return `${cls}-n${nodes}`;
+}
+
+/**
+ * The screen set `exact-v1-bounds` (EXACT-BOUNDS): the boards of the classes of `exact-v1` at 18, 24 and 40 nodes, with 10 seeds each.
+ * Each family is one class at one size. The member `k` uses the seed `exactSeed(class, k)`, as in `exact-v1`.
+ * The file `optima-exact-v1-bounds.json` of `bench/exact` keeps the best bound and the best solution of each input, each rule and each cap.
+ * This set does not change. The tests compare it with the files in `corpus/exact-v1-bounds`.
+ */
+export const EXACT_V1_BOUNDS: ScreenSet = {
+  id: "exact-v1-bounds",
+  families: EXACT_V1_BOUNDS_SIZES.flatMap((n) =>
+    EXACT_CLASSES.map((cls) => ({
+      ...exactFamily(cls, [n], EXACT_V1_SEEDS),
+      name: boundsFamilyName(cls, n),
+      shows: `Boards of the class ${cls} with ${n} nodes, with a bound of the optimum.`,
+    })),
+  ),
+};