@mark1russell7/highways 0.8.1 → 0.9.0

package/src/families/cases.ts

@@ -0,0 +1,108 @@
+// The 3 case families of the screen sets: `hub-chain`, `many-groups` and `packed-grid` (CORPUS-GEN).
+import type { CorpusDimension, DimensionValues, GenerateContext } from "@mark1russell7/layout-contract";
+import { hubChainBoard, manyGroupsBoard, packedGridBoard } from "../cases.ts";
+import type { Graph } from "../model.ts";
+import { changedDimensions, numberDimension, numberOf, type HighwaysBoard, type HighwaysFamily } from "./model.ts";
+
+/** This function gives a whole-number dimension with a linear scale. */
+const count = (name: string, min: number, max: number, value: number, meaning: string): CorpusDimension =>
+  numberDimension({ name, kind: "int", min, max, default: value, meaning });
+
+/** This function gives the numbers of the full dimension values, by name. */
+function numbers(dimensions: readonly CorpusDimension[], dims: DimensionValues): Record<string, number> {
+  return Object.fromEntries(dimensions.map((d) => [d.name, numberOf(dims, d.name)]));
+}
+
+/** The fields of a case family of `caseFamily`. */
+interface CaseFields {
+  readonly name: string;
+  readonly meaning: string;
+  readonly dimensions: readonly CorpusDimension[];
+  /** The name of the generator record, for example `case.hub-chain`. */
+  readonly generator: string;
+  /** This function gives the parameters of the generator record from the full values. The default gives the values that differ from their defaults. */
+  readonly params?: (dims: DimensionValues) => Readonly<Record<string, unknown>>;
+  /** This function makes the board. It gets the values by name, the input seed and the source of random numbers of the registry. */
+  readonly make: (values: Readonly<Record<string, number>>, seed: number, random: () => number) => Graph;
+}
+
+/** This function gives a case family. Its stream is mulberry32 of the input seed, and it uses only the stream, `Math.floor` and `Math.ceil`. */
+function caseFamily(fields: CaseFields): HighwaysFamily {
+  const { name, meaning, dimensions } = fields;
+  const params = fields.params ?? ((dims: DimensionValues) => changedDimensions(dimensions, dims));
+  return Object.freeze({
+    name,
+    version: 1,
+    owner: "highways",
+    meaning,
+    dimensions,
+    seeding: "mulberry32 of the input seed. The fixed part of the board takes no number. Then one stream gives the random links.",
+    crossEngine: "exact",
+    generate(seed: number, dims: DimensionValues, context: GenerateContext): HighwaysBoard {
+      return { graph: fields.make(numbers(dimensions, dims), seed, context.random), generator: { name: fields.generator, version: 1, params: params(dims), seed } };
+    },
+  });
+}
+
+/** The dimensions of `hub-chain`. */
+const HUB_CHAIN_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("rows", 1, 8, 3, "The number of rows of cards."),
+  count("cols", 4, 64, 32, "The number of cards in each row."),
+  count("long", 0, 200, 40, "The number of tries for a long link between two rows."),
+  count("gap", 0, 96, 48, "The free space between two cards, in units."),
+]);
+
+/** The family `hub-chain`: rows of cards in a chain, and long links between rows. At its defaults, it is `hubChainBoard`. */
+export const HUB_CHAIN: HighwaysFamily = caseFamily({
+  name: "hub-chain",
+  meaning: "Rows of cards in a chain, and long links that climb a chain of hubs away from their targets.",
+  dimensions: HUB_CHAIN_DIMENSIONS,
+  generator: "case.hub-chain",
+  make: (v, seed, random) => hubChainBoard({ seed, rows: v["rows"]!, cols: v["cols"]!, long: v["long"]!, gap: v["gap"]! }, random),
+});
+
+/** The dimensions of `many-groups`. */
+const MANY_GROUPS_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("groupCols", 1, 16, 8, "The number of columns of groups."),
+  count("groupRows", 1, 8, 4, "The number of rows of groups."),
+  count("perGroup", 1, 16, 4, "The number of cards in each group."),
+  count("crossLinksPerGroup", 0, 8, 3, "The number of random links between groups, for each group."),
+  count("groupGap", 0, 120, 60, "The free space between two groups, in units."),
+]);
+
+/** The family `many-groups`: groups of cards in a grid, with links between groups. At its defaults, it is `manyGroupsBoard`. */
+export const MANY_GROUPS: HighwaysFamily = caseFamily({
+  name: "many-groups",
+  meaning: "A grid of groups of cards, with random links between groups that go around the board.",
+  dimensions: MANY_GROUPS_DIMENSIONS,
+  generator: "case.many-groups",
+  make: (v, seed, random) =>
+    manyGroupsBoard(
+      { seed, groupCols: v["groupCols"]!, groupRows: v["groupRows"]!, perGroup: v["perGroup"]!, crossLinksPerGroup: v["crossLinksPerGroup"]!, groupGap: v["groupGap"]! },
+      random,
+    ),
+});
+
+/** The dimensions of `packed-grid`. */
+const PACKED_GRID_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("cols", 2, 32, 12, "The number of columns of boxes."),
+  count("rows", 2, 32, 8, "The number of rows of boxes."),
+  count("long", 0, 256, 48, "The number of long links between boxes far apart."),
+  count("reach", 1, 4, 2, "The largest step, in rows and in columns, of the link of a box to a box near it."),
+]);
+
+/**
+ * The family `packed-grid`: a grid of boxes that touch. At its defaults, it is `packedGridBoard` with 12 columns, 8 rows and 48 long links.
+ * Its generator record always has `cols`, `rows` and `long`, as the screen sets of today. It has `reach` only away from its default.
+ */
+export const PACKED_GRID: HighwaysFamily = caseFamily({
+  name: "packed-grid",
+  meaning: "A packed grid of boxes that touch, with no channel for the routes.",
+  dimensions: PACKED_GRID_DIMENSIONS,
+  generator: "case.packed-grid",
+  params: (dims) => {
+    const reach = numberOf(dims, "reach");
+    return { cols: numberOf(dims, "cols"), rows: numberOf(dims, "rows"), long: numberOf(dims, "long"), ...(reach === 2 ? {} : { reach }) };
+  },
+  make: (v, seed, random) => packedGridBoard({ seed, cols: v["cols"]!, rows: v["rows"]!, long: v["long"]!, reach: v["reach"]! }, random),
+});

