@mark1russell7/highways 0.4.1 → 0.5.0

package/src/highways/edge-paths/index.ts

@@ -0,0 +1,155 @@
+import { center, dist, type Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The options of the highway strategy `edge-paths` (HWY-012 of the note on highways). */
+export interface EdgePathOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** An edge takes a path of other edges only when the path is this many times its own length or less. The default is 2. */
+  readonly distortion: number;
+  /** The weight of a link in the search is its length to this power. A larger power prefers paths of many short links. The default is 2. */
+  readonly power: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `edge-paths`. */
+export const EDGE_PATH_DEFAULTS: Readonly<Required<Omit<EdgePathOptions, "margin" | "k">>> = Object.freeze({ distortion: 2, power: 2, minSize: 2 });
+
+/** One step of the path of an edge: the edge of the step and `true` when the path goes from its target to its source. */
+export interface PathStep {
+  readonly edge: string;
+  readonly back: boolean;
+}
+
+/**
+ * This function gives the edge paths of the graph (Wallinger and others 2022). The edges go in the order of their lengths, the longest first.
+ * An edge looks for the shortest path of other edges between its nodes, with the weight `length ^ power`. A path is good when its length is `distortion` times the length of the edge or less.
+ * The edges of a good path lock: they keep their own ways. An edge with a good path leaves the graph of the search. The map holds the path of each such edge.
+ */
+export function edgePaths(input: HighwayInput, o: Readonly<Pick<EdgePathOptions, "distortion" | "power">>): Map<string, PathStep[]> {
+  const nodes = new Map(input.graph.nodes.map((n) => [n.id, center(n.box)] as const));
+  const links = input.graph.edges
+    .filter((e) => e.source.node !== e.target.node && nodes.has(e.source.node) && nodes.has(e.target.node))
+    .map((e) => ({ id: e.id, s: e.source.node, t: e.target.node, len: dist(nodes.get(e.source.node)!, nodes.get(e.target.node)!) }));
+  const around = new Map<string, number[]>();
+  links.forEach((l, i) => {
+    for (const n of [l.s, l.t]) {
+      const list = around.get(n);
+      if (list) list.push(i);
+      else around.set(n, [i]);
+    }
+  });
+  const order = links.map((_, i) => i).sort((a, b) => links[b]!.len - links[a]!.len || (links[a]!.id < links[b]!.id ? -1 : 1));
+  const skip = new Uint8Array(links.length);
+  const lock = new Uint8Array(links.length);
+  const paths = new Map<string, PathStep[]>();
+  for (const i of order) {
+    if (lock[i]) continue;
+    const e = links[i]!;
+    skip[i] = 1;
+    const path = shortest(e.s, e.t, links, around, skip, o.power, o.distortion * e.len);
+    if (!path) {
+      skip[i] = 0;
+      continue;
+    }
+    for (const step of path) lock[step.index] = 1;
+    paths.set(e.id, path.map((step) => ({ edge: links[step.index]!.id, back: step.back })));
+  }
+  return paths;
+}
+
+/** This function gives the shortest path (Dijkstra) from the node `from` to the node `to` over the links that do not skip. It gives `undefined` when the length is more than `limit`. */
+function shortest(
+  from: string,
+  to: string,
+  links: readonly { s: string; t: string; len: number }[],
+  around: ReadonlyMap<string, readonly number[]>,
+  skip: Uint8Array,
+  power: number,
+  limit: number,
+): { index: number; back: boolean }[] | undefined {
+  const cost = new Map<string, number>([[from, 0]]);
+  const via = new Map<string, { index: number; back: boolean; prev: string }>();
+  const done = new Set<string>();
+  const open: { node: string; c: number }[] = [{ node: from, c: 0 }];
+  while (open.length > 0) {
+    let k = 0;
+    for (let j = 1; j < open.length; j++) if (open[j]!.c < open[k]!.c || (open[j]!.c === open[k]!.c && open[j]!.node < open[k]!.node)) k = j;
+    const { node } = open.splice(k, 1)[0]!;
+    if (done.has(node)) continue;
+    done.add(node);
+    if (node === to) break;
+    for (const index of around.get(node) ?? []) {
+      if (skip[index]) continue;
+      const l = links[index]!;
+      const back = l.t === node;
+      const next = back ? l.s : l.t;
+      if (done.has(next)) continue;
+      const c = cost.get(node)! + Math.pow(Math.max(l.len, 1e-9), power);
+      if (c < (cost.get(next) ?? Infinity)) {
+        cost.set(next, c);
+        via.set(next, { index, back, prev: node });
+        open.push({ node: next, c });
+      }
+    }
+  }
+  if (!via.has(to)) return undefined;
+  const out: { index: number; back: boolean }[] = [];
+  let length = 0;
+  for (let n = to; n !== from; ) {
+    const v = via.get(n)!;
+    out.push({ index: v.index, back: v.back });
+    length += links[v.index]!.len;
+    n = v.prev;
+  }
+  if (length > limit) return undefined;
+  return out.reverse();
+}
+
+/**
+ * This function gives the highways of the edge paths (HWY-012). An edge with a good path follows the ways of the edges of its path.
+ * Each edge of the path keeps its own way through the corner graph. So the ways share their links, and each shared stretch is a highway.
+ */
+export function edgePathPlan(input: HighwayInput, o: Readonly<EdgePathOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const corners = finder.corners;
+  const plugs = edgePlugs(input.graph);
+  const own = new Map<string, Point[]>();
+  for (const { edge, ps, pt } of plugs) {
+    const a = finder.out(ps);
+    const b = finder.out(pt);
+    own.set(edge.id, corners.path(a, b) ?? [a, b]);
+  }
+  const paths = edgePaths(input, o);
+  const ways: KeyedWay[] = [];
+  for (const { edge, ps, pt } of plugs) {
+    const path = paths.get(edge.id);
+    if (!path) {
+      ways.push({ edge: edge.id, key: "", points: own.get(edge.id)! });
+      continue;
+    }
+    const points: Point[] = [];
+    const join = (to: Point): void => {
+      const last = points[points.length - 1];
+      if (!last) {
+        points.push(to);
+        return;
+      }
+      if (dist(last, to) <= 1e-9) return;
+      const link = corners.path(last, to) ?? [last, to];
+      points.push(...link.slice(1));
+    };
+    join(finder.out(ps));
+    for (const step of path) {
+      const way = own.get(step.edge) ?? [];
+      const along = step.back ? [...way].reverse() : way;
+      if (along.length === 0) continue;
+      join(along[0]!);
+      points.push(...along.slice(1));
+    }
+    join(finder.out(pt));
+    ways.push({ edge: edge.id, key: "", points });
+  }
+  return sharedStretches(ways, { minSize: o.minSize, pull: (p) => corners.pull(p) });
+}

package/src/highways/fixtures.test-util.ts

@@ -0,0 +1,71 @@
+import { expect, it } from "vitest";
+import { checkProperties } from "../bench/properties.ts";
+import { inputGraph } from "../bench/screen/forms.ts";
+import { screenInputs } from "../bench/screen/set.ts";
+import { CASES } from "../cases.ts";
+import type { Box } from "../geom.ts";
+import type { Graph } from "../model.ts";
+import { STRATEGIES } from "../strategies/builtins.ts";
+import { getStrategy } from "../strategies/model.ts";
+import { checkPlan, type HighwayInput, type HighwayPlan } from "./model.ts";
+import { highwayRouterStrategy } from "./router.ts";
+
+/** This function gives a box at `x`, `y` with the size `w` by `h`. */
+export const box = (x: number, y: number, w = 40, h = 20): Box => ({ x, y, w, h });
+
+/** The case `case-hub-chain`. */
+export const hub: Graph = CASES.find((c) => c.name === "case-hub-chain")!.make();
+
+/** The input `screen-v1/small-clustered/s0`. */
+export const clustered: Graph = inputGraph(screenInputs().find((i) => i.id === "screen-v1/small-clustered/s0")!);
+
+/** Three edges from one area on the left to one area on the right (one of them reversed), and two edges from the top to the bottom. Two keys alternate. */
+export const flows: Graph = {
+  nodes: [
+    ...[0, 1, 2].flatMap((i) => [
+      { id: `l${i}`, box: box(0, 30 * i) },
+      { id: `r${i}`, box: box(600, 30 * i) },
+    ]),
+    ...[0, 1].flatMap((i) => [
+      { id: `u${i}`, box: box(250 + 60 * i, -400) },
+      { id: `d${i}`, box: box(250 + 60 * i, 400) },
+    ]),
+  ],
+  edges: [
+    { id: "a", source: { node: "l0" }, target: { node: "r0" }, data: { collection: "p" } },
+    { id: "b", source: { node: "l1" }, target: { node: "r1" }, data: { collection: "q" } },
+    { id: "c", source: { node: "r2" }, target: { node: "l2" }, data: { collection: "p" } },
+    { id: "x", source: { node: "u0" }, target: { node: "d0" }, data: { collection: "p" } },
+    { id: "y", source: { node: "u1" }, target: { node: "d1" }, data: { collection: "q" } },
+  ],
+};
+
+/** Three thin nodes on the left and three on the right, with three near horizontal edges between them. */
+export const parallel: Graph = {
+  nodes: [0, 1, 2].flatMap((i) => [
+    { id: `l${i}`, box: box(0, 8 * i, 40, 6) },
+    { id: `r${i}`, box: box(600, 8 * i, 40, 6) },
+  ]),
+  edges: [0, 1, 2].map((i) => ({ id: `e${i}`, source: { node: `l${i}` }, target: { node: `r${i}` } })),
+};
+
+/**
+ * This function adds the common tests of a highway strategy. The strategy is in the registry, and it gives a correct plan the same each time.
+ * Its routes break no hard rule after `follow`.
+ */
+export function commonTests<O extends object>(name: string, defaults: O, plan: (input: HighwayInput, o: O) => HighwayPlan, graphs: readonly Graph[]): void {
+  it("is in the registry, and gives a correct plan, the same each time", () => {
+    const strategy = getStrategy(STRATEGIES, "highway", name);
+    for (const graph of [...graphs, hub, clustered]) {
+      const made = strategy.run({ graph }, { ...defaults });
+      expect(checkPlan(graph, made)).toEqual([]);
+      expect(plan({ graph }, defaults)).toEqual(made);
+    }
+  });
+
+  it("gives routes with no break of a hard rule after follow", () => {
+    const router = highwayRouterStrategy(getStrategy(STRATEGIES, "highway", name));
+    expect(checkProperties(hub, router.run(hub), 1_000_000)).toEqual([]);
+    expect(checkProperties(clustered, router.run(clustered), 1_000_000)).toEqual([]);
+  });
+}

package/src/highways/flow-clusters/index.ts

@@ -0,0 +1,143 @@
+import { dist, type Point } from "../../geom.ts";
+import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs } from "../stretches.ts";
+
+/** The linkage of the hierarchical clustering: the distance of two clusters from the distances of their edges. */
+export type Linkage = "average" | "complete" | "single";
+
+/** The values of `Linkage`. */
+export const LINKAGES: readonly Linkage[] = Object.freeze(["average", "complete", "single"]);
+
+/** The options of the highway strategy `flow-clusters` (HWY-023 of the note on highways). */
+export interface FlowClusterOptions {
+  /** Two clusters join while their distance is this value or less. The distance is a share of the length of the shorter edge. The default is 0.3. */
+  readonly tau: number;
+  /** The linkage. The default is `average`. */
+  readonly linkage: Linkage;
+  /** With `true`, the source of one edge only compares with the source of the other edge. The default is `false`. */
+  readonly directed: boolean;
+  /** A cluster with this number of edges or more gets highways. The default is 2. */
+  readonly minSize: number;
+  /** The spine of each cluster. The default is `trunk`: one flow line from one area to the other area. */
+  readonly spine: GroupSpine;
+}
+
+/** The default options of the strategy `flow-clusters`. */
+export const FLOW_CLUSTER_DEFAULTS: Readonly<FlowClusterOptions> = Object.freeze({ tau: 0.3, linkage: "average", directed: false, minSize: 2, spine: "trunk" });
+
+/** The largest number of edges in one distance matrix. A larger graph splits into blocks of edges in the order of their sources. */
+const BLOCK = 2500;
+
+/**
+ * This function gives the flow distance of two edges (Zhu and Guo 2014): `max(|s_e - s_f|, |t_e - t_f|) / min(len e, len f)`.
+ * Without `directed`, it is the smaller value of the two directions of `f`, and `flip` is `true` when the opposite direction is smaller.
+ */
+export function flowDistance(s1: Point, t1: Point, s2: Point, t2: Point, directed: boolean): { d: number; flip: boolean } {
+  const len = Math.max(1e-9, Math.min(dist(s1, t1), dist(s2, t2)));
+  const direct = Math.max(dist(s1, s2), dist(t1, t2)) / len;
+  if (directed) return { d: direct, flip: false };
+  const back = Math.max(dist(s1, t2), dist(t1, s2)) / len;
+  return back < direct ? { d: back, flip: true } : { d: direct, flip: false };
+}
+
+/**
+ * This function clusters the points of a distance matrix with the chain of nearest neighbours. The linkage is reducible, so the chain gives the same tree as the greedy order.
+ * The clusters join while their distance is `tau` or less. The function gives the cluster of each point, as the index of a point of the cluster.
+ */
+export function chainClusters(n: number, d: Float64Array, tau: number, linkage: Linkage): Int32Array {
+  const size = new Int32Array(n).fill(1);
+  const alive = new Uint8Array(n).fill(1);
+  const parent = new Int32Array(n);
+  for (let i = 0; i < n; i++) parent[i] = i;
+  // A cluster that has no neighbour within `tau` is done: under a reducible linkage, its distances only grow.
+  const done = new Uint8Array(n);
+  const find = (i: number): number => {
+    while (parent[i] !== i) i = parent[i] = parent[parent[i]!]!;
+    return i;
+  };
+  const chain: number[] = [];
+  for (;;) {
+    if (chain.length === 0) {
+      let start = -1;
+      for (let i = 0; i < n && start < 0; i++) if (alive[i] && !done[i]) start = i;
+      if (start < 0) break;
+      chain.push(start);
+    }
+    const a = chain[chain.length - 1]!;
+    let b = -1;
+    let best = Infinity;
+    for (let j = 0; j < n; j++) {
+      if (j === a || !alive[j] || done[j]) continue;
+      const v = d[a * n + j]!;
+      if (v < best || (v === best && j < b)) [best, b] = [v, j];
+    }
+    const prev = chain.length >= 2 ? chain[chain.length - 2]! : -1;
+    if (b < 0 || best > tau) {
+      done[a] = 1;
+      chain.length = 0;
+      continue;
+    }
+    if (prev >= 0 && d[a * n + prev]! <= best) {
+      // `a` and `prev` are nearest neighbours of each other: they join.
+      chain.length -= 2;
+      const [i, j] = a < prev ? [a, prev] : [prev, a];
+      for (let k = 0; k < n; k++) {
+        if (!alive[k] || k === i || k === j) continue;
+        const di = d[i * n + k]!;
+        const dj = d[j * n + k]!;
+        const v = linkage === "single" ? Math.min(di, dj) : linkage === "complete" ? Math.max(di, dj) : (size[i]! * di + size[j]! * dj) / (size[i]! + size[j]!);
+        d[i * n + k] = v;
+        d[k * n + i] = v;
+      }
+      size[i] = size[i]! + size[j]!;
+      alive[j] = 0;
+      parent[j] = i;
+      continue;
+    }
+    chain.push(b);
+  }
+  const out = new Int32Array(n);
+  for (let i = 0; i < n; i++) out[i] = find(i);
+  return out;
+}
+
+/**
+ * This function gives the flow clusters of the edges (HWY-023). It clusters the edges as points in 4D, with the cut at `tau`.
+ * Each edge of a cluster gets the key of the cluster. It gets `flip` when it goes opposite to the first edge of the cluster.
+ */
+export function flowClusters(input: HighwayInput, o: Readonly<FlowClusterOptions>): Map<string, EdgeGroup> {
+  const ends = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({ edge: edge.id, s: ps.point, t: pt.point }));
+  const groups = new Map<string, EdgeGroup>();
+  // A large graph splits into blocks of `BLOCK` edges, in the order of the x of the sources.
+  const order = ends.length > BLOCK ? [...ends].sort((a, b) => a.s.x - b.s.x || a.s.y - b.s.y || (a.edge < b.edge ? -1 : 1)) : ends;
+  for (let from = 0; from < order.length; from += BLOCK) {
+    const block = order.slice(from, from + BLOCK);
+    const n = block.length;
+    const d = new Float64Array(n * n);
+    for (let i = 0; i < n; i++)
+      for (let j = i + 1; j < n; j++) {
+        const v = flowDistance(block[i]!.s, block[i]!.t, block[j]!.s, block[j]!.t, o.directed).d;
+        d[i * n + j] = v;
+        d[j * n + i] = v;
+      }
+    const cluster = chainClusters(n, d, o.tau, o.linkage);
+    const first = new Map<number, number>();
+    block.forEach((e, i) => {
+      const c = cluster[i]!;
+      if (!first.has(c)) first.set(c, i);
+      const lead = block[first.get(c)!]!;
+      const flip = i === first.get(c) ? false : flowDistance(lead.s, lead.t, e.s, e.t, o.directed).flip;
+      groups.set(e.edge, { key: `f${from + first.get(c)!}`, flip });
+    });
+  }
+  return groups;
+}
+
+/**
+ * This function gives the highways of the flow clusters (HWY-023). The clusters of `flowClusters` with `minSize` edges or more get highways.
+ * With the spine `trunk`, each cluster gets one trunk from one area to the other area. With `shared`, the edges of a cluster share their ways.
+ */
+export function flowClusterPlan(input: HighwayInput, o: Readonly<FlowClusterOptions>): HighwayPlan {
+  return groupedPlan(input, flowClusters(input, o), { spine: o.spine, minSize: o.minSize });
+}

