@mark1russell7/packing 0.2.5 → 0.2.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",
@@ -49,7 +49,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@mark1russell7/layout-contract": "^0.2.4"
+    "@mark1russell7/layout-contract": "^0.2.6"
   },
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.2",

package/src/index.ts

@@ -80,12 +80,15 @@ export {
 } from "./adapters.ts";
 export { fromRects, toRects } from "./convert.ts";
 export { packWith, strategies, strategy } from "./registry.ts";
+export { hardBreaks, packPortfolio, PORTFOLIO_LEVELS, PORTFOLIO_STAGE, type PackPortfolioOptions, type PortfolioEntry } from "./portfolio.ts";
+export type { Portfolio, PortfolioPick, PortfolioTrace, MemberTrace, SelectLevel } from "@mark1russell7/layout-contract";
 export { checkHard, type ContainerTest, type PackHard } from "./check.ts";
 export {
   canonicalJson,
   countCell,
   fnv1a32,
   hashInput,
+  outputHash,
   round3,
   toPackInput,
   type CorpusCell,

package/src/layout-input.ts

@@ -1,7 +1,7 @@
 // The input file `layout-input/1` of `docs/FORMAT.md`: its types, its numbers, its canonical form and its hash.
 
 import type { LayoutContainer, LayoutEdge, LayoutGenerator, LayoutInput } from "@mark1russell7/layout-contract";
-import type { PackInput } from "./contract.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
 import { sha256Hex, utf8 } from "./sha256.ts";
 import type { Cell } from "./strategy.ts";
 
@@ -90,6 +90,16 @@ export function hashInput(file: LayoutInput): string {
   return sha256Hex(canonicalJson(rest)).slice(0, 16);
 }
 
+/**
+ * This function gives the `outputHash` of an output. It is the first 16 hex characters of the SHA-256 of the canonical form of
+ * its placements, sorted by id. The canonical form rounds each number with `round3`. Thus the order of the list does not count.
+ * The records of the benchmark and the key of `packPortfolio` use it. It is not `outputHash` of the contract, which uses a grid.
+ */
+export function outputHash(output: Pick<PackOutput, "placements">): string {
+  const sorted = output.placements.toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return sha256Hex(canonicalJson(sorted)).slice(0, 16);
+}
+
 /** This function gives the scale of a count: the nearest of 1, 10, 100, 1000 and 10000 on a log scale. The count 0 gives `1`. */
 export function countCell(count: number): CountScale {
   if (count <= 3) return "1";

package/src/portfolio.ts

@@ -0,0 +1,103 @@
+// The portfolio of roadmap item k20, part 1 (`docs/PACKER.md`, "The portfolio"). A portfolio packs an input with each
+// member and keeps the best output by the one pick rule `selectBest` of the contract. Nothing default uses it.
+
+import { pickMoves, portfolio, type Member, type Portfolio, type PortfolioKey, type PortfolioPick, type SelectLevel } from "@mark1russell7/layout-contract";
+import { checkHard } from "./check.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
+import { outputHash } from "./layout-input.ts";
+import { MEASURE_SPECS, measure, type LayoutMeasures } from "./measures.ts";
+import { packWith, strategy } from "./registry.ts";
+
+/** A member of `packPortfolio`: a strategy of the registry with some options. The id names the member in the trace. */
+export interface PortfolioEntry {
+  id: string;
+  /** The id of a strategy of the registry */
+  strategy: string;
+  /** The options of the member over the defaults of the strategy */
+  options?: unknown;
+}
+
+/** The options of `packPortfolio`. The time limit and the member limit are those of `portfolio` of the contract. */
+export interface PackPortfolioOptions {
+  /** The id of the portfolio. The default is `portfolio`. */
+  id?: string;
+  /** The seed of each member. The default is 0, as for `packWith`. */
+  seed?: number;
+  /** The time limit in milliseconds. Without it, each member runs. A cut member makes the pick not deterministic. */
+  budgetMs?: number;
+  /** The largest count of members that run */
+  maxMembers?: number;
+  /** The clock in milliseconds. The default is `performance.now`. */
+  now?: () => number;
+}
+
+/** The id of the trace stage of `packPortfolio`. Its measure `move.pick` is 1 when the pick is not member 0. */
+export const PORTFOLIO_STAGE = "portfolio";
+
+/**
+ * The levels of the pick of `packPortfolio` and of the portfolio report of the benchmark, in order. Level 0 is `hard`.
+ *
+ * - `hard`: the count of hard breaks of `checkHard` with `exactContainer`. Lower is better, with the minimum effect 0.
+ * - `pack.overflow.excessArea`: the overflow area above its bound. Lower is better.
+ * - `pack.fill`: the fill of the hull. Higher is better.
+ */
+export const PORTFOLIO_LEVELS: readonly SelectLevel[] = Object.freeze([
+  { id: "hard", spec: { direction: "lower", minEffect: 0 } },
+  { id: "pack.overflow.excessArea", spec: MEASURE_SPECS["pack.overflow.excessArea"] },
+  { id: "pack.fill", spec: MEASURE_SPECS["pack.fill"] },
+] as SelectLevel[]);
+
+/** This function gives the count of the hard breaks of an output: the sum of `checkHard` with `exactContainer`. */
+export function hardBreaks(input: PackInput, output: PackOutput): number {
+  return Object.values(checkHard(input, output, undefined, { exactContainer: true })).reduce((sum, n) => sum + n, 0);
+}
+
+/**
+ * This function makes an opt-in portfolio of strategies of the registry with `portfolio` of the contract.
+ * Its `pick(input)` packs the input with each member and gives the output of the winner, its id and the trace.
+ *
+ * - A member is a strategy id, or a `PortfolioEntry` with options. The members run in the given order.
+ * - The key is the hard breaks, then `pack.overflow.excessArea`, then `pack.fill`. `PORTFOLIO_LEVELS` gives the specs.
+ * - The hash of the key is `outputHash`. `selectBest` of the contract picks the winner.
+ * - The output of the winner gets the trace stage `portfolio` with `move.pick` of `pickMoves`.
+ * - The function throws a `RangeError` for an unknown strategy, an empty list and two members with the same id.
+ */
+export function packPortfolio(members: readonly (string | PortfolioEntry)[], options: PackPortfolioOptions = {}): Portfolio<PackInput, PackOutput> {
+  const seed = options.seed ?? 0;
+  const list: Member<PackInput, PackOutput>[] = members.map((m) => {
+    const e = typeof m === "string" ? { id: m, strategy: m } : m;
+    strategy(e.strategy);
+    return { id: e.id, run: (input: PackInput): PackOutput => packWith(e.strategy, input, e.options, seed) };
+  });
+  // Each level reads the measures of one output, so the measures of an output are computed one time
+  const cache = new WeakMap<PackOutput, LayoutMeasures>();
+  const measured = (input: PackInput, output: PackOutput): LayoutMeasures => {
+    let m = cache.get(output);
+    if (m === undefined) {
+      m = measure(input, output);
+      cache.set(output, m);
+    }
+    return m;
+  };
+  const key: PortfolioKey<PackInput, PackOutput> = {
+    hard: hardBreaks,
+    levels: PORTFOLIO_LEVELS.slice(1).map((level) => ({
+      id: level.id,
+      spec: level.spec,
+      value: (input: PackInput, output: PackOutput): number => measured(input, output)[level.id as "pack.fill" | "pack.overflow.excessArea"],
+    })),
+    hash: outputHash,
+  };
+  const limits = {
+    ...(options.budgetMs !== undefined ? { budgetMs: options.budgetMs } : {}),
+    ...(options.maxMembers !== undefined ? { maxMembers: options.maxMembers } : {}),
+    ...(options.now !== undefined ? { now: options.now } : {}),
+  };
+  const inner = portfolio(options.id ?? PORTFOLIO_STAGE, list, key, limits);
+  const pick = (input: PackInput): PortfolioPick<PackOutput> => {
+    const got = inner.pick(input);
+    const stage = { id: PORTFOLIO_STAGE, measures: { "move.pick": pickMoves(got.trace).pick } };
+    return { ...got, output: { ...got.output, trace: [...(got.output.trace ?? []), stage] } };
+  };
+  return { id: inner.id, pick, run: (input: PackInput): PackOutput => pick(input).output };
+}