package/src/families/fixtures.ts

@@ -0,0 +1,101 @@
+// The 3 fixture families of the screen sets: `tiny-uniform`, `small-clustered` and `dense-groups` (CORPUS-GEN).
+import type { CorpusDimension, DimensionValues, GenerateContext } from "@mark1russell7/layout-contract";
+import { fixtureRngSeed, makeFixture, type FixtureKind, type FixtureSpec } from "../fixtures.ts";
+import { enumDimension, numberDimension, numberOf, type HighwaysBoard, type HighwaysFamily } from "./model.ts";
+
+/** The values of the dimension `layout`: each `FixtureKind`. */
+export const FIXTURE_LAYOUTS: readonly FixtureKind[] = Object.freeze(["uniform", "clustered", "grid", "hubs", "collections"]);
+
+/** The share of the edges near the source when a spec has no `locality`: the default of `makeFixture`. */
+export const FIXTURE_LOCALITY = 0.65;
+
+/** The defaults of the dimensions of one fixture family: the spec of its board in the benchmark. */
+interface FixtureDefaults {
+  readonly layout: FixtureKind;
+  readonly nodes: number;
+  readonly edgesPerNode: number;
+  readonly fixedPorts: number;
+}
+
+/**
+ * This function gives the 5 dimensions of a fixture family. The name `kind` is reserved, so the dimension of the `FixtureKind` is `layout`.
+ * No dimension has a `when`, because each kind reads `locality` and `fixedPorts`.
+ */
+function fixtureDimensions(d: FixtureDefaults): readonly CorpusDimension[] {
+  return Object.freeze([
+    enumDimension("layout", FIXTURE_LAYOUTS, d.layout, "The way that the board puts its nodes and picks its edges: the `kind` of the `FixtureSpec`."),
+    numberDimension({ name: "nodes", kind: "int", min: 2, max: 400, default: d.nodes, scale: "log", meaning: "The number of nodes of the board." }),
+    numberDimension({ name: "edgesPerNode", kind: "real", min: 0, max: 6, default: d.edgesPerNode, meaning: "The number of edges, divided by the number of nodes." }),
+    numberDimension({ name: "locality", kind: "real", min: 0, max: 1, default: FIXTURE_LOCALITY, meaning: "The share of the edges that join a node near the source." }),
+    numberDimension({ name: "fixedPorts", kind: "real", min: 0, max: 1, default: d.fixedPorts, meaning: "The share of the nodes with one fixed plug for their outgoing edges." }),
+  ]);
+}
+
+/** This function gives the spec of a fixture board from the full dimension values. A field at the default of `makeFixture` stays out of the spec. */
+export function fixtureSpecOf(name: string, seed: number, dims: DimensionValues): FixtureSpec {
+  const layout = dims["layout"];
+  if (typeof layout !== "string" || !FIXTURE_LAYOUTS.includes(layout as FixtureKind)) throw new RangeError(`The dimension "layout" is ${String(layout)}, not a fixture kind.`);
+  const locality = numberOf(dims, "locality");
+  const fixedPorts = numberOf(dims, "fixedPorts");
+  return {
+    name,
+    kind: layout as FixtureKind,
+    nodes: numberOf(dims, "nodes"),
+    edgesPerNode: numberOf(dims, "edgesPerNode"),
+    seed,
+    ...(locality === FIXTURE_LOCALITY ? {} : { locality }),
+    ...(fixedPorts === 0 ? {} : { fixedPorts }),
+  };
+}
+
+/**
+ * This function gives the parameters of the generator record of a fixture board: the spec without its name and its seed.
+ * Thus the record of each screen board stays the record of today, for example `{ kind, nodes, edgesPerNode, fixedPorts }` of `small-clustered`.
+ */
+export function fixtureParams(spec: FixtureSpec): Readonly<Record<string, unknown>> {
+  const { name: _name, seed: _seed, ...params } = spec;
+  return params;
+}
+
+/** This function gives one fixture family with the defaults of its board in the benchmark. */
+function fixtureFamily(name: string, meaning: string, defaults: FixtureDefaults): HighwaysFamily {
+  return Object.freeze({
+    name,
+    version: 1,
+    owner: "highways",
+    meaning,
+    dimensions: fixtureDimensions(defaults),
+    seeding: "mulberry32 of (seed × 2654435761 + nodes) >>> 0. One stream gives the boxes, the plugs and then the edges, in a fixed order.",
+    // The kinds `clustered` and `collections` use `Math.log` and `Math.cos`, and the kind `hubs` uses `**`. Each fixture family has these kinds in `layout`.
+    crossEngine: "libm-dependent",
+    rngSeed: (seed: number, dims: DimensionValues) => fixtureRngSeed(seed, numberOf(dims, "nodes")),
+    generate(seed: number, dims: DimensionValues, context: GenerateContext): HighwaysBoard {
+      const spec = fixtureSpecOf(name, seed, dims);
+      return { graph: makeFixture(spec, context.random), generator: { name: "fixture", version: 1, params: fixtureParams(spec), seed } };
+    },
+  });
+}
+
+/** The family `tiny-uniform`: 10 nodes at random places. It is the fixture `tiny-uniform` of `FIXTURES` at its defaults. */
+export const TINY_UNIFORM: HighwaysFamily = fixtureFamily("tiny-uniform", "A tiny board of nodes at random places: the cost of a strategy at its start.", {
+  layout: "uniform",
+  nodes: 10,
+  edgesPerNode: 1.5,
+  fixedPorts: 0,
+});
+
+/** The family `small-clustered`: 100 nodes in clusters, with a fixed plug on 20% of the nodes. It is the fixture `small-clustered` at its defaults. */
+export const SMALL_CLUSTERED: HighwaysFamily = fixtureFamily("small-clustered", "Nodes in clusters, and fixed plugs on a share of the nodes.", {
+  layout: "clustered",
+  nodes: 100,
+  edgesPerNode: 2,
+  fixedPorts: 0.2,
+});
+
+/** The family `dense-groups`: 150 nodes in tight clusters. It is `denseGroupsBoard` at its defaults. */
+export const DENSE_GROUPS: HighwaysFamily = fixtureFamily("dense-groups", "Dense clusters whose groups overlap at the far view.", {
+  layout: "clustered",
+  nodes: 150,
+  edgesPerNode: 2,
+  fixedPorts: 0,
+});