package/src/highways/flow-field/index.ts

@@ -0,0 +1,49 @@
+import type { Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { edgePlugs, sharedStretches, type KeyedWay } from "../stretches.ts";
+
+/** The end of the edges that gets a field: the target of a fan-in, or the source of a fan-out. */
+export type FieldEnd = "target" | "source";
+
+/** The options of the highway strategy `flow-field` (EDA-046 with HWY-037 of the notes). */
+export interface FlowFieldOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** An end with this number of edges or more on one side of its box gets a field. The default is 2. */
+  readonly minFanIn: number;
+  /** The end that gets a field. The default is `target`. */
+  readonly end: FieldEnd;
+}
+
+/** The default options of the strategy `flow-field`. */
+export const FLOW_FIELD_DEFAULTS: Readonly<Required<Omit<FlowFieldOptions, "margin" | "k">>> = Object.freeze({ minFanIn: 2, end: "target" });
+
+/**
+ * This function gives the highways of a flow field for each target (EDA-046, HWY-037).
+ * The edges into one side of one box make a fan. The root of the fan is the point out of the median plug of the fan.
+ * Each edge of the fan goes the shortest way from the point out of its other plug to the root, through the corner graph.
+ * The shortest ways to one root make a tree, so they merge like streams and do not cross. Each stretch that two ways share is one highway.
+ * With the end `source`, the same holds for the edges out of one side of one box.
+ */
+export function flowFieldPlan(input: HighwayInput, o: Readonly<FlowFieldOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes, { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) });
+  const fans = new Map<string, { edge: string; root: Point; far: Point; along: number }[]>();
+  for (const { edge, ps, pt } of edgePlugs(input.graph)) {
+    const [near, far, node] = o.end === "target" ? [pt, ps, edge.target.node] : [ps, pt, edge.source.node];
+    const key = `${node}\u0000${near.normal.x},${near.normal.y}`;
+    const item = { edge: edge.id, root: finder.out(near), far: finder.out(far), along: near.normal.x === 0 ? near.point.x : near.point.y };
+    const list = fans.get(key);
+    if (list) list.push(item);
+    else fans.set(key, [item]);
+  }
+  const ways: KeyedWay[] = [];
+  for (const [key, fan] of fans) {
+    if (fan.length < Math.max(2, o.minFanIn)) continue;
+    const sorted = [...fan].sort((a, b) => a.along - b.along || (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : 0));
+    const root = sorted[Math.floor((sorted.length - 1) / 2)]!.root;
+    for (const f of fan) {
+      const way = finder.corners.path(f.far, root);
+      if (way) ways.push({ edge: f.edge, key, points: o.end === "target" ? way : [...way].reverse() });
+    }
+  }
+  return sharedStretches(ways, { minSize: 2, pull: (p) => finder.corners.pull(p) });
+}

