@mark1russell7/highways 0.9.4 → 0.9.5

package/src/plugs/leaders/index.ts

@@ -0,0 +1,42 @@
+/**
+ * The plug strategy `leaders` (EDA-041): boundary leaders of the labeling of maps, used as the stubs of the plugs.
+ * Each wall places its plugs in an order that gives leaders with no crossing, and the least length of the leaders.
+ */
+import type { PlugInput, PlugPair } from "../../strategies/model.ts";
+import { spreadWith, SPREAD_DEFAULTS } from "../spread/index.ts";
+
+/**
+ * The type of leader of a plug. With `s`, the order of a wall is the order of the angles of the far ends, as in `spread`.
+ * With `po`, the stub leaves along the normal and turns once, so the order is the order of the far ends along the wall.
+ * With `opo`, the plugs of a wall go at even places, in the order of the angles.
+ */
+export type LeaderType = "s" | "po" | "opo";
+
+/** The values of `LeaderType`. */
+export const LEADER_TYPES: readonly LeaderType[] = Object.freeze(["s", "po", "opo"]);
+
+/** The options of the plug strategy `leaders`. */
+export interface LeaderOptions {
+  /** The type of leader. The default is `po`. */
+  readonly leader: LeaderType;
+  /** The least gap between two plugs of one wall, from 2 to 8. The default is 8. */
+  readonly slotSpacing: number;
+  /** The distance from a plug to a corner of its box, or a quarter of the wall when the wall is short. The default is 6. */
+  readonly inset: number;
+  /** The number of passes that sort each wall again by the new places of the far ends, from 0 to 4. The default is 2. */
+  readonly rounds: number;
+}
+
+/** The defaults of the plug strategy `leaders`. */
+export const LEADER_DEFAULTS: Readonly<LeaderOptions> = Object.freeze({ leader: "po", slotSpacing: 8, inset: SPREAD_DEFAULTS.inset, rounds: SPREAD_DEFAULTS.rounds });
+
+/**
+ * This function gives the plugs of the plug strategy `leaders` (EDA-041, after Bekos 2007). A fixed plug stays at its point, and a plug with a side stays on that side.
+ * Each free plug goes on the side that faces the other end. The plugs of each wall keep at least `slotSpacing` between two of them.
+ * The type of leader sets their order and their places. The output has one entry for each edge with two known nodes, in the order of the edges.
+ */
+export function leaderEnds(input: PlugInput, options: Partial<LeaderOptions> = {}): PlugPair[] {
+  const o = { ...LEADER_DEFAULTS, ...options };
+  const spread = { plugGap: o.slotSpacing, inset: o.inset, rounds: o.rounds };
+  return spreadWith(input, spread, o.leader === "s" ? undefined : o.leader);
+}

package/src/plugs/spread/index.ts

@@ -84,6 +84,20 @@ function keyOf(box: Box, side: Side, far: Point): number {
   return along >= 0 ? 2 - p : -2 - p;
 }
 
+/**
+ * This function gives the sort key of a far point for a po-leader (EDA-041): its place on the axis along the wall.
+ * A far point behind the wall gets the key of `keyOf` with a large shift, so it goes to an end of the wall.
+ */
+function poKeyOf(box: Box, side: Side, far: Point): number {
+  const c = center(box);
+  const n = SIDE_NORMAL[side];
+  const out = (far.x - c.x) * n.x + (far.y - c.y) * n.y;
+  const along = alongOf(side) === "y" ? far.y : far.x;
+  if (out > 0) return along;
+  const k = keyOf(box, side, far);
+  return k >= 0 ? 1e12 + k : -1e12 + k;
+}
+
 /**
  * This function places `ideal.length` plugs in their given order on the segment from `lo` to `hi`. Two neighbours are at least `gap` apart.
  * The gap shrinks evenly when the segment is too short. The sum of the squares of the moves from the ideal places is the least.
@@ -102,7 +116,7 @@ function placeInOrder(ideal: readonly number[], lo: number, hi: number, gap: num
  * Each slot goes into the part of its ideal place, and the parts keep the order of the slots. In each part, two plugs and a plug and a fixed plug are at least `gap` apart.
  * The gap of a part shrinks evenly when the part is too short.
  */
