@mark1russell7/highways 0.9.3 → 0.9.5

package/src/strategies/schemas.ts

@@ -9,6 +9,15 @@ import type { CutOptions } from "../groups/cut/index.ts";
 import type { JustifyOptions } from "../plugs/justify.ts";
 import type { SidePlugOptions } from "../plugs/side.ts";
 import type { SpreadOptions } from "../plugs/spread/index.ts";
+import type { LeaderOptions } from "../plugs/leaders/index.ts";
+import type { BalanceOptions } from "../highways/balance/index.ts";
+import type { ManifoldOptions } from "../highways/manifolds/index.ts";
+import type { DetailOptions } from "../levels/detail/index.ts";
+import type { CurriculumOptions } from "../whole/curriculum/index.ts";
+import type { SlotOptions } from "../highways/slots/index.ts";
+import type { PreferenceOptions } from "../whole/preferences/index.ts";
+import type { FireflyOptions } from "../whole/fireflies/index.ts";
+import type { TracingOptions } from "../whole/tracing/index.ts";
 import type { KdOptions } from "../groups/kd/index.ts";
 import type { KeyOptions } from "../groups/keys/index.ts";
 import type { HighwayBase } from "../highways/base.ts";
@@ -44,6 +53,8 @@ import type { RoadClassOptions } from "../highways/road-classes/index.ts";
 import type { ScaleSpaceOptions } from "../highways/scale-space/index.ts";
 import type { GapOptions } from "../highways/gaps/index.ts";
 import type { InterchangeOptions } from "../highways/interchanges/index.ts";
+import type { KneeOptions } from "../highways/knee/index.ts";
+import type { BronchialOptions } from "../highways/bronchial/index.ts";
 import type { SearchOptions } from "../highways/search/index.ts";
 import type { SteinerOptions } from "../highways/steiner/index.ts";
 import type { StreetOptions } from "../highways/streets/index.ts";
@@ -59,6 +70,8 @@ import type { WspdOptions } from "../highways/wspd/index.ts";
 import type { ZipperOptions } from "../highways/zipper/index.ts";
 import type { LaneStretchOptions } from "../lane-orders/stretch/index.ts";
 import type { DepthLevelOptions } from "../levels/depths/index.ts";
+import type { VenationOptions } from "../levels/venation/index.ts";
+import type { BoardPortfolioOptions } from "../whole/portfolio/index.ts";
 import type { CornersOptions } from "../routers/corners.ts";
 import type { SectionsOptions } from "../routers/sections.ts";
 import type { SharedOptions } from "../routers/shared.ts";
@@ -141,6 +154,20 @@ export const CORNERS_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = {
     step: 1,
     describe: "The distance from the walls of a frame to the bounds of its inner routes. Without a value, the inset is the margin.",
   },
+  inner: {
+    type: "enum",
+    values: ["corners", "gutter"],
+    default: "corners",
+    describe: "The mode of the inner routes. With `gutter`, each inner route is orthogonal in the gaps between the nodes of the frame, with a lane in each shared gap.",
+  },
+  bendCost: {
+    type: "number",
+    min: 0,
+    max: 100,
+    step: 1,
+    default: 16,
+    describe: "The cost of one bend of an inner route of the mode `gutter`, in units of length. A larger cost gives fewer bends.",
+  },
 };
 
 /** The declarations of the options of the router `trunks`. */
@@ -1016,3 +1043,119 @@ export const INTERCHANGE_SCHEMA: OptionSchema<InterchangeOptions> = {
   discount: { type: "number", min: 0.1, max: 1, step: 0.05, marks: [0.3, 0.5, 0.7], default: 0.5, describe: "The cost of a length on a highway against a length off the highways." },
   detour: { type: "number", min: 1, max: 3, step: 0.05, marks: [1.25, 1.5, 2], default: 1.5, describe: "An edge rides the network only when its way is this many times its first route or less." },
 };
