@mark1russell7/highways 0.3.0 → 0.4.1

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,8 @@ 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` |
-| `curve` | `CurveInput`: the points, the normals of the plugs and the free space | `CurveSegment[]` | `straight`, `rounded`, `spline`, `arc`, `smooth`, `clothoid` |
+| `highway` | `HighwayInput`: the graph, and optionally the first routes of a router | `HighwayPlan`: the highways as data | `keys`, `shared-ways`, `corridors` |
+| `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` |
 
 A strategy has a `step`, a `name`, a `describe` text, its `defaults` and the method `run(input, options?)`. The type of the options comes from `defaults`. Each option that a call does not give gets its default value.
@@ -333,7 +355,27 @@ A strategy has a `step`, a `name`, a `describe` text, its `defaults` and the met
 - `register(registry, ...strategies)` gives a new registry. It does not change the registry before it.
 - `listStrategies(registry, step)` gives the strategies of a step, in order. `findStrategy` and `getStrategy` give one strategy by its name.
 - `asRouter(strategy, options?)` gives a `Router`, and `routersOf(registry)` gives the routers of a registry.
-- `STRATEGIES` is the registry of `BUILT_IN_STRATEGIES`. The records `groupStrategies`, `routerStrategies`, `curveStrategies` and `roomStrategies` give each built-in strategy with its typed options.
+- `STRATEGIES` is the registry of `BUILT_IN_STRATEGIES`. The records `groupStrategies`, `routerStrategies`, `highwayStrategies`, `curveStrategies` and `roomStrategies` give each built-in strategy with its typed options.
+
+### The step `highway`
+
+The step `highway` decides which edges share a way. It gives a plan, not routes. `follow` routes the plan.
+
+- A `Highway` has an `id`, a `key`, a `spine`, its `lanes` and its `members`. Lane 0 is on the left of the spine.
+- A `HighwayMember` is an edge with its merge point and its split point. `on` and `off` give their places on the spine.
+- `checkPlan(graph, plan)` lists the problems of a plan. A good plan gives an empty list.
+- `follow(graph, plan, options?)` routes each member from its plug to its merge point, along the spine, and from its split point to its target.
+- `follow` routes an edge that is not a member with its first route, or with the way finder. It gives one run for each stretch that two members or more share.
+- `highwayRouter(strategy)` and `highwayRouterStrategy(strategy)` give a router that makes the plan and then calls `follow`.
+
+| Strategy | Decision |
+|---|---|
+| `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. |
+
+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 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 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:
 
@@ -362,6 +404,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.
@@ -448,10 +509,13 @@ The workflow `Bench` runs the suite in parts. Each part writes its report, and `
 
 `compareStep` runs each strategy of one step on one board, with the measures of the suite. It gives one row for each strategy and the Pareto front of the step. The options give each strategy its own options. The compare page of the site uses it.
 
+With the option `lanes`, the step `curve` opens each shared way of the routes of `curveRouter` into lanes, and each curve draws the lanes. Each input then has its `lane`, so the curve `highway` bends the lanes of a bundle as one with each of its options.
+
 ```ts
 import { compareStep } from "@mark1russell7/highways";
 
 const { rows, front } = compareStep("curve", graph, { options: { arc: { radius: 20 } } });
+const lanes = compareStep("curve", graph, { curveRouter: "shared", lanes: { width: 5, maxWidth: 30 }, options: { highway: { jog: "quintic" } } });
 ```
 
 ## License