-function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number, hi: number, gap: number): void {
+function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number, hi: number, gap: number, idealOf: (s: Slot) => number = (s) => s.ideal): void {
   const cuts = [...new Set(fixed.filter((f) => f > lo - 1e-9 && f < hi + 1e-9))].sort((a, b) => a - b);
   // The part i is from cuts[i - 1] to cuts[i]. The first part starts at lo, and the last part ends at hi.
   const ends = [lo, ...cuts, hi];
@@ -110,7 +124,7 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
   let part = 0;
   for (const s of slots) {
     let p = 0;
-    while (p < cuts.length && s.ideal > cuts[p]!) p++;
+    while (p < cuts.length && idealOf(s) > cuts[p]!) p++;
     part = Math.max(part, p);
     parts[part]!.push(s);
   }
@@ -125,7 +139,7 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
     const lower = a + fa * s;
     const upper = Math.max(lower, b - fb * s);
     const at = placeInOrder(
-      list.map((x) => x.ideal),
+      list.map((x) => idealOf(x)),
       lower,
       upper,
       s,
@@ -144,6 +158,21 @@ function placeWall(slots: readonly Slot[], fixed: readonly number[], lo: number,
  * The output has one entry for each edge with two known nodes, in the order of the edges.
  */
 export function spreadEnds(input: PlugInput, options: SpreadOptions = {}): PlugPair[] {
+  return spreadWith(input, options);
+}
+
+/**
+ * The order and the places of the plugs of one wall in the strategy `leaders` (EDA-041).
+ * With `po`, the sort key of a far end in front of the wall is its place on the axis along the wall.
+ * With `opo`, the plugs of a wall go at even places in the order of the keys of `spread`.
+ */
+export type WallLeader = "po" | "opo";
+
+/**
+ * This function does the work of `spreadEnds`, and of the strategy `leaders` with the argument `leader`.
+ * Without `leader`, it gives the plugs of `spread`.
+ */
+export function spreadWith(input: PlugInput, options: SpreadOptions = {}, leader?: WallLeader): PlugPair[] {
   const { graph } = input;
   const gap = options.plugGap ?? SPREAD_DEFAULTS.plugGap;
   const inset = options.inset ?? SPREAD_DEFAULTS.inset;
@@ -206,11 +235,16 @@ export function spreadEnds(input: PlugInput, options: SpreadOptions = {}): PlugP
   for (let round = 0; round <= rounds; round++) {
     for (const wall of walls.values()) {
       const [lo, hi] = roomOf(wall.node.box, wall.side, inset);
-      const keys = new Map<Slot, number>(wall.slots.map((s) => [s, keyOf(wall.node.box, wall.side, resolve(s.far!).point)]));
+      const key = leader === "po" ? poKeyOf : keyOf;
+      const keys = new Map<Slot, number>(wall.slots.map((s) => [s, key(wall.node.box, wall.side, resolve(s.far!).point)]));
       const tie = (a: Slot, b: Slot): number => (round === 0 ? a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1] : order.get(a)! - order.get(b)!);
       const sorted = [...wall.slots].sort((a, b) => keys.get(a)! - keys.get(b)! || tie(a, b));
       sorted.forEach((s, i) => order.set(s, i));
-      placeWall(sorted, wall.fixed, lo, hi, gap);
+      if (leader === "opo") {
+        // The even places: the plugs split the room into equal parts, so the plug spacing of the wall is the largest that it can be.
+        const even = new Map<Slot, number>(sorted.map((s, i) => [s, lo + ((i + 0.5) * (hi - lo)) / sorted.length]));
+        placeWall(sorted, wall.fixed, lo, hi, gap, (s) => even.get(s)!);
+      } else placeWall(sorted, wall.fixed, lo, hi, gap);
     }
   }
   return ends.map((x) => ({ edge: x.edge, source: resolve(x.source), target: resolve(x.target) }));

package/src/routers/adam/index.ts

@@ -0,0 +1,294 @@
+import { checkProperties } from "../../bench/properties.ts";
+import { measureQuality } from "../../bench/quality.ts";
+import { rng } from "../../fixtures.ts";
+import { segmentsCross, type Box, type Point } from "../../geom.ts";
+import { outerGraph, type Graph, type GroupRule, type Result, type Route, type Router } from "../../model.ts";
+import { defineStrategy, type Strategy } from "../../strategies/model.ts";
+import type { OptionSchema } from "../../strategies/options.ts";
+import { sharedRouter } from "../shared.ts";
+import { byCollection } from "../trunks.ts";
+
+/** The options of the router `adam` (RULE-020: Adam with a seeded sample of pairs). */
+export interface AdamOptions {
+  /** The first step size `eta0`, in units of `clearance`, from 0.01 to 1. The step size falls to a tenth of it at the last step. The default is 0.1. */
+  readonly eta: number;
+  /** The number of other legs that each leg samples at each step, from 4 to 32. The default is 8. */
+  readonly samples: number;
+  /** The number of steps: the budget of the search, from 100 to 2000. The default is 200. */
+  readonly steps: number;
+  /** The seed of the samples, a whole number from 0. The same seed gives the same routes. The default is 1. */
+  readonly seed: number;
+  /** A leg nearer than this distance to another leg or to a box gets a push, from 4 to 32. The default is 8. */
+  readonly clearance: number;
+}
+
+/** The default options of the router `adam`. */
+export const ADAM_DEFAULTS: Readonly<AdamOptions> = Object.freeze({ eta: 0.1, samples: 8, steps: 200, seed: 1, clearance: 8 });
+
+/** The declarations of the options of the router `adam` (RULE-020). */
+export const ADAM_SCHEMA: OptionSchema<AdamOptions> = {
+  eta: { type: "number", min: 0.01, max: 1, step: 0.01, marks: [0.01, 0.1, 1], default: 0.1, describe: "The first step size, in units of the clearance. It falls to a tenth at the last step." },
+  samples: { type: "integer", min: 4, max: 32, step: 1, marks: [4, 8, 16, 32], default: 8, describe: "The number of other legs that each leg samples at each step." },
+  steps: { type: "integer", min: 100, max: 2000, step: 100, marks: [100, 200, 500, 2000], default: 200, describe: "The number of steps: the budget of the search." },
+  seed: { type: "integer", min: 0, max: 1_000_000, step: 1, marks: [1, 2, 3], default: 1, describe: "The seed of the samples. The same seed gives the same routes." },
+  clearance: { type: "number", min: 4, max: 32, step: 1, marks: [4, 8, 16, 32], default: 8, describe: "A leg nearer than this distance to another leg or to a box gets a push." },
+};
+
+/** The moment factors of Adam (Kingma and Ba 2015), as the record gives them. */
+const BETA1 = 0.9;
+const BETA2 = 0.999;
+const EPS = 1e-8;
+
+/** The weight of the push from a box, against the push from a leg. */
+const BOX_WEIGHT = 4;
+
+/** The weight of the term that holds a leg near its first place. */
+const HOLD = 0.05;
+
+/** A free leg of a route. No end of it is an end of its route or a point of another route. No run or trunk holds it. */
+interface Leg {
+  readonly route: number;
+  /** The index of the first point of the leg in its route. */
+  readonly k: number;
+  /** The unit normal of the leg. The leg moves along it. */
+  readonly nx: number;
+  readonly ny: number;
+  /** The boxes near the leg. */
+  readonly boxes: readonly Box[];
+}
+
+/** This function gives the point of the segment `ab` nearest to `p`. */
+function nearestOn(p: Point, a: Point, b: Point): Point {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const l2 = dx * dx + dy * dy;
+  const t = l2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / l2)) : 0;
+  return { x: a.x + t * dx, y: a.y + t * dy };
+}
+
+/** This function gives the point of a box nearest to `p`. A point in the box gives the nearest point of its border. */
+function nearestOfBox(p: Point, b: Box): Point {
+  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));
+  if (qx !== p.x || qy !== p.y) return { x: qx, y: qy };
+  const sides = [p.x - b.x, b.x + b.w - p.x, p.y - b.y, b.y + b.h - p.y];
+  const m = Math.min(...sides);
+  if (m === sides[0]) return { x: b.x, y: p.y };
+  if (m === sides[1]) return { x: b.x + b.w, y: p.y };
+  if (m === sides[2]) return { x: p.x, y: b.y };
+  return { x: p.x, y: b.y + b.h };
+}
+
+/** This function gives the crossings of the route `a` with itself and with the routes of `others`. It skips the route with the index `skip`. */
+function crossingsOf(a: readonly Point[], others: readonly (readonly Point[])[], skip: number): number {
+  const [ax0, ay0, ax1, ay1] = boundsOf(a);
+  let n = 0;
+  for (let i = 1; i < a.length; i++) for (let k = i + 2; k < a.length; k++) if (segmentsCross(a[i - 1]!, a[i]!, a[k - 1]!, a[k]!)) n++;
+  others.forEach((b, j) => {
+    if (j === skip) return;
+    const [bx0, by0, bx1, by1] = boundsOf(b);
+    if (bx0 > ax1 || bx1 < ax0 || by0 > ay1 || by1 < ay0) return;
+    for (let i = 1; i < a.length; i++) for (let k = 1; k < b.length; k++) if (segmentsCross(a[i - 1]!, a[i]!, b[k - 1]!, b[k]!)) n++;
+  });
+  return n;
+}
+
+/** The bounds of each polyline, once for each polyline object. */
+const BOUNDS = new WeakMap<readonly Point[], readonly [number, number, number, number]>();
+
+/** This function gives the bounds of a polyline: the least x and y, and the largest x and y. */
+function boundsOf(p: readonly Point[]): readonly [number, number, number, number] {
+  let b = BOUNDS.get(p);
+  if (b) return b;
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const q of p) {
+    x0 = Math.min(x0, q.x);
+    y0 = Math.min(y0, q.y);
+    x1 = Math.max(x1, q.x);
+    y1 = Math.max(y1, q.y);
+  }
+  b = [x0, y0, x1, y1];
+  BOUNDS.set(p, b);
+  return b;
+}
+
+/**
+ * This function moves the free legs of the routes of `result` with Adam (RULE-020, after Kingma and Ba 2015, and the SGD layouts of Zheng, Pawar and Goodman 2019).
+ * A leg is free when its two points are inside its route, and no other route, run or trunk holds them. The variable of a leg is a shift along its normal.
+ * The energy of a leg is `Σ (1 - d / c)²` over a seeded sample of `samples` other legs nearer than `c`. The near boxes add the same term times 4.
+ * A term `0.05 × (t / c)²` holds each leg near its first place. The step size falls from `eta` to a tenth of it, with only `+`, `*` and `/`.
+ * A moved route goes back to its first points when it has more crossings than before, or a break of a hard rule.
+ * When the output still has more crossings than the routes of `shared`, it is the routes of `shared`.
+ */
+export function adamRoutes(input: Graph, result: Result, options: Partial<AdamOptions> = {}): Result {
+  const o = { ...ADAM_DEFAULTS, ...options };
+  const c = Math.max(1e-6, o.clearance);
+  const graph = outerGraph(input);
+  const first = result.routes.map((r) => r.points);
+  const pinned = new Set<string>();
+  const keyOf = (p: Point): string => `${p.x},${p.y}`;
+  for (const run of result.runs ?? []) for (const p of run.points) pinned.add(keyOf(p));
+  for (const b of result.bundles ?? []) for (const p of b.trunk) pinned.add(keyOf(p));
+  // A point of two routes or more stays, so two routes that share a leg keep it as one drawn leg.
+  const owners = new Map<string, number>();
+  first.forEach((pts, route) => {
+    for (const p of pts) {
+      const k = keyOf(p);
+      const o = owners.get(k);
+      if (o === undefined) owners.set(k, route);
+      else if (o !== route) pinned.add(k);
+    }
+  });
+  const boxes = graph.nodes.map((n) => n.box);
+  const legs: Leg[] = [];
+  first.forEach((pts, route) => {
+    for (let k = 1; k + 2 < pts.length; k++) {
+      const a = pts[k]!;
+      const b = pts[k + 1]!;
+      if (pinned.has(keyOf(a)) || pinned.has(keyOf(b))) continue;
+      const dx = b.x - a.x;
+      const dy = b.y - a.y;
+      const len = Math.sqrt(dx * dx + dy * dy);
+      if (len <= 1e-9) continue;
+      const reach = 3 * c;
+      const near = boxes.filter((bx) => Math.min(a.x, b.x) - reach <= bx.x + bx.w && Math.max(a.x, b.x) + reach >= bx.x && Math.min(a.y, b.y) - reach <= bx.y + bx.h && Math.max(a.y, b.y) + reach >= bx.y);
+      legs.push({ route, k, nx: -dy / len, ny: dx / len, boxes: near });
+    }
+  });
+  if (legs.length === 0) return result;
+  const shift = new Float64Array(legs.length);
+  const m1 = new Float64Array(legs.length);
+  const m2 = new Float64Array(legs.length);
+  // The legs that touch each point of each route, so a point moves with each of its legs.
+  const legAt = new Map<string, number[]>();
+  legs.forEach((l, i) => {
+    for (const k of [l.k, l.k + 1]) {
+      const key = `${l.route}:${k}`;
+      const list = legAt.get(key);
+      if (list) list.push(i);
+      else legAt.set(key, [i]);
+    }
+  });
+  const pointOf = (route: number, k: number): Point => {
+    const p = first[route]![k]!;
+    const list = legAt.get(`${route}:${k}`);
+    if (!list) return p;
+    let x = p.x;
+    let y = p.y;
+    for (const i of list) {
+      x += shift[i]! * legs[i]!.nx;
+      y += shift[i]! * legs[i]!.ny;
+    }
+    return { x, y };
+  };
+  // Each leg of each route, as the pairs of the sample: the free legs and the fixed legs.
+  const all: { route: number; k: number }[] = [];
+  first.forEach((pts, route) => {
+    for (let k = 0; k + 1 < pts.length; k++) all.push({ route, k });
+  });
+  const random = rng(Math.max(0, Math.floor(o.seed)));
+  const steps = Math.max(1, Math.floor(o.steps));
+  const count = Math.max(1, Math.floor(o.samples));
+  let b1 = 1;
+  let b2 = 1;
+  for (let t = 0; t < steps; t++) {
+    b1 *= BETA1;
+    b2 *= BETA2;
+    const eta = (o.eta * c) / (1 + (9 * t) / Math.max(1, steps - 1));
+    const grads = new Float64Array(legs.length);
+    legs.forEach((l, i) => {
+      const a = pointOf(l.route, l.k);
+      const b = pointOf(l.route, l.k + 1);
+      const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+      let g = (2 * HOLD * shift[i]!) / (c * c);
+      for (let s = 0; s < count; s++) {
+        const other = all[Math.floor(random() * all.length)]!;
+        if (other.route === l.route) continue;
+        const q = nearestOn(mid, pointOf(other.route, other.k), pointOf(other.route, other.k + 1));
+        const dx = mid.x - q.x;
+        const dy = mid.y - q.y;
+        const d = Math.sqrt(dx * dx + dy * dy);
+        if (d >= c || d <= 1e-9) continue;
+        // E = (1 - d / c)², so dE/dt = -2 (1 - d / c) / c × (n · (mid - q)) / d.
+        g += ((-2 * (1 - d / c)) / c) * ((l.nx * dx + l.ny * dy) / d);
+      }
+      for (const bx of l.boxes) {
+        for (const p of [a, mid, b]) {
+          const q = nearestOfBox(p, bx);
+          const inside = p.x >= bx.x && p.x <= bx.x + bx.w && p.y >= bx.y && p.y <= bx.y + bx.h;
+          const dx = (inside ? q.x - p.x : p.x - q.x) || 0;
+          const dy = (inside ? q.y - p.y : p.y - q.y) || 0;
+          const d0 = Math.sqrt(dx * dx + dy * dy);
+          if (d0 <= 1e-9) continue;
+          const d = inside ? -d0 : d0;
+          if (d >= c) continue;
+          g += ((BOX_WEIGHT * -2 * (1 - d / c)) / c) * ((l.nx * dx + l.ny * dy) / d0);
+        }
+      }
+      grads[i] = g;
+    });
+    for (let i = 0; i < legs.length; i++) {
+      const g = grads[i]!;
+      m1[i] = BETA1 * m1[i]! + (1 - BETA1) * g;
+      m2[i] = BETA2 * m2[i]! + (1 - BETA2) * g * g;
+      const mh = m1[i]! / (1 - b1);
+      const vh = m2[i]! / (1 - b2);
+      shift[i] = Math.max(-2 * c, Math.min(2 * c, shift[i]! - (eta * mh) / (Math.sqrt(vh) + EPS)));
+    }
+  }
+  const moved = new Set(legs.map((l) => l.route));
+  const points = first.map((pts, route) => (moved.has(route) ? pts.map((_, k) => pointOf(route, k)) : pts));
+  // A moved route with more crossings than its first points, against the other routes as they are, goes back to its first points.
+  for (let round = 0; round < 8; round++) {
+    let back = 0;
+    for (const route of moved) {
+      if (points[route] === first[route] || crossingsOf(points[route]!, points, route) <= crossingsOf(first[route]!, points, route)) continue;
+      points[route] = first[route]!;
+      back++;
+    }
+    if (back === 0) break;
+  }
+  const build = (pts: readonly (readonly Point[])[]): Result => ({ ...result, routes: result.routes.map((r, i): Route => (pts[i] === r.points ? r : { ...r, points: pts[i]! })) });
+  let out = build(points);
+  for (let round = 0; round < 3; round++) {
+    const faulty = new Set(checkProperties(input, out, 1_000_000).map((v) => v.edge));
+    const fix = result.routes.map((r, i) => (faulty.has(r.edge) && points[i] !== first[i] ? i : -1)).filter((i) => i >= 0);
+    if (fix.length === 0) break;
+    for (const i of fix) points[i] = first[i]!;
+    out = build(points);
+  }
+  // The output keeps the routes of `shared` when it has a break of a hard rule, or more crossings, after the fixes.
+  if (checkProperties(input, out, 1).length > checkProperties(input, result, 1).length) return result;
+  return measureQuality(input, out).crossings > measureQuality(input, result).crossings ? result : out;
+}
+
+/**
+ * This function makes the router `adam` (RULE-020). It is the router `shared`, then the steps of Adam of `adamRoutes`.
+ * The runs and the bundles of `shared` stay, because no point of a run or of a trunk moves.
+ */
+export function adamRouter(options: Partial<AdamOptions> & { readonly name: string; readonly rule?: GroupRule; readonly maxNodes?: number }): Router {
+  const o = { ...ADAM_DEFAULTS, ...options };
+  const base = sharedRouter({ name: o.name, ...(o.rule === undefined ? {} : { rule: o.rule }), ...(o.maxNodes === undefined ? {} : { maxNodes: o.maxNodes }) });
+  return {
+    name: o.name,
+    ...(o.maxNodes === undefined ? {} : { maxNodes: o.maxNodes }),
+    route: (graph: Graph): Result => adamRoutes(graph, base.route(graph), o),
+  };
+}
+
+/**
+ * The router strategy `adam` (RULE-020), with the rule `byCollection` of `shared`. It is not a built-in router, so the benchmark and the hashes of `ROUTERS` do not change.
+ * A screen module or a consumer adds it to a registry.
+ */
+export const adamStrategy: Strategy<"router", AdamOptions> = defineStrategy({
+  step: "router",
+  name: "adam",
+  describe: "Adam with a seeded sample of pairs (RULE-020). The free legs of the routes of `shared` move along their normals, away from near legs and boxes.",
+  defaults: { ...ADAM_DEFAULTS },
+  schema: ADAM_SCHEMA,
+  maxNodes: 10_000,
+  run: (graph: Graph, o: Readonly<AdamOptions>): Result => adamRouter({ ...o, name: "adam", rule: byCollection }).route(graph),
+});

