@mark1russell7/highways 0.4.1 → 0.4.2

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/src/bench/measures/highways.ts

@@ -0,0 +1,93 @@
+import { follow } from "../../highways/follow.ts";
+import { commonEdges, matchHighways } from "../../highways/gates/model.ts";
+import type { HighwayPlan } from "../../highways/model.ts";
+import { wayOptionsOf } from "../../highways/router.ts";
+import type { Graph } from "../../model.ts";
+import type { Strategy } from "../../strategies/model.ts";
+import { changeGraph, routeStability } from "./stability.ts";
+
+/**
+ * This function gives the churn of the highways over one edit (Z10 for highways, from HWY-046). Two edges are a pair when they share a highway.
+ * The churn is the share of the pairs that come or go: `|P ∆ P'| / |P ∪ P'|`. Only the edges of `edges` count, for example the edges of both graphs.
+ * Two plans without pairs give 0. The scale is 0 to 1, and lower is better.
+ */
+export function highwayChurn(before: HighwayPlan, after: HighwayPlan, edges: ReadonlySet<string>): number {
+  const pairs = (plan: HighwayPlan): Set<string> => {
+    const out = new Set<string>();
+    for (const h of plan.highways) {
+      const list = [...new Set(h.members.map((m) => m.edge).filter((e) => edges.has(e)))].sort();
+      for (let i = 0; i < list.length; i++) for (let j = i + 1; j < list.length; j++) out.add(`${list[i]}\u0000${list[j]}`);
+    }
+    return out;
+  };
+  const a = pairs(before);
+  const b = pairs(after);
+  let common = 0;
+  for (const p of a) if (b.has(p)) common++;
+  const all = a.size + b.size - common;
+  return all === 0 ? 0 : (all - common) / all;
+}
+
+/** The match of the highways over one edit. */
+export interface HighwayIdKeep {
+  /** The number of new highways with a match in the old plan: a Jaccard index of their edges of 0.5 or more. */
+  readonly matched: number;
+  /** The number of matched highways that keep the id of their match. */
+  readonly kept: number;
+  /** `kept / matched`, or `NaN` without a match. The scale is 0 to 1, and higher is better. */
+  readonly share: number;
+}
+
+/**
+ * This function tells how many highways keep their id over one edit (HWY-054). It matches the new highways with the old ones by `matchHighways`, with the index 0.5.
+ * A matched highway keeps its id when its id is the id of its match. Only the edges of `edges` count.
+ */
+export function highwayIdKeep(before: HighwayPlan, after: HighwayPlan, edges: ReadonlySet<string>): HighwayIdKeep {
+  const match = matchHighways(before, after, 0.5, edges);
+  let kept = 0;
+  for (const [i, i0] of match) if (after.highways[i]!.id === before.highways[i0]!.id) kept++;
+  return { matched: match.size, kept, share: match.size === 0 ? Number.NaN : kept / match.size };
+}
+
+/** The stability of a highway strategy over a seeded sequence of edits. Each value is the mean over the edits. */
+export interface HighwayEdits {
+  /** The mean Fréchet distance of the routes over one edit, in units of the board (Z10). */
+  readonly mean: number;
+  /** The share of the routes that move over one edit (Z10). */
+  readonly moved: number;
+  /** The churn of the highways over one edit (`highwayChurn`). */
+  readonly churn: number;
+  /** The share of the matched highways that keep their id over one edit (`highwayIdKeep`), or `NaN` without a match. */
+  readonly ids: number;
+}
+
+/**
+ * This function measures a highway strategy over a sequence of `edits` seeded edits. Each edit is the small change of `changeGraph` with the seed `seed + i`.
+ * The strategy gets the graph and its plan before the edit as `previous`, so a strategy with memory can keep its highways.
+ * `follow` routes each plan with the way options of the strategy. The same graph, strategy, options and seed give the same values.
+ */
+export function highwayEdits(graph: Graph, strategy: Strategy<"highway", object>, options: object | undefined, edits: number, seed = 1): HighwayEdits {
+  const way = wayOptionsOf({ ...strategy.defaults, ...options });
+  let g = graph;
+  let plan = strategy.run({ graph: g }, options);
+  let routes = follow(g, plan, way);
+  const mean: number[] = [];
+  const moved: number[] = [];
+  const churn: number[] = [];
+  const ids: number[] = [];
+  for (let i = 0; i < edits; i++) {
+    const next = changeGraph(g, seed + i).graph;
+    const p = strategy.run({ graph: next, previous: { graph: g, plan } }, options);
+    const r = follow(next, p, way);
+    const s = routeStability(g, routes, r, { seed });
+    const edges = commonEdges(g, next);
+    mean.push(s.mean);
+    moved.push(s.moved);
+    churn.push(highwayChurn(plan, p, edges));
+    const keep = highwayIdKeep(plan, p, edges);
+    if (keep.matched > 0) ids.push(keep.share);
+    [g, plan, routes] = [next, p, r];
+  }
+  const avg = (v: readonly number[]): number => (v.length === 0 ? Number.NaN : v.reduce((a, b) => a + b, 0) / v.length);
+  return { mean: avg(mean), moved: avg(moved), churn: avg(churn), ids: avg(ids) };
+}

