@mark1russell7/layout-contract 0.2.13 → 0.2.14

package/src/input.ts

@@ -86,6 +86,19 @@ export interface LayoutGenerator {
   readonly seed: number;
 }
 
+/**
+ * One minimum distance between two boxes (`a` and `b`). It replaces the two margins of the boxes for this pair, and the global `gap`.
+ * The order of `a` and `b` has no meaning. A pair without an entry keeps the margins and the `gap`.
+ */
+export interface PairGap {
+  readonly a: string;
+  readonly b: string;
+  /** The minimum distance between the two boxes, in units: a finite number of 0 or more. */
+  readonly gap: number;
+  /** The count of the channels that the gap has space for. It is information only: a whole number of 0 or more. */
+  readonly lanes?: number;
+}
+
 /** The cell of an input in the taxonomy: one value for each dimension. The dimensions are in `docs/FORMAT.md` of `packing`. */
 export interface LayoutCell {
   readonly containerSize?: "fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea";
@@ -124,6 +137,8 @@ export interface LayoutInput {
   readonly container?: LayoutContainer;
   /** The free space between two boxes with their margins. Routes use it. */
   readonly gap?: number;
+  /** The distances of some pairs of boxes. An entry replaces the margins and the `gap` for its pair. `canonicalInput` sorts the list. */
+  readonly pairGaps?: readonly PairGap[];
   readonly boxes: readonly LayoutBox[];
   readonly edges?: readonly LayoutEdge[];
   readonly obstacles?: readonly Obstacle[];
@@ -141,6 +156,7 @@ export interface PackInput {
   readonly items: readonly Item[];
   readonly obstacles?: readonly Obstacle[];
   readonly gap?: number;
+  readonly pairGaps?: readonly PairGap[];
 }
 
 /** This function gives the packer input of a file. An input without a container gets `{ fixed: "none" }`, so the packer picks the size. */
@@ -150,5 +166,22 @@ export function toPackInput(input: LayoutInput): PackInput {
     items: input.boxes,
     ...(input.obstacles === undefined ? {} : { obstacles: input.obstacles }),
     ...(input.gap === undefined ? {} : { gap: input.gap }),
+    ...(input.pairGaps === undefined ? {} : { pairGaps: input.pairGaps }),
   };
 }
+
+/** This function compares two strings by their UTF-16 code units, as `Array.prototype.sort` does without a compare function. */
+const byCode = (x: string, y: string): number => (x < y ? -1 : x > y ? 1 : 0);
+
+/**
+ * This function gives the canonical form of an input. `documentHash` uses it for each `layout-input/1` document.
+ * Each pair of `pairGaps` gets `a` before `b`, and the list is sorted by `a` and then by `b`.
+ * An input without `pairGaps` is the same object, so its hash does not change.
+ */
+export function canonicalInput<T extends LayoutInput>(input: T): T {
+  if (!Array.isArray(input.pairGaps)) return input;
+  const pairGaps = input.pairGaps
+    .map((p): PairGap => (byCode(p.a, p.b) > 0 ? { ...p, a: p.b, b: p.a } : p))
+    .sort((x, y) => byCode(x.a, y.a) || byCode(x.b, y.b));
+  return { ...input, pairGaps };
+}

package/src/rules.ts

@@ -1,5 +1,5 @@
 import { boundsOf, grow, overlapOf, type Rect, type Region } from "./geometry.ts";
-import type { LayoutBox, LayoutInput, Obstacle } from "./input.ts";
+import type { LayoutBox, LayoutInput, Obstacle, PairGap } from "./input.ts";
 import { applyPack, type PackOutput } from "./output.ts";
 import { SHAPE_KIND_IDS, shapeKindProblem, type ShapeSupport } from "./shapes.ts";
 import { DEFAULT_TOLERANCE, EPS, RECORD_EPS } from "./tolerance.ts";
@@ -15,20 +15,52 @@ export function placedRect(box: LayoutBox): Rect | undefined {
 /**
  * This function counts the pairs of placed boxes whose insides, with their margins, overlap by more than `tolerance` on each axis.
  * A box with a shape counts as its bounding box. That area is larger, thus the count is safe.
+ *
+ * A pair of `pairGaps`, in either order, uses its `gap` in place of the two margins. One box grows by the gap, and the other box does not grow.
+ * Thus the pair breaks the rule only when the boxes are nearer than the gap on each axis. The other pairs do not change.
  */
-export function countOverlaps(boxes: readonly LayoutBox[], tolerance: number = DEFAULT_TOLERANCE.overlap): number {
-  const rects: Rect[] = [];
+export function countOverlaps(boxes: readonly LayoutBox[], tolerance: number = DEFAULT_TOLERANCE.overlap, pairGaps?: readonly PairGap[]): number {
+  if (pairGaps === undefined || pairGaps.length === 0) return marginOverlaps(boxes, tolerance, undefined);
+  const gaps = new Map<string, number>();
+  for (const p of pairGaps) {
+    const key = pairKey(p.a, p.b);
+    if (p.a !== p.b && !gaps.has(key)) gaps.set(key, p.gap);
+  }
+  const raw = new Map<string, Rect>();
+  for (const box of boxes) {
+    const r = placedRect(box);
+    if (r !== undefined && !raw.has(box.id)) raw.set(box.id, r);
+  }
+  let count = marginOverlaps(boxes, tolerance, gaps);
+  for (const [key, gap] of gaps) {
+    const [a, b] = JSON.parse(key) as [string, string];
+    const ra = raw.get(a);
+    const rb = raw.get(b);
+    if (ra === undefined || rb === undefined) continue;
+    const o = overlapOf(grow(ra, gap), rb);
+    if (o.x > tolerance && o.y > tolerance) count++;
+  }
+  return count;
+}
+
+/** This function gives the key of a pair of box ids, with the same key for each order. */
+const pairKey = (a: string, b: string): string => JSON.stringify(a < b ? [a, b] : [b, a]);
+
+/** This function counts the overlaps of the boxes with their margins. It skips the pairs of `skip`. Without `skip`, it is the rule of 0.2.13. */
+function marginOverlaps(boxes: readonly LayoutBox[], tolerance: number, skip: ReadonlyMap<string, number> | undefined): number {
+  const rects: { readonly id: string; readonly r: Rect }[] = [];
   for (const box of boxes) {
     const r = placedRect(box);
-    if (r !== undefined) rects.push(grow(r, box.margin));
+    if (r !== undefined) rects.push({ id: box.id, r: grow(r, box.margin) });
   }
-  rects.sort((a, b) => a.x - b.x);
+  rects.sort((a, b) => a.r.x - b.r.x);
   let count = 0;
   for (let i = 0; i < rects.length; i++) {
-    const a = rects[i]!;
+    const a = rects[i]!.r;
     for (let j = i + 1; j < rects.length; j++) {
-      const b = rects[j]!;
+      const b = rects[j]!.r;
       if (b.x >= a.x + a.w - tolerance) break;
+      if (skip !== undefined && skip.has(pairKey(rects[i]!.id, rects[j]!.id))) continue;
       const o = overlapOf(a, b);
       if (o.x > tolerance && o.y > tolerance) count++;
     }
@@ -279,7 +311,8 @@ export function countObstacleHits(
 /**
  * This function gives the count of each hard rule of the output of a packer.
  * It applies the output with `applyPack`. Only the placed boxes and the locked boxes count for the overlaps and the container.
- * `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle.
+ * `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle. A pair of `pairGaps` uses its gap in place of the margins.
+ *
  * A locked box without a placement, or with a move of more than `RECORD_EPS`, breaks `locked-kept`.
  * A locked box without a position in the input is a bad input, not a break. `checkInput` finds it.
  * Another box without a placement that is not in `overflow` breaks `complete`.
@@ -308,7 +341,7 @@ export function packHard(input: LayoutInput, output: PackOutput, tolerance: numb
     }
   }
   return {
-    "no-overlap": countOverlaps(kept, tolerance) + countObstacleHits(kept, after.obstacles, tolerance),
+    "no-overlap": countOverlaps(kept, tolerance, input.pairGaps) + countObstacleHits(kept, after.obstacles, tolerance),
     "in-container": countOutside({ ...after, boxes: kept }, tolerance, options),
     "locked-kept": lockedMoved,
     complete: incomplete,
@@ -318,6 +351,7 @@ export function packHard(input: LayoutInput, output: PackOutput, tolerance: numb
 /**
  * This function gives the problems of an input file. An empty list tells that the file is good.
  * A problem is a bad input, not a break of a hard rule. Thus an engine refuses the input.
+ * In `pairGaps`, an unknown box, a pair of one box, a repeated pair in either order, a bad `gap` and bad `lanes` are problems.
  */
 export function checkInput(input: LayoutInput): readonly string[] {
   const problems: string[] = [];
@@ -334,5 +368,31 @@ export function checkInput(input: LayoutInput): readonly string[] {
   for (const edge of input.edges ?? []) {
     if (!ids.has(edge.source) || !ids.has(edge.target)) problems.push(`edge ${edge.id}: a box of the edge is not in the input`);
   }
+  problems.push(...pairGapProblems(input.pairGaps, ids));
+  return problems;
+}
+
+/** This function gives the problems of the `pairGaps` of an input. `ids` has the ids of the boxes. */
+function pairGapProblems(pairGaps: LayoutInput["pairGaps"], ids: ReadonlySet<string>): string[] {
+  if (pairGaps === undefined) return [];
+  if (!Array.isArray(pairGaps)) return ["pairGaps: the value is not a list"];
+  const problems: string[] = [];
+  const seen = new Map<string, number>();
+  pairGaps.forEach((p: PairGap, i) => {
+    const at = `pair gap ${i} (${String(p?.a)}, ${String(p?.b)})`;
+    if (typeof p !== "object" || p === null || typeof p.a !== "string" || typeof p.b !== "string") {
+      problems.push(`pair gap ${i}: the entry has no string ids a and b`);
+      return;
+    }
+    for (const id of [p.a, p.b]) if (!ids.has(id)) problems.push(`${at}: the box ${id} is not in the input`);
+    if (p.a === p.b) problems.push(`${at}: the two ids are the same box`);
+    if (typeof p.gap !== "number" || !Number.isFinite(p.gap) || p.gap < 0) problems.push(`${at}: the gap ${String(p.gap)} is not a finite number of 0 or more`);
+    if (p.lanes !== undefined && (typeof p.lanes !== "number" || !Number.isInteger(p.lanes) || p.lanes < 0))
+      problems.push(`${at}: the lanes value ${String(p.lanes)} is not a whole number of 0 or more`);
+    const key = JSON.stringify(p.a < p.b ? [p.a, p.b] : [p.b, p.a]);
+    const first = seen.get(key);
+    if (first !== undefined) problems.push(`${at}: the pair is also pair gap ${first}`);
+    else seen.set(key, i);
+  });
   return problems;
 }

package/src/strategy-space.ts

@@ -46,6 +46,12 @@ export interface MemberRule {
   readonly min: number;
   readonly max: number;
   readonly ordered: boolean;
+  /**
+   * The member lists that the option permits. Each entry is a list of whole configs of the space of the members.
+   * Without `pool`, each list of base configs with a good count is a member list.
+   * With `pool`, a config of the option has the members of one entry, and `spaceSize` counts each entry one time.
+   */
+  readonly pool?: readonly (readonly StrategyConfig[])[];
 }
 
 /** The inputs that an option supports. A missing field supports each value. */
@@ -149,7 +155,7 @@ export interface SampleOptions extends ShapeFilter {
   /** The count of the configs, a whole number of 0 or more. */
   readonly n: number;
   readonly seed: number;
-  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples. */
+  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples, or one entry of its `pool`. */
   readonly meta?: "skip" | "sample";
   /** The largest count of option draws. The default is the larger value of 1000 and `100 * n`. */
   readonly maxTries?: number;
@@ -204,6 +210,21 @@ function isActive(p: SpaceParam, values: Values): boolean {
   return p.when.in.some((x) => x === v);
 }
 
+/** This function gives the problem of a value of a param, or `undefined` for a value in its range. The corpus dimensions of `families.ts` use it. */
+export function paramProblem(param: SpaceParam, value: unknown): string | undefined {
+  return valueProblem(param, value);
+}
+
+/** This function tells if a param is active for the values of the earlier params. A param without `when` is always active. */
+export function paramActive(param: SpaceParam, values: Readonly<Record<string, ParamValue>>): boolean {
+  return isActive(param, values);
+}
+
+/** This function gives the stable form of a value of a param: a real number gets 12 significant digits, and `-0` becomes `0`. */
+export function paramValue(param: SpaceParam, value: ParamValue): ParamValue {
+  return normalize(param, value);
+}
+
 /** This function gives the part of a space that has a stage, and the prefix of the names of its stages. */
 function partOf(space: StrategySpace, stage: string): { readonly space: StrategySpace; readonly prefix: string } {
   for (const part of space.parts ?? []) {
@@ -291,6 +312,9 @@ function optionProblems(stage: SpaceStage, o: StageOption): Problem[] {
     const { min, max, ordered } = o.members;
     if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || min > max || typeof ordered !== "boolean")
       out.push(["members", `${at} has a member rule without whole counts 1 <= min <= max and a boolean ordered`]);
+    const pool: unknown = o.members.pool;
+    if (pool !== undefined && (!Array.isArray(pool) || pool.length === 0 || !pool.every((entry: unknown) => Array.isArray(entry))))
+      out.push(["pool", `${at} has a pool that is not a list of one or more member lists`]);
   }
   return out;
 }
@@ -407,14 +431,47 @@ function memberProblems(part: StrategySpace, rule: MemberRule, members: unknown,
     if (ids.has(id)) out.push(["duplicate", `the members ${ids.get(id)} and ${k} of ${at} are the same config ${id}`]);
     else ids.set(id, k);
   });
+  if (rule.pool !== undefined && out.length === 0) {
+    const key = memberKey(part, rule, members as readonly StrategyConfig[]);
+    if (!rule.pool.some((entry) => memberKey(part, rule, entry) === key))
+      out.push(["pool", `${at} has a member list that is not in its pool of ${rule.pool.length} ${rule.pool.length === 1 ? "list" : "lists"}`]);
+  }
+  return out;
+}
+
+/** This function gives the key of a good member list: the `configId` of each member, sorted when the rule is not ordered. */
+function memberKey(part: StrategySpace, rule: MemberRule, members: readonly StrategyConfig[]): string {
+  const ids = members.map((m) => idOf(canonicalOf(part, m, true)));
+  if (!rule.ordered) ids.sort();
+  return ids.join(",");
+}
+
+/** This function gives the problems of the pool of a meta option of a good space. `part` is the space of the members. */
+function poolProblems(part: StrategySpace, rule: MemberRule, at: string): Problem[] {
+  const out: Problem[] = [];
+  const keys = new Map<string, number>();
+  const plain: MemberRule = { min: rule.min, max: rule.max, ordered: rule.ordered };
+  (rule.pool ?? []).forEach((entry, j) => {
+    const inner = memberProblems(part, plain, entry, `the pool entry ${j} of ${at}`);
+    out.push(...inner);
+    if (inner.length > 0) return;
+    const key = memberKey(part, rule, entry);
+    if (keys.has(key)) out.push(["duplicate", `the pool entries ${keys.get(key)} and ${j} of ${at} have the same members`]);
+    else keys.set(key, j);
+  });
   return out;
 }
 
+/** This function tells if a member list fits a space: each member is a good config of the space. A shape filter removes options from the space. */
+const fits = (part: StrategySpace, entry: readonly StrategyConfig[]): boolean => entry.every((m) => configProblems(part, m, true).length === 0);
+
 const toBreaks = (problems: readonly Problem[], inputs: readonly string[] = []): ClaimBreak[] => problems.map(([claim, detail]) => ({ claim, detail, inputs }));
 
 /**
  * This function checks one config of a space. It gives one break for each problem. An empty list tells that the config is good.
  * The `claim` of a break is the kind of the problem, for example `missing`, `unknown`, `inactive`, `param`, `constraint`, `members` or `depth`.
+ *
+ * A member list that is not an entry of the `pool` of its option gives the claim `pool`.
  * With `shapes`, an option that does not support a kind of the list gives the claim `shape`. A member of a meta option gets the same check.
  */
 export function checkConfig(space: StrategySpace, config: StrategyConfig, options: ShapeFilter = {}): ClaimBreak[] {
@@ -424,6 +481,7 @@ export function checkConfig(space: StrategySpace, config: StrategyConfig, option
 /**
  * This function checks a space. It gives one break for each problem. An empty list tells that the space is good.
  * It finds duplicate names, empty ranges, defaults out of range, enums without values, bad log scales, unknown names and bad named configs.
+ * It also checks each entry of a `pool`: the count of its members, each member and a repeated entry.
  * The `inputs` of a break of a named config have the name of the config.
  */
 export function checkSpace(space: StrategySpace): ClaimBreak[] {
@@ -462,6 +520,9 @@ export function checkSpace(space: StrategySpace): ClaimBreak[] {
     for (const s of space.stages) if (partOf(space, s.name).prefix === "") out.push(["parts", `the stage ${s.name} is not a stage of a part`]);
   const breaks = toBreaks(out);
   if (breaks.length > 0) return breaks;
+  for (const s of space.stages)
+    for (const o of s.options) if (o.members?.pool !== undefined) breaks.push(...toBreaks(poolProblems(partOf(space, s.name).space, o.members, `the option ${s.name}.${o.id}`)));
+  if (breaks.length > 0) return breaks;
   for (const [name, config] of Object.entries(space.named ?? {}))
     breaks.push(...toBreaks(configProblems(space, config, false).map(([c, d]) => [c, `the named config ${name}: ${d}`] as const), [name]));
   return breaks;
@@ -608,7 +669,7 @@ interface Combo {
 const optionIds = (choices: Choices): Map<string, string | null> => new Map([...choices].map(([k, o]) => [k, o?.id ?? null]));
 const keeps = (space: StrategySpace, choices: Choices): boolean => (space.constraints ?? []).every((c) => holds(c, optionIds(choices)));
 
-/** This function gives the count of the member lists of a meta option from `base` base configs, or `null` above `limit`. */
+/** This function gives the count of the member lists of a meta option without a pool from `base` base configs, or `null` above `limit`. */
 function memberLists(base: bigint, rule: MemberRule, limit: bigint): bigint | null {
   let sum = 0n;
   for (let m = rule.min; m <= rule.max; m++) {
@@ -677,7 +738,8 @@ function combos(space: StrategySpace, levels: number, meta: boolean, limit: bigi
     for (const o of s.options) {
       if (o.members === undefined) continue;
       const choices = new Map<string, StageOption | null>(stages.map((x) => [x.name, x === s ? o : null]));
-      if (keeps(space, choices)) out.push({ choices, base: false, weight: times(countOf(o), memberLists(base, o.members, limit), limit) });
+      const lists = o.members.pool === undefined ? memberLists(base, o.members, limit) : BigInt(o.members.pool.length);
+      if (keeps(space, choices)) out.push({ choices, base: false, weight: times(countOf(o), lists, limit) });
     }
   return out;
 }
@@ -685,6 +747,7 @@ function combos(space: StrategySpace, levels: number, meta: boolean, limit: bigi
 /**
  * This function gives the count of the grid points of a space, with `levels` levels for each numeric param.
  * It counts only the active params and the combinations that keep the constraints. It gives the meta configs apart.
+ * A meta option with a `pool` counts each entry of the pool one time.
  * With `shapes`, it counts only the options that support each kind of the list.
  */
 export function spaceSize(space: StrategySpace, options: SpaceSizeOptions): SpaceSize {
@@ -697,14 +760,22 @@ export function spaceSize(space: StrategySpace, options: SpaceSizeOptions): Spac
 /**
  * This function gives the space with only the options that support each shape kind of `shapes`. Without `shapes`, it gives the same space.
  * A stage can lose all of its options. Then the space has no config with that stage.
+ * A pool keeps only the entries whose members fit the smaller space. A meta option without such an entry goes out.
  */
 function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined): StrategySpace {
   if (shapes === undefined) return space;
-  return {
+  const kept: StrategySpace = {
     ...space,
     stages: space.stages.map((s) => ({ ...s, options: s.options.filter((o) => supportsShapes(o, shapes)) })),
     ...(space.parts === undefined ? {} : { parts: space.parts.map((p) => restrict(p, shapes)) }),
   };
+  const withPool = (s: SpaceStage, o: StageOption): StageOption[] => {
+    if (o.members?.pool === undefined) return [o];
+    const part = partOf(kept, s.name).space;
+    const pool = o.members.pool.filter((entry) => fits(part, entry));
+    return pool.length === 0 ? [] : [{ ...o, members: { ...o.members, pool } }];
+  };
+  return { ...kept, stages: kept.stages.map((s) => ({ ...s, options: s.options.flatMap((o) => withPool(s, o)) })) };
 }
 
 /** This function throws a `RangeError` for a list of shape kinds with a kind that is not declared. */
@@ -828,6 +899,14 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
         });
       }
       if (o.members === undefined) continue;
+      const fixed = o.members.pool;
+      if (fixed !== undefined) {
+        const r = stepRandom(seed, `pool-entry:${s.name}:${o.id}`);
+        permutation(users.length, r).forEach((stratum, j) => {
+          members[users[j]!]![k] = [...fixed[Math.min(fixed.length - 1, Math.floor(((stratum + r()) / users.length) * fixed.length))]!];
+        });
+        continue;
+      }
       const part = partOf(space, s.name).space;
       const poolSize = Math.max(n, 4 * o.members.max, 8);
       const seen = new Set<string>();
@@ -862,6 +941,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
  * - The mode `sample` gives `n` configs of a seeded Latin hypercube. The options of a stage get equal strata, and each active param gets its own strata.
  * - A sample draws again when a point breaks a constraint. After `maxTries` draws, it throws an `Error`. Two sampled configs can be equal.
  * - With `shapes`, only the options that support each kind of the list count. Without `shapes`, the result does not change.
+ * - A meta option with a `pool` gives only the entries of its pool. With `shapes`, only the entries whose members support each kind count.
  */
 export function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[] {
   assertSpace(space);