+
+/** The declarations of the options of the highway strategy `knee` (NAT-018). */
+export const KNEE_SCHEMA: OptionSchema<KneeOptions> = {
+  sweep: { type: "integer", min: 5, max: 21, step: 1, marks: [5, 11, 21], default: 11, describe: "The number of points of the sweep of the balancing factor." },
+  rule: { type: "enum", values: ["chord", "weights"], default: "chord", describe: "The rule that picks one tree: the knee of the chord, or the least weighted sum." },
+  ink: { type: "number", min: 0, max: 1, step: 0.05, marks: [0.25, 0.5, 0.75], default: 0.5, describe: "The weight of the ink in the rule `weights`. The rest of the weight goes to the path length." },
+  detour: { type: "number", min: 1, max: 3, step: 0.05, marks: [1.25, 1.5, 2], default: 1.5, describe: "An edge rides the tree only when its path in the tree is this many times its first route or less." },
+  minSize: { type: "integer", min: 2, max: 16, step: 1, default: 2, describe: "A stretch of a tree with fewer edges than this number is not a highway." },
+};
+
+/** The declarations of the options of the highway strategy `bronchial` (NAT-019). */
+export const BRONCHIAL_SCHEMA: OptionSchema<BronchialOptions> = {
+  split: { type: "enum", values: ["count", "weight", "gap"], default: "count", describe: "The rule that splits the targets of a tip in two: by count, by weight, or at the widest gap." },
+  share: { type: "number", min: 0.3, max: 0.7, step: 0.05, marks: [0.3, 0.5, 0.7], default: 0.5, describe: "The share of the distance to the center of the targets that a branch grows." },
+  smallest: { type: "integer", min: 1, max: 3, step: 1, default: 1, describe: "A set with this number of targets or fewer stops the splits." },
+  detour: { type: "number", min: 1, max: 3, step: 0.05, marks: [1.25, 1.5, 2], default: 1.5, describe: "An edge rides the tree only when its path in the tree is this many times its first route or less." },
+  minSize: { type: "integer", min: 2, max: 16, step: 1, default: 2, describe: "A stretch of a tree with fewer edges than this number is not a highway." },
+};
+
+/** The declarations of the options of the level strategy `venation` (NAT-016): the options of `depths`, and the options of the backbone. */
+export const VENATION_SCHEMA: OptionSchema<VenationOptions> = {
+  ...DEPTHS_SCHEMA,
+  backbone: { type: "enum", values: ["rng", "gabriel"], default: "rng", describe: "The graph of the backbone: the relative neighbourhood graph, or the Gabriel graph." },
+  discount: { type: "number", min: 0, max: 0.8, step: 0.05, marks: [0, 0.4, 0.8], default: 0.4, describe: "The share of the cost of a backbone link that a later level link saves when an earlier link uses it." },
+  detour: { type: "number", min: 1, max: 3, step: 0.05, marks: [1.25, 1.5, 2], default: 1.5, describe: "A level link takes its way on the backbone only when that way is this many times its direct link or less." },
+  maxItems: { type: "integer", min: 10, max: 2000, step: 10, marks: [100, 400, 1000], default: 400, describe: "A level with more items than this number keeps the links of `depths`." },
+};
+
+/** The declarations of the options of the whole strategy `board-portfolio` (WILD-045). */
+export const BOARD_PORTFOLIO_SCHEMA: OptionSchema<BoardPortfolioOptions> = {
+  settings: { type: "integer", min: 3, max: 12, step: 1, marks: [3, 4, 8, 12], default: 4, describe: "The number of settings that the portfolio tries, from the start of its list." },
+  crossings: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 1, 2], default: 1, describe: "The weight of the crossings (R1) in the score." },
+  detour: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 1, 2], default: 1, describe: "The weight of the median detour (R5) in the score." },
+  ink: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 1, 2], default: 1, describe: "The weight of the ink saved (B1) in the score." },
+  budget: { type: "number", min: 0, max: 10, step: 0.1, marks: [0, 1, 10], default: 0, describe: "The time budget in seconds. The value 0 sets no budget." },
+};
+
+/** The declarations of the options of the highway strategy `balance` (EDA-017). */
+export const BALANCE_SCHEMA: OptionSchema<BalanceOptions> = {
+  tau: { type: "number", min: 1.1, max: 2, step: 0.05, marks: [1.1, 1.2, 1.5, 2], default: 1.2, describe: "The target of the stretch of an edge: its route on the plan over its route alone." },
+  iterations: { type: "integer", min: 5, max: 30, step: 1, marks: [5, 10, 30], default: 5, describe: "The number of updates of the prices." },
+  end: { type: "enum", values: ["exit", "entry", "both"], default: "exit", describe: "The end of a ride that the price moves: the exit, the entry, or both by half." },
+  from: { ...HIGHWAY_BASE, default: "shared-ways" },
+};
+
+/** The declarations of the options of the highway strategy `manifolds` (WILD-036). */
+export const MANIFOLD_SCHEMA: OptionSchema<ManifoldOptions> = {
+  kMin: { type: "integer", min: 3, max: 8, step: 1, marks: [3, 4, 6, 8], default: 3, describe: "A manifold has this number of taps or more." },
+  band: { type: "number", min: 0.5, max: 2, step: 0.25, marks: [0.5, 1, 2], default: 1, describe: "The nodes of one row have centers in a band of this many median box heights." },
+  side: { type: "enum", values: ["near", "far"], default: "near", describe: "The place of the header in the gap before the row: near the row, or near the feed node." },
+  detour: { type: "number", min: 1, max: 3, step: 0.05, marks: [1.25, 1.5, 2], default: 1.5, describe: "A tap stays on the manifold only when its way is this many times the direct line or less." },
+  from: { ...HIGHWAY_BASE, default: "shared-ways" },
+};
+
+/** The declarations of the options of the highway strategy `slots` (RULE-047). */
+export const SLOT_SCHEMA: OptionSchema<SlotOptions> = {
+  pull: { type: "number", min: 0.25, max: 8, step: 0.25, marks: [0.5, 1, 2, 4, 8], default: 2, describe: "The weight of the pull toward the slot of a new lane." },
+  reach: { type: "number", min: 8, max: 64, step: 4, marks: [8, 16, 24, 48, 64], default: 24, describe: "A route point farther than this distance from a trunk gets no pull." },
+  laneSpacing: { type: "number", min: 2, max: 8, step: 1, marks: [2, 4, 8], default: 4, describe: "The distance between two lanes of a trunk." },
+  maxStretch: { type: "number", min: 1.05, max: 2, step: 0.05, marks: [1.1, 1.25, 1.5, 2], default: 1.25, describe: "The largest new length of a route over its first length after it joins a trunk." },
+  keys: { type: "enum", values: ["same", "any"], default: "same", describe: "The edges that can join a trunk: only the edges with the key of the trunk, or each edge." },
+  from: { ...HIGHWAY_BASE, default: "shared-ways" },
+};
+
+/** The declarations of the options of the plug strategy `leaders` (EDA-041). */
+export const LEADER_SCHEMA: OptionSchema<LeaderOptions> = {
+  leader: { type: "enum", values: ["s", "po", "opo"], default: "po", describe: "The type of leader: the order of the angles, the order along the wall, or even places." },
+  slotSpacing: { type: "number", min: 2, max: 8, step: 1, marks: [2, 4, 8], default: 8, describe: "The least gap between two plugs of one wall." },
+  inset: SPREAD_SCHEMA.inset,
+  rounds: { type: "integer", min: 0, max: 4, step: 1, default: 2, describe: "The passes that sort each wall again by the new places of the far ends." },
+};
+
+/** The declarations of the options of the level strategy `detail` (WILD-016 with EDA-038): the options of `depths`, and the limits of the collapse. */
+export const DETAIL_SCHEMA: OptionSchema<DetailOptions> = {
+  ...DEPTHS_SCHEMA,
+  pxMin: { type: "number", min: 0.5, max: 4, step: 0.5, marks: [1, 2, 3, 4], default: 3, describe: "Two parallel legs closer than this number of pixels on the screen become one stroke." },
+  minCount: { type: "integer", min: 2, max: 5, step: 1, default: 2, describe: "A stroke holds this number of edges or more." },
+  w0: { type: "number", min: 1, max: 4, step: 0.5, default: 1.5, describe: "The width of a stroke of one edge, in pixels." },
+  widthScale: { type: "enum", values: ["linear", "sqrt", "log"], default: "log", describe: "The growth of the width of a stroke with its count." },
+};
+
+/** The declarations of the options of the whole strategy `curriculum` (RULE-048). */
+export const CURRICULUM_SCHEMA: OptionSchema<CurriculumOptions> = {
+  order: { type: "enum", values: ["R1-R12-R2", "R12-R1-R2", "R1-R2-R12"], default: "R1-R12-R2", describe: "The order in which the stages add the rules." },
+  passes: { type: "integer", min: 1, max: 3, step: 1, default: 1, describe: "The number of passes over the edges in each stage." },
+  settings: { type: "integer", min: 2, max: 3, step: 1, default: 3, describe: "The number of settings in the pool of routes, from the start of its list." },
+  detour: { type: "number", min: 1.5, max: 4, step: 0.25, marks: [1.5, 2, 3], default: 2, describe: "A new route has a detour of at most this value, or of its old route." },
+};
+
+/** The declarations of the options of the whole strategy `preferences` (RULE-038). */
+export const PREFERENCE_SCHEMA: OptionSchema<PreferenceOptions> = {
+  l2: { type: "number", min: 0, max: 1, step: 0.01, marks: [0, 0.01, 0.1, 1], default: 0.01, describe: "The weight of the L2 term of the fit of the weights to the made-up pairs." },
+  passes: { type: "integer", min: 1, max: 3, step: 1, default: 1, describe: "The number of passes over the edges." },
+  settings: { type: "integer", min: 2, max: 3, step: 1, default: 3, describe: "The number of settings in the pool of routes, from the start of its list." },
+  detour: { type: "number", min: 1.5, max: 4, step: 0.25, marks: [1.5, 2, 3], default: 2, describe: "A new route has a detour of at most this value, or of its old route." },
+};
+
+/** The declarations of the options of the whole strategy `fireflies` (NAT-047). */
+export const FIREFLY_SCHEMA: OptionSchema<FireflyOptions> = {
+  search: { type: "enum", values: ["firefly", "bees"], default: "firefly", describe: "The search: the firefly algorithm, or the artificial bee colony." },
+  budget: { type: "integer", min: 4, max: 40, step: 1, marks: [4, 12, 20, 40], default: 12, describe: "The largest number of different settings that the search routes." },
+  colony: { type: "integer", min: 4, max: 20, step: 1, marks: [4, 6, 10, 20], default: 6, describe: "The number of fireflies or food sources." },
+  gamma: { type: "number", min: 0.01, max: 10, step: 0.01, scale: "log", marks: [0.01, 0.1, 1, 10], default: 1, describe: "The absorption of the light of a firefly." },
+  alpha: { type: "number", min: 0.01, max: 0.5, step: 0.01, marks: [0.01, 0.1, 0.2, 0.5], default: 0.2, describe: "The size of the random step of a firefly, as a share of the range." },
+  limit: { type: "integer", min: 10, max: 100, step: 10, marks: [10, 50, 100], default: 10, describe: "A scout bee leaves a food source after this number of tries with no gain." },
+  seed: { type: "integer", min: 0, max: 1_000_000, step: 1, marks: [1, 2, 3], default: 1, describe: "The seed of the search. The same seed gives the same routes." },
+};
+
+/** The declarations of the options of the whole strategy `tracing` (WILD-057). */
+export const TRACING_SCHEMA: OptionSchema<TracingOptions> = {
+  crossing: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 1, 2, 4], default: 1, describe: "The weight of a crossing in the tracing load." },
+  merge: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 1, 2, 4], default: 2, describe: "The weight of a merge or a split where the edge is not an outer lane." },
+  bend: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 0.5, 1, 4], default: 0.5, describe: "The weight of a bend in the tracing load." },
+  settings: { type: "integer", min: 1, max: 12, step: 1, marks: [1, 4, 8, 12], default: 4, describe: "The number of settings that the strategy tries, from the start of its list." },
+  quantile: { type: "enum", values: ["q50", "q95", "mean"], default: "q95", describe: "The value of the loads of the edges that the pick reads." },
+};

