@mark1russell7/highways 0.9.3 → 0.9.5

package/README.md

@@ -59,11 +59,15 @@ A plug rule is a strategy of the step `plugs`. It places the free plugs of each
 | `side` | The search of the route starts from the whole free side. The plug goes where the way leaves the side (WILD-001). |
 | `justify` | The plugs of `facing`, then the plugs of each side keep their order and the gap `plugGap` (WILD-002). |
 | `spread` | The plugs of each wall share the room of the wall, with the gap `plugGap`, in the order of their far ends. |
+| `leaders` | The boundary leaders of EDA-041. The plugs of each wall take the order of `po`, `s` or `opo` leaders, with the gap `slotSpacing`. |
 
 - `side` gives the plugs of `corners` with `plugs: "side"`. `justify` gives the plugs of `corners` with the same `plugGap`.
 - `spread` keeps the room of a wall free of the corner insets (`inset`) and of the fixed plugs on the wall.
   - When the room is too small for the gap, the gap shrinks evenly. No plug drops.
   - The order on the wall keeps the order of the far ends, so the straight lines of two plugs do not cross at the wall.
+- `leaders` (EDA-041) uses the walls of `spread`. With `po`, the default, the order on a wall is the order of the far ends along the wall.
+  - A `po` stub leaves along the normal and turns one time, so this order gives stubs with no crossing.
+  - With `s`, the plugs are the plugs of `spread`. With `opo`, the plugs of a wall go at even places.
   - The ends of one port share one plug. The option `rounds` sorts each wall again by the new places of the far ends.
 - The option `plug` of `corners` takes a plug rule. The other routers place the plugs as `facing` does.
 
@@ -99,6 +103,16 @@ A node can name a frame node in `parent`. A frame is a node that holds other nod
   - `throw` (the default) throws a `RangeError`.
   - `skip` gives no route to the edges of that node.
   - `clamp` cuts the box to the bounds of the frame.
+- The option `inner` sets the mode of the inner routes:
+  - `corners` (the default) finds each route in the corner graph, as above.
+  - `gutter` gives orthogonal routes in the gaps between the nodes and in the strips at the walls.
+- In the mode `gutter`, a route uses the whole box of the frame. The mode does not use `frameInset`.
+- A route of the mode `gutter` goes into its row at the port, or at the left or right end of the row.
+- The plug stub stays perpendicular to the wall. A plug that is level with its row gives only the stub.
+- The option `bendCost` is the cost of one bend in units of length. A larger cost gives fewer bends. The default is 16.
+- Each gap that two or more routes share gets one lane for each route. The lanes are evenly spaced, in an order with few crossings.
+- The space between two lanes is the margin of the router. In a narrow gap, the space becomes smaller.
+- An edge with no way through the free room gets no route, as with `skip`. Rows that touch each other with gap 0 can block a way.
 
 ```ts
 const nodes = [
@@ -107,6 +121,7 @@ const nodes = [
 ];
 const edges = [{ id: "inner", source: { node: "row" }, target: { node: "card", port: "in" } }];
 const inner = cornersRouter({ name: "corners" }).route({ nodes, edges }).routes; // inner[0].frame is "card"
+const gutters = cornersRouter({ name: "corners", inner: "gutter", bendCost: 24 }).route({ nodes, edges }).routes; // only H and V legs
 ```
 
 ## Curve types
@@ -430,13 +445,13 @@ The steps of the pipeline that vary have strategies. Each step has one interface
 | Step | Input | Output | Built-in strategies |
 |---|---|---|---|
 | `group` | `Graph` | `Section`: the tree of groups of the router `sections` | `quadtree`, `keys`, `kd`, `cut` |
-| `plugs` | `PlugInput`: the graph, and optionally the ways of the router | `PlugPair[]`: the two plugs of each edge | `facing`, `side`, `justify`, `spread` |
+| `plugs` | `PlugInput`: the graph, and optionally the ways of the router | `PlugPair[]`: the two plugs of each edge | `facing`, `side`, `justify`, `spread`, `leaders` |
 | `router` | `Graph` | `Result` | `straight`, `plugs`, `corners`, `corners-smooth`, `trunks`, `shared`, `shared-all`, `sections`, `sections-tree` |
