@mark1russell7/packing 0.1.7 → 0.2.0

package/src/generators.ts

@@ -2,7 +2,7 @@
 // container, then the obstacles, then the boxes. Each step has its own random numbers: `mulberry32` of
 // `fnv1a32("<seed>:<step>")`. Thus a packing input and a routing input with the same seed get the same obstacles.
 
-import type { Container, Item, Obstacle, Region } from "./contract.ts";
+import type { Item, LayoutContainer, Obstacle, Region } from "./contract.ts";
 import {
   countCell,
   fnv1a32,
@@ -10,7 +10,7 @@ import {
   round3,
   type CorpusCell,
   type GeneratorParams,
-  type LayoutInput,
+  type GeneratedInput,
   type ObstacleLayout,
   type SizeDistribution,
 } from "./layout-input.ts";
@@ -36,11 +36,11 @@ export interface CorpusGenerator<P extends GeneratorParams = GeneratorParams> {
   /** This method gives the cell of each input of the parameters. The cell does not depend on the seed. */
   cell(params?: Partial<P>): CorpusCell;
   /** This method gives the input file of a seed. The `id` is `<set>/<family>/s<seed>`. */
-  generate(seed: number, params?: Partial<P>, set?: string): LayoutInput;
+  generate(seed: number, params?: Partial<P>, set?: string): GeneratedInput;
 }
 
 /** The parts of a file that a generator makes. */
-type Parts = Pick<LayoutInput, "container" | "boxes"> & { obstacles: Obstacle[] };
+type Parts = Pick<GeneratedInput, "container" | "boxes"> & { obstacles: Obstacle[] };
 
 /** The data of a generator, before `defineGenerator` adds the common steps. */
 interface GeneratorSpec<P extends GeneratorParams> {
@@ -153,12 +153,12 @@ function defineGenerator<P extends GeneratorParams>(spec: GeneratorSpec<P>): Cor
     values: spec.values,
     withDefaults,
     cell: (params?: Partial<P>): CorpusCell => spec.cell(withDefaults(params)),
-    generate(seed: number, params?: Partial<P>, set: string = spec.set): LayoutInput {
+    generate(seed: number, params?: Partial<P>, set: string = spec.set): GeneratedInput {
       if (!Number.isInteger(seed) || seed < 0) throw new RangeError(`The seed is a whole number from 0. It is ${seed}.`);
       const full = withDefaults(params);
       const family = spec.family(full);
       const { container, obstacles, boxes } = spec.build(seed, full);
-      const file: Omit<LayoutInput, "hash"> = roundNumbers({
+      const file: Omit<GeneratedInput, "hash"> = roundNumbers({
         schema: "layout-input/1" as const,
         id: `${set}/${family}/s${seed}`,
         set,
@@ -195,7 +195,7 @@ export const rectScattered: CorpusGenerator<RectScatteredParams> = defineGenerat
     let r = stepRandom(seed, "container");
     const w = int(r, 600, 1000);
     const h = int(r, 400, 800);
-    const container: Container = { w, h, fixed: "size" };
+    const container: LayoutContainer = { w, h, fixed: "size" };
 
     r = stepRandom(seed, "obstacles");
     const n = int(r, 3, 8);
@@ -232,8 +232,8 @@ const OBSTACLE_LAYOUTS = ["none", "center", "scattered", "wall", "corridors", "t
 const SIZE_DISTRIBUTIONS = ["identical", "nearIdentical", "uniform", "heavyTail", "bimodal", "extremeAspect"] as const;
 
 /** This function gives the container of a size value for the nominal rectangle `w` by `h`, with an optional shape. */
-function containerOf(size: DimensionValue<"containerSize">, w: number, h: number, shape?: Region): Container {
-  const containers: Record<DimensionValue<"containerSize">, Container> = {
+function containerOf(size: DimensionValue<"containerSize">, w: number, h: number, shape?: Region): LayoutContainer {
+  const containers: Record<DimensionValue<"containerSize">, LayoutContainer> = {
     fixed: { w, h, fixed: "size" },
     freeHeight: { w, fixed: "width" },
     freeWidth: { h, fixed: "height" },
@@ -241,8 +241,7 @@ function containerOf(size: DimensionValue<"containerSize">, w: number, h: number
     freeArea: { fixed: "none", aspectWeight: 0 },
   };
   const container = containers[size];
-  if (shape !== undefined) container.shape = shape;
-  return container;
+  return shape === undefined ? container : { ...container, shape };
 }
 
 /** This function gives the 4 corners of a rectangle, clockwise from the top left. */
@@ -625,7 +624,7 @@ export const edgeCases: CorpusGenerator<EdgeCaseParams> = defineGenerator<EdgeCa
       w = int(r, 600, 1000);
       h = int(r, 400, 800);
     }
-    const container: Container = { w, h, fixed: "size" };
+    const container: LayoutContainer = { w, h, fixed: "size" };
 
     r = stepRandom(seed, "obstacles");
     const obstacles: Obstacle[] = [];

package/src/index.ts

@@ -29,13 +29,14 @@ export {
   DEFAULT_TOLERANCE,
   EPS,
   RECORD_EPS,
+  checkInput,
   marginOf,
   turnItem,
   turnPoint,
   turnPort,
   turnRegion,
-  type Container,
   type Item,
+  type LayoutContainer,
   type Margin,
   type Obstacle,
   type PackInput,
@@ -43,6 +44,8 @@ export {
   type Placement,
   type Port,
   type Region,
+  type Side,
+  type Sides,
   type StageTrace,
   type Tolerance,
 } from "./contract.ts";
@@ -65,7 +68,7 @@ export {
 export { logSweep, push, rows, shelf, skyline, type LayoutStrategyOptions, type PushStrategyOptions } from "./adapters.ts";
 export { fromRects, toRects } from "./convert.ts";
 export { packWith, strategies, strategy } from "./registry.ts";
-export { checkHard, type HardBreaks } from "./check.ts";
+export { checkHard, type PackHard } from "./check.ts";
 export {
   canonicalJson,
   countCell,
@@ -75,9 +78,10 @@ export {
   toPackInput,
   type CorpusCell,
   type CountScale,
-  type Edge,
+  type GeneratedInput,
   type GeneratorParams,
   type GeneratorStamp,
+  type LayoutEdge,
   type LayoutInput,
   type ObstacleLayout,
   type SizeDistribution,

package/src/layout-input.ts

@@ -1,52 +1,39 @@
 // The input file `layout-input/1` of `docs/FORMAT.md`: its types, its numbers, its canonical form and its hash.
 
-import type { Container, Item, Obstacle, PackInput } from "./contract.ts";
+import type { LayoutContainer, LayoutEdge, LayoutGenerator, LayoutInput } from "@mark1russell7/layout-contract";
+import type { PackInput } from "./contract.ts";
 import { sha256Hex, utf8 } from "./sha256.ts";
 import type { Cell } from "./strategy.ts";
 
-/** An edge between two boxes. The router reads it, and the packer ignores it. */
-export interface Edge {
-  id: string;
-  source: string;
-  target: string;
-  sourcePort?: string;
-  targetPort?: string;
-  /** The free data of the edge. The packer does not read it. */
-  data?: Readonly<Record<string, unknown>>;
-}
+export type { LayoutEdge, LayoutInput } from "@mark1russell7/layout-contract";
 
 /** The parameters of a generator: a name and a string or a number for each parameter. */
 export type GeneratorParams = Record<string, string | number>;
 
-/** The stamp of a generated input: the generator, its version, the full parameters and the seed. */
-export interface GeneratorStamp {
-  name: string;
-  version: number;
-  params: GeneratorParams;
-  seed: number;
+/**
+ * The stamp of a generated input: the generator, its version, the full parameters and the seed.
+ * It is `LayoutGenerator` of the contract with a string or a number for each parameter.
+ */
+export interface GeneratorStamp extends LayoutGenerator {
+  readonly params: Readonly<GeneratorParams>;
 }
 
-/** One input file `layout-input/1`. `docs/FORMAT.md` gives each field. */
-export interface LayoutInput {
-  schema: "layout-input/1";
-  id: string;
-  set: string;
-  family: string;
-  seed: number;
+/**
+ * A generated input file `layout-input/1`. It is a `LayoutInput` with each field that a generator writes.
+ * `docs/FORMAT.md` gives each field.
+ */
+export interface GeneratedInput extends LayoutInput {
+  readonly set: string;
+  readonly family: string;
+  readonly seed: number;
   /** The origin: `made-up`, `published:<set>` or `known-best:<construction>`. */
-  source: string;
+  readonly source: string;
   /** The generator of a generated input. A hand-made or published input has `null`. */
-  generator: GeneratorStamp | null;
-  container: Container;
-  obstacles?: Obstacle[];
-  gap?: number;
-  boxes: Item[];
-  edges: Edge[];
-  base?: string;
-  change?: string;
-  step?: number;
+  readonly generator: GeneratorStamp | null;
+  readonly container: LayoutContainer;
+  readonly edges: readonly LayoutEdge[];
   /** The first 16 hex characters of the SHA-256 of the canonical form of the other fields. */
-  hash: string;
+  readonly hash: string;
 }
 
 /** The layout of the obstacles (`docs/research/TAXONOMY.md`, dimension 3). */
@@ -98,9 +85,8 @@ export function canonicalJson(value: unknown): string {
 }
 
 /** This function gives the hash of an input file: the first 16 hex characters of the SHA-256 of its canonical form without `hash`. */
-export function hashInput(file: Omit<LayoutInput, "hash"> | LayoutInput): string {
-  const rest: Partial<LayoutInput> = { ...file };
-  delete rest.hash;
+export function hashInput(file: LayoutInput): string {
+  const { hash: _hash, ...rest } = file;
   return sha256Hex(canonicalJson(rest)).slice(0, 16);
 }
 
@@ -113,10 +99,15 @@ export function countCell(count: number): CountScale {
   return "10k";
 }
 
-/** This function gives the packing input of a file. The boxes become the items, and the edges go. */
+/**
+ * This function gives the packing input of a file. The boxes become the items, and the edges go.
+ * A file without a container gets `{ fixed: "none" }`, so the packer picks the size. It is `toPackInput` of the contract.
+ */
 export function toPackInput(file: Pick<LayoutInput, "container" | "boxes" | "obstacles" | "gap">): PackInput {
-  const input: PackInput = { container: file.container, items: file.boxes };
-  if (file.obstacles !== undefined) input.obstacles = file.obstacles;
-  if (file.gap !== undefined) input.gap = file.gap;
-  return input;
+  return {
+    container: file.container ?? { fixed: "none" },
+    items: file.boxes,
+    ...(file.obstacles === undefined ? {} : { obstacles: file.obstacles }),
+    ...(file.gap === undefined ? {} : { gap: file.gap }),
+  };
 }

package/src/measures.ts

@@ -1,11 +1,12 @@
 // The algebra of measures (roadmap item k8). `docs/MEASURES.md` defines each measure. This file computes them.
 
+import type { MeasureSpec as ContractMeasureSpec, Direction } from "@mark1russell7/layout-contract";
 import { RECORD_EPS, type PackInput, type PackOutput } from "./contract.ts";
 import { aspectError } from "./free.ts";
 import { round3 } from "./layout-input.ts";
 
-/** The direction of a measure: `lower` when a lower value is better, `higher` when a higher value is better. */
-export type Direction = "lower" | "higher";
+/** The direction of a measure comes from the contract: `lower` when a lower value is better, `higher` when a higher value is better. */
+export type { Direction } from "@mark1russell7/layout-contract";
 
 /** The family of a measure. Each family has a section in `docs/MEASURES.md`. */
 export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "overflow" | "stability" | "determinism" | "speed";
@@ -13,21 +14,17 @@ export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "ove
 /** The id of a measure of the packer. The ids are those of `docs/FORMAT.md`, and `highways` uses the same ids. */
 export type MeasureId = "pack.area" | "pack.fill" | "pack.whitespace" | "pack.aspect" | "pack.aspectError" | "pack.order.inversions" | "pack.order.breaks" | "pack.raggedness" | "pack.overflow" | "pack.stability.moved" | "pack.stability.mean" | "pack.stability.q95" | "pack.deterministic" | "pack.search.widths" | "pack.search.ms";
 
-/** The facts of one measure: its family, its unit, its direction and its range. */
-export interface MeasureSpec {
-  id: MeasureId;
-  family: MeasureFamily;
-  unit: string;
-  direction: Direction;
-  /** The lowest value. */
-  min: number;
-  /** The highest value. The value `Infinity` tells that the measure has no upper limit. */
-  max: number;
+/**
+ * The facts of one measure: its family, its unit, its direction and its range.
+ * It is `MeasureSpec` of the contract for a packer measure id, with a family.
+ */
+export interface MeasureSpec extends ContractMeasureSpec<MeasureId> {
+  readonly family: MeasureFamily;
   /**
    * The floor is the best value of a guard measure. The floor rule of `docs/PROMOTION.md` of `highways` reads it. Each
    * guard of the packer has the floor 0. A measure without a floor has no floor rule.
    */
-  floor?: number;
+  readonly floor?: number;
   /**
    * The tolerance is the absolute tolerance at the floor. A candidate within the tolerance ties with a default at the floor.
    *
@@ -36,7 +33,7 @@ export interface MeasureSpec {
    * - `pack.stability.mean` has 0.005 container widths, and `pack.stability.q95` has 0.01. The default often moves no item.
    * - `pack.stability.moved` has 0.02: 2% of the items that stay. On a small change, the default often moves no item.
    */
-  tol?: number;
+  readonly tol?: number;
 }
 
 /** The measures of one layout, by id. `measure` gives them. The values are not rounded. */
@@ -175,7 +172,7 @@ export function readsBefore(a: Pick<Box, "x" | "y" | "h">, b: Pick<Box, "x" | "y
 /** This function sums one measure over the stages of a trace. A trace without the measure gives 0. */
 function traceSum(output: PackOutput, id: string): number {
   let sum = 0;
-  for (const stage of output.trace) sum += stage.measures[id] ?? 0;
+  for (const stage of output.trace ?? []) sum += stage.measures?.[id] ?? 0;
   return sum;
 }
 

package/src/strategy.ts

@@ -1,4 +1,4 @@
-import type { Container, PackInput, PackOutput, Region } from "./contract.ts";
+import type { LayoutContainer, PackInput, PackOutput, Region } from "./contract.ts";
 
 /**
  * For each dimension of the taxonomy, the values that a strategy supports. `docs/research/TAXONOMY.md` gives the values.
@@ -108,7 +108,7 @@ export function createContext(seed = 0, more: Omit<PackContext, "seed" | "rng">
 }
 
 /** This function tells if a polygon ring is convex. A ring with fewer than 3 points is convex. */
-function isConvex(points: readonly [number, number][]): boolean {
+function isConvex(points: readonly (readonly [number, number])[]): boolean {
   let sign = 0;
   const n = points.length;
   for (let i = 0; i < n; i++) {
@@ -163,7 +163,7 @@ export function cellOf(input: PackInput): Cell {
   const { container, items } = input;
   const obstacles = input.obstacles ?? [];
 
-  const sizes: Record<Container["fixed"], DimensionValue<"containerSize">> = {
+  const sizes: Record<LayoutContainer["fixed"], DimensionValue<"containerSize">> = {
     size: "fixed",
     width: "freeHeight",
     height: "freeWidth",