package/src/families/index.ts

@@ -0,0 +1,36 @@
+// The corpus families of highways on the shared registry of `@mark1russell7/layout-contract` (CORPUS-GEN, L45).
+import { createFamilyRegistry, type FamilyRegistry } from "@mark1russell7/layout-contract";
+import { HUB_CHAIN, MANY_GROUPS, PACKED_GRID } from "./cases.ts";
+import { DENSE_GROUPS, SMALL_CLUSTERED, TINY_UNIFORM } from "./fixtures.ts";
+import type { HighwaysBoard, HighwaysFamily } from "./model.ts";
+
+export * from "./model.ts";
+export { DENSE_GROUPS, FIXTURE_LAYOUTS, FIXTURE_LOCALITY, fixtureParams, fixtureSpecOf, SMALL_CLUSTERED, TINY_UNIFORM } from "./fixtures.ts";
+export { HUB_CHAIN, MANY_GROUPS, PACKED_GRID } from "./cases.ts";
+// The parts of the shared registry that a host of the families uses. The site imports only `@mark1russell7/highways`.
+export {
+  createFamilyRegistry,
+  DEFAULT_RNG,
+  dimensionAt,
+  dimensionUnit,
+  familyKind,
+  levelsOf,
+  paramProblem,
+  type CorpusDimension,
+  type CorpusFamily,
+  type DimensionValues,
+  type FamilyRegistry,
+  type GenerateContext,
+  type ParamValue,
+} from "@mark1russell7/layout-contract";
+
+/**
+ * The corpus families of highways, in the order of the screen sets. Each family at its defaults makes the board of its screen family.
+ * An import registers nothing. A host makes a registry with `createFamilyRegistry(HIGHWAYS_FAMILIES)`, or with the lists of other engines too.
+ */
+export const HIGHWAYS_FAMILIES: readonly HighwaysFamily[] = Object.freeze([TINY_UNIFORM, SMALL_CLUSTERED, DENSE_GROUPS, HUB_CHAIN, MANY_GROUPS, PACKED_GRID]);
+
+/** This function gives a new registry of `HIGHWAYS_FAMILIES`. */
+export function highwaysRegistry(): FamilyRegistry<HighwaysBoard> {
+  return createFamilyRegistry(HIGHWAYS_FAMILIES);
+}