package/src/bench/measures/index.ts

@@ -8,3 +8,4 @@ export * from "./stability.ts";
 export * from "./room.ts";
 export * from "./pareto.ts";
 export * from "./order.ts";
+export * from "./highways.ts";

package/src/bench/screen/measures.ts

@@ -68,6 +68,11 @@ const ROWS: readonly Row[] = [
   ["Z10.base.mean", "Z10", "route.stability.base.mean", "units of the board", "lower", false],
   ["Z10.base.max", "Z10", "route.stability.base.max", "units of the board", "lower", false],
   ["Z10.base.moved", "Z10", "route.stability.base.moved", "0 to 1", "lower", false],
+  // The stability of a highway strategy over a sequence of seeded edits, with its plan before each edit (the screen option `edits`).
+  ["Z10.edits.mean", "Z10", "route.stability.edits.mean", "units of the board", "lower", false],
+  ["Z10.edits.moved", "Z10", "route.stability.edits.moved", "0 to 1", "lower", false],
+  ["Z10.churn", "Z10", "route.stability.highway-churn", "0 to 1", "lower", false],
+  ["Z10.ids", "Z10", "route.stability.highway-ids", "0 to 1", "higher", false],
   // The zoom levels and the groups. The default grouping rule reads the positions, so most of these measures depend on the placement.
   ["level-nesting", "Z6", "route.level.nesting", "count", "lower", false],
   ["Z3.through", "Z3", "route.level.through", "count", "lower", true],

package/src/bench/screen/screen.ts

@@ -6,6 +6,7 @@ import { STRATEGIES } from "../../strategies/builtins.ts";
 import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS, type AnyStrategy, type Registry, type Strategy } from "../../strategies/model.ts";
 import { compareStep, type CompareRow, type CompareStep, type StepComparison } from "../compare.ts";
 import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
+import { highwayEdits } from "../measures/highways.ts";
 import { orderFragility } from "../measures/order.ts";
 import { paretoFront, type Objective } from "../measures/pareto.ts";
 import { routeStability } from "../measures/stability.ts";
@@ -84,6 +85,12 @@ export interface ScreenOptions {
    * The default is 0: no measure of the order fragility. The steps `group` and `curve` do not read it.
    */
   readonly shuffles?: number;
+  /**
+   * The number of seeded edits of the step `highway` (BUILD-W2A). Each highway strategy runs again after each edit of `highwayEdits`, with its plan before the edit.
+   * The records then get `Z10.edits.*`, the churn of the highways and the share of the highways that keep their id.
+   * The default is 0: no edits. The other steps and the base routers do not read it.
+   */
+  readonly edits?: number;
   /** The commit of the code, for the records. */
   readonly commit?: string;
   /** The predictions of the run. Each record names the first prediction with its strategy, its set and its input. */
@@ -295,6 +302,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
   }
   const shuffles = givesRoutes(step) ? Math.max(0, Math.floor(options.shuffles ?? 0)) : 0;
   const seed = options.seed ?? 1;
