@mark1russell7/highways 0.4.2 → 0.5.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,
+});

package/src/portfolio/sets.ts

@@ -0,0 +1,28 @@
+// 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 records come from the CI runs 40631516113, 40644555345, 40644557536, 40644560237, 40644562652, 40644565132, 40644567956, 40644570455, 40644572910, 40644575649, 40644578541, 40644580965, 40644583603.
+import type { PortfolioCap, PortfolioRule } from "./bands.ts";
+
+/**
+ * The greedy set of each rule, cap and size band, by the key `<rule>|<cap>|<band>`. The set of k strategies is the first k names.
+ * Each set comes from the train seeds (0 to 4) of its band. The base `shared` is not in a set: the portfolio always runs it first.
+ */
+export const PORTFOLIO_SETS: Readonly<Record<`${PortfolioRule}|${PortfolioCap}|${string}`, readonly string[]>> = {
+  "collection|1.1|n1-12": ["corners-side", "w2c:select+stretch", "trunks-gilbert-a05", "w3a:spiral-a15", "trunks-tree-bf08", "hw:zipper", "w2c:level-links+stretch-b1.1", "hw:stubs"],
+  "collection|1.1|n13-24": ["w3e:crossbars+stretch", "corners-side", "shared-p2", "w2c:zipper+stretch-b1.1", "trunks-tree-bf08", "hw:weiszfeld", "trunks-gilbert-a07", "hw:stubs"],
+  "collection|1.1|n25-40": ["w2a:shared-ways+breakeven", "w2b:weiszfeld-a1", "w2c:level-links+stretch-b1.1"],
+  "collection|1.25|n1-12": ["corners-side", "trunks-tree-bf06", "w3f:p-hub-a0.2", "hw:stubs", "hw:p-hub", "hw:spiral", "w2c:level-links+stretch", "w3f:spectral-c0.3"],
+  "collection|1.25|n13-24": ["w2a:shared-ways+stretch", "shared-p3", "trunks-gilbert-a07", "w3e:crossbars+stretch", "trunks-tree-bf06", "w3c:hdbscan+stretch", "shared-wind-p2-r1-e2", "hw:stubs"],
+  "collection|1.25|n25-40": ["w2a:shared-ways+stretch", "shared-p3", "shared-order-shortest", "w2b:weiszfeld-a1", "w3e:crossbars+stretch", "trunks-tree-bf08", "w2a:shared-ways+ambiguity", "w2b:weiszfeld-a0"],
+  "collection|1.5|n1-12": ["trunks-gilbert-a03", "w3e:areas-keys", "trunks-tree-bf02", "w3f:p-hub-a0.2", "w2b:zipper-a1", "w3a:spiral-a35", "w3f:spectral-c0.3", "w2c:level-links+stretch"],
+  "collection|1.5|n13-24": ["shared-wind-p2-r0.5", "trunks-gilbert-a03", "w3e:crossbars+stretch", "shared-wind-p2-r1-e2", "trunks-tree-bf06", "shared-flow-a06-p3", "shared-wind-p3-r1", "trunks-gilbert-a07"],
+  "collection|1.5|n25-40": ["shared-p3", "hw:lanes", "shared-wind-p2-r1-e2", "hw:crossbars", "shared-flow-a06-p3", "trunks-tree-bf06", "shared-wind-p2-r1", "shared-wind-p2-r2"],
+  "all|1.1|n1-12": ["w2b:zipper-p2", "hw:cubu", "w3d:kdeeb+stretch", "w3c:hough-wide", "w3d:kdeeb-routes", "hw:stubs", "hw:spiral", "w3b:growth-s0.7"],
+  "all|1.1|n13-24": ["w3e:frechet-e0.5", "w3a:diffusion-wide", "w2c:zipper+stretch-b1.1", "w3d:cubu+stretch", "w3a:spiral-a15", "w3d:kdeeb-routes", "hw:diffusion", "hw:mesh"],
+  "all|1.1|n25-40": ["w2c:zipper+stretch-b1.1", "w3a:spiral-a15", "w3d:mesh+stretch", "w3a:diffusion+stretch", "w3a:diffusion-wide", "w2c:road-classes-d0.3", "w3d:kdeeb-routes"],
+  "all|1.25|n1-12": ["w3d:kdeeb-routes", "w3e:mlseb+stretch", "hw:growth", "hw:level-links", "w3b:growth-input", "w3e:confluent+stretch", "w3d:kdeeb-nomask", "w3a:diffusion-g2"],
+  "all|1.25|n13-24": ["w3d:kdeeb-routes", "w3e:mlseb+stretch", "w3f:p-hub-a0.2", "w3a:spiral-n3", "w3a:diffusion-l3", "trunks-tree-bf06", "hw:cubu", "w3a:spiral-a35"],
+  "all|1.25|n25-40": ["w3d:kdeeb-routes", "hw:spiral", "hw:shared-ways-all", "w3a:diffusion-g2", "w3e:frechet+stretch", "hw:cubu"],
+  "all|1.5|n1-12": ["w3b:growth-s0.3", "w3e:mlseb-a0", "w3e:mlseb-routes", "w3c:edge-paths-k1.5", "w3f:territories-r2", "hw:mlseb", "hw:growth", "w3e:mlseb-parabola"],
+  "all|1.5|n13-24": ["hw:growth", "w3b:growth-input", "hw:mlseb", "w3e:mlseb+stretch", "w3b:growth-s0.3"],
+  "all|1.5|n25-40": ["hw:growth", "w3b:growth-s0.7", "w3b:growth-s0.3", "w3b:growth-t1.2", "w3b:growth-input"],
+};

package/src/routers/shared.ts

