@mark1russell7/highways 0.9.6 → 0.9.7

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -48,6 +48,7 @@
     "profile": "node scripts/profile.ts",
     "levels": "node scripts/levels.ts",
     "screen": "node scripts/screen.ts",
+    "promotion": "node scripts/promotion.ts",
     "exact": "node scripts/exact.ts",
     "oracle": "node scripts/oracle.ts",
     "portfolio": "node scripts/portfolio.ts",

package/src/bench/compare.ts

@@ -14,7 +14,7 @@ import { measureLevelFaults, sumFaults } from "./links.ts";
 import { paretoFront, type Objective } from "./measures/pareto.ts";
 import { roomOrderFaults } from "./measures/room.ts";
 import { boardUnit } from "./measures/routes.ts";
-import { changeGraph, routeStability } from "./measures/stability.ts";
+import { changeGraph, moveResponse, routeStability } from "./measures/stability.ts";
 import { farLinks, measureBoard } from "./room.ts";
 import { benchRun } from "./run.ts";
 import { curveRuns, fixtureGroupOptions, FRONT_OBJECTIVES, groupRun, routeMeasures } from "./suite.ts";
@@ -146,6 +146,7 @@ export function compareStep(step: CompareStep, graph: Graph, options: CompareOpt
   let rows: CompareRow[];
   if (step === "router") {
     const change = graph.nodes.length <= stabilityMax ? changeGraph(graph, seed) : undefined;
+    const move = graph.nodes.length <= stabilityMax ? changeGraph(graph, seed, { edges: false }) : undefined;
     rows = listStrategies(registry, "router").map((strategy): CompareRow => {
       if (graph.nodes.length > (strategy.maxNodes ?? Infinity)) return { step, strategy: strategy.name, violations: 0, ms: 0, values: {}, skipped: `over ${strategy.maxNodes} nodes` };
       const router = asRouter(strategy, own[strategy.name]);
@@ -157,6 +158,28 @@ export function compareStep(step: CompareStep, graph: Graph, options: CompareOpt
         values["Z10.max"] = s.max;
         values["Z10.moved"] = s.moved;
       }
+      // Z11: the routes after a change that only moves one node by one unit.
+      if (move) {
+        const z = moveResponse(graph, move, result, router.route(move.graph), { seed });
+        if (z) {
+          values["Z11.gain"] = z.gain;
+          values["Z11.spill"] = z.spill;
+        }
+      }
+      // Z12: the routes with the next seed, for a strategy with the option `seed`. A strategy without a seed gives the same routes, so its values are 0.
+      if (change) {
+        const given = (own[strategy.name] ?? {}) as { seed?: unknown };
+        const base = typeof given.seed === "number" ? given.seed : (strategy.defaults as { seed?: unknown } | undefined)?.seed;
+        if (typeof base === "number") {
+          const next = asRouter(strategy, { ...own[strategy.name], seed: base + 1 } as object);
+          const s = routeStability(graph, result, next.route(graph), { seed });
+          values["Z12.mean"] = s.mean;
+          values["Z12.moved"] = s.moved;
+        } else {
+          values["Z12.mean"] = 0;
+          values["Z12.moved"] = 0;
+        }
+      }
       return { step, strategy: strategy.name, violations: row.violations + (row.deterministic ? 0 : 1), ms: row.ms, values, result };
     });
   } else if (step === "curve") {

package/src/bench/measures/lanes.ts

@@ -92,7 +92,7 @@ export function routeSeparation(routes: readonly Route[], near: number = MEASURE
   if (ink <= 0) return 0;
   const grid = new Grid<number>(Math.max(16, 4 * near));
   legs.forEach((l, i) => grid.addSegment(i, l.a, l.b));
-  const sin = Math.sin((maxAngle * Math.PI) / 180);
+  const sin = parallelSine(maxAngle);
   let close = 0;
   legs.forEach((s, i) => {
     const length = dist(s.a, s.b);
@@ -118,6 +118,100 @@ export function routeSeparation(routes: readonly Route[], near: number = MEASURE
   return Math.min(1, close / ink);
 }
 
+/** This function gives the sine of the largest angle between two legs that R12 and R16 count as parallel. */
+function parallelSine(maxAngle: number): number {
+  return Math.sin((maxAngle * Math.PI) / 180);
+}
+
+/** The lane balance of the routes (R16 of MEAS0). */
+export interface RouteBalance {
+  /** The coefficient of variation of the gaps, weighted by the overlap: the standard deviation over the mean. 0 is even. */
+  readonly cv: number;
+  /** The share of the overlap with a gap less than half of the weighted median gap. */
+  readonly low: number;
+  /** The count of the pairs of neighbor legs. */
+  readonly pairs: number;
+}
+
+/** The distance in units of the board up to which two parallel legs are neighbors for R16. It is 8 lane widths. */
+export const MEASURE_BALANCE_REACH: number = 8 * MEASURE_LANE_WIDTH;
+
+/**
+ * This function gives the lane balance of the routes (R16 of MEAS0): the spread of the gaps between parallel routes.
+ *
+ * The legs are the legs of R12. For each leg `s`, its neighbor at each side is the nearest leg `t` of other edges with three properties.
+ * It is within `maxAngle` degrees of parallel. Its projection overlaps `s`. Its distance at the middle of the overlap is less than `reach`.
+ * Each neighbor pair gives a gap `g` with the weight `w`, the length of the overlap. A pair counts one time.
+ * Two legs on one line have the gap 0.
+ *
+ * `cv = sqrt(Σ w (g − ḡ)² / Σ w) / ḡ`, with `ḡ = Σ w g / Σ w`. Lower is better. Routes without a neighbor pair give 0.
+ * R12 counts the parallel ink that is too near. R16 counts uneven gaps, also when each gap is wide.
+ */
+export function routeBalance(routes: readonly Route[], reach: number = MEASURE_BALANCE_REACH, maxAngle = 5): RouteBalance {
+  const legs = legsOf(routes);
+  const grid = new Grid<number>(Math.max(16, reach));
+  legs.forEach((l, i) => grid.addSegment(i, l.a, l.b));
+  const sin = parallelSine(maxAngle);
+  // The key of a pair is the two indices in order, so a pair that each leg finds counts one time.
+  const gaps = new Map<string, { g: number; w: number }>();
+  legs.forEach((s, i) => {
+    const length = dist(s.a, s.b);
+    if (length <= 0) return;
+    const ux = (s.b.x - s.a.x) / length;
+    const uy = (s.b.y - s.a.y) / length;
+    // The nearest neighbor on each side of `s`: the side +1 is the left of its direction, and -1 is the right. A gap of 0 goes to the side +1.
+    const best = new Map<number, { j: number; g: number; w: number }>();
+    grid.querySegment(s.a, s.b, reach, (j) => {
+      const t = legs[j]!;
+      if (j === i || t.edges === s.edges) return;
+      const tx = t.b.x - t.a.x;
+      const ty = t.b.y - t.a.y;
+      // The squared length of `t`. The test of the angle compares squares, so it needs no square root.
+      const tl2 = tx * tx + ty * ty;
+      const cross = ux * ty - uy * tx;
+      if (tl2 <= 0 || cross * cross > sin * sin * tl2) return;
+      const p = (t.a.x - s.a.x) * ux + (t.a.y - s.a.y) * uy;
+      const q = (t.b.x - s.a.x) * ux + (t.b.y - s.a.y) * uy;
+      const lo = Math.max(0, Math.min(p, q));
+      const hi = Math.min(length, Math.max(p, q));
+      if (hi - lo <= 1e-9) return;
+      // The offset of the line of `t` from the middle of the overlap on `s`, along the normal of `s`.
+      const m = (lo + hi) / 2;
+      const px = s.a.x + ux * m;
+      const py = s.a.y + uy * m;
+      const k = ((px - t.a.x) * tx + (py - t.a.y) * ty) / tl2;
+      const o = (t.a.x + tx * k - px) * -uy + (t.a.y + ty * k - py) * ux;
+      const g = Math.abs(o);
+      if (g >= reach) return;
+      const side = o < -1e-9 ? -1 : 1;
+      const now = best.get(side);
+      if (!now || g < now.g) best.set(side, { j, g, w: hi - lo });
+    });
+    for (const n of best.values()) {
+      const key = i < n.j ? `${i},${n.j}` : `${n.j},${i}`;
+      if (!gaps.has(key)) gaps.set(key, { g: n.g, w: n.w });
+    }
+  });
+  const list = [...gaps.values()];
+  const W = list.reduce((sum, x) => sum + x.w, 0);
+  if (list.length === 0 || W <= 0) return { cv: 0, low: 0, pairs: 0 };
+  const mean = list.reduce((sum, x) => sum + x.w * x.g, 0) / W;
+  const variance = list.reduce((sum, x) => sum + x.w * (x.g - mean) ** 2, 0) / W;
+  // The weighted median: the gap where the sorted weights reach half of the sum.
+  const sorted = [...list].sort((x, y) => x.g - y.g);
+  let acc = 0;
+  let median = sorted[sorted.length - 1]!.g;
+  for (const x of sorted) {
+    acc += x.w;
+    if (acc >= W / 2) {
+      median = x.g;
+      break;
+    }
+  }
+  const low = list.filter((x) => x.g < median / 2).reduce((sum, x) => sum + x.w, 0) / W;
+  return { cv: mean > 0 ? Math.sqrt(variance) / mean : 0, low, pairs: list.length };
+}
+
 /**
  * This function gives the orthogonality of the routes (R14 of MEAS0): `orth = Σ L(legs within maxAngle degrees of an axis) / Σ_e L(r_e)`.
  * Each route counts its own legs, also on a shared segment. The scale is 0 to 1, and higher is better for an orthogonal style.

package/src/bench/measures/stability.ts

@@ -1,4 +1,4 @@
-import { inflate, type Box } from "../../geom.ts";
+import { frechet, inflate, type Box } from "../../geom.ts";
 import { rng } from "../../fixtures.ts";
 import type { Edge, Graph, Node, Result } from "../../model.ts";
 import { measureStability } from "../quality.ts";
@@ -19,8 +19,9 @@ export interface GraphChange {
 /**
  * This function makes a seeded small change of a graph: one node moves by `boardUnit`, one edge goes and one new edge comes.
  * The moved box keeps a gap of 4 units to the other boxes. The same graph and the same seed give the same change.
+ * With `edges: false`, the change only moves the node (Z11). The moved node is the node of the full change with the same seed.
  */
-export function changeGraph(graph: Graph, seed: number): GraphChange {
+export function changeGraph(graph: Graph, seed: number, options: { readonly edges?: boolean } = {}): GraphChange {
   const R = rng(seed * 2654435761 + 97);
   const n = graph.nodes.length;
   const u = boardUnit(graph);
@@ -51,7 +52,7 @@ export function changeGraph(graph: Graph, seed: number): GraphChange {
   let edges: Edge[] = [...graph.edges];
   let removed: string | undefined;
   let added: string | undefined;
-  if (edges.length > 1) {
+  if (edges.length > 1 && options.edges !== false) {
     const j = Math.floor(R() * edges.length);
     const gone = edges[j]!;
     removed = gone.id;
@@ -102,3 +103,46 @@ export function routeStability(graph: Graph, before: Result, after: Result, opti
   const u = boardUnit(graph);
   return { mean: s.mean / u, max: s.max / u, moved: s.moved };
 }
+
+/** The move response of a router (Z11 of MEAS0): the routes after a change that only moves one node by one unit of the board. */
+export interface MoveResponse {
+  /**
+   * The sum of the Fréchet distances of the routes, divided by the unit of the board and by the degree of the moved node (at least 1).
+   * The edges of the moved node move by approximately one unit, so 1 is a local response. A larger value tells that other routes also move.
+   */
+  readonly gain: number;
+  /** The share of the other routes that move more than 1 unit of length, as `moved` of Z10. An other route has no end at the moved node. */
+  readonly spill: number;
+}
+
+/**
+ * This function measures the move response of a router (Z11 of MEAS0). `change` is a change of `changeGraph` with `edges: false`.
+ * It gives `undefined` when no node moved. Above `sample` routes, a seeded sample serves, and the sum scales to all the routes.
+ */
+export function moveResponse(graph: Graph, change: GraphChange, before: Result, after: Result, options: RouteStabilityOptions = {}): MoveResponse | undefined {
+  const node = change.moved;
+  if (node === undefined) return undefined;
+  const max = options.sample ?? 2000;
+  const prev = new Map(before.routes.map((r) => [r.edge, r.points] as const));
+  const ends = new Map(graph.edges.map((e) => [e.id, e.source.node === node || e.target.node === node] as const));
+  let routes = after.routes.filter((r) => prev.has(r.edge));
+  const all = routes.length;
+  if (routes.length > max) {
+    const R = rng(options.seed ?? 1);
+    routes = Array.from({ length: max }, () => routes[Math.floor(R() * routes.length)]!);
+  }
+  const u = boardUnit(graph);
+  const degree = graph.edges.filter((e) => ends.get(e.id) === true).length;
+  let sum = 0;
+  let far = 0;
+  let spilled = 0;
+  for (const r of routes) {
+    const f = frechet(prev.get(r.edge)!, r.points);
+    sum += f;
+    if (ends.get(r.edge) === true) continue;
+    far++;
+    if (f > 1) spilled++;
+  }
+  const scale = routes.length > 0 ? all / routes.length : 0;
+  return { gain: (sum * scale) / u / Math.max(1, degree), spill: far > 0 ? spilled / far : 0 };
+}

package/src/bench/screen/measures.ts

@@ -98,6 +98,9 @@ const ROWS: readonly Row[] = [
   // MEAS3A, for the steps `router` and `highway`. R12 is the share of the ink near a parallel leg of other edges. A narrow channel between boxes moves it.
   ["R12.share", "R12", "route.lane.separation", "0 to 1", "lower", true],
   ["R14.share", "R14", "route.orthogonality", "0 to 1", "higher", false],
+  // BALANCE-STABILITY. R16 is the spread of the gaps between neighbor parallel legs of two edges, also when each gap is wide.
+  ["R16.cv", "R16", "route.balance.cv", "no unit", "lower", true, "The spread of the gaps between parallel routes: the standard deviation of the gaps over their mean. A value of 0 is even."],
+  ["R16.low", "R16", "route.balance.low", "0 to 1", "lower", true, "The share of the parallel overlap with a gap less than half of the median gap."],
   ["ink", "R1", "route.ink", "units", "lower", true],
   // The bundles.
   ["B1.inkSaved", "B1", "route.bundle.ink-saved", "0 to 1", "higher", false],
@@ -154,6 +157,11 @@ const ROWS: readonly Row[] = [
   ["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],
+  // BALANCE-STABILITY. Z11 is the response to a move of one node by one unit. Z12 is the change of the routes with the next seed of a strategy.
+  ["Z11.gain", "Z11", "route.stability.move.gain", "no unit", "lower", false, "The movement of all the routes after one node moves by one unit, for each edge of that node. A value of 1 is a local response."],
+  ["Z11.spill", "Z11", "route.stability.move.spill", "0 to 1", "lower", false, "The share of the routes of other nodes that move after one node moves by one unit. A value of 0 is a local response."],
+  ["Z12.mean", "Z12", "route.stability.seed.mean", "units of the board", "lower", false, "The mean movement of the routes with the next seed of the strategy. A strategy without a seed has 0."],
+  ["Z12.moved", "Z12", "route.stability.seed.moved", "0 to 1", "lower", false, "The share of the routes that move with the next seed of the strategy. A strategy without a seed has 0."],
   // 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],
   // MEAS3A, for the steps `router`, `highway` and `group`. Z2 is the count of the hard rule `link-ends`. Z9 needs a result with zoom levels.

package/src/bench/screen/screen.ts

@@ -6,7 +6,7 @@ import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS,
 import { compareStep, highwayRouters, isRoutedStep, stepRouters, wholeBoard, type CompareRow, type CompareStep, type RoutedStep, type StepComparison } from "../compare.ts";
 import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
 import { highwayEdits } from "../measures/highways.ts";
-import { laneArea, laneCrossings, laneFidelity, lanesThrough, occupiedArea, openLanes, orthogonality, routeSeparation, runProfile } from "../measures/lanes.ts";
+import { laneArea, laneCrossings, laneFidelity, lanesThrough, occupiedArea, openLanes, orthogonality, routeBalance, routeSeparation, runProfile } from "../measures/lanes.ts";
 import { farLevel, groupFill, itemOverlaps, silhouette } from "../measures/groups.ts";
 import { levelRatio, linkAgreement } from "../measures/levels.ts";
 import { orderFragility } from "../measures/order.ts";
@@ -274,6 +274,9 @@ function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () =>
     const open = openLanes(row.result);
     values["R12.share"] = routeSeparation(routes);
     values["R14.share"] = orthogonality(routes);
+    const balance = routeBalance(routes);
+    values["R16.cv"] = balance.cv;
+    values["R16.low"] = balance.low;
     values["B5.crossings"] = laneCrossings(open.graph);
     values["B7.ratio"] = occupiedArea(routes, boardUnit(graph));
     const runs = runProfile(open.graph);