-| `highway` | `HighwayInput`: the graph, optionally the first routes of a router, and optionally the plan before an edit | `HighwayPlan`: the highways as data | `keys`, `shared-ways`, `corridors`, `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `quickbundles`, `road-classes`, `flow-field`, `wspd`, `od-cells`, `select`, `mingle`, `spiral`, `flow-clusters`, `traclus`, `diffusion`, `nested`, `lanes`, `growth`, `edge-paths`, `soft-keys`, `hough`, `ridges`, `hdbscan`, `hub-arcs`, `divided`, `hierarchy`, `fdeb`, `mesh`, `kdeeb`, `cubu`, `mlseb`, `sbeb`, `areas`, `confluent`, `power`, `crossbars`, `frechet`, `spectral`, `resistance`, `link-communities`, `territories`, `consensus`, `p-hub`, `scale-space`, `corridors+breakeven`, `corridors+stretch`, `corridors+ambiguity`, `corridors+hysteresis`, `corridors+ids` |
-| `levels` | `LevelInput`: the graph, the tree of groups and the routes | `Level[]`: the zoom levels of the router `sections` | `depths` |
+| `highway` | `HighwayInput`: the graph, optionally the first routes of a router, and optionally the plan before an edit | `HighwayPlan`: the highways as data | `keys`, `shared-ways`, `corridors`, `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `quickbundles`, `road-classes`, `flow-field`, `wspd`, `od-cells`, `select`, `mingle`, `spiral`, `flow-clusters`, `traclus`, `diffusion`, `nested`, `lanes`, `growth`, `edge-paths`, `soft-keys`, `hough`, `ridges`, `hdbscan`, `hub-arcs`, `divided`, `hierarchy`, `fdeb`, `mesh`, `kdeeb`, `cubu`, `mlseb`, `sbeb`, `areas`, `confluent`, `power`, `crossbars`, `frechet`, `spectral`, `resistance`, `link-communities`, `territories`, `consensus`, `p-hub`, `scale-space`, `gaps`, `streets`, `search`, `interchanges`, `knee`, `bronchial`, `balance`, `manifolds`, `slots`, `corridors+breakeven`, `corridors+stretch`, `corridors+ambiguity`, `corridors+hysteresis`, `corridors+ids` |
+| `levels` | `LevelInput`: the graph, the tree of groups and the routes | `Level[]`: the zoom levels of the router `sections` | `depths`, `venation`, `detail` |
 | `curve` | `CurveInput`: the points, the normals of the plugs, the free space and the lane on its board | `CurveSegment[]` | `straight`, `rounded`, `spline`, `arc`, `smooth`, `clothoid`, `highway` |
 | `room` | `RoomInput`: the boxes and the links of a board, and the tree of sections for `levels` | `Gap[]` | `routes`, `lines`, `levels` |
-| `whole` | `Graph` | `WholeOutput`: the board and its `Result` | `pipeline` |
+| `whole` | `Graph` | `WholeOutput`: the board and its `Result` | `pipeline`, `board-portfolio`, `curriculum`, `preferences`, `fireflies`, `tracing` |
 
 `STEPS` gives the steps in the order of the pipeline: `group`, `plugs`, `router`, `highway`, `levels`, `curve`, `room`, `whole`.
 
@@ -463,6 +478,29 @@ Each of these steps has one default strategy. The default gives the output of th
   The option `level` of `sections` takes a level strategy, and `levelOptions` gives its options. The strategy also gets the level options of the router.
 - `pipeline` (the step `whole`) runs a room strategy, then a router or a highway plan, with the rules that the router reads (`runPipeline`).
   Without options, it routes with `corners`. The demo of the site runs it. It does not draw the curves.