package/src/highways/gates/ambiguity/index.ts

@@ -0,0 +1,110 @@
+import type { Graph } from "../../../model.ts";
+import type { HighwayInput, HighwayPlan } from "../../model.ts";
+import { keepMembers, type Gate } from "../model.ts";
+
+/** The options of the gate `ambiguity` (HWY-049). */
+export interface AmbiguityGuardOptions {
+  /** Two groups of edges merge only when the merge adds this share of false pairs, or less. The default is 0.5. */
+  readonly maxAmbiguity: number;
+  /** With `node`, the default, two groups merge only when they share an end node. With `any`, only `maxAmbiguity` decides. */
+  readonly link: "node" | "any";
+}
+
+/** The default options of the gate `ambiguity`. */
+export const AMBIGUITY_GUARD_DEFAULTS: Readonly<AmbiguityGuardOptions> = Object.freeze({ maxAmbiguity: 0.5, link: "node" });
+
+/** The adjacency of the nodes of a graph: the neighbours of each node, by the edges. */
+function adjacency(graph: Graph): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  const add = (a: string, b: string): void => {
+    const set = out.get(a);
+    if (set) set.add(b);
+    else out.set(a, new Set([b]));
+  };
+  for (const e of graph.edges) {
+    add(e.source.node, e.target.node);
+    add(e.target.node, e.source.node);
+  }
+  return out;
+}
+
+/**
+ * This function gives the ambiguity of a set of nodes: the share of the pairs of distinct nodes without an edge between them.
+ * The nodes are the ends of the edges of one highway. A set with fewer than two nodes gives 0.
+ */
+export function nodeAmbiguity(nodes: ReadonlySet<string>, adj: ReadonlyMap<string, ReadonlySet<string>>): number {
+  const n = nodes.size;
+  if (n < 2) return 0;
+  let linked = 0;
+  for (const v of nodes) for (const w of adj.get(v) ?? []) if (w !== v && nodes.has(w)) linked++;
+  return 1 - linked / 2 / ((n * (n - 1)) / 2);
+}
+
+/** A group of the members of one highway: the edges, their end nodes and the ambiguity of the nodes. */
+interface Group {
+  readonly edges: string[];
+  readonly nodes: Set<string>;
+  readonly amb: number;
+  /** The first lane of the group, for a fixed order. */
+  readonly first: number;
+}
+
+/**
+ * This function applies the ambiguity guard of HWY-049 to a plan. A highway joins edges that belong together.
+ *
+ * Two nodes are a false pair when their edges share a highway and no edge joins them. The ambiguity of a group of edges is the share of false pairs among the pairs of its end nodes.
+ * In each highway, each edge starts as a group. Two groups merge only when `amb(A ∪ B) - max(amb A, amb B)` is at most `maxAmbiguity`.
+ * With the link `node`, they also must share an end node. The merge with the smallest rise comes first.
+ *
+ * The largest group stays on the highway. The other edges leave it and go alone.
+ */
+export function ambiguityPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<AmbiguityGuardOptions>): HighwayPlan {
+  const adj = adjacency(input.graph);
+  const ends = new Map(input.graph.edges.map((e) => [e.id, [e.source.node, e.target.node] as const]));
+  const stay = new Map<string, Set<string>>();
+  for (const h of plan.highways) {
+    let groups: Group[] = h.lanes.flatMap((edge, i): Group[] => {
+      const end = ends.get(edge);
+      if (!end) return [];
+      const nodes = new Set(end);
+      return [{ edges: [edge], nodes, amb: nodeAmbiguity(nodes, adj), first: i }];
+    });
+    for (;;) {
+      let best: { a: number; b: number; rise: number; group: Group } | undefined;
+      for (let a = 0; a < groups.length; a++)
+        for (let b = a + 1; b < groups.length; b++) {
+          const ga = groups[a]!;
+          const gb = groups[b]!;
+          if (options.link === "node" && ![...gb.nodes].some((v) => ga.nodes.has(v))) continue;
+          const nodes = new Set([...ga.nodes, ...gb.nodes]);
+          const amb = nodeAmbiguity(nodes, adj);
+          const rise = amb - Math.max(ga.amb, gb.amb);
+          if (rise > options.maxAmbiguity + 1e-12) continue;
+          if (best === undefined || rise < best.rise - 1e-12)
+            best = { a, b, rise, group: { edges: [...ga.edges, ...gb.edges], nodes, amb, first: Math.min(ga.first, gb.first) } };
+        }
+      if (!best) break;
+      const merged = best.group;
+      const { a, b } = best;
+      groups = groups.filter((_, i) => i !== a && i !== b);
+      groups.push(merged);
+      groups.sort((p, q) => p.first - q.first);
+    }
+    let top: Group | undefined;
+    for (const g of groups) if (top === undefined || g.edges.length > top.edges.length) top = g;
+    stay.set(h.id, new Set(top?.edges ?? []));
+  }
+  return keepMembers(plan, (h, m) => stay.get(h.id)?.has(m.edge) ?? false);
+}
+
+/** The gate `ambiguity` (HWY-049): the ambiguity guard. A highway does not join edges whose end nodes have no edges between them. */
+export const ambiguityGate: Gate<AmbiguityGuardOptions> = {
+  name: "ambiguity",
+  describe: "The gate `ambiguity` (HWY-049) keeps on each highway the largest group of edges that a reader can tell apart. A merge of two groups must add few false pairs of nodes.",
+  defaults: AMBIGUITY_GUARD_DEFAULTS,
+  schema: {
+    maxAmbiguity: { type: "number", min: 0, max: 1, step: 0.05, marks: [0.3, 0.5], default: 0.5, describe: "Two groups merge only when the merge adds this share of false pairs, or less." },
+    link: { type: "enum", values: ["node", "any"], default: "node", describe: "With `node`, two groups merge only when they share an end node. With `any`, only `maxAmbiguity` decides." },
+  },
+  apply: (input, plan, options) => ambiguityPlan(input, plan, options),
+};