+  const edits = step === "highway" ? Math.max(0, Math.floor(options.edits ?? 0)) : 0;
+  const plans = new Map(listStrategies(screened.registry, "highway").map((s) => [s.name, s]));
   const log = options.log ?? ((): void => {});
   const families = options.families;
   const inputs = (options.inputs ?? screenInputs(set)).filter((i) => families?.includes(i.family) ?? true);
@@ -346,6 +355,11 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
         const f = orderFragility(graph, (g) => router.route(g), { orders: shuffles, seed, base: row.result });
         Object.assign(values, { "W3.crossings": f.crossings, "W3.detour": f.detour, "W3.inkSaved": f.inkSaved, "W3.ink": f.ink, "W3.changed": f.changed, "W3.poa": f.poa });
       }
+      const plan = edits > 0 && row.result ? plans.get(row.strategy) : undefined;
+      if (plan) {
+        const z = highwayEdits(graph, plan, own[row.strategy], edits, seed);
+        Object.assign(values, { "Z10.edits.mean": z.mean, "Z10.edits.moved": z.moved, "Z10.churn": z.churn, "Z10.ids": z.ids });
+      }
       const record = { ...head, measures: named(values), hard, tolerance: { through: TOLERANCE }, deterministic, ms: row.ms, ...tail };
       records.push(record);
       if (givesRoutes(step) && input.base !== undefined && row.result) variants.push({ record, base: input.base, result: row.result });

package/src/highways/base.ts

