@mark1russell7/highways 0.9.3 → 0.9.4

package/src/routers/annealing/index.ts

@@ -0,0 +1,260 @@
+import { rng } from "../../fixtures.ts";
+import { dist, type Point } from "../../geom.ts";
+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 `annealing` (RULE-021: simulated annealing over candidate routes, with its rider WILD-028). */
+export interface AnnealingOptions {
+  /** The number of candidate ways of each edge, from 3 to 8. The default is 4. */
+  readonly candidates: number;
+  /** The cost of one crossing, in units of the median box side, from 0 to 20. The default is 4. */
+  readonly crossing: number;
+  /** The start temperature, in units of the median box side, from 0.1 to 10. The default is 1. */
+  readonly temperature: number;
+  /** The factor of the temperature after each sweep of the edges, from 0.9 to 0.99. The default is 0.95. */
+  readonly cooling: number;
+  /** The budget: the number of changes for each edge, from 20 to 200. The default is 50. */
+  readonly budget: number;
+  /** The seed of the random choices, a whole number from 0. The same seed gives the same routes. The default is 1. */
+  readonly seed: number;
+}
+
+/** The default options of the router `annealing`. */
+export const ANNEALING_DEFAULTS: Readonly<AnnealingOptions> = Object.freeze({ candidates: 4, crossing: 4, temperature: 1, cooling: 0.95, budget: 50, seed: 1 });
+
+/** The declarations of the options of the router `annealing` (RULE-021). */
+export const ANNEALING_SCHEMA: OptionSchema<AnnealingOptions> = {
+  candidates: { type: "integer", min: 3, max: 8, step: 1, marks: [3, 4, 6], default: 4, describe: "The number of candidate ways of each edge." },
+  crossing: { type: "number", min: 0, max: 20, step: 0.5, marks: [1, 4, 10], default: 4, describe: "The cost of one crossing, in units of the median box side." },
+  temperature: { type: "number", min: 0.1, max: 10, step: 0.1, marks: [0.5, 1, 4], default: 1, describe: "The start temperature, in units of the median box side." },
+  cooling: { type: "number", min: 0.9, max: 0.99, step: 0.01, marks: [0.9, 0.95, 0.98], default: 0.95, describe: "The factor of the temperature after each sweep of the edges." },
+  budget: { type: "integer", min: 20, max: 200, step: 10, marks: [20, 50, 100], default: 50, describe: "The budget: the number of changes for each edge." },
+  seed: { type: "integer", min: 0, max: 1_000_000, step: 1, marks: [1, 2, 3], default: 1, describe: "The seed of the random choices. The same seed gives the same routes." },
+};
+
+/** The share of the cost of a link that the edges of one key use already, as in `shared` with its default discount. */
+const DISCOUNT = 0.5;
+/** The cost factor of the links of the earlier candidates in the search of the next candidate. */
+const PENALTY = 3;
+
+/** One candidate way of an edge: its points, the indices of its points and the keys of its links. */
+interface Candidate {
+  readonly seq: Point[];
+  readonly ids: number[];
+  readonly links: number[];
+  readonly lengths: number[];
+  readonly length: number;
+}
+
+/** This function tells if the segments `a b` and `c d` cross at one inner point of each. A touch at an end or a common line is not a crossing. */
+function properCross(a: Point, b: Point, c: Point, d: Point): boolean {
+  const o = (p: Point, q: Point, r: Point): number => (q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x);
+  const d1 = o(c, d, a);
+  const d2 = o(c, d, b);
+  const d3 = o(a, b, c);
+  const d4 = o(a, b, d);
+  return ((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0));
+}
+
+/** This function gives the median of the smaller side of the boxes, the unit of the costs. */
+function unitOf(graph: Graph): number {
+  const sides = graph.nodes.map((n) => Math.min(n.box.w, n.box.h)).sort((a, b) => a - b);
+  const u = sides.length === 0 ? 1 : sides[Math.floor((sides.length - 1) / 2)]!;
+  return u > 0 ? u : 1;
+}
+
+/**
+ * This function anneals the choice of one candidate way for each edge (RULE-021, after Davidson and Harel, 1996).
+ * The candidates of an edge are its way in `shared` and its shortest way. Other candidates are the shortest ways when the links of earlier candidates cost 3 times more.
+ * The energy is `(1 - 0.5) ink + 0.5 Σ L + crossing u X`: the cost of `shared` plus a cost for each crossing `X` between the ways of two edges.
+ * A change takes one edge to another candidate. A worse change stays with the rational chance `1 / (1 + y + y^2 / 2)`, with `y = ΔE / T`.
+ * The temperature falls by `cooling` after each sweep. The ways at the end are the ways of the lowest energy of the run.
+ */
+export function annealWays(ways: readonly Way[], search: SharedSearch, o: Readonly<AnnealingOptions>): void {
+  const live = ways.filter((w) => w.found);
+  const m = live.length;
+  if (m < 2) return;
+  const unit = unitOf(search.graph);
+  const n = search.corners;
+  let maxId = 0;
+  for (const w of live) for (const i of w.ids) maxId = Math.max(maxId, i);
+  const N = maxId + 1;
+  const pairOf = (a: number, b: number): number => (a < b ? a * N + b : b * N + a);
+  const make = (seq: Point[], ids: number[]): Candidate => {
+    const links: number[] = [];
+    const lengths: number[] = [];
+    let length = 0;
+    for (let i = 1; i < ids.length; i++) {
+      const d = dist(seq[i - 1]!, seq[i]!);
+      links.push(pairOf(ids[i - 1]!, ids[i]!));
+      lengths.push(d);
+      length += d;
+    }
+    return { seq, ids, links, lengths, length };
+  };
+  const k = Math.min(8, Math.max(1, Math.floor(o.candidates)));
+  // The candidates of each edge. The first is the way of `shared`, the start state.
+  const cands: Candidate[][] = live.map((w) => {
+    const list = [make(w.seq, w.ids)];
+    const seen = new Set([w.ids.join(",")]);
+    const hit = new Set<number>();
+    const mark = (c: Candidate): void => {
+      for (let i = 1; i < c.ids.length; i++) if (c.ids[i - 1]! < n && c.ids[i]! < n) hit.add(search.link(c.ids[i - 1]!, c.ids[i]!));
+    };
+    const add = (found: { seq: Point[]; ids: number[] } | undefined): boolean => {
+      if (!found) return false;
+      const key = found.ids.join(",");
+      if (seen.has(key)) return false;
+      seen.add(key);
+      const c = make(found.seq, found.ids);
+      list.push(c);
+      mark(c);
+      return true;
+    };
+    mark(list[0]!);
+    if (list.length < k) add(search.find(w));
+    for (let tries = 0; list.length < k && tries < k; tries++) {
+      if (!add(search.find(w, (i, j, d) => (hit.has(search.link(i, j)) ? d * PENALTY : d), 1))) break;
+    }
+    return list;
+  });
+  // The crossings of each pair of candidates of two edges, in a table for each pair of edges whose boxes meet.
+  type Bounds = { x0: number; y0: number; x1: number; y1: number };
+  const boundsOf = (seqs: readonly Point[][]): Bounds => {
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const seq of seqs)
+      for (const p of seq) {
+        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 { x0, y0, x1, y1 };
+  };
+  const apart = (A: Bounds, B: Bounds): boolean => A.x1 < B.x0 || B.x1 < A.x0 || A.y1 < B.y0 || B.y1 < A.y0;
+  const own = cands.map((list) => list.map((c) => boundsOf([c.seq])));
+  const boxes = cands.map((list) => boundsOf(list.map((c) => c.seq)));
+  const near: { f: number; table: Int32Array; mine: boolean }[][] = live.map(() => []);
+  for (let e = 0; e < m; e++) {
+    for (let f = e + 1; f < m; f++) {
+      if (apart(boxes[e]!, boxes[f]!)) continue;
+      const ke = cands[e]!.length;
+      const kf = cands[f]!.length;
+      const table = new Int32Array(ke * kf);
+      let any = false;
+      for (let i = 0; i < ke; i++) {
+        const p = cands[e]![i]!.seq;
+        for (let j = 0; j < kf; j++) {
+          if (apart(own[e]![i]!, own[f]![j]!)) continue;
+          const q = cands[f]![j]!.seq;
+          let x = 0;
+          for (let s = 1; s < p.length; s++) for (let t = 1; t < q.length; t++) if (properCross(p[s - 1]!, p[s]!, q[t - 1]!, q[t]!)) x++;
+          table[i * kf + j] = x;
+          if (x > 0) any = true;
+        }
+      }
+      if (!any) continue;
+      near[e]!.push({ f, table, mine: true });
+      near[f]!.push({ f: e, table, mine: false });
+    }
+  }
+  // The users of each link in each key, for the ink.
+  const keys = live.map((w) => w.key);
+  const users = new Map<string, Map<number, number>>();
+  const use = (e: number, c: Candidate, step: number): number => {
+    let mine = users.get(keys[e]!);
+    if (!mine) users.set(keys[e]!, (mine = new Map()));
+    let ink = 0;
+    for (let i = 0; i < c.links.length; i++) {
+      const before = mine.get(c.links[i]!) ?? 0;
+      const after = before + step;
+      if (after === 0) mine.delete(c.links[i]!);
+      else mine.set(c.links[i]!, after);
+      if (before === 0 && after > 0) ink += c.lengths[i]!;
+      if (before > 0 && after === 0) ink -= c.lengths[i]!;
+    }
+    return ink;
+  };
+  const choice = new Int32Array(m);
+  for (let e = 0; e < m; e++) use(e, cands[e]![0]!, 1);
+  const crossCost = Math.max(0, o.crossing) * unit;
+  const crossings = (e: number, i: number): number => {
+    let x = 0;
+    for (const { f, table, mine } of near[e]!) {
+      const kf = cands[f]!.length;
+      const ke = cands[e]!.length;
+      x += mine ? table[i * kf + choice[f]!]! : table[choice[f]! * ke + i]!;
+    }
+    return x;
+  };
+  const random = rng(Math.max(0, Math.floor(o.seed)));
+  const cooling = Math.min(0.99, Math.max(0.9, o.cooling));
+  let temperature = Math.max(1e-6, o.temperature) * unit;
+  const moves = Math.max(1, Math.floor(o.budget)) * m;
+  let energy = 0;
+  let best = 0;
+  let bestChoice = choice.slice();
+  for (let s = 0; s < moves; s++) {
+    if (s > 0 && s % m === 0) temperature *= cooling;
+    const e = Math.floor(random() * m);
+    const list = cands[e]!;
+    if (list.length < 2) continue;
+    const from = choice[e]!;
+    const to = (from + 1 + Math.floor(random() * (list.length - 1))) % list.length;
+    // The change of the energy: the ink and the length of the key, and the crossings with the other edges.
+    const dInk = use(e, list[from]!, -1) + use(e, list[to]!, 1);
+    const dLength = list[to]!.length - list[from]!.length;
+    const dCross = crossings(e, to) - crossings(e, from);
+    const delta = (1 - DISCOUNT) * dInk + DISCOUNT * dLength + crossCost * dCross;
+    const y = delta / temperature;
+    if (delta <= 0 || random() < 1 / (1 + y + (y * y) / 2)) {
+      choice[e] = to;
+      energy += delta;
+      if (energy < best - 1e-9) {
+        best = energy;
+        bestChoice = choice.slice();
+      }
+    } else {
+      use(e, list[to]!, -1);
+      use(e, list[from]!, 1);
+    }
+  }
+  live.forEach((w, e) => {
+    const c = cands[e]![bestChoice[e]!]!;
+    w.seq = c.seq;
+    w.ids = c.ids;
+  });
+}
+
+/**
+ * This function makes the router `annealing` (RULE-021 with its rider WILD-028). It is the router `shared`, then the annealing of `annealWays`.
+ * Each candidate is a way through the corner graph, as in `shared`, so each one keeps the hard rules.
+ */
+export function annealingRouter(options: Partial<AnnealingOptions> & { readonly name: string; readonly rule?: GroupRule; readonly maxNodes?: number }): Router {
+  const o = { ...ANNEALING_DEFAULTS, ...options };
+  return sharedRouter(
+    { name: o.name, ...(o.rule === undefined ? {} : { rule: o.rule }), ...(o.maxNodes === undefined ? {} : { maxNodes: o.maxNodes }) },
+    undefined,
+    { refine: (ways, search) => annealWays(ways, search, o) },
+  );
+}
+
+/**
+ * The router strategy `annealing` (RULE-021), 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 annealingStrategy: Strategy<"router", AnnealingOptions> = defineStrategy({
+  step: "router",
+  name: "annealing",
+  describe: "Simulated annealing over candidate routes (RULE-021, with WILD-028). Each edge picks one of a few ways, for less ink and fewer crossings.",
+  defaults: { ...ANNEALING_DEFAULTS },
+  schema: ANNEALING_SCHEMA,
+  maxNodes: 10_000,
+  run: (graph: Graph, o: Readonly<AnnealingOptions>): Result => annealingRouter({ ...o, name: "annealing", rule: byCollection }).route(graph),
+});

package/src/routers/frames.ts

@@ -1,7 +1,8 @@
 import { center, dist, type Box, type Point } from "../geom.ts";
-import { nodeIndex, type Graph, type InnerEdge, type Node, type Route } from "../model.ts";
+import { fixedPortPoint, nodeIndex, type Graph, type InnerEdge, type Node, type Route } from "../model.ts";
 import { placePlug, type Plug } from "../plugs.ts";
 import { WayFinder, type WayOptions } from "../ways.ts";
+import { gutterRoutes, type GutterEdge } from "./gutter.ts";
 
 /**
  * The rule for a node box that is not fully inside the box of its frame.
@@ -10,12 +11,22 @@ import { WayFinder, type WayOptions } from "../ways.ts";
  */
 export type Outside = "throw" | "skip" | "clamp";
 