package/src/families/model.ts

@@ -0,0 +1,55 @@
+// The form of the corpus families of highways (CORPUS-GEN) on the shared registry of `@mark1russell7/layout-contract` (L45).
+import type { CorpusDimension, CorpusFamily, DimensionValues, ParamValue } from "@mark1russell7/layout-contract";
+import type { LayoutGenerator } from "../bench/screen/forms.ts";
+import type { Graph } from "../model.ts";
+
+/**
+ * The output of a family of highways: the graph of the board and its generator record.
+ * A screen set puts the board into an input file with `graphInput`. The set gives the id, the member seed and the cell.
+ */
+export interface HighwaysBoard {
+  readonly graph: Graph;
+  /** The generator of the board: its name, its version, its parameters and its input seed. */
+  readonly generator: LayoutGenerator;
+}
+
+/** A corpus family of highways: a family of the shared registry whose output is a `HighwaysBoard`. */
+export type HighwaysFamily = CorpusFamily<HighwaysBoard>;
+
+/** The engine of each dimension of the families of highways. */
+export const HIGHWAYS_ENGINE = "highways";
+
+/** The fields of a numeric dimension of `numberDimension`. */
+interface NumberFields {
+  readonly name: string;
+  readonly kind: "int" | "real";
+  readonly min: number;
+  readonly max: number;
+  readonly default: number;
+  readonly scale?: "linear" | "log";
+  readonly meaning: string;
+}
+
+/** This function gives an `int` or a `real` dimension that only highways reads. */
+export function numberDimension(fields: NumberFields): CorpusDimension {
+  return Object.freeze({ ...fields, scale: fields.scale ?? "linear", engines: Object.freeze([HIGHWAYS_ENGINE]) });
+}
+
+/** This function gives an `enum` dimension that only highways reads. */
+export function enumDimension(name: string, values: readonly string[], value: string, meaning: string): CorpusDimension {
+  return Object.freeze({ name, kind: "enum", values: Object.freeze([...values]), default: value, meaning, engines: Object.freeze([HIGHWAYS_ENGINE]) });
+}
+
+/** This function gives the values of the dimensions that differ from their defaults, in the order of the dimensions. */
+export function changedDimensions(dimensions: readonly CorpusDimension[], dims: DimensionValues): Record<string, ParamValue> {
+  const out: Record<string, ParamValue> = {};
+  for (const d of dimensions) if (!Object.is(dims[d.name], d.default)) out[d.name] = dims[d.name]!;
+  return out;
+}
+
+/** This function gives the value of a numeric dimension. It throws a `RangeError` when the value is not a number. */
+export function numberOf(dims: DimensionValues, name: string): number {
+  const v = dims[name];
+  if (typeof v !== "number") throw new RangeError(`The dimension "${name}" is ${String(v)}, not a number.`);
+  return v;
+}