package/src/highways/gates/breakeven/index.ts

@@ -0,0 +1,62 @@
+import type { WayOptions } from "../../../ways.ts";
+import { lengthBetween, type HighwayInput, type HighwayPlan } from "../../model.ts";
+import { edgeLengths, keepMembers, type Gate } from "../model.ts";
+
+/** The options of the gate `breakeven` (HWY-047). */
+export interface BreakEvenOptions {
+  /**
+   * The exponent of the cost law: a stretch with `n` edges costs `n^shareAlpha` times its length. Each edge pays the share `n^(shareAlpha - 1)`.
+   * With 0, a shared stretch is one line, as the ink of B1 counts it. The default is 0.5, as the break-even floor of `corridors`.
+   */
+  readonly shareAlpha: number;
+}
+
+/** The default options of the gate `breakeven`. */
+export const BREAK_EVEN_DEFAULTS: Readonly<BreakEvenOptions> = Object.freeze({ shareAlpha: 0.5 });
+
+/**
+ * This function applies the break-even law of HWY-047 to a plan. An edge stays on its highways only when sharing saves ink.
+ *
+ * The edge pays `n^(shareAlpha - 1)` of each shared stretch, with `n` the members of the highway. Thus it saves `(1 - n^(shareAlpha - 1)) L` on a stretch of the length `L`.
+ * It adds the length of its route along the plan less the length of its route alone. An edge stays when the saving is as large as the added length.
+ * For two parallel edges at the gap `d`, this rule gives the break-even overlap `d √((2 + t) / (2 - t))` with `t = 2^shareAlpha`.
+ *
+ * An edge that does not save ink leaves each of its highways. Then the other members of those highways save less, so the test repeats until no edge leaves.
+ */
+export function breakEvenPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<BreakEvenOptions>, way: WayOptions = {}): HighwayPlan {
+  const lengths = edgeLengths(input.graph, plan, way);
+  let now = plan;
+  for (;;) {
+    const saving = new Map<string, number>();
+    for (const h of now.highways) {
+      const share = 1 - Math.pow(h.members.length, options.shareAlpha - 1);
+      for (const m of h.members) saving.set(m.edge, (saving.get(m.edge) ?? 0) + share * lengthBetween(h.spine, Math.min(m.on, m.off), Math.max(m.on, m.off)));
+    }
+    const out = new Set<string>();
+    for (const [edge, saved] of saving) {
+      const l = lengths.get(edge);
+      if (l && saved < l.route - l.alone) out.add(edge);
+    }
+    if (out.size === 0) return now;
+    now = keepMembers(now, (_, m) => !out.has(m.edge));
+  }
+}
+
+/** The gate `breakeven` (HWY-047): an edge stays on a highway only when sharing saves ink. */
+export const breakEvenGate: Gate<BreakEvenOptions> = {
+  name: "breakeven",
+  describe: "The gate `breakeven` (HWY-047) keeps an edge on a highway only when its share of the highway saves more ink than its detour adds.",
+  defaults: BREAK_EVEN_DEFAULTS,
+  schema: {
+    shareAlpha: {
+      type: "number",
+      min: 0,
+      max: 0.9,
+      step: 0.1,
+      marks: [0, 0.5],
+      default: 0.5,
+      describe: "The exponent of the cost law. An edge pays the share `n^(shareAlpha - 1)` of a stretch with `n` edges.",
+    },
+  },
+  apply: breakEvenPlan,
+};