package/src/routers/canals/index.ts

@@ -0,0 +1,191 @@
+import type { Graph, GroupRule, Result, Router } from "../../model.ts";
+import { defineStrategy, type Strategy } from "../../strategies/model.ts";
+import type { OptionSchema } from "../../strategies/options.ts";
+import { sharedRouter, type SharedSearch, type Way } from "../shared.ts";
+import { byCollection } from "../trunks.ts";
+
+/** The options of the router `canals` (NAT-004: canalization feeder trees to hubs). */
+export interface CanalOptions {
+  /** The exponent `mu` of the flux in the growth of a conductance, from 1 to 3 in steps of 0.5. A value above 1 gives a tree. The default is 2. */
+  readonly mu: number;
+  /** The largest number of updates of the conductances, from 30 to 150. The updates stop when the ways do not change for 3 updates. The default is 60. */
+  readonly steps: number;
+  /** The decay `r` of a conductance, from 0.5 to 2. The default is 1. */
+  readonly decay: number;
+  /** A hub has this number of edges of one key or more, from 2 to 8. The default is 3. */
+  readonly minMembers: number;
+}
+
+/** The default options of the router `canals`. */
+export const CANAL_DEFAULTS: Readonly<CanalOptions> = Object.freeze({ mu: 2, steps: 60, decay: 1, minMembers: 3 });
+
+/** The declarations of the options of the router `canals` (NAT-004). */
+export const CANAL_SCHEMA: OptionSchema<CanalOptions> = {
+  mu: { type: "number", min: 1, max: 3, step: 0.5, marks: [1, 2, 3], default: 2, describe: "The exponent of the flux in the growth of a conductance. A value above 1 gives a tree." },
+  steps: { type: "integer", min: 30, max: 150, step: 10, marks: [30, 60, 150], default: 60, describe: "The largest number of updates of the conductances." },
+  decay: { type: "number", min: 0.5, max: 2, step: 0.25, marks: [0.5, 1, 2], default: 1, describe: "The decay of a conductance." },
+  minMembers: { type: "integer", min: 2, max: 8, step: 1, marks: [2, 3, 5, 8], default: 3, describe: "A hub has this number of edges of one key or more." },
+};
+
+/** The time step of one update of the conductances. */
+const DT = 0.5;
+
+/** The gain of a conductance in the cost of a link: a link with the conductance `D` costs `d / (1 + GAIN × D)`. */
+const GAIN = 4;
+
+/** The cost share of a link that another way of the key uses, as the default `discount` of `shared`. */
+const SHARE = 0.5;
+
+/** The updates with no change of a way, after which the updates stop. */
+const PATIENCE = 3;
+
+/**
+ * This function gives `x^mu` for `x` from 0 to 1 and `mu` in steps of 0.5, with only `*` and `Math.sqrt`.
+ * These operations are exact to the last bit on each platform, so a decision does not depend on the engine.
+ */
+export function halfPower(x: number, mu: number): number {
+  const twice = Math.max(2, Math.min(6, Math.round(mu * 2)));
+  let out = 1;
+  for (let i = 0; i < Math.floor(twice / 2); i++) out *= x;
+  return twice % 2 === 1 ? out * Math.sqrt(x) : out;
+}
+
+/** A hub: a node, the key of its edges, and the ways of those edges. */
+export interface CanalHub {
+  readonly node: string;
+  readonly key: string;
+  readonly ways: readonly Way[];
+}
+
+/**
+ * This function gives the hubs of the ways. In each key, the node with the most ends is a hub when it has `minMembers` edges or more.
+ * Its edges leave the key, and the next hub of the key comes from the edges that stay. A tie goes to the smaller node id.
+ * An edge with no key is in no hub.
+ */
+export function canalHubs(ways: readonly Way[], minMembers: number): CanalHub[] {
+  const byKey = new Map<string, Way[]>();
+  for (const w of ways) {
+    if (!w.found || w.ids.length < 2 || w.key.startsWith("\u0000")) continue;
+    const list = byKey.get(w.key);
+    if (list) list.push(w);
+    else byKey.set(w.key, [w]);
+  }
+  const out: CanalHub[] = [];
+  for (const key of [...byKey.keys()].sort()) {
+    let left = byKey.get(key)!;
+    for (;;) {
+      const count = new Map<string, number>();
+      for (const w of left) for (const n of new Set([w.edge.source.node, w.edge.target.node])) count.set(n, (count.get(n) ?? 0) + 1);
+      let node: string | undefined;
+      let most = 0;
+      for (const [n, c] of count) if (c > most || (c === most && node !== undefined && n < node)) [node, most] = [n, c];
+      if (node === undefined || most < Math.max(2, minMembers)) break;
+      const hub = node;
+      const members = left.filter((w) => w.edge.source.node === hub || w.edge.target.node === hub);
+      out.push({ node: hub, key, ways: [...members].sort((a, b) => (a.edge.id < b.edge.id ? -1 : a.edge.id > b.edge.id ? 1 : 0)) });
+      left = left.filter((w) => !members.includes(w));
+    }
+  }
+  return out;
+}
+
+/**
+ * This function grows a feeder tree to each hub (NAT-004, after the canalization of Sachs 1981 and Mitchison 1980).
+ * Each member edge is a source of one unit of flux, and the hub is the sink. The flux of a link is the share of the members whose ways use it.
+ * At each update, each conductance changes by `DT × (flux^mu - decay × D)`, and each member finds its way again with the cost `d / (1 + GAIN × D)`.
+ * A link that another way of the key uses costs half, as in `shared`.
+ * With `mu` above 1, a link with more flux grows faster, so the ways gather into one tree. The updates stop after `steps`, or when no way changes for 3 updates.
+ */
+export function canalWays(ways: readonly Way[], search: SharedSearch, options: Partial<CanalOptions> = {}): void {
+  const o = { ...CANAL_DEFAULTS, ...options };
+  const n = search.corners;
+  const linksOf = (w: Way): number[] => {
+    const out = new Set<number>();
+    for (let i = 1; i < w.ids.length; i++) if (w.ids[i - 1]! < n && w.ids[i]! < n) out.add(search.link(w.ids[i - 1]!, w.ids[i]!));
+    return [...out];
+  };
+  // The number of ways of each key on each link, so a link that another way of the key uses keeps the share of `shared`.
+  const usage = new Map<string, Map<number, number>>();
+  const use = (w: Way, add: number): void => {
+    let m = usage.get(w.key);
+    if (!m) usage.set(w.key, (m = new Map()));
+    for (const k of linksOf(w)) m.set(k, (m.get(k) ?? 0) + add);
+  };
+  for (const w of ways) if (w.found) use(w, 1);
+  for (const hub of canalHubs(ways, Math.floor(o.minMembers))) {
+    const members = hub.ways;
+    const used = usage.get(hub.key)!;
+    const conductance = new Map<number, number>();
+    let calm = 0;
+    for (let step = 0; step < Math.max(1, Math.floor(o.steps)); step++) {
+      const flux = new Map<number, number>();
+      for (const w of members) {
+        const seen = new Set<number>();
+        for (let i = 1; i < w.ids.length; i++) {
+          const a = w.ids[i - 1]!;
+          const b = w.ids[i]!;
+          if (a >= n || b >= n) continue;
+          const k = search.link(a, b);
+          if (seen.has(k)) continue;
+          seen.add(k);
+          flux.set(k, (flux.get(k) ?? 0) + 1);
+        }
+      }
+      for (const k of new Set([...conductance.keys(), ...flux.keys()])) {
+        const phi = (flux.get(k) ?? 0) / members.length;
+        const d = conductance.get(k) ?? 0;
+        const next = d + DT * (halfPower(phi, o.mu) - o.decay * d);
+        if (next > 1e-6) conductance.set(k, next);
+        else conductance.delete(k);
+      }
+      let top = 0;
+      for (const d of conductance.values()) top = Math.max(top, d);
+      const floor = SHARE / (1 + GAIN * top);
+      let changed = 0;
+      for (const w of members) {
+        use(w, -1);
+        const next = search.find(
+          w,
+          (i, j, d) => {
+            const k = search.link(i, j);
+            return ((used.get(k) ?? 0) > 0 ? SHARE * d : d) / (1 + GAIN * (conductance.get(k) ?? 0));
+          },
+          floor,
+        );
+        if (next) {
+          if (next.ids.length !== w.ids.length || next.ids.some((id, i) => id !== w.ids[i])) changed++;
+          w.seq = next.seq;
+          w.ids = next.ids;
+        }
+        use(w, 1);
+      }
+      calm = changed === 0 ? calm + 1 : 0;
+      if (calm >= PATIENCE) break;
+    }
+  }
+}
+
+/**
+ * This function makes the router `canals` (NAT-004). It is the router `shared`, then the feeder trees of `canalWays` to the hubs of each key.
+ * The runs and the bundles come from the ways after the trees.
+ */
+export function canalRouter(options: Partial<CanalOptions> & { readonly name: string; readonly rule?: GroupRule; readonly maxNodes?: number }): Router {
+  const o = { ...CANAL_DEFAULTS, ...options };
+  return sharedRouter({ name: o.name, ...(o.rule === undefined ? {} : { rule: o.rule }), ...(o.maxNodes === undefined ? {} : { maxNodes: o.maxNodes }) }, undefined, {
+    refine: (ways, search) => canalWays(ways, search, o),
+  });
+}
+
+/**
+ * The router strategy `canals` (NAT-004), with the rule `byCollection` of `shared`. It is not a built-in router, so the benchmark and the hashes of `ROUTERS` do not change.
+ * A screen module or a consumer adds it to a registry.
+ */
+export const canalStrategy: Strategy<"router", CanalOptions> = defineStrategy({
+  step: "router",
+  name: "canals",
+  describe: "Canalization feeder trees (NAT-004). The members of a hub are sources of flux, and the links with more flux get cheaper until the ways make one tree.",
+  defaults: { ...CANAL_DEFAULTS },
+  schema: CANAL_SCHEMA,
+  maxNodes: 10_000,
+  run: (graph: Graph, o: Readonly<CanalOptions>): Result => canalRouter({ ...o, name: "canals", rule: byCollection }).route(graph),
+});

