@mark1russell7/highways 0.5.0 → 0.5.1

package/src/highways/trace.ts

@@ -0,0 +1,153 @@
+import { dist, type Point } from "../geom.ts";
+import type { Obstacles } from "../visibility.ts";
+import type { WayFinder } from "../ways.ts";
+import type { HighwayInput, HighwayPlan } from "./model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "./stretches.ts";
+
+/** The options of `tracePlan`. */
+export interface TraceOptions {
+  /** The side of the grid that the waypoints snap to, in units of the board. The value 0 keeps each waypoint where it is. */
+  readonly snap: number;
+  /** A highway has this number of edges or more. The value is 2 or more. */
+  readonly minSize: number;
+  /** The key of the ways. Only the ways with one key share a highway. */
+  readonly key: string;
+}
+
+/**
+ * This function moves a point out of each box, made larger by `pad`. A point in a box moves to the nearest side of that box.
+ * The function tries four times, so a point between two near boxes can stay in a box.
+ */
+export function outOfBoxes(obstacles: Obstacles, p: Point, pad: number): Point {
+  let q = p;
+  for (let k = 0; k < 4; k++) {
+    let hit: { x: number; y: number; w: number; h: number } | undefined;
+    obstacles.query({ x: q.x - pad, y: q.y - pad, w: 2 * pad, h: 2 * pad }, (n) => {
+      const b = n.box;
+      if (!hit && q.x > b.x - pad && q.x < b.x + b.w + pad && q.y > b.y - pad && q.y < b.y + b.h + pad) hit = b;
+    });
+    if (!hit) return q;
+    const b = hit;
+    const eps = 1e-3;
+    const moves = [
+      { d: q.x - (b.x - pad), p: { x: b.x - pad - eps, y: q.y } },
+      { d: b.x + b.w + pad - q.x, p: { x: b.x + b.w + pad + eps, y: q.y } },
+      { d: q.y - (b.y - pad), p: { x: q.x, y: b.y - pad - eps } },
+      { d: b.y + b.h + pad - q.y, p: { x: q.x, y: b.y + b.h + pad + eps } },
+    ];
+    moves.sort((u, v) => u.d - v.d);
+    q = moves[0]!.p;
+  }
+  return q;
+}
+
+/**
+ * This function gives the push of the boxes on a point. Each box nearer than `reach` adds a unit vector away from it, times `(reach - d) / reach`.
+ * The value `d` is the distance from the point to the box. It is the gradient of a field that is 0 at the distance `reach` from each box.
+ */
+export function boxPush(obstacles: Obstacles, p: Point, reach: number): Point {
+  let x = 0;
+  let y = 0;
+  if (reach <= 0) return { x, y };
+  obstacles.query({ x: p.x - reach, y: p.y - reach, w: 2 * reach, h: 2 * reach }, (n) => {
+    const b = n.box;
+    const qx = Math.max(b.x, Math.min(b.x + b.w, p.x));
+    const qy = Math.max(b.y, Math.min(b.y + b.h, p.y));
+    let dx = p.x - qx;
+    let dy = p.y - qy;
+    let d = Math.hypot(dx, dy);
+    if (d >= reach) return;
+    if (d < 1e-9) {
+      // The point is in the box: it goes out through the nearest side.
+      const sides = [
+        { d: p.x - b.x, v: [-1, 0] },
+        { d: b.x + b.w - p.x, v: [1, 0] },
+        { d: p.y - b.y, v: [0, -1] },
+        { d: b.y + b.h - p.y, v: [0, 1] },
+      ].sort((u, v) => u.d - v.d);
+      [dx, dy] = sides[0]!.v as [number, number];
+      d = 0;
+    } else {
+      dx /= d;
+      dy /= d;
+    }
+    const f = (reach - d) / reach;
+    x += dx * f;
+    y += dy * f;
+  });
+  return { x, y };
+}
+
+/** This function gives points at equal steps of `step` or a little less along a polyline, without its two ends. A polyline without length gives no point. */
+export function innerPoints(line: readonly Point[], step: number): Point[] {
+  const at: number[] = [0];
+  for (let i = 1; i < line.length; i++) at.push(at[i - 1]! + dist(line[i - 1]!, line[i]!));
+  const total = at[at.length - 1] ?? 0;
+  if (total <= 1e-9 || step <= 0) return [];
+  const count = Math.floor(total / step);
+  const out: Point[] = [];
+  let j = 1;
+  for (let k = 1; k <= count; k++) {
+    const s = (total * k) / (count + 1);
+    while (j < line.length - 1 && at[j]! < s) j++;
+    const a = line[j - 1]!;
+    const b = line[j]!;
+    const len = at[j]! - at[j - 1]!;
+    const u = len > 0 ? Math.max(0, Math.min(1, (s - at[j - 1]!) / len)) : 0;
+    out.push({ x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+  }
+  return out;
+}
+
+/**
+ * This function gives the way of one edge through its waypoints. The way starts at `a` and ends at `b`.
+ * Each waypoint snaps to the grid of side `snap`. A waypoint in a box moves to the nearest corner of the corner graph.
+ * From each waypoint to the next one, the way is a straight line when that line is clear. Otherwise it goes through the corner graph.
+ * A waypoint that the graph does not reach is not on the way. When the way cannot reach `b`, the function gives the way of the corner graph from `a` to `b`.
+ */
+export function waypointWay(finder: WayFinder, a: Point, b: Point, waypoints: readonly Point[], snap: number): Point[] | undefined {
+  const corners = finder.corners;
+  const pad = finder.margin / 2;
+  const fixed: Point[] = [];
+  for (const w of waypoints) {
+    let q = snap > 0 ? { x: Math.round(w.x / snap) * snap, y: Math.round(w.y / snap) * snap } : w;
+    if (finder.obstacles.inside(q, pad)) {
+      const i = corners.nearest(q);
+      if (i < 0) continue;
+      q = corners.points[i]!;
+    }
+    const last = fixed[fixed.length - 1];
+    if (last && dist(last, q) <= 1e-9) continue;
+    fixed.push(q);
+  }
+  const out: Point[] = [a];
+  let at = a;
+  for (const q of fixed) {
+    if (dist(at, q) <= 1e-9) continue;
+    const piece = corners.path(at, q);
+    if (!piece) continue;
+    out.push(...piece.slice(1));
+    at = q;
+  }
+  const tail = dist(at, b) <= 1e-9 ? [b] : corners.path(at, b);
+  if (!tail) return corners.path(a, b);
+  out.push(...tail.slice(1));
+  return out;
+}
+
+/**
+ * This function gives the highways of the waypoints of each edge. The ways go through the corner graph, so they stay out of the boxes.
+ * Each edge goes from the point at `margin` from its source plug, through its waypoints, to the point at `margin` from its target plug.
+ * Each stretch that `minSize` ways or more share is one highway, with the needless corners removed.
+ * An edge without waypoints takes its way of the corner graph.
+ */
+export function tracePlan(input: HighwayInput, finder: WayFinder, waypoints: ReadonlyMap<string, readonly Point[]>, o: Readonly<TraceOptions>): HighwayPlan {
+  const ways: KeyedWay[] = [];
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    const way = waypointWay(finder, a, b, waypoints.get(edge.id) ?? [], o.snap);
+    if (way) ways.push({ edge: edge.id, key: o.key, points: way });
+  }
+  return sharedStretches(ways, { minSize: o.minSize, pull: (p) => finder.corners.pull(p) });
+}

package/src/index.ts

@@ -32,3 +32,4 @@ export * from "./bench/screen/index.ts";
 export * from "./highways/index.ts";
 export * from "./order/index.ts";
 export * from "./repair/index.ts";
+export * from "./portfolio/index.ts";

package/src/portfolio/bands.ts

@@ -0,0 +1,33 @@
+/** The rule of the caller. Under `collection`, a shared segment holds edges of one collection only. Under `all`, collections can mix. */
+export type PortfolioRule = "collection" | "all";
+
+/** The stretch caps of the portfolio router: the caps of the gap closed (B10). */
+export type PortfolioCap = 1.1 | 1.25 | 1.5;
+
+/** The rules of the portfolio router. */
+export const PORTFOLIO_RULES: readonly PortfolioRule[] = ["collection", "all"];
+
+/** The caps of the portfolio router. */
+export const PORTFOLIO_CAPS: readonly PortfolioCap[] = [1.1, 1.25, 1.5];
+
+/** The sizes of the sets of the portfolio router, without the base. */
+export const PORTFOLIO_KS_API: readonly (3 | 5 | 8)[] = [3, 5, 8];
+
+/** One size band of the inputs. Each band has its own greedy sets. */
+export interface PortfolioBand {
+  readonly id: string;
+  /** The largest node count of the band. An input with more nodes than the last band uses the last band. */
+  readonly maxNodes: number;
+}
+
+/** The size bands: up to 12 nodes, 13 to 24 nodes, and 25 to 40 nodes. An input above 40 nodes uses the band `n25-40`. */
+export const PORTFOLIO_BANDS: readonly PortfolioBand[] = [
+  { id: "n1-12", maxNodes: 12 },
+  { id: "n13-24", maxNodes: 24 },
+  { id: "n25-40", maxNodes: 40 },
+];
+
+/** This function gives the band of a node count: the first band whose `maxNodes` is the count or more, else the last band. */
+export function portfolioBand(nodes: number, bands: readonly PortfolioBand[] = PORTFOLIO_BANDS): PortfolioBand {
+  return bands.find((b) => nodes <= b.maxNodes) ?? bands[bands.length - 1]!;
+}

package/src/portfolio/fit.ts

@@ -0,0 +1,29 @@
+// This file is generated by `scripts/portfolio-sets.ts` (`pnpm portfolio:sets`). Do not edit it. The test `sets.test.ts` checks that it is current.
+// The times come from the CI run 40658558076 (the workflow `Portfolio`, `portfolio:time --members`).
+import type { PortfolioCap, PortfolioRule } from "./bands.ts";
+
+/**
+ * The fit of each rule, cap and size band, by the key `<rule>|<cap>|<band>`: the members of the default of the portfolio router, in their order.
+ * Each member has a node limit: it runs only on an input with that many nodes or fewer. The limits keep the model time at or below 40 ms.
+ * The base `shared` is not in a fit: the portfolio always runs it first.
+ */
+export const PORTFOLIO_FIT: Readonly<Record<`${PortfolioRule}|${PortfolioCap}|${string}`, readonly (readonly [string, number])[]>> = {
+  "collection|1.1|n1-12": [["corners-side", 12], ["w2c:select+stretch", 12], ["trunks-gilbert-a05", 12], ["w3a:spiral-a15", 12], ["trunks-tree-bf08", 12], ["hw:zipper", 12], ["w2c:level-links+stretch-b1.1", 12], ["hw:stubs", 12]],
+  "collection|1.1|n13-24": [["w3e:crossbars+stretch", 24], ["corners-side", 24], ["shared-p2", 24], ["w2c:zipper+stretch-b1.1", 18], ["trunks-tree-bf08", 18], ["hw:weiszfeld", 18]],
+  "collection|1.1|n25-40": [["w2a:shared-ways+breakeven", 32], ["w2b:weiszfeld-a1", 32]],
+  "collection|1.25|n1-12": [["corners-side", 12], ["trunks-tree-bf06", 12], ["w3f:p-hub-a0.2", 12], ["hw:stubs", 12], ["hw:p-hub", 12], ["hw:spiral", 12], ["w2c:level-links+stretch", 12], ["w3f:spectral-c0.3", 12]],
+  "collection|1.25|n13-24": [["w2a:shared-ways+stretch", 24], ["shared-p3", 24], ["trunks-gilbert-a07", 24], ["w3e:crossbars+stretch", 24], ["trunks-tree-bf06", 18], ["w3c:hdbscan+stretch", 18], ["shared-wind-p2-r1-e2", 18], ["hw:stubs", 18]],
+  "collection|1.25|n25-40": [["w2a:shared-ways+stretch", 32], ["shared-p3", 32], ["shared-order-shortest", 32]],
+  "collection|1.5|n1-12": [["trunks-gilbert-a03", 12], ["w3e:areas-keys", 12], ["trunks-tree-bf02", 12], ["w3f:p-hub-a0.2", 12], ["w2b:zipper-a1", 12], ["w3a:spiral-a35", 12], ["w3f:spectral-c0.3", 12], ["w2c:level-links+stretch", 12]],
+  "collection|1.5|n13-24": [["shared-wind-p2-r0.5", 24], ["trunks-gilbert-a03", 24], ["w3e:crossbars+stretch", 24], ["shared-wind-p2-r1-e2", 24], ["trunks-tree-bf06", 24], ["shared-flow-a06-p3", 18], ["shared-wind-p3-r1", 18], ["trunks-gilbert-a07", 18]],
+  "collection|1.5|n25-40": [["shared-p3", 40], ["hw:lanes", 32], ["shared-wind-p2-r1-e2", 32]],
+  "all|1.1|n1-12": [["w2b:zipper-p2", 12], ["hw:cubu", 12], ["w3d:kdeeb+stretch", 12], ["w3c:hough-wide", 12], ["w3d:kdeeb-routes", 12], ["hw:stubs", 12], ["hw:spiral", 12], ["w3b:growth-s0.7", 12]],
+  "all|1.1|n13-24": [["w3e:frechet-e0.5", 24], ["w3a:diffusion-wide", 24], ["w2c:zipper+stretch-b1.1", 24], ["w3d:cubu+stretch", 18]],
+  "all|1.1|n25-40": [["w2c:zipper+stretch-b1.1", 32], ["w3a:spiral-a15", 32]],
+  "all|1.25|n1-12": [["w3d:kdeeb-routes", 12], ["w3e:mlseb+stretch", 12], ["hw:growth", 12], ["hw:level-links", 12], ["w3b:growth-input", 12], ["w3e:confluent+stretch", 12], ["w3d:kdeeb-nomask", 10], ["w3a:diffusion-g2", 10]],
+  "all|1.25|n13-24": [["w3d:kdeeb-routes", 24], ["w3e:mlseb+stretch", 18]],
+  "all|1.25|n25-40": [["w3d:kdeeb-routes", 32]],
+  "all|1.5|n1-12": [["w3b:growth-s0.3", 12], ["w3e:mlseb-a0", 12], ["w3e:mlseb-routes", 10], ["w3c:edge-paths-k1.5", 10]],
+  "all|1.5|n13-24": [["hw:growth", 24], ["w3b:growth-input", 24]],
+  "all|1.5|n25-40": [["hw:growth", 40], ["w3b:growth-s0.7", 32], ["w3b:growth-s0.3", 32]],
+};

package/src/portfolio/index.ts

@@ -0,0 +1,6 @@
+export * from "./bands.ts";
+export * from "./fit.ts";
+export * from "./key.ts";
+export * from "./members.ts";
+export * from "./router.ts";
+export * from "./sets.ts";

package/src/portfolio/key.ts

@@ -0,0 +1,98 @@
+// The key of the portfolio router (PORTFOLIO-FIT): one guard for the router, the records and the greedy choice of the sets.
+// A member passes the guard when it has no more breaks of each hard rule than the base, a stretch at or below the cap, and, under `collection`, no mixed segment.
+// The base `shared` is the fallback output, so it passes the guard at each cap. The script `portfolio.ts` applies the same guard to the records.
+import { exactStretches } from "../bench/exact/index.ts";
+import { inkSaved } from "../bench/measures/bundles.ts";
+import { checkProperties } from "../bench/properties.ts";
+import { resultHash } from "../bench/screen/exercise.ts";
+import { mixedSegments } from "../bench/screen/gap.ts";
+import type { CompareSpec } from "../bench/screen/compare.ts";
+import { compareSpec, measureByKey } from "../bench/screen/measures.ts";
+import type { PortfolioKey } from "../bench/screen/portfolio-pick.ts";
+import type { Graph, Result } from "../model.ts";
+import type { PortfolioCap, PortfolioRule } from "./bands.ts";
+
+/** The id of the B1 level of the key of the portfolio router. */
+export const PORTFOLIO_B1 = "B1";
+
+/** This function gives the spec of the B1 level: higher is better, with the `minEffect` of the row `B1.inkSaved` of the table `MEASURES`. */
+export function portfolioB1Spec(): CompareSpec {
+  const info = measureByKey("B1.inkSaved");
+  if (info === undefined) throw new Error("The table MEASURES has no row B1.inkSaved.");
+  return compareSpec(info);
+}
+
+/** The facts of one output that the guard reads. The router takes them from the output, and the script `portfolio.ts` from a record. */
+export interface PortfolioFacts {
+  /** The count of the breaks of each hard rule. */
+  readonly hard: Readonly<Record<string, number>>;
+  /** The count of the edges with a stretch above each cap, by the cap. The largest stretch of a record gives 1 or 0. */
+  readonly over: (cap: number) => number;
+  /** The count of the shared segments that hold edges of two collections. */
+  readonly mixed: number;
+}
+
+/**
+ * This function gives the count of the breaks of the guard of an output against the base, with the rule `rule` and the cap `cap`.
+ * The count is the sum of three parts:
+ * - for each hard rule, the breaks above the breaks of the base
+ * - the edges with a stretch above the cap
+ * - under the rule `collection`, the mixed segments.
+ * An output passes the guard when the count is 0.
+ */
+export function guardBreaks(facts: PortfolioFacts, base: PortfolioFacts | undefined, rule: PortfolioRule, cap: number): number {
+  let n = 0;
+  for (const [k, v] of Object.entries(facts.hard)) n += Math.max(0, v - (base?.hard[k] ?? 0));
+  n += facts.over(cap);
+  if (rule === "collection") n += facts.mixed;
+  return n;
+}
+
+/** This function counts the breaks of each hard rule in a list of breaks. */
+function countRules(breaks: readonly { readonly rule: string }[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const b of breaks) out[b.rule] = (out[b.rule] ?? 0) + 1;
+  return out;
+}
+
+/**
+ * This function gives the function of the facts of the outputs on the graph `graph`. It builds the network of the stretch one time for the graph.
+ * The hard rules are the rules of `checkProperties`. The stretch is the stretch of the exact model, as the records of the gap screen give it.
+ */
+export function portfolioFacts(graph: Graph): (result: Result) => PortfolioFacts {
+  // The network of the stretch is built at the first call. A portfolio of the base alone does not build it.
+  let stretches: ReturnType<typeof exactStretches> | undefined;
+  return (result) => {
+    stretches ??= exactStretches(graph);
+    const values = [...stretches(result.routes).values()];
+    return {
+      hard: countRules(checkProperties(graph, result, 1_000_000)),
+      over: (cap) => values.filter((v) => v > cap + 1e-9).length,
+      mixed: mixedSegments(graph, result),
+    };
+  };
+}
+
+/**
+ * This function gives the key of the portfolio router on the graph `graph`, with the rule `rule` and the cap `cap`.
+ * - `hard` is `guardBreaks` against the output of the base. `base` gives that output after the base runs. The output of the base has 0 breaks.
+ *   Before the base runs, or when the base throws, a member has its own breaks of the hard rules.
+ * - The one level `B1` is the ink saved (higher is better), with the `minEffect` of the table `MEASURES`.
+ * - The hash is `resultHash`.
+ * The winner is the first member with the most B1 of the members with 0 breaks (`selectBest`). The base has 0 breaks, so a member that fails the guard does not win.
+ */
+export function portfolioKey(graph: Graph, rule: PortfolioRule, cap: PortfolioCap, base: () => Result | undefined = () => undefined): PortfolioKey<Graph, Result> {
+  const facts = portfolioFacts(graph);
+  const spec = portfolioB1Spec();
+  let baseFacts: { readonly of: Result; readonly facts: PortfolioFacts } | undefined;
+  return {
+    hard: (_g, result) => {
+      const b = base();
+      if (b !== undefined && result === b) return 0;
+      if (b !== undefined && baseFacts?.of !== b) baseFacts = { of: b, facts: facts(b) };
+      return guardBreaks(facts(result), b === undefined ? undefined : baseFacts!.facts, rule, cap);
+    },
+    levels: [{ id: PORTFOLIO_B1, spec, value: (_g, result) => inkSaved(result.routes) }],
+    hash: resultHash,
+  };
+}

package/src/portfolio/members.ts

@@ -0,0 +1,171 @@
+// The members of the portfolio router (PORTFOLIO-API). Each member is a router strategy with the name of its records in the gap screen.
+// A built-in highway strategy has the name `hw:<name>`, and an option of an idea wave has the name `<wave>:<name>`. A router option has its own name.
+// The test `members.test.ts` checks that each member gives the same output hash as the strategy of the same name in the screen module of MEAS2.
+import { ambiguityGate } from "../highways/gates/ambiguity/index.ts";
+import { breakEvenGate } from "../highways/gates/breakeven/index.ts";
+import { gateStrategy } from "../highways/gates/model.ts";
+import { stretchGate } from "../highways/gates/stretch/index.ts";
+import type { HighwayInput, HighwayPlan } from "../highways/model.ts";
+import { highwayRouterStrategy } from "../highways/router.ts";
+import type { Graph, Result } from "../model.ts";
+import { cornersRouter, type CornersOptions } from "../routers/corners.ts";
+import { sharedRouter, type SharedOptions } from "../routers/shared.ts";
+import { byCollection, trunksRouter, type TrunksOptions } from "../routers/trunks.ts";
+import { highwayStrategies } from "../strategies/builtins.ts";
+import { defineStrategy, type Strategy } from "../strategies/model.ts";
+import { sharedWaysAll } from "../bench/screen/gap.ts";
+
+/** The name of a built-in highway strategy. */
+type HighwayName = keyof typeof highwayStrategies;
+
+/**
+ * The form of one member:
+ * - `["shared", options]`, `["trunks", options]` or `["corners", options]`: the router with the options. `shared` and `trunks` use the rule `byCollection`.
+ * - `["highway", name]`: the built-in highway strategy `name`, or `shared-ways-all`, with `follow`.
+ * - `["gate", name, gate, budget?]`: the built-in highway strategy with the gate `stretch`, `breakeven` or `ambiguity`. `budget` sets the budget of the gate `stretch`.
+ * - `["plan", name, options]`: the plan of the built-in highway strategy `name` with other options.
+ */
+export type MemberForm =
+  | readonly ["shared", Omit<SharedOptions, "name" | "rule">]
+  | readonly ["trunks", Omit<TrunksOptions, "name" | "rule">]
+  | readonly ["corners", Omit<CornersOptions, "name">]
+  | readonly ["highway", HighwayName | "shared-ways-all"]
+  | readonly ["gate", HighwayName, "stretch" | "breakeven" | "ambiguity", number?]
+  | readonly ["plan", HighwayName, Readonly<Record<string, unknown>>];
+
+/** The forms of the members, by the names of the records. `shared` is the base. The greedy sets of `sets.ts` name only these members. */
+export const MEMBER_FORMS: Readonly<Record<string, MemberForm>> = {
+  shared: ["shared", {}],
+  "corners-side": ["corners", { plugs: "side" }],
+  "shared-flow-a06-p3": ["shared", { cost: "flow", alpha: 0.6, passes: 3 }],
+  "shared-order-shortest": ["shared", { order: "shortest" }],
+  "shared-p2": ["shared", { passes: 2 }],
+  "shared-p3": ["shared", { passes: 3 }],
+  "shared-wind-p2-r0.5": ["shared", { passes: 2, reuse: 0.5 }],
+  "shared-wind-p2-r1": ["shared", { passes: 2, reuse: 1 }],
+  "shared-wind-p2-r1-e2": ["shared", { passes: 2, reuse: 1, reuseExponent: 2 }],
+  "shared-wind-p2-r2": ["shared", { passes: 2, reuse: 2 }],
+  "shared-wind-p3-r1": ["shared", { passes: 3, reuse: 1 }],
+  "trunks-gilbert-a03": ["trunks", { splitAt: "gilbert", alpha: 0.3 }],
+  "trunks-gilbert-a05": ["trunks", { splitAt: "gilbert", alpha: 0.5 }],
+  "trunks-gilbert-a07": ["trunks", { splitAt: "gilbert", alpha: 0.7 }],
+  "trunks-tree-bf02": ["trunks", { fan: "tree", bf: 0.2 }],
+  "trunks-tree-bf06": ["trunks", { fan: "tree", bf: 0.6 }],
+  "trunks-tree-bf08": ["trunks", { fan: "tree", bf: 0.8 }],
+  "hw:crossbars": ["highway", "crossbars"],
+  "hw:cubu": ["highway", "cubu"],
+  "hw:diffusion": ["highway", "diffusion"],
+  "hw:growth": ["highway", "growth"],
+  "hw:lanes": ["highway", "lanes"],
+  "hw:level-links": ["highway", "level-links"],
+  "hw:mesh": ["highway", "mesh"],
+  "hw:mlseb": ["highway", "mlseb"],
+  "hw:p-hub": ["highway", "p-hub"],
+  "hw:shared-ways-all": ["highway", "shared-ways-all"],
+  "hw:spiral": ["highway", "spiral"],
+  "hw:stubs": ["highway", "stubs"],
+  "hw:weiszfeld": ["highway", "weiszfeld"],
+  "hw:zipper": ["highway", "zipper"],
+  "hw:areas": ["highway", "areas"],
+  "w2a:shared-ways+ambiguity": ["gate", "shared-ways", "ambiguity"],
+  "w2a:shared-ways+breakeven": ["gate", "shared-ways", "breakeven"],
+  "w2a:shared-ways+stretch": ["gate", "shared-ways", "stretch"],
+  "w2b:weiszfeld-a0": ["plan", "weiszfeld", { alpha: 0 }],
+  "w2b:weiszfeld-a1": ["plan", "weiszfeld", { alpha: 1 }],
+  "w2b:zipper-a1": ["plan", "zipper", { adhesion: 1 }],
+  "w2b:zipper-p2": ["plan", "zipper", { passes: 2 }],
+  "w2c:level-links+stretch": ["gate", "level-links", "stretch"],
+  "w2c:level-links+stretch-b1.1": ["gate", "level-links", "stretch", 1.1],
+  "w2c:road-classes-d0.3": ["plan", "road-classes", { discount: 0.3 }],
+  "w2c:select+stretch": ["gate", "select", "stretch"],
+  "w2c:zipper+stretch-b1.1": ["gate", "zipper", "stretch", 1.1],
+  "w3a:diffusion+stretch": ["gate", "diffusion", "stretch"],
+  "w3a:diffusion-g2": ["plan", "diffusion", { gamma: 2 }],
+  "w3a:diffusion-l3": ["plan", "diffusion", { lambda: 3 }],
+  "w3a:diffusion-wide": ["plan", "diffusion", { a: 0.5, steps: 6 }],
+  "w3a:spiral-a15": ["plan", "spiral", { alpha: 15 }],
+  "w3a:spiral-a35": ["plan", "spiral", { alpha: 35 }],
+  "w3a:spiral-n3": ["plan", "spiral", { minTargets: 3 }],
+  "w3b:growth-input": ["plan", "growth", { order: "input" }],
+  "w3b:growth-s0.3": ["plan", "growth", { share: 0.3 }],
+  "w3b:growth-s0.7": ["plan", "growth", { share: 0.7 }],
+  "w3b:growth-t1.2": ["plan", "growth", { stretch: 1.2 }],
+  "w3c:edge-paths-k1.5": ["plan", "edge-paths", { distortion: 1.5 }],
+  "w3c:hdbscan+stretch": ["gate", "hdbscan", "stretch"],
+  "w3c:hough-wide": ["plan", "hough", { dTheta: 12, dRho: 24 }],
+  "w3d:cubu+stretch": ["gate", "cubu", "stretch"],
+  "w3d:kdeeb+stretch": ["gate", "kdeeb", "stretch"],
+  "w3d:kdeeb-nomask": ["plan", "kdeeb", { mask: false }],
+  "w3d:kdeeb-routes": ["plan", "kdeeb", { source: "routes" }],
+  "w3d:mesh+stretch": ["gate", "mesh", "stretch"],
+  "w3e:areas-keys": ["plan", "areas", { group: "keys" }],
+  "w3e:confluent+stretch": ["gate", "confluent", "stretch"],
+  "w3e:crossbars+stretch": ["gate", "crossbars", "stretch"],
+  "w3e:frechet+stretch": ["gate", "frechet", "stretch"],
+  "w3e:frechet-e0.5": ["plan", "frechet", { eps: 0.5 }],
+  "w3e:mlseb+stretch": ["gate", "mlseb", "stretch"],
+  "w3e:mlseb-a0": ["plan", "mlseb", { angleWeight: 0 }],
+  "w3e:mlseb-parabola": ["plan", "mlseb", { fit: "parabola" }],
+  "w3e:mlseb-routes": ["plan", "mlseb", { source: "routes" }],
+  "w3f:p-hub-a0.2": ["plan", "p-hub", { alpha: 0.2 }],
+  "w3f:spectral-c0.3": ["plan", "spectral", { c0: 0.3 }],
+  "w3f:territories-r2": ["plan", "territories", { radius: 2 }],
+};
+
+const GATES = { stretch: stretchGate, breakeven: breakEvenGate, ambiguity: ambiguityGate } as const;
+
+/** This function gives a highway strategy with no options: it runs `run`, with the node limit `maxNodes`. As in the screen, `follow` then gets no way options. */
+function fixedHighway(name: string, run: (input: HighwayInput) => HighwayPlan, maxNodes: number | undefined): Strategy<"highway", object> {
+  return defineStrategy({ step: "highway", name, describe: `The member ${name} of the portfolio router.`, defaults: {}, schema: {}, maxNodes: maxNodes ?? 10_000, run });
+}
+
+/** This function gives a router strategy with no options: it runs `route`. */
+function fixedRouter(name: string, route: (graph: Graph) => Result): Strategy<"router", object> {
+  return defineStrategy({ step: "router", name, describe: `The member ${name} of the portfolio router.`, defaults: {}, schema: {}, maxNodes: 10_000, run: (graph: Graph) => route(graph) });
+}
+
+/** This function gives the router strategy of a member form, with the name `name`. */
+export function memberStrategy(name: string, form: MemberForm): Strategy<"router", object> {
+  const highway = (h: Strategy<"highway", object>): Strategy<"router", object> => {
+    const r = highwayRouterStrategy(h);
+    return defineStrategy({ step: "router", name, describe: r.describe, defaults: r.defaults, ...(r.schema === undefined ? {} : { schema: r.schema }), maxNodes: r.maxNodes ?? 10_000, run: r.run });
+  };
+  switch (form[0]) {
+    case "shared": {
+      const o = form[1];
+      return fixedRouter(name, (g) => sharedRouter({ ...o, rule: byCollection, name }).route(g));
+    }
+    case "trunks": {
+      const o = form[1];
+      return fixedRouter(name, (g) => trunksRouter({ ...o, rule: byCollection, name }).route(g));
+    }
+    case "corners": {
+      const o = form[1];
+      return fixedRouter(name, (g) => cornersRouter({ ...o, name }).route(g));
+    }
+    case "highway":
+      return highway(form[1] === "shared-ways-all" ? sharedWaysAll : (highwayStrategies[form[1]] as Strategy<"highway", object>));
+    case "gate": {
+      const gated = gateStrategy(highwayStrategies[form[1]] as Strategy<"highway", object>, GATES[form[2]] as Parameters<typeof gateStrategy>[1]);
+      const budget = form[3];
+      if (budget === undefined) return highway(gated);
+      const options = { ...gated.defaults, budget };
+      return highway(fixedHighway(name, (input) => gated.run(input, options), gated.maxNodes));
+    }
+    case "plan": {
+      const base = highwayStrategies[form[1]] as Strategy<"highway", object>;
+      const options = { ...base.defaults, ...form[2] };
+      return highway(fixedHighway(name, (input) => base.run(input, options), base.maxNodes));
+    }
+  }
+}
+
+const cache = new Map<string, Strategy<"router", object>>();
+
+/** This function gives the member with the name `name`, or `undefined` for a name without a form in `MEMBER_FORMS`. */
+export function portfolioMember(name: string): Strategy<"router", object> | undefined {
+  const form = MEMBER_FORMS[name];
+  if (form === undefined) return undefined;
+  if (!cache.has(name)) cache.set(name, memberStrategy(name, form));
+  return cache.get(name);
+}

package/src/portfolio/router.ts

@@ -0,0 +1,133 @@
+// The portfolio router (PORTFOLIO-API, PORTFOLIO-FIT): it runs the base `shared` and a small greedy set of members on an input, and gives the output with the most
+// ink saved inside the rule and the stretch cap of the caller. The combinator is `portfolio` of `@mark1russell7/layout-contract`.
+// The router is opt-in: it is not in the registry `STRATEGIES`, so no default output changes.
+import { pickMoves, portfolio, type Member, type PortfolioTrace } from "../bench/screen/portfolio-pick.ts";
+import type { Graph, Result, Router } from "../model.ts";
+import { asRouter, defineStrategy, type Strategy } from "../strategies/model.ts";
+import { PORTFOLIO_CAPS, PORTFOLIO_KS_API, PORTFOLIO_RULES, portfolioBand, type PortfolioCap, type PortfolioRule } from "./bands.ts";
+import { PORTFOLIO_FIT } from "./fit.ts";
+import { portfolioKey } from "./key.ts";
+import { portfolioMember } from "./members.ts";
+import { PORTFOLIO_SETS } from "./sets.ts";
+
+/** The options of the portfolio router. */
+export interface PortfolioRouterOptions {
+  /** The rule of the caller. Under `collection` (the default), a shared segment must hold edges of one collection only. Under `all`, collections can mix. */
+  readonly rule?: PortfolioRule;
+  /** The stretch cap of the caller: 1.1, 1.25 or 1.5 (the default). An output with an edge above the cap does not win. The base is the fallback output. */
+  readonly cap?: PortfolioCap;
+  /**
+   * The count of members after the base: 3, 5 or 8. Without `k` (the default), the router runs the fit of `fit.ts`.
+   * The fit gives a member count for each rule, cap and band, and a node limit for each member. Thus the default is deterministic.
+   */
+  readonly k?: 3 | 5 | 8;
+  /**
+   * A time limit of the pick in milliseconds, as a ceiling that the caller sets. The base always runs. The combinator cuts the members that start after the limit.
+   * A cut by the budget makes the output depend on the speed of the machine. Then the trace has `deterministic: false`.
+   */
+  readonly budgetMs?: number;
+  /** The largest count of members that run, with the base. */
+  readonly maxMembers?: number;
+  /** The clock in milliseconds. The default is `performance.now`. */
+  readonly now?: () => number;
+}
+
+/** The base member of each portfolio: the router `shared` with the rule `byCollection`. It is the fallback output above the cap. */
+export const PORTFOLIO_BASE_MEMBER = "shared";
+
+/** The result of the portfolio router: the output of the winner, the winner, the trace of the pick, the move counts and the band. */
+export interface PortfolioRoute {
+  readonly result: Result;
+  readonly winner: string;
+  readonly trace: PortfolioTrace;
+  /** The move count of the pick (ACTIVATION): `{ "move.pick": 1 }` when the winner is not the base and has another output. */
+  readonly moves: Readonly<Record<string, number>>;
+  /** The size band of the input, from its node count. */
+  readonly band: string;
+  /** The names of the members, in their order. */
+  readonly members: readonly string[];
+}
+
+/** This function checks the options of the portfolio router, and gives them with their defaults. It throws a `RangeError` for a bad value. */
+function checked(o: PortfolioRouterOptions): { rule: PortfolioRule; cap: PortfolioCap; k: 3 | 5 | 8 | undefined } {
+  const rule = o.rule ?? "collection";
+  const cap = o.cap ?? 1.5;
+  const k = o.k;
+  if (!PORTFOLIO_RULES.includes(rule)) throw new RangeError(`The portfolio router has the rule "${String(rule)}". It must be ${PORTFOLIO_RULES.join(" or ")}.`);
+  if (!PORTFOLIO_CAPS.includes(cap)) throw new RangeError(`The portfolio router has the cap ${String(cap)}. It must be ${PORTFOLIO_CAPS.join(", ")}.`);
+  if (k !== undefined && !PORTFOLIO_KS_API.includes(k)) throw new RangeError(`The portfolio router has the k ${String(k)}. It must be ${PORTFOLIO_KS_API.join(", ")}.`);
+  return { rule, cap, k };
+}
+
+/** This function gives the name of the portfolio router with the options `options`: `portfolio-<rule>-<cap>-k<k>`, or `portfolio-<rule>-<cap>-fit` without `k`. */
+export function portfolioName(options: PortfolioRouterOptions = {}): string {
+  const { rule, cap, k } = checked(options);
+  return `portfolio-${rule}-${cap}-${k === undefined ? "fit" : `k${k}`}`;
+}
+
+/**
+ * This function gives the names of the members for an input with `nodes` nodes. The base comes first.
+ * - With `k`, the first `k` names of the set of the band follow.
+ * - Without `k`, the members of the fit of the band follow, each only when `nodes` is at or below its node limit.
+ */
+export function portfolioMembers(nodes: number, options: PortfolioRouterOptions = {}): string[] {
+  const { rule, cap, k } = checked(options);
+  const key: `${PortfolioRule}|${PortfolioCap}|${string}` = `${rule}|${cap}|${portfolioBand(nodes).id}`;
+  if (k === undefined) return [PORTFOLIO_BASE_MEMBER, ...(PORTFOLIO_FIT[key] ?? []).filter(([s, limit]) => s !== PORTFOLIO_BASE_MEMBER && nodes <= limit).map(([s]) => s)];
+  const set = PORTFOLIO_SETS[key] ?? [];
+  return [PORTFOLIO_BASE_MEMBER, ...set.filter((s) => s !== PORTFOLIO_BASE_MEMBER).slice(0, k)];
+}
+
+/**
+ * This function routes the graph `graph` with the portfolio of its size band, rule and cap. The base runs first, then the members in their order.
+ * The key is `portfolioKey`: a member wins only when it passes the guard against the base. Of those members, the winner has the most ink saved.
+ * A tie within the `minEffect` of B1 goes to the first member (`selectBest`). A member that throws does not win.
+ * The result carries the trace of the pick and the move count `move.pick`.
+ */
+export function routePortfolio(graph: Graph, options: PortfolioRouterOptions = {}): PortfolioRoute {
+  // A member with a node limit below the size of the graph does not run. The base `shared` has no such limit below the limit of the router.
+  const names = portfolioMembers(graph.nodes.length, options).filter((name) => name === PORTFOLIO_BASE_MEMBER || (portfolioMember(name)?.maxNodes ?? Infinity) >= graph.nodes.length);
+  const { rule, cap } = checked(options);
+  // The key compares each member with the output of the base, so the run of the base keeps its output.
+  let base: Result | undefined;
+  const members: Member<Graph, Result>[] = names.map((name) => {
+    const s = portfolioMember(name);
+    if (s === undefined) throw new Error(`The portfolio router has no member "${name}".`);
+    const router = asRouter(s);
+    if (name !== PORTFOLIO_BASE_MEMBER) return { id: name, run: (g: Graph) => router.route(g) };
+    return {
+      id: name,
+      run: (g: Graph) => {
+        base = router.route(g);
+        return base;
+      },
+    };
+  });
+  const p = portfolio(portfolioName(options), members, portfolioKey(graph, rule, cap, () => base), {
+    ...(options.budgetMs === undefined ? {} : { budgetMs: options.budgetMs }),
+    ...(options.maxMembers === undefined ? {} : { maxMembers: options.maxMembers }),
+    ...(options.now === undefined ? {} : { now: options.now }),
+  });
+  const pick = p.pick(graph);
+  const moves = Object.fromEntries(Object.entries(pickMoves(pick.trace)).map(([k, v]) => [`move.${k}`, v]));
+  return { result: pick.output, winner: pick.winner, trace: pick.trace, moves, band: portfolioBand(graph.nodes.length).id, members: names };
+}
+
+/** This function gives a router that routes each graph with `routePortfolio` and the options `options`. Its name is `portfolioName(options)`. */
+export function portfolioRouter(options: PortfolioRouterOptions = {}): Router {
+  checked(options);
+  return { name: portfolioName(options), maxNodes: 10_000, route: (graph) => routePortfolio(graph, options).result };
+}
+
+/**
+ * The portfolio router as a router strategy. It is not in the registry `STRATEGIES`, so the benchmark and the site do not race it by default.
+ * A caller adds it to a registry of its own, or calls `routePortfolio` for the trace.
+ */
+export const portfolioStrategy: Strategy<"router", PortfolioRouterOptions> = defineStrategy<"router", PortfolioRouterOptions>({
+  step: "router",
+  name: "portfolio",
+  describe: "The portfolio router (PORTFOLIO-API). It runs `shared` and the fit of the size band, and gives the output with the most ink saved inside the rule and the cap.",
+  defaults: { rule: "collection", cap: 1.5 },
+  maxNodes: 10_000,
+  run: (graph, options) => routePortfolio(graph, options).result,
+});