@mark1russell7/packing 0.2.6 → 0.2.7

package/src/portfolio-strategy.ts

@@ -0,0 +1,62 @@
+// The strategy `portfolio` of roadmap item k20, part 2 (`docs/PACKER.md`, "The per-cell portfolio"). It is a composite
+// strategy: it packs an input with the members of the set of its cell, and it keeps the best output. Nothing default uses it.
+
+import { maxrects, push, rows, shelf, skyline } from "./adapters.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
+import { portfolioDefaultMembers, portfolioMembers } from "./portfolio-cell.ts";
+import { PORTFOLIO_SETS } from "./portfolio-sets.ts";
+import { packPortfolio } from "./portfolio.ts";
+import type { PackContext, Strategy, Supports } from "./strategy.ts";
+
+/** The options of the strategy `portfolio`. Without options, the output is a function of the input only. */
+export interface PortfolioStrategyOptions {
+  /** The size of the set of the cell: 2 or 3. With `k`, each of the `k` members runs. Without `k`, the strategy uses the set of 3. */
+  k?: 2 | 3;
+  /** The largest count of the members that run. Without `k` and `maxMembers`, the count is `defaultMembers` of the cell. */
+  maxMembers?: number;
+  /** The opt-in time limit of `portfolio` of the contract, in milliseconds. It has no default. A cut member makes the result not deterministic. */
+  budgetMs?: number;
+}
+
+/** The single strategies that the members of the table use */
+const SINGLES: readonly Strategy[] = [rows, skyline, shelf, push, maxrects] as Strategy[];
+
+/** This function gives the union of the supports of the strategies of the members of the table. */
+function unionSupports(): Supports {
+  const used = new Set(Object.values(PORTFOLIO_SETS.entries).map((e) => e.strategy));
+  const out: Record<string, string[]> = {};
+  for (const s of SINGLES.filter((x) => used.has(x.id))) {
+    for (const [dim, values] of Object.entries(s.supports) as [string, string[]][]) {
+      const list = (out[dim] ??= []);
+      for (const v of values) if (!list.includes(v)) list.push(v);
+    }
+  }
+  return out as unknown as Supports;
+}
+
+/**
+ * The strategy `portfolio`: `packPortfolio` with the function form `(input) => portfolioMembers(input, k)`. The seed of the context
+ * goes to each member. Its supports are the union of the supports of the members.
+ *
+ * - Without `k` and `maxMembers`, the members are the set of 3 of the cell, and `maxMembers` is `defaultMembers` of the cell.
+ *   The default output thus does not depend on the clock.
+ * - A member that does not support the cell of an input throws, and it does not win. When each member throws, the strategy throws the first error.
+ * - The option `budgetMs` goes to `portfolio` of the contract. The first member always runs.
+ * - The strategy throws a `RangeError` for a `k` other than 2 or 3.
+ */
+export const portfolioStrategy: Strategy<PortfolioStrategyOptions> = {
+  id: "portfolio",
+  family: "portfolio",
+  catalog: [],
+  supports: unionSupports(),
+  defaults: {},
+  deterministic: true,
+  pack(input: PackInput, options: PortfolioStrategyOptions, context: PackContext): PackOutput {
+    const { k, maxMembers, budgetMs } = options;
+    if (k !== undefined && k !== 2 && k !== 3) throw new RangeError(`The option k of the strategy portfolio is 2 or 3, not ${String(k)}.`);
+    const size = k ?? 3;
+    const count = maxMembers ?? (k === undefined ? portfolioDefaultMembers(input) : undefined);
+    const limits = { ...(count === undefined ? {} : { maxMembers: count }), ...(budgetMs === undefined ? {} : { budgetMs }) };
+    return packPortfolio((x: PackInput) => portfolioMembers(x, size), { id: k === undefined ? "portfolio" : `portfolio-k${k}`, seed: context.seed, ...limits }).run(input);
+  },
+};

package/src/portfolio.ts

@@ -57,18 +57,25 @@ export function hardBreaks(input: PackInput, output: PackOutput): number {
  * 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.
+ * - `members` is a list, or a function of the input that gives the list. The strategy `portfolio` uses the function form.
  * - 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.
+ *   With the function form, `pick` throws this error for the list of an input.
  */
-export function packPortfolio(members: readonly (string | PortfolioEntry)[], options: PackPortfolioOptions = {}): Portfolio<PackInput, PackOutput> {
+export function packPortfolio(
+  members: readonly (string | PortfolioEntry)[] | ((input: PackInput) => 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) };
-  });
+  const toMembers = (given: readonly (string | PortfolioEntry)[]): Member<PackInput, PackOutput>[] =>
+    given.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) };
+    });
+  const list = typeof members === "function" ? (input: PackInput): Member<PackInput, PackOutput>[] => toMembers(members(input)) : toMembers(members);
   // 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 => {

package/src/registry.ts

@@ -1,13 +1,20 @@
 import { maxrects, push, rows, shelf, skyline } from "./adapters.ts";
 import type { PackInput, PackOutput } from "./contract.ts";
+import { portfolioStrategy } from "./portfolio-strategy.ts";
 import { createContext, type Strategy } from "./strategy.ts";
 
-/** Each strategy of the package. The benchmark starts each one on each input of the corpus. */
+/** Each single strategy of the package. The benchmark starts each one on each input of the corpus. */
 export const strategies: readonly Strategy[] = Object.freeze([rows, skyline, shelf, push, maxrects] as Strategy[]);
 
-/** This function gives the strategy with an id. It throws a `RangeError` for an id that the registry does not have. */
+/**
+ * The composite strategies of the registry: each one packs an input with other strategies. They are not in `strategies`.
+ * Since 0.2.7, the list has `portfolio` of roadmap item k20.
+ */
+export const composites: readonly Strategy[] = Object.freeze([portfolioStrategy] as Strategy[]);
+
+/** This function gives the strategy with an id, also a composite strategy. It throws a `RangeError` for an id that the registry does not have. */
 export function strategy(id: string): Strategy {
-  const found = strategies.find((s) => s.id === id);
+  const found = strategies.find((s) => s.id === id) ?? composites.find((s) => s.id === id);
   if (found === undefined) throw new RangeError(`The registry has no strategy "${id}".`);
   return found;
 }