package/src/whole/curriculum/index.ts

@@ -0,0 +1,243 @@
+import { checkProperties } from "../../bench/properties.ts";
+import { dist, polylineLength, segmentsCross, type Point } from "../../geom.ts";
+import type { Graph, Route } from "../../model.ts";
+import type { WholeOutput } from "../../strategies/model.ts";
+import { runPipeline } from "../pipeline/index.ts";
+import type { PortfolioSetting } from "../portfolio/index.ts";
+
+/** One rule of the curriculum: the crossings (R1), the lane separation (R12) or the crossing angle (R2). */
+export type CurriculumRule = "R1" | "R12" | "R2";
+
+/** The order in which the curriculum adds its rules. */
+export type CurriculumOrder = "R1-R12-R2" | "R12-R1-R2" | "R1-R2-R12";
+
+/** The values of `CurriculumOrder`. */
+export const CURRICULUM_ORDERS: readonly CurriculumOrder[] = Object.freeze(["R1-R12-R2", "R12-R1-R2", "R1-R2-R12"]);
+
+/** The options of the whole strategy `curriculum` (RULE-048). */
+export interface CurriculumOptions {
+  /** The order in which the stages add the rules. The default is `R1-R12-R2`. */
+  readonly order: CurriculumOrder;
+  /** The number of passes over the edges in each stage, from 1 to 3. The default is 1. */
+  readonly passes: number;
+  /** The number of settings in the pool of routes, from the start of its list, from 2 to 3. The default is 3. */
+  readonly settings: number;
+  /** A new route has a detour of at most this value, or of its old route, from 1.5 to 4. The default is 2. */
+  readonly detour: number;
+}
+
+/** The default options of the strategy `curriculum`. */
+export const CURRICULUM_DEFAULTS: Readonly<CurriculumOptions> = Object.freeze({ order: "R1-R12-R2", passes: 1, settings: 3, detour: 2 });
+
+/** Two legs closer than this distance count for the lane separation (R12), as in the screen. */
+const NEAR = 4;
+
+/** A route with its bounding box, for the quick test of two routes. */
+interface Shape {
+  readonly route: Route;
+  readonly x0: number;
+  readonly y0: number;
+  readonly x1: number;
+  readonly y1: number;
+}
+
+/** This function gives the shape of a route. */
+function shapeOf(route: Route): Shape {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const p of route.points) {
+    x0 = Math.min(x0, p.x);
+    y0 = Math.min(y0, p.y);
+    x1 = Math.max(x1, p.x);
+    y1 = Math.max(y1, p.y);
+  }
+  return { route, x0, y0, x1, y1 };
+}
+
+/** The sine of 5 degrees, as a literal. A literal gives the same bits on each platform, so a decision does not depend on `Math.sin`. */
+const SIN_5 = 0.08715574274765817;
+
+/** The constants of the arc sine of fdlibm (`e_asin.c`). */
+const PIO2_HI = 1.5707963267948966;
+const PIO2_LO = 6.123233995736766e-17;
+const PIO4_HI = 0.7853981633974483;
+const PS = [1.66666666666666657415e-1, -3.25565818622400915405e-1, 2.01212532134862925881e-1, -4.00555345006794114027e-2, 7.91534994289814532176e-4, 3.47933107596021167570e-5] as const;
+const QS = [-2.40339491173441421878, 2.02094576023350569471, -6.88283971605453293030e-1, 7.70381505559019352791e-2] as const;
+const WORDS = new DataView(new ArrayBuffer(8));
+
+/** This function gives the rational part `p / q` of the arc sine of fdlibm at `t`. */
+function asinRatio(t: number): [number, number] {
+  const p = t * (PS[0] + t * (PS[1] + t * (PS[2] + t * (PS[3] + t * (PS[4] + t * PS[5])))));
+  const q = 1 + t * (QS[0] + t * (QS[1] + t * (QS[2] + t * QS[3])));
+  return [p, q];
+}
+
+/**
+ * This function gives the arc sine of `x` in radians, from -1 to 1. It is the algorithm of fdlibm, with only `+`, `*`, `/` and `Math.sqrt`.
+ * These operations are exact to the last bit on each platform, so the result does not depend on the engine.
+ */
+export function arcsin(x: number): number {
+  const ax = Math.abs(x);
+  if (Number.isNaN(x) || ax > 1) return Number.NaN;
+  if (ax === 1) return x * PIO2_HI + x * PIO2_LO;
+  if (ax < 0.5) {
+    if (ax < 2 ** -27) return x;
+    const [p, q] = asinRatio(x * x);
+    return x + x * (p / q);
+  }
+  const t = (1 - ax) * 0.5;
+  const [p, q] = asinRatio(t);
+  const s = Math.sqrt(t);
+  let r: number;
+  WORDS.setFloat64(0, ax);
+  if (WORDS.getUint32(0) >= 0x3fef3333) {
+    r = PIO2_HI - (2 * (s + s * (p / q)) - PIO2_LO);
+  } else {
+    WORDS.setFloat64(0, s);
+    WORDS.setUint32(4, 0);
+    const w = WORDS.getFloat64(0);
+    const c = (t - w * w) / (s + w);
+    const pp = 2 * s * (p / q) - (PIO2_LO - 2 * c);
+    const qq = PIO4_HI - 2 * w;
+    r = PIO4_HI - (pp - qq);
+  }
+  return x > 0 ? r : -r;
+}
+
+/** This function gives the distance between the segments `ab` and `cd`, when they do not cross. */
+function segmentGap(a: Point, b: Point, c: Point, d: Point): number {
+  const at = (p: Point, u: Point, v: Point): number => {
+    const dx = v.x - u.x;
+    const dy = v.y - u.y;
+    const l2 = dx * dx + dy * dy;
+    const t = l2 > 0 ? Math.max(0, Math.min(1, ((p.x - u.x) * dx + (p.y - u.y) * dy) / l2)) : 0;
+    const ex = p.x - u.x - t * dx;
+    const ey = p.y - u.y - t * dy;
+    return Math.sqrt(ex * ex + ey * ey);
+  };
+  return Math.min(at(a, c, d), at(b, c, d), at(c, a, b), at(d, a, b));
+}
+
+/**
+ * This function gives the costs of the rules between two routes. R1 is the number of crossings.
+ * R2 is the sum of `1 - θ / 90` over the crossings. θ is the crossing angle in degrees.
+ * R12 is the overlap of the legs of `a` and `b` that are within 5 degrees of parallel. The two legs are nearer than 4 units.
+ */
+export function pairCosts(a: readonly Point[], b: readonly Point[]): Record<CurriculumRule, number> {
+  let r1 = 0;
+  let r2 = 0;
+  let r12 = 0;
+  for (let i = 1; i < a.length; i++) {
+    const p = a[i - 1]!;
+    const q = a[i]!;
+    const ux = q.x - p.x;
+    const uy = q.y - p.y;
+    const lu = Math.sqrt(ux * ux + uy * uy);
+    if (lu <= 1e-9) continue;
+    for (let j = 1; j < b.length; j++) {
+      const r = b[j - 1]!;
+      const s = b[j]!;
+      const vx = s.x - r.x;
+      const vy = s.y - r.y;
+      const lv = Math.sqrt(vx * vx + vy * vy);
+      if (lv <= 1e-9) continue;
+      if (segmentsCross(p, q, r, s)) {
+        r1++;
+        const angle = (arcsin(Math.min(1, Math.abs(ux * vy - uy * vx) / (lu * lv))) * 180) / Math.PI;
+        r2 += 1 - angle / 90;
+        continue;
+      }
+      if (Math.abs(ux * vy - uy * vx) > SIN_5 * lu * lv) continue;
+      const t0 = ((r.x - p.x) * ux + (r.y - p.y) * uy) / lu;
+      const t1 = ((s.x - p.x) * ux + (s.y - p.y) * uy) / lu;
+      const overlap = Math.min(lu, Math.max(t0, t1)) - Math.max(0, Math.min(t0, t1));
+      if (overlap > 1e-9 && segmentGap(p, q, r, s) < NEAR) r12 += overlap;
+    }
+  }
+  return { R1: r1, R2: r2, R12: r12 };
+}
+
+/** This function gives the detour of a route: its length over the distance between its ends. */
+function detourOf(points: readonly Point[]): number {
+  const span = dist(points[0]!, points[points.length - 1]!);
+  return span > 1e-9 ? polylineLength(points) / span : 1;
+}
+
+/**
+ * This function runs the whole strategy `curriculum` (RULE-048, after curriculum learning, Bengio 2009). The record has no energy solver yet (RULE-019).
+ * Thus a pool of routes of fixed settings takes its place. Each edge can take its route from any setting of the pool.
+ * The first answer is the first setting. Each stage adds one rule, in the order `order`. A pass of a stage visits the edges, the worst first.
+ * An edge takes the route of the pool with the least cost of the new rule. That cost is lower, and the earlier rules do not get worse.
+ * A route with a break of a hard rule is not in the pool. The output has the routes alone, with no runs, bundles or levels.
+ */
+export function curriculum(graph: Graph, list: readonly PortfolioSetting[], options: Partial<CurriculumOptions> = {}): WholeOutput {
+  const o = { ...CURRICULUM_DEFAULTS, ...options };
+  const count = Math.max(1, Math.min(list.length, Math.floor(o.settings)));
+  const pool = new Map<string, Route[]>();
+  let first: WholeOutput | undefined;
+  for (const s of list.slice(0, count)) {
+    const limit = (s.pipeline.highway ?? s.pipeline.router).maxNodes;
+    if (limit !== undefined && graph.nodes.length > limit) continue;
+    const output = runPipeline(graph, s.pipeline);
+    first ??= output;
+    const faulty = new Set(checkProperties(output.graph, output.result, 1_000_000).map((v) => v.edge));
+    for (const r of output.result.routes) {
+      if (faulty.has(r.edge) || r.points.length < 2) continue;
+      const list2 = pool.get(r.edge);
+      if (list2) list2.push(r);
+      else pool.set(r.edge, [r]);
+    }
+  }
+  if (!first) return runPipeline(graph, list[0]!.pipeline);
+  const rules = o.order.split("-") as CurriculumRule[];
+  const current = new Map<string, Shape>(first.result.routes.map((r) => [r.edge, shapeOf(r)]));
+  // A faulty first route takes the first route of the pool, so no stage starts from a break of a hard rule.
+  for (const [edge, shape] of current) {
+    const own = pool.get(edge);
+    if (own && !own.includes(shape.route)) current.set(edge, shapeOf(own[0]!));
+  }
+  const costOf = (edge: string, s: Shape): Record<CurriculumRule, number> => {
+    const sum = { R1: 0, R2: 0, R12: 0 };
+    for (const [other, t] of current) {
+      if (other === edge || t.x0 > s.x1 + NEAR || t.x1 < s.x0 - NEAR || t.y0 > s.y1 + NEAR || t.y1 < s.y0 - NEAR) continue;
+      const c = pairCosts(s.route.points, t.route.points);
+      sum.R1 += c.R1;
+      sum.R2 += c.R2;
+      sum.R12 += c.R12;
+    }
+    return sum;
+  };
+  const edges = [...current.keys()];
+  for (let stage = 0; stage < rules.length; stage++) {
+    const rule = rules[stage]!;
+    const earlier = rules.slice(0, stage);
+    for (let pass = 0; pass < Math.max(1, Math.floor(o.passes)); pass++) {
+      const costs = new Map(edges.map((e) => [e, costOf(e, current.get(e)!)]));
+      const order = [...edges].sort((a, b) => costs.get(b)![rule] - costs.get(a)![rule] || (a < b ? -1 : a > b ? 1 : 0));
+      let moved = 0;
+      for (const edge of order) {
+        const now = current.get(edge)!;
+        const base = costOf(edge, now);
+        if (base[rule] <= 1e-9) continue;
+        const cap = Math.max(o.detour, detourOf(now.route.points));
+        let best: { shape: Shape; cost: number } | undefined;
+        for (const r of pool.get(edge) ?? []) {
+          if (r === now.route || detourOf(r.points) > cap + 1e-9) continue;
+          const shape = shapeOf(r);
+          const c = costOf(edge, shape);
+          if (c[rule] >= base[rule] - 1e-9 || earlier.some((k) => c[k] > base[k] + 1e-9)) continue;
+          if (!best || c[rule] < best.cost - 1e-9) best = { shape, cost: c[rule] };
+        }
+        if (best) {
+          current.set(edge, best.shape);
+          moved++;
+        }
+      }
+      if (moved === 0) break;
+    }
+  }
+  const routes = first.result.routes.map((r) => current.get(r.edge)?.route ?? r);
+  return { graph: first.graph, result: { routes } };
+}

