@mark1russell7/highways 0.8.1 → 0.9.1

package/README.md

@@ -26,6 +26,29 @@ const result = cornersRouter({ name: "corners" }).route(graph);
 // Each route is a polyline: result.routes[0].points
 ```
 
+### Plugs
+
+A node can have `ports`, and an end of an edge can name one of them in `port`. Each plug has one of these forms:
+
+| Form | The place of the plug |
+|---|---|
+| `{ id }` | The router picks the side and the point. |
+| `{ id, side }` | The router picks the point on that side. |
+| `{ id, at }` | The plug is fixed at `at`, relative to the top-left corner of the box. |
+| `{ id, side, along }` | The plug is fixed at the side start plus `along` times the side length. |
+
+- `along` goes from 0 to 1. The start of `north` and `south` is the left end. The start of `east` and `west` is the top end.
+- When the box gets taller or wider, a plug with `along` keeps its fraction of the side.
+- `resolvePorts(graph)` gives each plug with `along` a fixed `at`. Each router calls it at the start of `route`.
+- The arithmetic is the arithmetic of `portPoint` of `@mark1russell7/layout-contract`. `portOffset` calls it.
+- `resolvePorts` throws a `RangeError` for a bad `along`. A bad value is not finite or is outside 0 to 1. A plug with `along` also needs a `side` and has no `at`.
+- In an input file, such a plug has `side` and `along`, with no `x` and no `y`.
+
+```ts
+const node = { id: "a", box: { x: 0, y: 0, w: 80, h: 40 }, ports: [{ id: "out", side: "east", along: 0.25 }] };
+// The plug "out" is at (80, 10). With h = 120, it is at (80, 30).
+```
+
 ## Curve types
 
 A router gives polylines. The curve layer turns a polyline into a curve of a type. The polyline can come from any router, from a lane of `laneRoutes` or from a link of a zoom level.
@@ -107,6 +130,8 @@ Two edges can go along several runs one after the other. The option `laneOrder`
 - The default of `trunks` and `shared` is `bundle`. The default of `sections` is `run`, so its runs keep the lane order of version 0.2.0.
 - `orderLanes(run, routes, order)` gives the order of one run. Its default order is `run`.
 - The option changes only the lane order. The routes, the runs and their keys stay the same.
+- The option `stretchOrder` of `shared` and `shared-all` gives one order to each stretch of runs: `none` (the default), `consensus`, `periphery` or `sifting`. The default of `shared-stretch` is `sifting`. `siftPasses` sets the passes of `sifting`.
+- `stretchLaneOrders(runs, options?)` gives the order of each run. `laneStretches` gives the stretches. [One lane order for each stretch](../../docs/research/XPLAT.md#one-lane-order-for-each-stretch-lane-stretch) gives the numbers.
 
 The benchmark measures the lanes of `highwayCurves` on the case boards, with each lane order. A crossing in the body is between the middles of the first and the last leg of a bundle. An end crossing is near a merge or a split.
 
@@ -345,10 +370,19 @@ 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` |
 | `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` |
 | `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` |
+
+`STEPS` gives the steps in the order of the pipeline: `group`, `plugs`, `router`, `highway`, `levels`, `curve`, `room`, `whole`.
+
+- The plugs come before the router, because the router finds its ways between the plugs.
+- The levels come after the routes, because the last level uses the routes.
+- The step `whole` runs the other steps, so it comes last.
 
 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.
 
@@ -357,7 +391,29 @@ 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`, `highwayStrategies`, `curveStrategies` and `roomStrategies` give each built-in strategy with its typed options.
+- `STRATEGIES` is the registry of `BUILT_IN_STRATEGIES`. The records `groupStrategies`, `plugStrategies`, `routerStrategies`, `highwayStrategies`, `levelStrategies`, `curveStrategies`, `roomStrategies` and `wholeStrategies` give each built-in strategy with its typed options.
+
+### The steps `plugs`, `levels` and `whole`
+
+Each of these steps has one default strategy. The default gives the output of the code before the step, so each route stays the same.
+
+- `facing` (the step `plugs`) puts each free plug on the side that faces the other end of its edge. The router `corners` uses it by default.
+  The option `plug` of `corners` takes a plug strategy, and `plugOptions` gives its options.
+- `depths` (the step `levels`) makes one zoom level for each depth of the tree, and a last level with each node alone (`depthLevels`).
+  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.
+- `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.
+
+```ts
+import { asRouter, CASES, plugStrategies, routerStrategies, wholeStrategies } from "@mark1russell7/highways";
+
+const graph = CASES.find((c) => c.name === "case-hub-chain")!.make();
+// The two calls give the routes of `corners` with no option.
+const a = asRouter(routerStrategies.corners, { plug: plugStrategies.facing }).route(graph);
+const b = wholeStrategies.pipeline.run(graph).result;
+```
 
 ### The step `highway`
 