+- `venation` (the step `levels`, NAT-016) keeps the levels of `depths`. Its level links take their ways on a closed backbone of the items.
+  The backbone is the relative neighbourhood graph (`rng`) or the Gabriel graph. A backbone link that a level link uses costs less for the next level links.
+  The routes do not change, so only the level links (Z3) change.
+- `board-portfolio` (the step `whole`, WILD-045) runs a short list of settings on the board and keeps the best one.
+  The list `BOARD_PORTFOLIO_SETTINGS` holds 12 routers and highway plans. The option `settings` sets how many of them run.
+  A setting with a break of a hard rule does not count. The score adds the rank shares of the crossings, the median detour and the ink saved.
+  It reads no screen record and has no fit. With `budget: 0`, the default, the pick does not depend on the speed of the machine.
+- `detail` (the step `levels`, WILD-016 with EDA-038) keeps the levels of `depths`. Close legs of level links become one stroke.
+  At the scale where a level first shows, two parallel legs closer than `pxMin` pixels collapse onto the leg with the larger count.
+  `detailWidth(count, options)` gives the width of a stroke for a renderer. The routes do not change, so only the level links change.
+- `curriculum` (the step `whole`, RULE-048) adds the rules one at a time: the crossings, the lane separation and the crossing angle.
+  The pool `CURRICULUM_POOL` holds the routes of `corners`, `shared` and `trunks`. The first answer is the routes of `corners`.
+  In each stage, an edge takes a route of the pool that improves the new rule with no loss on the earlier rules.
+  The output has the routes alone, with no runs or bundles.
+- `preferences` (the step `whole`, RULE-038) fits the weights of five rules to made-up pairs of routes, with a Bradley-Terry model.
+  A made-up panel labels the pairs (`PREFERENCE_PANEL`). The pairs do not come from the screen or from a board.
+  `fitPreferences()` gives the weights and the agreement with 50 held-out pairs. Each edge takes the route of `CURRICULUM_POOL` with the least weighted cost.
+- `fireflies` (the step `whole`, NAT-047) searches the options `discount` and `margin` of `shared` on the board, with a seeded swarm.
+  The option `search` is `firefly` or `bees`. The option `budget` (4 to 40) is the largest number of different settings that the search routes.
+  The first setting is the default of `shared`. The attraction of a firefly is rational, so it uses no `Math.exp`.
+- `tracing` (the step `whole`, WILD-057) runs the settings of `BOARD_PORTFOLIO_SETTINGS` and keeps the one with the least tracing load.
+  The load of an edge is `crossing × crossings + merge × merges and splits + bend × bends`. A merge counts only where the edge is not an outer lane.
+  `tracingLoads(result, weights)` gives the load of each edge, as the measure W4. The pick reads the quantile 0.95 of the loads by default.
 - `strategyKey(router, step)` gives the option of a router that takes a strategy of the step. `pipeline` uses it for the steps `group`, `plugs` and `levels`.
 - `stepRouterStrategy(strategy)` runs a strategy of a step of `RoutedStep` as a router. `stepRouters(registry, step)` gives one router for each strategy of the step.
 
@@ -541,9 +579,14 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `streets` | The orthogonal streets of HWY-058. A greedy set cover picks the free horizontal and vertical lines that carry the most edge length. |
 | `search` | The local search of HWY-059. It adds, drops and changes the highways of a start plan, and it keeps the plan with the best score. |
 | `interchanges` | The interchanges of HWY-060. An edge can change from one highway to another at an interchange, where two spines come near. |
+| `knee` | The knee tree of NAT-018. A sweep of the balancing factor gives trees from the least ink to the most direct paths, and the knee of that front is the pick. |
+| `bronchial` | The bronchial tree of NAT-019. The tree grows toward the center of its targets, then splits them in two sectors, again and again. |
+| `balance` | The stretch balance of EDA-017. A price for each edge grows while its stretch is above `tau`, and the price moves the exit of its ride forward. |
+| `manifolds` | The manifolds of WILD-036. A fan from one node to a row of nodes gets a straight header in the gap before the row, with taps at right angles. |
+| `slots` | The lane slots of RULE-047. An edge whose first route runs near a trunk joins it on a new outer lane, when the pull is larger than its detour. |
 
 The strategy `corridors` joins two ways when they share a long length. The length is `BREAK_EVEN` times the lane width or more, and the share `rho` of the shorter way or more.