package/src/whole/fireflies/index.ts

@@ -0,0 +1,177 @@
+import { inkSaved } from "../../bench/measures/bundles.ts";
+import { detourSpread } from "../../bench/measures/routes.ts";
+import { checkProperties } from "../../bench/properties.ts";
+import { measureQuality } from "../../bench/quality.ts";
+import { rng } from "../../fixtures.ts";
+import type { Graph } from "../../model.ts";
+import type { Strategy, WholeOutput } from "../../strategies/model.ts";
+import { runPipeline } from "../pipeline/index.ts";
+
+/** The search of the whole strategy `fireflies`: the firefly algorithm, or the artificial bee colony. */
+export type SwarmSearch = "firefly" | "bees";
+
+/** The values of `SwarmSearch`. */
+export const SWARM_SEARCHES: readonly SwarmSearch[] = Object.freeze(["firefly", "bees"]);
+
+/** The options of the whole strategy `fireflies` (NAT-047). */
+export interface FireflyOptions {
+  /** The search. The default is `firefly`. */
+  readonly search: SwarmSearch;
+  /** The budget: the largest number of different settings that the search routes, from 4 to 40. The default is 12. */
+  readonly budget: number;
+  /** The number of fireflies or food sources, from 4 to 20. The default is 6. */
+  readonly colony: number;
+  /** The absorption `gamma` of the light of a firefly, from 0.01 to 10. The default is 1. */
+  readonly gamma: number;
+  /** The size `alpha` of the random step of a firefly, as a share of the range, from 0.01 to 0.5. The default is 0.2. */
+  readonly alpha: number;
+  /** The number of tries with no gain, after which a scout bee leaves a food source, from 10 to 100. The default is 10. */
+  readonly limit: number;
+  /** The seed of the search, a whole number from 0. The same seed gives the same routes. The default is 1. */
+  readonly seed: number;
+}
+
+/** The default options of the strategy `fireflies`. */
+export const FIREFLY_DEFAULTS: Readonly<FireflyOptions> = Object.freeze({ search: "firefly", budget: 12, colony: 6, gamma: 1, alpha: 0.2, limit: 10, seed: 1 });
+
+/** The attraction of a firefly at the distance 0, as the record gives it. */
+const BETA0 = 1;
+
+/** The grid of the option `discount` of the router `shared`: 0.05 to 1 in steps of 0.05. */
+const DISCOUNTS = 20;
+
+/** The grid of the option `margin` of the router `shared`: 3 to 10 in steps of 1. */
+const MARGINS = 8;
+
+/** The largest number of rounds of a search. A round with no new setting still counts. */
+const ROUNDS = 60;
+
+/**
+ * This function gives the attraction of a firefly at the distance `r`: `BETA0 / (1 + u + u² / 2)` with `u = gamma × r²`.
+ * It is a rational stand-in for `BETA0 × exp(-u)`, with only `+`, `*` and `/`, so it is exact to the last bit on each platform.
+ */
+export function attraction(gamma: number, r2: number): number {
+  const u = gamma * r2;
+  return BETA0 / (1 + u + (u * u) / 2);
+}
+
+/** One setting of the router `shared`: the option `discount` and the option `margin`. */
+export interface SwarmSetting {
+  readonly discount: number;
+  readonly margin: number;
+}
+
+/** This function gives the setting of a point of the unit square, on the grid of the search. */
+export function settingAt(x: number, y: number): SwarmSetting {
+  const i = Math.max(0, Math.min(DISCOUNTS - 1, Math.round(x * (DISCOUNTS - 1))));
+  const j = Math.max(0, Math.min(MARGINS - 1, Math.round(y * (MARGINS - 1))));
+  return { discount: (i + 1) / 20, margin: 3 + j };
+}
+
+/** The point of the unit square of the defaults of `shared`: the discount 0.5 and the margin 5. */
+const HOME: readonly [number, number] = [9 / (DISCOUNTS - 1), 2 / (MARGINS - 1)];
+
+/** One setting that the search routed: its score and its output. A setting with a break of a hard rule has the score `Infinity`. */
+export interface SwarmEntry {
+  readonly setting: SwarmSetting;
+  readonly score: number;
+  readonly output: WholeOutput;
+}
+
+/** The result of `fireflies`: the output, the best setting and each setting that the search routed, in order. */
+export interface SwarmRun {
+  readonly output: WholeOutput;
+  readonly best: SwarmSetting;
+  readonly entries: readonly SwarmEntry[];
+}
+
+/**
+ * This function gives the score of an output on its board. A lower score is better.
+ * The score is `crossings / edges + (median detour - 1) - ink saved`. A break of a hard rule gives `Infinity`.
+ */
+export function swarmScore(output: WholeOutput): number {
+  if (checkProperties(output.graph, output.result, 1).length > 0) return Infinity;
+  const edges = Math.max(1, output.result.routes.length);
+  return measureQuality(output.graph, output.result).crossings / edges + (detourSpread(output.result.routes).median - 1) - inkSaved(output.result.routes);
+}
+
+/**
+ * This function runs the whole strategy `fireflies` (NAT-047, after the firefly algorithm of Yang 2008 and the bee colony of Karaboga 2005).
+ * It searches the options `discount` and `margin` of the router `router` on the board, on a grid of 20 × 8 settings.
+ * The first firefly or food source is the default setting, so the score of the output is not worse than the score of the default.
+ * A firefly moves toward each brighter one by `attraction(gamma, r²)` of the distance, plus a seeded step of size `alpha`.
+ * A bee tries `v = x + phi (x - x_k)` in one dimension, and a scout takes a new seeded place after `limit` tries with no gain.
+ * The search stops after `budget` different settings, or after 60 rounds. It reads only the board and the outputs of its own settings.
+ */
+export function fireflies(graph: Graph, router: Strategy<"router">, options: Partial<FireflyOptions> = {}): SwarmRun {
+  const o = { ...FIREFLY_DEFAULTS, ...options };
+  const budget = Math.max(1, Math.floor(o.budget));
+  const random = rng(Math.max(0, Math.floor(o.seed)));
+  const known = new Map<string, SwarmEntry>();
+  const entries: SwarmEntry[] = [];
+  const score = (x: number, y: number): number => {
+    const setting = settingAt(x, y);
+    const key = `${setting.discount}:${setting.margin}`;
+    const seen = known.get(key);
+    if (seen) return seen.score;
+    if (entries.length >= budget) return Infinity;
+    const output = runPipeline(graph, { router, routerOptions: { ...setting } });
+    const entry = { setting, score: swarmScore(output), output };
+    known.set(key, entry);
+    entries.push(entry);
+    return entry.score;
+  };
+  const clamp = (v: number): number => Math.max(0, Math.min(1, v));
+  const colony = Math.max(2, Math.min(20, Math.floor(o.colony)));
+  const xs: [number, number][] = [[HOME[0], HOME[1]]];
+  while (xs.length < colony) xs.push([random(), random()]);
+  const fs = xs.map(([x, y]) => score(x, y));
+  if (o.search === "firefly") {
+    for (let round = 0; round < ROUNDS && entries.length < budget; round++) {
+      for (let i = 0; i < colony; i++) {
+        for (let j = 0; j < colony; j++) {
+          if (!(fs[j]! < fs[i]!)) continue;
+          const dx = xs[j]![0] - xs[i]![0];
+          const dy = xs[j]![1] - xs[i]![1];
+          const b = attraction(o.gamma, dx * dx + dy * dy);
+          xs[i] = [clamp(xs[i]![0] + b * dx + o.alpha * (random() - 0.5)), clamp(xs[i]![1] + b * dy + o.alpha * (random() - 0.5))];
+          fs[i] = score(xs[i]![0], xs[i]![1]);
+        }
+      }
+    }
+  } else {
+    const trials = new Array<number>(colony).fill(0);
+    const tryNear = (i: number): void => {
+      let k = Math.floor(random() * (colony - 1));
+      if (k >= i) k++;
+      const d = random() < 0.5 ? 0 : 1;
+      const phi = 2 * random() - 1;
+      const v: [number, number] = [xs[i]![0], xs[i]![1]];
+      v[d] = clamp(v[d] + phi * (v[d] - xs[k]![d]));
+      const f = score(v[0], v[1]);
+      if (f < fs[i]!) {
+        xs[i] = v;
+        fs[i] = f;
+        trials[i] = 0;
+      } else trials[i]!++;
+    };
+    for (let round = 0; round < ROUNDS && entries.length < budget; round++) {
+      for (let i = 0; i < colony; i++) tryNear(i);
+      // The onlooker bees go to the sources by rank: the best source gets the most visits.
+      const order = xs.map((_, i) => i).sort((a, b) => fs[a]! - fs[b]! || a - b);
+      for (let r = 0; r < colony; r++) {
+        const pick = order[Math.min(colony - 1, Math.floor(random() * random() * colony))]!;
+        tryNear(pick);
+      }
+      const worn = trials.findIndex((t, i) => t > o.limit && fs[i]! !== Math.min(...fs));
+      if (worn >= 0) {
+        xs[worn] = [random(), random()];
+        fs[worn] = score(xs[worn]![0], xs[worn]![1]);
+        trials[worn] = 0;
+      }
+    }
+  }
+  let best = entries[0]!;
+  for (const e of entries) if (e.score < best.score - 1e-12) best = e;
+  return { output: best.output, best: best.setting, entries };
+}