@@ -420,6 +476,11 @@ The step `highway` decides which edges share a way. It gives a plan, not routes.
 | `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. |
+| `steiner` | The Steiner trees of HWY-036. Each group of edges gets one rectilinear tree around the boxes, and the shared parts of the tree become highways. |
+| `gaps` | The gap highways of HWY-057. A free line in a gap between boxes holds a highway when enough edges can ride it. |
+| `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. |
 
 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`.
@@ -485,6 +546,16 @@ const shared = stableOrderStrategy(routerStrategies.shared);
 const result = repairStrategy(shared).run(graph); // The router `shared+stable+repair`.
 ```
 
+### The router `attraction`
+
+The router `attraction` is opt-in. It is not in `STRATEGIES`, so the default outputs do not change.
+
+- `attractionRouter(options)` gives the negotiated attraction of HWY-044, and `attractionStrategy` is its router strategy.
+- Each pass after the first routes each edge again. A link that many edges used in the passes before gets a lower cost.
+- The options are `passes` (1 to 10), `attraction` (0 to 1), `capacityWeight` (0 to 10) and `laneWidth` (1 to 12).
+- 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 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.
@@ -505,6 +576,7 @@ The router `portfolio` is opt-in. It is not in `STRATEGIES`, so the default outp
 - The result has the output, the winner, the trace of the pick and the move count `move.pick`.
 - `exactStretches(graph, options?)` gives a function from the routes to the stretch of each edge in the exact model. The router uses it for the cap. `exactStretch` gives the largest stretch.
 - `portfolioRouter(options?)` gives a `Router`, and `portfolioStrategy` is the router strategy. Add `portfolioStrategy` to a registry of your own to race it.
+- `portfolioStrategy.schema` declares each option except the clock `now` (SCHEMA-GAPS). The lists of `rule`, `cap`, `k` and `hashes` come from `PORTFOLIO_RULES`, `PORTFOLIO_CAPS`, `PORTFOLIO_KS_API` and `PORTFOLIO_HASHES`.
 
 ```ts
 import { routePortfolio } from "@mark1russell7/highways";
@@ -512,15 +584,24 @@ import { routePortfolio } from "@mark1russell7/highways";
 const { result, winner } = routePortfolio(graph, { rule: "all", cap: 1.25, k: 5, budgetMs: 50 });
 ```
 
+### The router `shared-stretch`
+
+The router `shared-stretch` is opt-in. It is `shared` with the stretch order `sifting`. It is not in `STRATEGIES`, so the default outputs do not change.
+
+- `sharedStretchStrategy` is the router strategy. Add it to a registry of your own to race it.
+- Its routes are the routes of `shared`. Only the lane order of the runs changes.
+- On `screen-v1`, the order `sifting` cuts the lane crossings and the broken pairs of `shared` from 21 to 16.
+- Each run calculates the relation of each pair of its lanes. On a dense board of 1000 boxes, a route takes 25 times the time of `shared`.
+
 ### 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.
 
 | Type | Fields | Values |
 |---|---|---|
-| `number`, `integer` | `min`, `max`, `step`, `scale`, `special`, `marks` | A number. An `integer` takes only whole numbers. |
+| `number`, `integer` | `min`, `max`, `step`, `scale`, `special`, `marks`, `values` | A number. An `integer` takes only whole numbers. With `values`, only one of `values`. |
 | `boolean` | | `false` or `true`. |
-| `enum` | `values` | One of `values`. |
+| `enum` | `values`, `custom` | One of `values`. With `custom: "function"`, also a rule of the caller. |
 | `function`, `strategy`, `list`, `object` | `step` (for `strategy`) | A rule, a strategy, an array or an object. A sweep cannot set them. |
 
 Each declaration has a `describe` sentence and an optional `default`.
@@ -529,18 +610,27 @@ Each declaration has a `describe` sentence and an optional `default`.
 - The `scale` is `linear` or `log`. A sweep on the scale `log` gives values with equal ratios.
 - The `special` values are valid outside the range. `Infinity` sets no limit.
 - The `marks` are the notable values: the default and the values of the sweeps of the benchmark.
+- The `values` of a number option are its only valid values. A control shows them as a list, and a sweep gives them. The `cap` of the portfolio router uses them.
+- An enum with `custom: "function"` names the known rules of an option that also takes a rule. A control sets the names, and a caller can still give its own rule.
 - The `default` is the value that the strategy uses when the caller and `defaults` give no value. A value of `defaults` comes first.
 
 The type `OptionSchema<O>` needs one declaration for each key of the options, and no other key. A number option needs a number declaration, and an enum declaration takes only the values of its type.