@@ -0,0 +1,126 @@
+import { dist, type Point } from "../geom.ts";
+import type { Graph, Result, Route } from "../model.ts";
+import { byCollection } from "../routers/trunks.ts";
+import { CORRIDOR_DEFAULTS, corridorPlan } from "./corridors/index.ts";
+import { follow } from "./follow.ts";
+import type { Highway, HighwayInput, HighwayMember, HighwayPlan } from "./model.ts";
+import { sharedWaysPlan } from "./shared-ways/index.ts";
+
+/**
+ * The plan that a post step changes. `none` is the empty plan: `follow` then routes each edge as the router `corners` does.
+ * `shared-ways` and `corridors` are the plans of those highway strategies, with their defaults.
+ */
+export type HighwayBase = "none" | "shared-ways" | "corridors";
+
+/** The values of `HighwayBase`. */
+export const HIGHWAY_BASES: readonly HighwayBase[] = Object.freeze(["none", "shared-ways", "corridors"]);
+
+/** This function gives the plan of a base. */
+export function basePlan(input: HighwayInput, base: HighwayBase): HighwayPlan {
+  if (base === "shared-ways") return sharedWaysPlan(input, { rule: byCollection });
+  if (base === "corridors") return corridorPlan(input, CORRIDOR_DEFAULTS);
+  return { highways: [] };
+}
+
+/** This function gives the routes of a plan after `follow`, with the default way finder. The plan `none` gives the first routes of the edges. */
+export function planRoutes(graph: Graph, plan: HighwayPlan): Result {
+  return follow(graph, plan);
+}
+
+/** This function gives the first route of each edge: the route of `input.routes`, or the route of the empty plan after `follow`. */
+export function firstRoutes(input: HighwayInput): Map<string, readonly Point[]> {
+  const given = routeIndex(input.routes?.routes ?? []);
+  const known = new Set(input.graph.edges.map((e) => e.id));
+  if (input.graph.edges.every((e) => given.has(e.id))) return given;
+  const made = routeIndex(planRoutes(input.graph, { highways: [] }).routes);
+  for (const [edge, points] of given) if (known.has(edge)) made.set(edge, points);
+  return made;
+}
+
+/** One stop of the trip of an edge: the index of the highway in the plan, and the member. */
+export interface TripStop {
+  readonly h: number;
+  readonly m: HighwayMember;
+}
+
+/** This function gives the trip of each edge of a plan. The trip is its highways in the order of `seq`, then in the order of the plan. */
+export function tripsOf(plan: HighwayPlan): Map<string, TripStop[]> {
+  const trips = new Map<string, TripStop[]>();
+  plan.highways.forEach((h, hi) => {
+    for (const m of h.members) {
+      const list = trips.get(m.edge);
+      if (list) list.push({ h: hi, m });
+      else trips.set(m.edge, [{ h: hi, m }]);
+    }
+  });
+  for (const list of trips.values()) list.sort((a, b) => a.m.seq - b.m.seq || a.h - b.h);
+  return trips;
+}
+
+/**
+ * This function gives a plan with the same trips, and with `seq` from 0 to the number of highways of the edge less 1.
+ * A post step can give `seq` values with gaps or below 0, and this function makes them whole again.
+ * It also drops each highway with fewer than two members, and gives the highways new ids in order.
+ */
+export function tidyPlan(plan: HighwayPlan): HighwayPlan {
+  const kept = plan.highways.filter((h) => h.members.length >= 2);
+  const seq = new Map<string, number>();
+  for (const list of tripsOf({ highways: kept }).values()) list.forEach((stop, i) => seq.set(`${stop.h}\u0000${stop.m.edge}`, i));
+  const highways: Highway[] = kept.map((h, hi) => ({
+    ...h,
+    id: `h${hi}`,
+    lanes: h.lanes.filter((e) => h.members.some((m) => m.edge === e)),
+    members: h.members.map((m) => ({ ...m, seq: seq.get(`${hi}\u0000${m.edge}`) ?? 0 })),
+  }));
+  return { highways };
+}
+
+/** This function gives the place along a polyline (as a length from its first point) of the point of the polyline nearest to `p`. */
+export function arcPlace(line: readonly Point[], p: Point): number {
+  let best = Infinity;
+  let at = 0;
+  let walked = 0;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!;
+    const b = line[i]!;
+    const len = dist(a, b);
+    const u = len > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / (len * len))) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best) [best, at] = [d, walked + u * len];
+    walked += len;
+  }
+  return at;
+}
+
+/** This function gives the place on a spine (the index of a point plus the share of the next leg) of the point of the spine nearest to `p`. */
+export function nearestPlace(spine: readonly Point[], p: Point): number {
+  let best = Infinity;
+  let at = 0;
+  for (let i = 1; i < spine.length; i++) {
+    const a = spine[i - 1]!;
+    const b = spine[i]!;
+    const len2 = (b.x - a.x) ** 2 + (b.y - a.y) ** 2;
+    const u = len2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * (b.x - a.x) + (p.y - a.y) * (b.y - a.y)) / len2)) : 0;
+    const d = dist(p, { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u });
+    if (d < best) [best, at] = [d, i - 1 + u];
+  }
+  return at;
+}
+
+/**
+ * This function gives a plan where the `seq` of each member follows the place of its merge point along the route of its edge.
+ * A post step that adds highways to the trips of edges uses it. Equal places keep the order of `seq`.
+ */
+export function orderAlongRoutes(plan: HighwayPlan, routes: ReadonlyMap<string, readonly Point[]>): HighwayPlan {
+  const rank = new Map<string, number>();
+  for (const [edge, list] of tripsOf(plan)) {
+    const route = routes.get(edge);
+    const placed = list.map((stop, i) => ({ stop, i, at: route ? arcPlace(route, stop.m.merge) : i }));
+    placed.sort((a, b) => a.at - b.at || a.i - b.i);
+    placed.forEach((p, k) => rank.set(`${p.stop.h}\u0000${edge}`, k));
+  }
+  return { highways: plan.highways.map((h, hi) => ({ ...h, members: h.members.map((m) => ({ ...m, seq: rank.get(`${hi}\u0000${m.edge}`) ?? m.seq })) })) };
+}
+
+/** This function gives the route of each edge by its id. */
+export const routeIndex = (routes: readonly Route[]): Map<string, readonly Point[]> => new Map(routes.map((r) => [r.edge, r.points]));

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),
+};

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