package/src/routers/index.ts

@@ -13,6 +13,9 @@ export { frameRoutes, type FrameOptions, type InnerMode, type Outside } from "./
 export { GUTTER_BEND_COST, gutterRoutes, type GutterEdge, type GutterOptions } from "./gutter.ts";
 export { sharedRouter, type ShareCost, type SharedHooks, type SharedNegotiation, type SharedOptions, type SharedSearch, type ShareMerge, type ShareOrder } from "./shared.ts";
 export { ANNEALING_DEFAULTS, ANNEALING_SCHEMA, annealingRouter, annealingStrategy, annealWays, type AnnealingOptions } from "./annealing/index.ts";
+export { CANAL_DEFAULTS, CANAL_SCHEMA, canalHubs, canalRouter, canalStrategy, canalWays, halfPower, type CanalHub, type CanalOptions } from "./canals/index.ts";
+export { ADAM_DEFAULTS, ADAM_SCHEMA, adamRouter, adamRoutes, adamStrategy, type AdamOptions } from "./adam/index.ts";
+export { REROUTE_DEFAULTS, REROUTE_SCHEMA, rerouteRouter, rerouteStrategy, rerouteWays, turnsOf, type RerouteOptions } from "./reroute/index.ts";
 export { TIGHT_DEFAULTS, TIGHT_FIRSTS, TIGHT_SCHEMA, TIGHT_TIES, tightRouter, tightStrategy, waySlacks, type TightFirst, type TightOptions, type TightTies } from "./tight/index.ts";
 export { ATTRACTION_DEFAULTS, ATTRACTION_SCHEMA, attractionRouter, attractionStrategy, type AttractionOptions } from "./attraction/index.ts";
 export { sectionsRouter, type SectionsOptions } from "./sections.ts";