+An option of a rule or its name, for example `GroupRule | "collection" | "all"`, takes an enum of the names or a declaration of the rule.
+
+The option `rule` of the routers `trunks`, `shared` and `shared-all`, and of the highway strategies `keys`, `shared-ways` and `soft-keys`, takes a name (SCHEMA-GAPS):
+
+- With `collection`, the rule is `byCollection`. With `all`, each edge has one key. For the router `shared`, `all` is the same as no rule.
+- The `defaults` of each strategy keep the rule `byCollection`, as before. The declaration gives its name `collection` as its `default`. The router `shared-all` sets no rule.
+- A rule of the caller stays valid. The name `collection` gives the same output as the rule `byCollection`.
 
 The helpers read the declarations:
 
 - `optionDefaults(strategy)` gives the effective default of each option. The strategy gives the same output with this object as with no options.
 - `listOptions(strategy)` gives each option with its key, its declaration and its default, in the order of the schema.
-- `checkOptions(strategy, options)` reports each value without a declaration, of the wrong type, out of the range or not a whole number. It changes no value.
-- `clampOptions(strategy, options)` moves each number into its range, for a control. A special value stays.
+- `checkOptions(strategy, options)` reports each value without a declaration, of the wrong type, out of the range, not a whole number or not one of `values`. It changes no value.
+- `clampOptions(strategy, options)` moves each number into its range, for a control. A number with `values` moves to the nearest value. A special value stays.
 - `checkSchema(strategy)` reports each option of `defaults` without a declaration, and each bad declaration.
-- `sweepValues(declaration, { count, special })` gives the values of a sweep. Without `count`, a number option gives its `marks`.
+- `sweepValues(declaration, { count, special })` gives the values of a sweep. Without `count`, a number option gives its `marks`. Else, a number option with `values` gives its `values`.
 - `sweepOf(strategy, key, options)` gives one setting for each value of a sweep. The name of a setting is the key and the value.
 - `sweepGrid(strategy, keys, options)` gives one setting for each combination of the values of the keys.
 
@@ -556,7 +646,7 @@ const rows = sweepSections("case-hub-chain", graph, sweepOf(routerStrategies.sec
 
 A test examines each built-in strategy with `checkSchema`. Thus an option of `defaults` without a declaration makes the test fail.
 
-The plugs have one strategy, so they have no step yet. The step `group` gives the grouping rule of the zoom levels.
+The step `plugs` gives the plugs of the router `corners`. The step `group` gives the grouping rule of the zoom levels, and the step `levels` makes the levels.
 
 ## Measures and the report
 
@@ -596,7 +686,20 @@ The script `bench` takes `--seeds <n>` and `--report <file>`. A family with more
 
 The workflow `Bench` runs the suite in parts. Each part writes its report, and `joinReports` joins the reports into the report of one run.
 
-`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.
+Three options of `runSuite` keep each part short (BENCH-GREEN):
+
+- `shard` runs one shard of the cells of the steps `router` and `highway`. The strategy at place `s` on the seed `k` belongs to the shard `(s + k) % count`.
+- `caps` stops a strategy above a fixture size. The report lists each such cell in `capped`.
+- `pair` names a baseline router, for example `shared`. On the first seed of each fixture to `pairMax` nodes, the baseline routes in turn with each strategy. The row gets `paired`, with the two medians and their ratio.
+
+`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.
+
+`compareAnyStep` does the same for each step of `COMPARE_ALL_STEPS`, which is `STEPS`. The compare page of the site uses it.
+
+- The step `highway` makes the plan of each strategy, and `follow` routes the plan, as in the screen. `highwayRouters` gives these routers.
+- The steps `plugs`, `levels` and `whole` run each strategy as a router (`stepRouterStrategy`), and measure the routes as the step `router`.
+- The step `room` opens the gaps of a packed board with each strategy and measures the open board with `roomValues`.
+- The option `onRow` gets each row when its strategy is done, so a host can show the progress.
 
 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.
 
@@ -615,6 +718,7 @@ A transcendental Math function, for example `Math.atan2` or `Math.hypot`, can gi
 - For a new decision, use exact arithmetic: a cross product, a dot product or a squared length.
 - A compare function of a sort must be a total order. Otherwise, two engines can give two orders.
 - The lane order of a run comes from a merge sort of the package, so each engine gives the same order (LANE-ORDER).
+- Each sort of the stretch orders (LANE-STRETCH) has a total order. Its ties break by the key of the edge or of the run. Thus the 4 cells of `Xplat` agree.
 - Version 0.8.0 changes the default lane order of some shared runs. No route point moves. [The lane order](../../docs/research/XPLAT.md#the-lane-order-lane-order) gives the changes.
 - The note [`XPLAT.md`](../../docs/research/XPLAT.md) gives the result of the item XPLAT-HASH.