package/src/highways/gates/hysteresis/index.ts

@@ -0,0 +1,48 @@
+import type { HighwayInput, HighwayPlan } from "../../model.ts";
+import { commonEdges, matchHighways, type Gate } from "../model.ts";
+
+/** The options of the gate `hysteresis` (HWY-046). */
+export interface HysteresisOptions {
+  /** A new highway needs this number of edges or more. The default is 3. */
+  readonly kOn: number;
+  /** A highway of the earlier plan stays while it has this number of edges or more. The default is 2. */
+  readonly kOff: number;
+}
+
+/** The default options of the gate `hysteresis`. */
+export const HYSTERESIS_DEFAULTS: Readonly<HysteresisOptions> = Object.freeze({ kOn: 3, kOff: 2 });
+
+/** Two highways of two plans are the same highway when the Jaccard index of their edges is this value or more. */
+export const SAME_HIGHWAY = 0.5;
+
+/**
+ * This function applies the count threshold with hysteresis of HWY-046 to a plan.
+ * A highway with `kOn` edges or more stays. A highway with fewer than `kOff` edges goes away.
+ * A highway between the two limits stays only when it was in the earlier plan, `input.previous`.
+ * The highway of the earlier plan with the most common edges is its match, with a Jaccard index of `SAME_HIGHWAY` or more.
+ *
+ * Thus an edit that adds or removes one edge near the limit does not make a highway come and go. Without an earlier plan, the limit is `kOn`.
+ */
+export function hysteresisPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<HysteresisOptions>): HighwayPlan {
+  const matched = input.previous ? matchHighways(input.previous.plan, plan, SAME_HIGHWAY, commonEdges(input.previous.graph, input.graph)) : new Map<number, number>();
+  const kOff = Math.max(2, Math.min(options.kOff, options.kOn));
+  const highways = plan.highways.filter((h, i) => {
+    const n = h.members.length;
+    if (n >= options.kOn) return true;
+    if (n < kOff) return false;
+    return matched.has(i);
+  });
+  return highways.length === plan.highways.length ? plan : { highways };
+}
+
+/** The gate `hysteresis` (HWY-046): a highway forms at `kOn` edges and goes away below `kOff` edges. */
+export const hysteresisGate: Gate<HysteresisOptions> = {
+  name: "hysteresis",
+  describe: "The gate `hysteresis` (HWY-046) keeps a new highway with `kOn` edges or more. A highway of the earlier plan stays while it has `kOff` edges or more.",
+  defaults: HYSTERESIS_DEFAULTS,
+  schema: {
+    kOn: { type: "integer", min: 2, max: 16, step: 1, default: 3, describe: "A new highway needs this number of edges or more." },
+    kOff: { type: "integer", min: 2, max: 16, step: 1, default: 2, describe: "A highway of the earlier plan stays while it has this number of edges or more." },
+  },
+  apply: (input, plan, options) => hysteresisPlan(input, plan, options),
+};