package/src/fixtures.ts

@@ -52,12 +52,18 @@ const SIDES: readonly Side[] = ["north", "east", "south", "west"];
 const GAP = 12;
 const SPACING = 90;
 
+/** This function gives the seed of the random numbers of a fixture: `(seed × 2654435761 + nodes) >>> 0`. */
+export function fixtureRngSeed(seed: number, nodes: number): number {
+  return (seed * 2654435761 + nodes) >>> 0;
+}
+
 /**
  * This function makes the graph of a fixture. The same spec always gives the same graph.
  * Node boxes do not overlap, and a gap of 12 units stays between them.
+ * The default source of random numbers is `rng(fixtureRngSeed(spec.seed, spec.nodes))`. A corpus family gives the same stream from its registry.
  */
-export function makeFixture(spec: FixtureSpec): Graph {
-  const R = rng(spec.seed * 2654435761 + spec.nodes);
+export function makeFixture(spec: FixtureSpec, random: () => number = rng(fixtureRngSeed(spec.seed, spec.nodes))): Graph {
+  const R = random;
   const gauss = (): number => Math.sqrt(-2 * Math.log(R() + 1e-12)) * Math.cos(2 * Math.PI * R());
   const side = Math.sqrt(spec.nodes) * SPACING;
   const grid = new Grid<Box>(SPACING);

package/src/highways/soft-keys/index.ts

@@ -1,5 +1,5 @@
 import type { GroupRule } from "../../model.ts";
-import { byCollection } from "../../routers/trunks.ts";
+import { byCollection, groupRuleOf, type GroupRuleName } from "../../routers/trunks.ts";
 import { chainClusters, flowDistance, type Linkage } from "../flow-clusters/index.ts";
 import { groupedPlan, type EdgeGroup, type GroupSpine } from "../grouped.ts";
 import type { HighwayInput, HighwayPlan } from "../model.ts";
@@ -7,8 +7,11 @@ import { edgePlugs } from "../stretches.ts";
 
 /** The options of the highway strategy `soft-keys` (HWY-019 of the note on highways). */
 export interface SoftKeyOptions {
-  /** The rule that gives the key of each edge. The default is `byCollection`: the string `data.collection`. */
-  readonly rule: GroupRule;
+  /**
+   * The rule that gives the key of each edge, or the name of a built-in rule (`GROUP_RULE_NAMES`). The default is `byCollection`: the string `data.collection`.
+   * With `all`, each edge has one key, so the keys add no distance.
+   */
+  readonly rule: GroupRule | GroupRuleName;
   /** The distance that two different keys add. `Infinity` keeps the edges of two keys apart, as the hard keys do. The default is 0.25. */
   readonly lambda: number;
   /** Two clusters join while their distance is this value or less. The default is 0.5. */
@@ -54,11 +57,12 @@ export function softDistance(geom: number, keyA: string | undefined, keyB: strin
  * Each edge of a cluster gets the key of the cluster. It gets `flip` when it goes opposite to the first edge of the cluster.
  */
 export function softKeyClusters(input: HighwayInput, o: Readonly<SoftKeyOptions>): Map<string, EdgeGroup> {
+  const rule = groupRuleOf(o.rule);
   const ends = edgePlugs(input.graph).map(({ edge, ps, pt }) => ({
     edge: edge.id,
     s: ps.point,
     t: pt.point,
-    key: o.rule(edge),
+    key: rule(edge),
     values: o.attributes.map((a) => {
       const v = edge.data?.[a];
       return typeof v === "number" && Number.isFinite(v) ? v : undefined;

package/src/index.ts

@@ -17,6 +17,9 @@ export * from "./routers/index.ts";
 export * from "./room/index.ts";
 export * from "./room/lanes.ts";
 export * from "./room/levels/index.ts";
+export * from "./plugs/facing/index.ts";
+export * from "./levels/depths/index.ts";
+export * from "./whole/pipeline/index.ts";
 export * from "./bench/properties.ts";
 export * from "./bench/quality.ts";
 export * from "./bench/links.ts";
@@ -29,9 +32,14 @@ export * from "./bench/suite.ts";
 export * from "./strategies/index.ts";
 export * from "./bench/compare.ts";
 export * from "./bench/screen/index.ts";
+// The corpus families of highways on the shared registry of the contract (CORPUS-GEN).
+export * from "./families/index.ts";
 // The stretch of the exact model, for a benchmark that compares routers with the measures of the portfolio (PORTFOLIO-SPEED).
 export { exactStretch, exactStretches } from "./bench/exact/index.ts";
 export * from "./highways/index.ts";
 export * from "./order/index.ts";
 export * from "./repair/index.ts";
 export * from "./portfolio/index.ts";
+// One lane order for each stretch of runs (LANE-STRETCH), and its opt-in router `shared-stretch`.
+export * from "./lane-orders/stretch/index.ts";
+export { sharedStretchStrategy } from "./lane-orders/stretch/router.ts";

package/src/lane-order.ts

@@ -2,6 +2,7 @@
 // The package index does not export this module.
 import { byText } from "./compare.ts";
 import { dist, type Point } from "./geom.ts";
+import type { Route } from "./model.ts";
 
 /** Two points nearer than this distance are the same point. The value is the same as in `segments.ts`. */
 const SAME = 1e-6;
@@ -14,6 +15,42 @@ export interface Placed {
   readonly e: number;
 }
 
+/** A placed route with the way that it goes through the run. */
+export interface PlacedRoute extends Placed {
+  /** This value is true when the route goes from the last point of the run to its first point. Then `p` holds the points of the route in reverse. */
+  readonly reversed: boolean;
+}
+
+/** This function gives the index where `p` holds the points of `part` in a row, from `from` on, or -1. */
+export function findRun(p: readonly Point[], part: readonly Point[], from: number): number {
+  for (let i = from; i + part.length <= p.length; i++) {
+    let ok = true;
+    for (let j = 0; ok && j < part.length; j++) ok = dist(p[i + j]!, part[j]!) <= SAME;
+    if (ok) return i;
+  }
+  return -1;
+}
+
+/**
+ * This function places the routes on the run `run`. A route holds the points of the run in a row, in either direction.
+ * The list `lost` holds the edges of the routes that do not hold the run, in the order of `routes`.
+ */
+export function placeRoutes(run: readonly Point[], routes: readonly Route[]): { readonly placed: PlacedRoute[]; readonly lost: string[] } {
+  const placed: PlacedRoute[] = [];
+  const lost: string[] = [];
+  for (const r of routes) {
+    let at = findRun(r.points, run, 0);
+    if (at >= 0) placed.push({ edge: r.edge, p: r.points, s: at, e: at + run.length - 1, reversed: false });
+    else {
+      const p = [...r.points].reverse();
+      at = findRun(p, run, 0);
+      if (at >= 0) placed.push({ edge: r.edge, p, s: at, e: at + run.length - 1, reversed: true });
+      else lost.push(r.edge);
+    }
+  }
+  return { placed, lost };
+}
+
 /** The place where two routes part past one end of their common stretch, and the side of the first route there. */
 interface Parting {
   /** The last common point. */