-The strategies `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `lanes`, `divided` and `crossbars` change the plan of the option `from`: `shared-ways` (the default), `corridors` or `none`.
+The strategies `meet`, `weiszfeld`, `stubs`, `zipper`, `level-links`, `lanes`, `divided`, `crossbars` and `slots` change the plan of the option `from`: `shared-ways` (the default), `corridors` or `none`.
 The routers `trunks` and `shared` keep their own code. A test pins their output, so the strategies `keys` and `shared-ways` read the same decision.
 
 A gate keeps, drops or changes the highways of a plan. `gateStrategy(strategy, gate)` puts a gate after a highway strategy, with the name `<strategy>+<gate>`.
@@ -616,6 +659,25 @@ The router `attraction` is opt-in. It is not in `STRATEGIES`, so the default out
 - A capacity term raises the cost of a link when its users are more than its width holds.
 - With 1 pass, `attraction: 0` and `capacityWeight: 0`, the routes are the routes of `shared`.
 
+### The routers `tight`, `annealing`, `reroute`, `canals` and `adam`
+
+The routers `tight`, `annealing`, `reroute`, `canals` and `adam` are opt-in. They are not in `STRATEGIES`, so the default outputs do not change. Each one starts from the router `shared`.
+
+- `tightRouter(options)` gives the order of WILD-023: the edges whose second way costs much more than their first way go first.
+  Its options are `penalty` (2 to 10), `first` (`tight` or `loose`) and `ties` (`id` or `length`). `tightStrategy` is its router strategy.
+- `annealingRouter(options)` gives the simulated annealing of RULE-021, with the candidate routes of WILD-028. Each edge picks one of a few ways.
+  The energy adds the ink, the path length and the crossings. The chance to keep a worse state is rational, so it uses no `Math.exp`.
+  Its options are `candidates` (3 to 8), `crossing` (0 to 20), `temperature` (0.1 to 10), `cooling` (0.9 to 0.99), `budget` (20 to 200) and `seed`.
+  The same seed gives the same routes. `annealingStrategy` is its router strategy.
+- `rerouteRouter(options)` gives the rule prices and the rip-up of RULE-044. A link costs more in a narrow channel and with edges of other keys.
+  A link with an edge of the same key costs less. Each round routes again the share `q` of the edges with the largest prices.
+  Its options are `alpha`, `beta`, `gamma` and `tau` (0 to 2), `rounds` (1 to 5), `q` (0.05 to 0.3) and `clearance`. `rerouteStrategy` is its router strategy.
+- `canalRouter(options)` gives the feeder trees of NAT-004. The edges of one key at a hub are sources of flux, and a link with more flux gets cheaper.
+  Its options are `mu` (1 to 3), `steps` (30 to 150), `decay` (0.5 to 2) and `minMembers` (2 to 8). `canalStrategy` is its router strategy.
+- `adamRouter(options)` gives the steps of Adam of RULE-020. The free legs of the routes move away from near legs and boxes, along their normals.
+  No point of a run, of a trunk or of two routes moves. A route goes back when it gets more crossings or a break of a hard rule.
+  Its options are `eta` (0.01 to 1), `samples` (4 to 32), `steps` (100 to 2000, the budget), `seed` and `clearance`. The same seed gives the same routes. `adamStrategy` is its router strategy.
+
 ### The portfolio router
 
 The router `portfolio` is opt-in. It is not in `STRATEGIES`, so the default outputs do not change. [`PORTFOLIO.md`](../../docs/research/PORTFOLIO.md#the-portfolio-router-portfolio-api) gives its tables.
@@ -774,6 +836,24 @@ const { rows, front } = compareStep("curve", graph, { options: { arc: { radius:
 const lanes = compareStep("curve", graph, { curveRouter: "shared", lanes: { width: 5, maxWidth: 30 }, options: { highway: { jog: "quintic" } } });
 ```
 
+## The corpus families
+
+`HIGHWAYS_FAMILIES` lists the 15 generators of the boards of the screen and the site. Each one is a family of `@mark1russell7/layout-contract`, with its dimensions as data. `highwaysRegistry()` makes a registry of them.
+
+- The first 6 families make the boards of `screen-v1` and `screen-v2`.
+- `COVERAGE_FAMILIES` adds 9 families: `frame-rows`, `pipeline`, `fan-out`, `two-hubs`, `uneven-sizes`, `thin-bars`, `sparse-long`, `local-mesh` and `bipartite`.
+- The screen set `screen-v3` has the 15 families, each with 10 seeds.
+- `signTestPower(n)` gives the least count of families out of `n` that passes a two-sided sign test at the level 0.05. For 15 families, the count is 12.
+
+```ts
+import { highwaysRegistry, signTestPower } from "@mark1russell7/highways";
+
+const { graph } = highwaysRegistry().generate("fan-out", 4, { leaves: 40 });
+console.log(graph.nodes.length, signTestPower(15)); // 41 12
+```
+
+[The corpus families](https://github.com/mark1russell7/highways/blob/main/docs/LAYOUT-RECORDS.md#the-corpus-families-corpus-gen) give the dimensions of each family.
+
 ## The same routes on each platform
 
 A transcendental Math function, for example `Math.atan2` or `Math.hypot`, can give a different last bit on another platform or node version. A decision of a router must not depend on that bit.