@mark1russell7/highways 0.4.0 → 0.4.2

package/README.md

@@ -142,6 +142,27 @@ The error of 47.6% is on a new run of two lanes. With `split`, these lanes go on
 
 The benchmark compares each curve type to the polylines of each router, on the fixtures of 100 nodes or fewer. It counts the curves that go through a box, with and without the free space. It also gives the ratio of the lengths.
 
+### Options of the cost, the order and the merges
+
+These options of `shared` and `trunks` are off by default. With the defaults, the routes do not change.
+
+- `cost: flow` of `shared` sets the cost of a link with `f` edges to `len * f^alpha`. A smaller `alpha` gives more sharing and a longer stretch (EDA-029).
+- `passes` of `shared` sets the number of passes. After the first pass, each edge finds its way again with the ways of the other edges fixed (HWY-039).
+- `order` of `shared` sets the order of the edges of a key: `span` (the default, the longest first), `shortest`, `load` or `input` (NAT-024).
+- `merge: snell` of `shared` moves each merge point to the angle `acos(d)` on the run (NAT-035). It cuts the sharp merges.
+- `splitAt: gilbert` of `trunks` puts the split point where the flow cost is least, with the exponent `alpha` (EDA-030).
+- `fan: tree` of `trunks` grows a balancing-factor tree for each group, with the factor `bf` (NAT-017). 0 gives the least ink.
+
+The screen `screen-v1` compares the options with the defaults on the boards `small-clustered`, `dense-groups`, `hub-chain` and `many-groups`.
+
+| Option | Router | Result |
+|---|---|---|
+| `passes: 3` | `shared-all` | B1 rises 1% to 8%, and the B3 q95 falls or stays, on 4 boards. Crossings fall up to 28%. |
+| `merge: snell` | `shared`, `shared-all` | The B6 max falls 8% to 27% on 6 board pairs. The ink rises 0.5% at most. Crossings rise 6% to 13%, and from 18 to 24 on `hub-chain`. |
+| `cost: flow`, `alpha` 0.5 | `shared-all` | B1 rises 1% to 32%, but the B3 q95 rises up to 67%. |
+| `fan: tree`, `bf` 0.2 | `trunks` | On `dense-groups`, B1 rises from 0.081 to 0.095 and the B3 q95 falls. |
+| `splitAt: gilbert` | `trunks` | The B6 max rises. The ink changes 0.6% at most. |
+
 ## Room for the links
 
 A host layout can pack the boxes of a far view in a grid, with no gap between them. Then the links have no channel, and they go through the boxes. The router knows the room that the links need. The room functions give that room, and they can open the gaps.
@@ -323,7 +344,7 @@ The steps of the pipeline that vary have strategies. Each step has one interface
 |---|---|---|---|
 | `group` | `Graph` | `Section`: the tree of groups of the router `sections` | `quadtree`, `keys`, `kd`, `cut` |
 | `router` | `Graph` | `Result` | `straight`, `plugs`, `corners`, `corners-smooth`, `trunks`, `shared`, `shared-all`, `sections`, `sections-tree` |
-| `highway` | `HighwayInput`: the graph, and optionally the first routes of a router | `HighwayPlan`: the highways as data | `keys`, `shared-ways`, `corridors` |
+| `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`, `corridors+breakeven`, `corridors+stretch`, `corridors+ambiguity`, `corridors+hysteresis`, `corridors+ids` |
 | `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` |
 
@@ -352,10 +373,36 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `keys` | The trunks and the runs of the router `trunks`. `planOfResult` reads them. The router does not change. |
 | `shared-ways` | The runs of the router `shared`. `planOfResult` reads them. The router does not change. |
 | `corridors` | The corridor signatures of HWY-031. The links of the first routes get a MinHash signature, and each cluster of ways gives a highway. |