@@ -1,5 +1,6 @@
 import { center, dist, type Point } from "../geom.ts";
 import { nodeIndex, type Edge, type Graph, type GroupRule, type Result, type Route, type Router, type SharedRun } from "../model.ts";
+import { channelWidth } from "../channels.ts";
 import { placePlug, type Plug } from "../plugs.ts";
 import { buildSections, type Section } from "../sections.ts";
 import { orderLanes, type RunOrder } from "../segments.ts";
@@ -44,6 +45,20 @@ export interface SharedOptions extends WayOptions {
    * With `snell`, the route meets the run at the angle `acos(d)`, with `d` the cost share of the run for the route (NAT-035).
    */
   readonly merge?: ShareMerge;
+  /**
+   * The pull of the busy links of the pass before (HWY-005, Winding Roads). With a value above 0 and two passes or more, each later pass routes each edge again from no ways.
+   * A link then costs `len / (1 + reuse * u)^reuseExponent`, with `u` the edges of the key on it in the pass before. The default is 0: the later passes are rip-up passes.
+   */
+  readonly reuse?: number;
+  /** The exponent of the pull of `reuse`. The default is 1. */
+  readonly reuseExponent?: number;
+  /**
+   * The cost of a lane that does not fit in its channel (HWY-016). One more edge on a link with `f` edges of the key costs `capacity * max(0, (f + 1) * laneWidth - width)` more.
+   * `width` is the free space across the link (`channelWidth`). The default is 0: the router does not read the channels.
+   */
+  readonly capacity?: number;
+  /** The width of one lane, for `capacity`. The default is 4. */
+  readonly laneWidth?: number;
   /** The benchmark skips a fixture with more nodes. */
   readonly maxNodes?: number;
 }
@@ -94,6 +109,10 @@ export function sharedRouter(options: SharedOptions): Router {
   // The cost share of a link for one more edge, when `f` edges of the key use it already. The share falls when `f` grows.
   const share = (f: number): number => (f <= 0 ? 1 : flow ? (f + 1) ** alpha - f ** alpha : discount);
   const passes = Math.max(1, Math.floor(options.passes ?? 1));
+  const reuse = Math.max(0, options.reuse ?? 0);
+  const reuseExponent = Math.max(0, options.reuseExponent ?? 1);
+  const capacity = Math.max(0, options.capacity ?? 0);
+  const laneWidth = Math.max(0, options.laneWidth ?? 4);
   const keyOf = (e: Edge): string => {
     if (!options.rule) return "*";
     return options.rule(e) ?? `\u0000${e.id}`;
@@ -131,14 +150,34 @@ export function sharedRouter(options: SharedOptions): Router {
       const order = orderWays(all, options.order ?? "span", graph);
       // The largest number of edges on one link of each key. The cost share of that number is the floor of the search.
       const top = new Map<string, number>();
-      const route = (w: Way): void => {
+      // The width of the channel of each link, for the option `capacity`. Each link gets its width at its first use.
+      const widths = new Map<number, number>();
+      const widthOf = (i: number, j: number): number => {
+        const k = link(i, j);
+        let wd = widths.get(k);
+        if (wd === undefined) widths.set(k, (wd = channelWidth(ways.obstacles, corners.points[i]!, corners.points[j]!)));
+        return wd;
+      };
+      /** This function routes one way. `before` holds the edges of the key on each link in the pass before, for the option `reuse`. */
+      const route = (w: Way, before?: ReadonlyMap<number, number>): void => {
         let used = discounted.get(w.key);
         if (!used) discounted.set(w.key, (used = new Map()));
         const mine = used;
-        const floor = flow ? share(top.get(w.key) ?? 0) : discount;
-        const cost = flow
+        let floor = flow ? share(top.get(w.key) ?? 0) : discount;
+        let cost = flow
           ? (i: number, j: number, d: number): number => d * share(mine.get(link(i, j))?.length ?? 0)
           : (i: number, j: number, d: number): number => (mine.has(link(i, j)) ? d * discount : d);
+        if (capacity > 0) {
+          const plain = cost;
+          cost = (i, j, d) => plain(i, j, d) + capacity * Math.max(0, ((mine.get(link(i, j))?.length ?? 0) + 1) * laneWidth - widthOf(i, j));
+        }
+        if (before !== undefined) {
+          const plain = cost;
+          let most = 0;
+          for (const u of before.values()) most = Math.max(most, u);
+          cost = (i, j, d) => plain(i, j, d) / (1 + reuse * (before.get(link(i, j)) ?? 0)) ** reuseExponent;
+          floor /= (1 + reuse * most) ** reuseExponent;
+        }
         const way = corners.path(ways.out(w.ps), ways.out(w.pt), cost, floor);
         if (!way) return;
         w.found = true;
@@ -157,6 +196,20 @@ export function sharedRouter(options: SharedOptions): Router {
       for (const w of order) route(w);
       // Each later pass takes each edge off its links and finds its way again, with the ways of the other edges fixed.
       for (let pass = 1; pass < passes; pass++) {
+        if (reuse > 0) {
+          // Winding Roads (HWY-005): each edge finds its way again from no ways, and the busy links of the pass before pull it.
+          const before = new Map<string, Map<number, number>>();
+          for (const [key, links] of discounted) before.set(key, new Map([...links].map(([k, list]) => [k, list.length])));
+          discounted.clear();
+          top.clear();
+          for (const w of order) {
+            w.found = false;
+            w.seq = [];
+            w.ids = [];
+          }
+          for (const w of order) route(w, before.get(w.key) ?? new Map());
+          continue;
+        }
         for (const w of order) {
           if (!w.found) continue;
           const mine = discounted.get(w.key)!;