-/** The options of the inner routes: the options of the way finder, the rule `outside` and the inset `frameInset`. */
+/**
+ * The mode of the inner routes. With `corners`, the corner graph gives each route, in the box of the frame smaller by `frameInset`.
+ * With `gutter`, each route is orthogonal in the free room of the frame box: the gaps between the nodes and the strips at the walls.
+ */
+export type InnerMode = "corners" | "gutter";
+
+/** The options of the inner routes: the options of the way finder, the rule `outside`, the inset `frameInset`, the mode `inner` and `bendCost`. */
 export interface FrameOptions extends WayOptions {
   /** The rule for a node box outside the box of its frame. The default is `throw`. */
   readonly outside?: Outside;
-  /** The distance from the walls of a frame to the bounds of its inner routes. The default is the margin of the router. */
+  /** The distance from the walls of a frame to the bounds of its inner routes. The default is the margin of the router. The mode `gutter` does not use it. */
   readonly frameInset?: number;
+  /** The mode of the inner routes. The default is `corners`. */
+  readonly inner?: InnerMode;
+  /** The cost of one bend of an inner route of the mode `gutter`, in units of length. The default is 16. */
+  readonly bendCost?: number;
 }
 
 /** The inside of one frame for the inner edges to one depth: the bounds, the way finder and the obstacles by id. */
