@mark1russell7/highways 0.9.3 → 0.9.5

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/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. */