@mark1russell7/highways 0.5.0 → 0.5.1

package/README.md

@@ -346,7 +346,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, 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`, `corridors+breakeven`, `corridors+stretch`, `corridors+ambiguity`, `corridors+hysteresis`, `corridors+ids` |
+| `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` |
 | `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` |
 
@@ -400,9 +400,29 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `ridges` | The density ridges of HWY-032. The ridges of the blurred density of the edges become highways. |
 | `hdbscan` | The density clusters of HWY-028 (HDBSCAN). The clusters of edges that live over a long range of densities become highways. |
 | `hub-arcs` | The hub arc location of HWY-042. A greedy pass with swaps chooses at most `q` arcs, and each edge rides its best arc. |
+| `divided` | The divided edge bundling of HWY-011. Each highway of two-way traffic splits into two carriageways, one for each direction. |
+| `hierarchy` | The hierarchical edge bundling of HWY-001. Each edge goes near the hubs of the sections between its two leaves. |
+| `fdeb` | The force-directed edge bundling of HWY-002 with the box field of RULE-002. The bundled points snap back to legal ways. |
+| `mesh` | The control mesh of HWY-004. The crossings of the edges with the mesh form clusters, and a cluster shares one point. |
+| `kdeeb` | The density bundling of RULE-028 with HWY-006. The edges move up a density that is 0 in the boxes. |
+| `cubu` | The fast density bundling of HWY-007. The steps of `kdeeb` with a separable blur or a Fourier transform. |
+| `mlseb` | The moving least squares bundling of HWY-008. Each point moves to a local fit of the near edges, and snaps back to a legal way. |
+| `sbeb` | The skeleton-based edge bundling of HWY-009. The edges of a group move toward the skeleton of their shape. |
+| `areas` | The image-based edge bundles of HWY-010. Each group of edges is one area around the longest path of its skeleton. |
+| `confluent` | The confluent drawings of HWY-013. Each biclique of a greedy search is one track with two junctions. |
+| `power` | The power graphs of HWY-014. The edges between two modules of nodes are one power edge, and one highway. |
+| `crossbars` | The bundled crossings of HWY-022. Two sets of edges that cross near one place cross as two bundles. |
+| `frechet` | The subtrajectory clusters of HWY-027. The parts of the first routes near one reference part, by the discrete Fréchet distance, become highways. |
+| `spectral` | The spectral clusters of HWY-029. The largest eigengap of the compatibility graph of the edges gives the number of clusters. |
+| `resistance` | The spectral bundling of HWY-021. The effective resistance of each edge lowers the weight of a pair of two bridges. |
+| `link-communities` | The link communities of HWY-030. The edges with a common node and similar neighbours form one community. |
+| `territories` | The territories of HWY-033. The plugs and the bends form cells, and the strong flows between two cells become highways. |
+| `consensus` | The consensus of HWY-035. The finders vote on the pairs of edges, and the pairs that most finders agree on stay. |
+| `p-hub` | The p-hub median of HWY-041. The p-median of the plugs gives the hubs, and the links between two hubs become highways. |
+| `scale-space` | The scale space of HWY-053. Only the clusters that live over a long range of scales get highways. |
 
 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` and `lanes` change the plan of the option `from`: `shared-ways` (the default), `corridors` or `none`.
+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 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>`.
@@ -465,6 +485,27 @@ const shared = stableOrderStrategy(routerStrategies.shared);
 const result = repairStrategy(shared).run(graph); // The router `shared+stable+repair`.
 ```
 
+### 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.
+
+- `routePortfolio(graph, options?)` runs the router `shared` first, then more members for the size band of the graph. It gives the output with the fewest guard breaks, then the most ink saved (B1).
+- The options are `rule` (`collection` or `all`), `cap` (1.1, 1.25 or 1.5), `k` (3, 5 or 8), `budgetMs` and `maxMembers`.
+- Without `k`, the members are the fit of the band. Each member has a node limit, so the default is deterministic. Above 40 nodes, the fit is `shared` alone.
+- With `k`, the members are the first `k` names of the greedy set of the band.
+- A member passes the guard when it has no more breaks of each hard rule than `shared`. It also has no edge with a stretch above the cap. Under the rule `collection`, it also has no shared segment with edges of two collections. The base `shared` always passes.
+- `budgetMs` is an opt-in ceiling. A cut by the budget makes the output depend on the speed of the machine.
+- `budgetMs` is a soft limit between members. The router examines it only before each member, so a slow member runs to its end. With `budgetMs: 50`, the median on large boards was 142 to 239 ms.
+- The router picks with `selectBest` of `@mark1russell7/layout-contract`, the one run-time dependency of the core.
+- The result has the output, the winner, the trace of the pick and the move count `move.pick`.
+- `portfolioRouter(options?)` gives a `Router`, and `portfolioStrategy` is the router strategy. Add `portfolioStrategy` to a registry of your own to race it.
+
+```ts
+import { routePortfolio } from "@mark1russell7/highways";
+
+const { result, winner } = routePortfolio(graph, { rule: "all", cap: 1.25, k: 5, budgetMs: 50 });
+```
+
 ### 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.