+| `meet` | The merge points and split points of HWY-050. Each member joins its spine where its first route meets the spine, and leaves where they part. |
+| `weiszfeld` | The meeting points of HWY-043. Each highway gets the merge and split points with the least ink, with the weight `k^alpha` on the trunk. |
+| `stubs` | The stubs of HWY-015. The ends on one side of a box that go in near directions share one plug and one short stub. |
+| `zipper` | The axon zipper of NAT-022. Two near, nearly parallel legs zip into one line when the shared length pays for the jogs. |
+| `level-links` | The level links of HWY-056. The edges between two items of a zoom level ride the link of the level. |
+| `quickbundles` | The QuickBundles of HWY-026. One pass puts each edge in the nearest cluster of resampled lines. Each cluster gets highways. |
+| `road-classes` | The road classes of HWY-034. The links that most ways use become main roads. A second pass routes the edges onto them. |
+| `flow-field` | The flow field of EDA-046. The edges into one side of a box merge like streams on shortest ways to one root. |
+| `wspd` | The well-separated pairs of HWY-018. The edges between the two sets of one pair share one highway. |
+| `od-cells` | The origin and destination cells of EDA-033. The edges between two cells of a zoom level share one trunk. |
+| `select` | The candidate selection of HWY-045. Some strategies propose highways, and a greedy pass with swaps keeps the best set. |
 
 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` and `level-links` 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>`.
+The new strategy has the options of both. The keys of the options of a gate are not keys of the strategy before it. Gates can follow gates.
+
+| Gate | Rule |
+|---|---|
+| `breakeven` (HWY-047) | An edge stays on its highways only when its share of the shared ink is larger than its detour. The option `shareAlpha` sets the cost `n^shareAlpha` of a stretch for `n` edges. |
+| `stretch` (HWY-048) | An edge stays only when its route is at most `budget` times its route alone, plus `pad`. |
+| `ambiguity` (HWY-049) | Each highway keeps its largest group of edges whose end nodes have an ambiguity of `maxAmbiguity` or less. The ambiguity is the share of the pairs of end nodes without an edge. |
+| `hysteresis` (HWY-046) | A new highway needs `kOn` edges. A highway of the plan before the edit stays while it has `kOff` edges. |
+| `ids` (HWY-054) | Each highway takes the id of the highway of the plan before the edit with the most common edges. The routes do not change. |
+
+The gates `hysteresis` and `ids` read `HighwayInput.previous`: the graph and the plan before an edit. Without it, `hysteresis` uses the limit `kOn` and `ids` changes nothing.
+The functions `keepMembers`, `edgeLengths`, `matchHighways`, `jaccard` and `commonEdges` help a new gate.
+
 A registry is data. No import changes it. The benchmark and the site take their lists from `STRATEGIES`, so a new built-in strategy gets its rows and its button with no other edit. A consumer makes its own registry:
 
 ```ts
@@ -383,6 +430,25 @@ const rows = runBenchmark(routersOf(registry), FIXTURES.slice(0, 1)); // The row
 
 The built-in strategies give the same output as their functions. `curveStrategies.rounded.run({ points, space }, { radius: 8 })` gives the segments of `curveOf(points, { type: "rounded", space, radius: 8 })`. `benchCurveStrategies` and the fourth argument of `benchRoom` take a list of strategies.
 
+### Wrappers of a router
+
+Two functions wrap a router strategy. The wrapped strategy has a new name, and the router does not change.
+
+- `stableOrderStrategy(strategy)` gives `<name>+stable`. It routes the edges in a stable order: by a hash of their ids, then by the ids. Thus each order of the input edges gives the same output.
+- `repairStrategy(strategy, repair?)` gives `<name>+repair`. After the router, `repairResult` repairs the breaks of the hard rules.
+  - It moves each free end back to its plug, and pushes each inner leg out of a box.
+  - It replaces each other leg through a box with a detour through the corner graph.
+  - When a leg does not repair, it routes the whole route again. Else it walks along the boundaries of the boxes, so boxes that touch do not block it.
+  - A route that it cannot repair keeps its base route.
+- `withStableOrder(router)` and `withRepair(router, repair?)` wrap a `Router` in the same way.
+
+```ts
+import { repairStrategy, routerStrategies, stableOrderStrategy } from "@mark1russell7/highways";
+
+const shared = stableOrderStrategy(routerStrategies.shared);
+const result = repairStrategy(shared).run(graph); // The router `shared+stable+repair`.
+```
+
 ### Declarations of the options
 
 Each strategy declares its options in `schema`. A declaration tells the type, the range, the step and the meaning of one option. Tools make controls and sweeps from these declarations, with no other data.