@@ -0,0 +1,59 @@
+import type { Highway, HighwayInput, HighwayPlan } from "../../model.ts";
+import { commonEdges, matchHighways, type Gate } from "../model.ts";
+
+/** The options of the gate `ids` (HWY-054). */
+export interface StableIdOptions {
+  /** A new highway takes the id of an old highway when the Jaccard index of their edges is this value or more. The default is 0.5. */
+  readonly minJaccard: number;
+}
+
+/** The default options of the gate `ids`. */
+export const STABLE_ID_DEFAULTS: Readonly<StableIdOptions> = Object.freeze({ minJaccard: 0.5 });
+
+/** This function gives the number at the end of an id, or -1 for an id without a number at its end. */
+function numberOf(id: string): number {
+  let start = id.length;
+  while (start > 0 && id.charCodeAt(start - 1) >= 48 && id.charCodeAt(start - 1) <= 57) start--;
+  return start === id.length ? -1 : Number(id.slice(start));
+}
+
+/**
+ * This function gives stable ids to the highways of a plan (HWY-054). The earlier plan is `input.previous`.
+ * Each new highway takes the id of the old highway with the most common edges.
+ * The pairs with the largest Jaccard index of their edges come first.
+ *
+ * A pair needs an index of `minJaccard` or more, and only the edges of both graphs count.
+ * A new highway without a match gets a new id `h<n>` that no old highway and no new highway has. Thus the old highway of a new id ends.
+ * The gate changes only the ids, so the routes do not change. Without an earlier plan, the plan does not change.
+ */
+export function stableIdPlan(input: HighwayInput, plan: HighwayPlan, options: Readonly<StableIdOptions>): HighwayPlan {
+  if (!input.previous) return plan;
+  const before = input.previous.plan;
+  const matched = matchHighways(before, plan, options.minJaccard, commonEdges(input.previous.graph, input.graph));
+  const taken = new Set<string>([...before.highways.map((h) => h.id)]);
+  for (const [, i0] of matched) taken.add(before.highways[i0]!.id);
+  let next = 1 + Math.max(-1, ...before.highways.map((h) => numberOf(h.id)), ...plan.highways.map((h) => numberOf(h.id)));
+  const fresh = (): string => {
+    while (taken.has(`h${next}`)) next++;
+    const id = `h${next++}`;
+    taken.add(id);
+    return id;
+  };
+  const highways = plan.highways.map((h, i): Highway => {
+    const i0 = matched.get(i);
+    const id = i0 === undefined ? fresh() : before.highways[i0]!.id;
+    return id === h.id ? h : { ...h, id };
+  });
+  return { highways };
+}
+
+/** The gate `ids` (HWY-054): stable highway ids across edits. A highway keeps the id of its match in the earlier plan. */
+export const stableIdGate: Gate<StableIdOptions> = {
+  name: "ids",
+  describe: "The gate `ids` (HWY-054) gives each highway the id of the highway of the earlier plan with the most common edges. The routes do not change.",
+  defaults: STABLE_ID_DEFAULTS,
+  schema: {
+    minJaccard: { type: "number", min: 0.3, max: 0.8, step: 0.05, default: 0.5, describe: "A new highway takes the id of an old highway when the Jaccard index of their edges is this value or more." },
+  },
+  apply: (input, plan, options) => stableIdPlan(input, plan, options),
+};

package/src/highways/gates/index.ts

@@ -0,0 +1,6 @@
+export { commonEdges, edgeLengths, gateStrategy, jaccard, keepMembers, matchHighways, type EdgeLengths, type Gate } from "./model.ts";
+export { BREAK_EVEN_DEFAULTS, breakEvenGate, breakEvenPlan, type BreakEvenOptions } from "./breakeven/index.ts";
+export { STRETCH_DEFAULTS, stretchGate, stretchPlan, type StretchOptions } from "./stretch/index.ts";
+export { AMBIGUITY_GUARD_DEFAULTS, ambiguityGate, ambiguityPlan, nodeAmbiguity, type AmbiguityGuardOptions } from "./ambiguity/index.ts";
+export { HYSTERESIS_DEFAULTS, hysteresisGate, hysteresisPlan, SAME_HIGHWAY, type HysteresisOptions } from "./hysteresis/index.ts";
+export { STABLE_ID_DEFAULTS, stableIdGate, stableIdPlan, type StableIdOptions } from "./ids/index.ts";