@@ -41,6 +52,7 @@ export function frameRoutes(graph: Graph, inner: readonly InnerEdge[], options:
     if (list) list.push(n);
     else children.set(n.parent, [n]);
   }
+  if (options.inner === "gutter") return gutterFrameRoutes(inner, options, byId, children);
   const margin = options.margin ?? 5;
   const inset = options.frameInset ?? margin;
   const rooms = new Map<string, Room>();
@@ -48,9 +60,7 @@ export function frameRoutes(graph: Graph, inner: readonly InnerEdge[], options:
   for (const { edge, frame, plug } of inner) {
     const f = byId.get(frame)!;
     const [own, far] = plug === "source" ? [edge.source, edge.target] : [edge.target, edge.source];
-    // The nodes between the frame and the far end: each of them holds the far end, so it is not an obstacle.
-    const chain: string[] = [];
-    for (let p = byId.get(far.node)!.parent!; p !== frame; p = byId.get(p)!.parent!) chain.push(p);
+    const chain = chainOf(byId, frame, far.node);
     const key = JSON.stringify([frame, ...chain]);
     let room = rooms.get(key);
     if (!room) rooms.set(key, (room = makeRoom(f, chain, children, byId, inset, options)));
@@ -69,6 +79,51 @@ export function frameRoutes(graph: Graph, inner: readonly InnerEdge[], options:
   return routes;
 }
 
+/** This function gives the nodes between the frame and the far end, the nearest first. Each of them holds the far end, so it is not an obstacle. */
+function chainOf(byId: ReadonlyMap<string, Node>, frame: string, far: string): string[] {
+  const chain: string[] = [];
+  for (let p = byId.get(far)!.parent!; p !== frame; p = byId.get(p)!.parent!) chain.push(p);
+  return chain;
+}
+
+/**
+ * This function gives the inner routes of the mode `gutter`. The inner edges of one room route together, so that they share the gaps in lanes.
+ * A route is orthogonal, in the free room of the frame box. An edge without a way through the free room gets no route.
+ */
+function gutterFrameRoutes(inner: readonly InnerEdge[], options: FrameOptions, byId: ReadonlyMap<string, Node>, children: ReadonlyMap<string, readonly Node[]>): Route[] {
+  const rooms = new Map<string, { readonly nodes: Map<string, Node>; readonly items: { at: number; edge: GutterEdge }[]; readonly frame: Box }>();
+  const routes: (Route | undefined)[] = inner.map(() => undefined);
+  inner.forEach(({ edge, frame, plug }, at) => {
+    const f = byId.get(frame)!;
+    const [own, far] = plug === "source" ? [edge.source, edge.target] : [edge.target, edge.source];
+    const chain = chainOf(byId, frame, far.node);
+    const key = JSON.stringify([frame, ...chain]);
+    let room = rooms.get(key);
+    if (!room) rooms.set(key, (room = { nodes: roomNodes(f, chain, children, byId, f.box, options), items: [], frame: f.box }));
+    const end = room.nodes.get(far.node);
+    if (!end) return;
+    const fp = placePlug(f, own, center(end.box));
+    const port = fixedPortPoint(end, far) === undefined ? undefined : placePlug(end, far, fp.point);
+    const side = far.port === undefined ? undefined : end.ports?.find((p) => p.id === far.port)?.side;
+    room.items.push({ at, edge: { plug: fp, end, ...(port ? { port } : {}), ...(side ? { side } : {}) } });
+  });
+  for (const room of rooms.values()) {
+    const found = gutterRoutes(
+      room.frame,
+      [...room.nodes.values()],
+      room.items.map((i) => i.edge),
+      { laneGap: options.margin ?? 5, ...(options.bendCost === undefined ? {} : { bendCost: options.bendCost }) },
+    );
+    room.items.forEach(({ at }, k) => {
+      const points = found[k];
+      if (!points) return;
+      const { edge, frame, plug } = inner[at]!;
+      routes[at] = { edge: edge.id, points: plug === "source" ? points : points.reverse(), frame };
+    });
+  }
+  return routes.filter((r): r is Route => r !== undefined);
+}
+
 /** This function puts the plug of the wall before a way that starts on the bounds. A first point on the line of the stub goes. */
 function stub(plug: Point, way: Point[]): Point[] {
   const [a, b] = way;
@@ -86,6 +141,24 @@ function stub(plug: Point, way: Point[]): Point[] {
 function makeRoom(f: Node, chain: readonly string[], children: ReadonlyMap<string, readonly Node[]>, byId: ReadonlyMap<string, Node>, inset: number, options: FrameOptions): Room {
   const margin = options.margin ?? 5;
   const bounds = shrink(f.box, inset);
+  const nodes = roomNodes(f, chain, children, byId, bounds, options);
+  // The band of each wall starts half a margin outside the bounds, so that a way keeps in the bounds.
+  const w = shrink(bounds, -(margin / 2 + EPS));
+  const t = 2 * margin + 1;
+  const walls: Node[] = [
+    { x: w.x - t, y: w.y - t, w: w.w + 2 * t, h: t },
+    { x: w.x - t, y: w.y + w.h, w: w.w + 2 * t, h: t },
+    { x: w.x - t, y: w.y, w: t, h: w.h },
+    { x: w.x + w.w, y: w.y, w: t, h: w.h },
+  ].map((box, i) => ({ id: `\u0000wall${i}`, box }));
+  return { ways: new WayFinder([...nodes.values(), ...walls], options), nodes };
+}
+
+/**
+ * This function gives the obstacles of a room by id. They are the children of the frame and of each node of the chain, but not the chain.
+ * It applies the rule `outside` to each box outside the box of its holder. The rule `clamp` cuts such a box to `bounds`.
+ */
+function roomNodes(f: Node, chain: readonly string[], children: ReadonlyMap<string, readonly Node[]>, byId: ReadonlyMap<string, Node>, bounds: Box, options: FrameOptions): Map<string, Node> {
   const skip = new Set(chain);
   const nodes = new Map<string, Node>();
   for (const holder of [f.id, ...chain]) {
@@ -104,16 +177,7 @@ function makeRoom(f: Node, chain: readonly string[], children: ReadonlyMap<strin
       if (cut) nodes.set(n.id, { ...n, box: cut, ...(n.ports ? { ports: n.ports.map((p) => (p.at ? { ...p, at: { x: p.at.x + n.box.x - cut.x, y: p.at.y + n.box.y - cut.y } } : p)) } : {}) });
     }
   }
-  // The band of each wall starts half a margin outside the bounds, so that a way keeps in the bounds.
-  const w = shrink(bounds, -(margin / 2 + EPS));
-  const t = 2 * margin + 1;
-  const walls: Node[] = [
-    { x: w.x - t, y: w.y - t, w: w.w + 2 * t, h: t },
-    { x: w.x - t, y: w.y + w.h, w: w.w + 2 * t, h: t },
-    { x: w.x - t, y: w.y, w: t, h: w.h },
-    { x: w.x + w.w, y: w.y, w: t, h: w.h },
-  ].map((box, i) => ({ id: `\u0000wall${i}`, box }));
-  return { ways: new WayFinder([...nodes.values(), ...walls], options), nodes };
+  return nodes;
 }
 
 /** This function gives the box, smaller by `d` on each side. A negative `d` makes it larger. */