@mark1russell7/layout-contract 0.2.5 → 0.2.7

package/README.md

@@ -18,8 +18,10 @@ The package has no runtime dependencies.
 | The random numbers | `mulberry32`, `fnv1a32`, `stepRandom`, `randomInt` |
 | The hashes | `sha256Hex`, `canonicalJson`, `documentHash`, `outputHash`, `HashOptions` |
 | The promotion guards | `outputGroups`, `OutputGroup`, `exercised`, `ExerciseEvidence` |
+| The portfolio | `portfolio`, `Portfolio`, `PortfolioKey`, `PortfolioLevel`, `PortfolioOptions`, `PortfolioPick`, `PortfolioTrace`, `Member`, `MemberTrace`, `MemberStatus`, `pickMoves` |
+| The pick rule | `selectBest`, `SelectCandidate`, `SelectLevel`, `Selection`, `PickSpec` |
 | The turn | `turnBox`, `turnPort`, `turnMargin`, `turnRegion`, `turnSide`, `turnPoint` |
-| The tolerances | `EPS`, `RECORD_EPS`, `Tolerance`, `DEFAULT_TOLERANCE` |
+| The tolerances | `EPS`, `RECORD_EPS`, `RECORD_SCALE`, `Tolerance`, `DEFAULT_TOLERANCE` |
 | The hard rules | `countOverlaps`, `countObstacleHits`, `regionHitsRect`, `rectInRegion`, `countOutside`, `ContainerTest`, `countPortsOffBorder`, `packHard`, `PackHard`, `placedRect`, `checkInput` |
 
 ## The rules
@@ -51,4 +53,4 @@ const placed = applyPack(input, output);
 const hard = packHard(input, output);
 ```
 
-The formats are in `docs/FORMAT.md` of `packing` and `docs/LAYOUT-RECORDS.md` of `highways`. The joint measures are in `docs/JOINT-MEASURES.md` of this repository, and the joint corpus is in `docs/JOINT-CORPUS.md`. The promotion guards are in `docs/PROMOTION.md`.
+The formats are in `docs/FORMAT.md` of `packing` and `docs/LAYOUT-RECORDS.md` of `highways`. The joint measures are in `docs/JOINT-MEASURES.md` of this repository, and the joint corpus is in `docs/JOINT-CORPUS.md`. The promotion guards are in `docs/PROMOTION.md`. The portfolio and its pick rule are in `docs/PORTFOLIO.md`.

package/build/index.d.ts

@@ -66,9 +66,14 @@ export declare function overlapOf(a: Rect, b: Rect): {
 };
 /** The epsilon for the float compares in an engine. */
 export declare const EPS = 1e-6;
+/**
+ * The count of grid steps in one unit of a written file. A file rounds each number `v` to `Math.round(v * RECORD_SCALE) / RECORD_SCALE`.
+ * Use a multiplication by this value, not a division by `RECORD_EPS`. The two differ at some half steps.
+ */
+export declare const RECORD_SCALE = 1e3;
 /**
  * The epsilon for the float compares on a written file. A file rounds each number to 3 decimals,
- * so a difference of two values can move by up to 0.001.
+ * so a difference of two values can move by up to 0.001. It is `1 / RECORD_SCALE`.
  */
 export declare const RECORD_EPS = .001;
 /**
@@ -437,7 +442,8 @@ export type Verdict = "better" | "worse" | "tie";
 export declare function minEffectOf(spec: Pick<MeasureSpec, "minEffect">, a?: number, b?: number): number;
 /**
  * This function compares the value `candidate` with the value `baseline` of one measure on one input.
- * A change of at most `minEffectOf(spec, candidate, baseline)` is a tie. The test is symmetric: a swap of the two values swaps better and worse.
+ * The compare uses whole grid steps of `RECORD_EPS`. Thus a live value and its rounded record give the same verdict.
+ * A change of at most the threshold of `minEffectOf` in grid steps is a tie. A swap of the two values swaps better and worse.
  * Two equal values are a tie, also two infinite values. A value `NaN` is an error.
  */
 export declare function compareMeasure(candidate: number, baseline: number, spec: Pick<MeasureSpec, "direction" | "minEffect">): Verdict;
@@ -556,4 +562,131 @@ export interface ExerciseEvidence {
  * The function throws a `RangeError` when only one of the two lists is given, or when their lengths are different.
  */
 export declare function exercised(evidence: ExerciseEvidence): boolean;
+/** The part of a `MeasureSpec` that a pick uses: the direction and the `minEffect`. */
+export type PickSpec = Pick<MeasureSpec, "direction" | "minEffect">;
+/** A member of a portfolio: a function with an id. A portfolio is also a member. */
+export interface Member<I, O> {
+  readonly id: string;
+  /** This function gives the output of the member for an input. */
+  run(input: I): O;
+}
+/** One level of the key of a portfolio: a measure of an output. */
+export interface PortfolioLevel<I, O> {
+  /** The id of the level. The id `hard` is reserved. */
+  readonly id: string;
+  readonly spec: PickSpec;
+  /** This function gives the value of the measure for the output of a member. The value must be finite. */
+  value(input: I, output: O): number;
+}
+/** The key of a portfolio: the hard level, then the other levels in order. */
+export interface PortfolioKey<I, O> {
+  /** This function gives the count of hard breaks. It is level 0, with the direction `lower` and the `minEffect` 0. */
+  hard(input: I, output: O): number;
+  /** The levels after the hard level, in the order of the pick. */
+  readonly levels: readonly PortfolioLevel<I, O>[];
+  /** This function gives the hash of an output. The default is `outputHash` with the default grid. */
+  hash?(output: O): string;
+}
+/** The options of a portfolio. */
+export interface PortfolioOptions {
+  /** The time limit in milliseconds, 0 or more. The first member always starts. A member that starts always finishes. */
+  readonly budgetMs?: number;
+  /** The largest count of members that run, a whole number of 1 or more. The other members are cut. */
+  readonly maxMembers?: number;
+  /** The clock in milliseconds. The default is `performance.now`, or `Date.now` without `performance`. */
+  readonly now?: () => number;
+}
+/** The status of a member in a pick. */
+export type MemberStatus = "ran" | "cut" | "error";
+/** The trace of one member in a pick. */
+export interface MemberTrace {
+  readonly id: string;
+  readonly status: MemberStatus;
+  /** The value of each level, with the key `hard` for the hard level. Only a member with the status `ran` has values. */
+  readonly values?: Readonly<Record<string, number>>;
+  /** The time of the run of the member, in milliseconds. */
+  readonly ms?: number;
+  /** The hash of the output of the member. */
+  readonly outputHash?: string;
+  /** The message of the error of a member with the status `error`. */
+  readonly error?: string;
+}
+/** The trace of one pick of a portfolio. */
+export interface PortfolioTrace {
+  /** One entry for each member, in the order of the members. A cut member is also in the list. */
+  readonly members: readonly MemberTrace[];
+  readonly winner: string;
+  /** The index of the winner in the list of the members. */
+  readonly winnerIndex: number;
+  /** The value `true` tells that the winner is not member 0 and has a different output hash. */
+  readonly picked: boolean;
+  /** The time of the full pick, in milliseconds. */
+  readonly totalMs: number;
+  readonly budgetMs?: number;
+  readonly maxMembers?: number;
+  /** The count of the cut members. */
+  readonly cut: number;
+  /** The value `false` tells that the time limit cut one member or more. Then a run on a different computer can give a different pick. */
+  readonly deterministic: boolean;
+  /** The ids of the members that stay in after each level of `selectBest`. The first list is for the hard level. */
+  readonly kept: readonly (readonly string[])[];
+}
+/** The result of one pick of a portfolio: the output of the winner, its id and the trace. */
+export interface PortfolioPick<O> {
+  readonly output: O;
+  readonly winner: string;
+  readonly trace: PortfolioTrace;
+}
+/** A portfolio: a member that runs its members and gives the output of the best member. */
+export interface Portfolio<I, O> extends Member<I, O> {
+  /** This function starts the members on an input and gives the output of the winner with the trace. */
+  pick(input: I): PortfolioPick<O>;
+}
+/** A candidate of `selectBest`: an id and the value of each level. */
+export interface SelectCandidate {
+  readonly id: string;
+  readonly values: Readonly<Record<string, number>>;
+}
+/** A level of `selectBest`: the id of a value and its spec. */
+export interface SelectLevel {
+  readonly id: string;
+  readonly spec: PickSpec;
+}
+/** The result of `selectBest`. */
+export interface Selection {
+  readonly winner: string;
+  /** The ids of the candidates that stay in after each level, in the given order. */
+  readonly kept: readonly (readonly string[])[];
+}
+/**
+ * This function picks the best candidate. For each level, it finds the best value of the candidates that stay in.
+ * It keeps each candidate that is not worse than that best value by `compareMeasure`.
+ * The winner is the first candidate, in the given order, that stays in after the last level.
+ * Without levels, the winner is the first candidate and `kept` is empty.
+ *
+ * The reason for the rule: a scan that compares each candidate with the current winner is not transitive, because of the `minEffect` ties.
+ * Such a scan can drift away from the best value. An example: "a" is lower with the `minEffect` 0.005, and "b" is higher.
+ * The candidates A (0, 1), B (0.004, 2) and C (0.008, 3) give the winner B.
+ * The scan picks C, but A is better than C on "a".
+ *
+ * The function throws a `RangeError` for an empty list of candidates, for a missing value, and for a value that is not finite.
+ */
+export declare function selectBest(candidates: readonly SelectCandidate[], levels: readonly SelectLevel[]): Selection;
+/** This function gives the move `pick` of a pick: 1 when `picked` is true, else 0. A record keeps it as the trace measure `move.pick`. */
+export declare function pickMoves(trace: Pick<PortfolioTrace, "picked">): {
+  pick: number;
+};
+/**
+ * This function makes a portfolio. Its `pick` starts the members in their order. `selectBest` picks the winner of the members with the status `ran`.
+ * The first level is the hard level, then the levels of the key follow.
+ * `members` is a list, or a function of the input that gives the list.
+ *
+ * A member that throws, or that gives a value that is not finite, gets the status `error`. It does not win.
+ * When each member has an error, `pick` throws the error of the first member.
+ * `docs/PORTFOLIO.md` tells the rules of the time limit, the trace and `picked`.
+ *
+ * The function throws a `RangeError` for a level with the id `hard`, for two levels with the same id and for a bad option.
+ * It also throws a `RangeError` for an empty list of members, or for two members with the same id.
+ */
+export declare function portfolio<I, O>(id: string, members: readonly Member<I, O>[] | ((input: I) => readonly Member<I, O>[]), key: PortfolioKey<I, O>, options?: PortfolioOptions): Portfolio<I, O>;
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/geometry.ts","../src/tolerance.ts","../src/input.ts","../src/output.ts","../src/record.ts","../src/rules.ts","../src/turn.ts","../src/measures.ts","../src/strategy.ts","../src/random.ts","../src/edges.ts","../src/hash.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/geometry.ts","../src/tolerance.ts","../src/input.ts","../src/output.ts","../src/record.ts","../src/rules.ts","../src/turn.ts","../src/measures.ts","../src/strategy.ts","../src/random.ts","../src/edges.ts","../src/hash.ts","../src/portfolio.ts"],"mappings":"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"}

package/build/index.js

@@ -114,8 +114,13 @@ function overlapOf(a, b) {
 /** The epsilon for the float compares in an engine. */
 const EPS = 1e-6;
 /**
+* The count of grid steps in one unit of a written file. A file rounds each number `v` to `Math.round(v * RECORD_SCALE) / RECORD_SCALE`.
+* Use a multiplication by this value, not a division by `RECORD_EPS`. The two differ at some half steps.
+*/
+const RECORD_SCALE = 1e3;
+/**
 * The epsilon for the float compares on a written file. A file rounds each number to 3 decimals,
-* so a difference of two values can move by up to 0.001.
+* so a difference of two values can move by up to 0.001. It is `1 / RECORD_SCALE`.
 */
 const RECORD_EPS = .001;
 /**
@@ -669,16 +674,29 @@ function minEffectOf(spec, a = 0, b = 0) {
 	const t = typeof m === "number" ? m : m.rel * Math.max(Math.abs(a), Math.abs(b));
 	return Math.max(RECORD_EPS, Number.isFinite(t) ? t : 0);
 }
+/** The slack of the threshold in grid steps. It absorbs only the float noise of the threshold, because the change is a whole number. */
+const STEP_NOISE = 1e-6;
 /**
 * This function compares the value `candidate` with the value `baseline` of one measure on one input.
-* A change of at most `minEffectOf(spec, candidate, baseline)` is a tie. The test is symmetric: a swap of the two values swaps better and worse.
+* The compare uses whole grid steps of `RECORD_EPS`. Thus a live value and its rounded record give the same verdict.
+* A change of at most the threshold of `minEffectOf` in grid steps is a tie. A swap of the two values swaps better and worse.
 * Two equal values are a tie, also two infinite values. A value `NaN` is an error.
 */
 function compareMeasure(candidate, baseline, spec) {
 	if (Number.isNaN(candidate) || Number.isNaN(baseline)) throw new RangeError("compareMeasure: a value is NaN");
 	if (candidate === baseline) return "tie";
-	const delta = candidate - baseline;
-	if (!(Math.abs(delta) > minEffectOf(spec, candidate, baseline))) return "tie";
+	const a = Math.round(candidate * RECORD_SCALE);
+	const b = Math.round(baseline * RECORD_SCALE);
+	let delta;
+	if (Number.isSafeInteger(a) && Number.isSafeInteger(b)) {
+		delta = a - b;
+		const m = spec.minEffect ?? 0;
+		const t = typeof m === "number" ? m * RECORD_SCALE : m.rel * Math.max(Math.abs(a), Math.abs(b));
+		if (Math.abs(delta) <= Math.max(1, Number.isFinite(t) ? t : 0) + STEP_NOISE) return "tie";
+	} else {
+		delta = candidate - baseline;
+		if (!(Math.abs(delta) > minEffectOf(spec, candidate, baseline))) return "tie";
+	}
 	return (spec.direction === "lower" ? delta < 0 : delta > 0) ? "better" : "worse";
 }
 // src/utf8.ts
@@ -1139,6 +1157,225 @@ function exercised(evidence) {
 	if (hashes && baseHashes) return hashes.some((h, i) => h !== baseHashes[i]);
 	return false;
 }
-export { DEFAULT_TOLERANCE, EDGE_DENSITY, EDGE_STEP_VERSION, EPS, JOINT_MEASURES, JOINT_MOVED_MIN, RECORD_EPS, SIDES, applyPack, boundsOf, canonicalJson, checkInput, compareMeasure, countObstacleHits, countOutside, countOverlaps, countPortsOffBorder, documentHash, edgeStep, exercised, fnv1a32, grow, marginSides, minEffectOf, mulberry32, outputGroups, outputHash, overlapOf, packHard, placedRect, randomInt, rectInRegion, regionHitsRect, sha256Hex, stepRandom, toLayoutRecord, toPackInput, translate, turnBox, turnMargin, turnPoint, turnPort, turnRegion, turnSide };
+// src/portfolio.ts
+/**
+* This function picks the best candidate. For each level, it finds the best value of the candidates that stay in.
+* It keeps each candidate that is not worse than that best value by `compareMeasure`.
+* The winner is the first candidate, in the given order, that stays in after the last level.
+* Without levels, the winner is the first candidate and `kept` is empty.
+*
+* The reason for the rule: a scan that compares each candidate with the current winner is not transitive, because of the `minEffect` ties.
+* Such a scan can drift away from the best value. An example: "a" is lower with the `minEffect` 0.005, and "b" is higher.
+* The candidates A (0, 1), B (0.004, 2) and C (0.008, 3) give the winner B.
+* The scan picks C, but A is better than C on "a".
+*
+* The function throws a `RangeError` for an empty list of candidates, for a missing value, and for a value that is not finite.
+*/
+function selectBest(candidates, levels) {
+	if (candidates.length === 0) throw new RangeError("selectBest: the list of candidates is empty.");
+	for (const level of levels) for (const c of candidates) {
+		const v = c.values[level.id];
+		if (typeof v !== "number") throw new RangeError(`selectBest: the candidate "${c.id}" has no value for the level "${level.id}".`);
+		if (!Number.isFinite(v)) throw new RangeError(`selectBest: the candidate "${c.id}" has the value ${v} for the level "${level.id}".`);
+	}
+	let alive = candidates;
+	const kept = [];
+	for (const level of levels) {
+		const at = (c) => c.values[level.id];
+		let best = at(alive[0]);
+		for (const c of alive) best = level.spec.direction === "lower" ? Math.min(best, at(c)) : Math.max(best, at(c));
+		alive = alive.filter((c) => compareMeasure(at(c), best, level.spec) !== "worse");
+		kept.push(alive.map((c) => c.id));
+	}
+	return {
+		winner: alive[0].id,
+		kept
+	};
+}
+/** This function gives the move `pick` of a pick: 1 when `picked` is true, else 0. A record keeps it as the trace measure `move.pick`. */
+function pickMoves(trace) {
+	return { pick: trace.picked ? 1 : 0 };
+}
+/** This function gives the default clock: `performance.now`, or `Date.now` without `performance`. */
+function defaultClock() {
+	const perf = globalThis.performance;
+	return perf ? () => perf.now() : () => Date.now();
+}
+/** This function gives the message of an error value. */
+function messageOf(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+/** This function throws a `RangeError` for an empty list of members or for two members with the same id. */
+function checkMembers(id, members) {
+	if (members.length === 0) throw new RangeError(`The portfolio "${id}" has no members.`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const m of members) {
+		if (seen.has(m.id)) throw new RangeError(`The portfolio "${id}" has two members with the id "${m.id}".`);
+		seen.add(m.id);
+	}
+}
+/**
+* This function makes a portfolio. Its `pick` starts the members in their order. `selectBest` picks the winner of the members with the status `ran`.
+* The first level is the hard level, then the levels of the key follow.
+* `members` is a list, or a function of the input that gives the list.
+*
+* A member that throws, or that gives a value that is not finite, gets the status `error`. It does not win.
+* When each member has an error, `pick` throws the error of the first member.
+* `docs/PORTFOLIO.md` tells the rules of the time limit, the trace and `picked`.
+*
+* The function throws a `RangeError` for a level with the id `hard`, for two levels with the same id and for a bad option.
+* It also throws a `RangeError` for an empty list of members, or for two members with the same id.
+*/
+function portfolio(id, members, key, options = {}) {
+	const levelIds = /* @__PURE__ */ new Set();
+	for (const level of key.levels) {
+		if (level.id === "hard") throw new RangeError(`The portfolio "${id}" has a level with the reserved id "hard".`);
+		if (levelIds.has(level.id)) throw new RangeError(`The portfolio "${id}" has two levels with the id "${level.id}".`);
+		levelIds.add(level.id);
+	}
+	const { budgetMs, maxMembers } = options;
+	if (budgetMs !== void 0 && !(budgetMs >= 0)) throw new RangeError(`The portfolio "${id}" has the budgetMs ${budgetMs}. It must be 0 or more.`);
+	if (maxMembers !== void 0 && !(Number.isInteger(maxMembers) && maxMembers >= 1)) throw new RangeError(`The portfolio "${id}" has the maxMembers ${maxMembers}. It must be a whole number of 1 or more.`);
+	if (typeof members !== "function") checkMembers(id, members);
+	const levels = [{
+		id: "hard",
+		spec: {
+			direction: "lower",
+			minEffect: 0
+		}
+	}, ...key.levels.map((l) => ({
+		id: l.id,
+		spec: l.spec
+	}))];
+	const now = options.now ?? defaultClock();
+	const evaluate = (m, input, output) => {
+		const values = {};
+		const measure = (level, f) => {
+			let v;
+			try {
+				v = f();
+			} catch (e) {
+				throw new RangeError(`The level "${level}" of the member "${m.id}" of the portfolio "${id}" throws: ${messageOf(e)}`, { cause: e });
+			}
+			if (typeof v !== "number" || !Number.isFinite(v)) throw new RangeError(`The member "${m.id}" of the portfolio "${id}" has the value ${v} for the level "${level}".`);
+			values[level] = v;
+		};
+		try {
+			measure("hard", () => key.hard(input, output));
+			for (const level of key.levels) measure(level.id, () => level.value(input, output));
+			let hash;
+			try {
+				hash = key.hash ? key.hash(output) : outputHash(output);
+			} catch (e) {
+				throw new RangeError(`The hash of the member "${m.id}" of the portfolio "${id}" throws: ${messageOf(e)}`, { cause: e });
+			}
+			return {
+				ok: true,
+				output,
+				values,
+				hash
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				error: e
+			};
+		}
+	};
+	const pick = (input) => {
+		const list = typeof members === "function" ? members(input) : members;
+		if (typeof members === "function") checkMembers(id, list);
+		const start = now();
+		const traces = [];
+		const outputs = /* @__PURE__ */ new Map();
+		const ran = [];
+		let firstError;
+		let cut = 0;
+		let outOfTime = false;
+		for (let i = 0; i < list.length; i++) {
+			const m = list[i];
+			if (maxMembers !== void 0 && i >= maxMembers) {
+				traces.push({
+					id: m.id,
+					status: "cut"
+				});
+				cut++;
+				continue;
+			}
+			if (i > 0 && budgetMs !== void 0 && (outOfTime || now() - start >= budgetMs)) {
+				outOfTime = true;
+				traces.push({
+					id: m.id,
+					status: "cut"
+				});
+				cut++;
+				continue;
+			}
+			const t0 = now();
+			let result;
+			let ms;
+			try {
+				const output = m.run(input);
+				ms = now() - t0;
+				result = evaluate(m, input, output);
+			} catch (e) {
+				ms = now() - t0;
+				result = {
+					ok: false,
+					error: e
+				};
+			}
+			if (result.ok) {
+				traces.push({
+					id: m.id,
+					status: "ran",
+					values: result.values,
+					ms,
+					outputHash: result.hash
+				});
+				outputs.set(m.id, result.output);
+				ran.push({
+					id: m.id,
+					values: result.values
+				});
+			} else {
+				traces.push({
+					id: m.id,
+					status: "error",
+					ms,
+					error: messageOf(result.error)
+				});
+				firstError ??= { error: result.error };
+			}
+		}
+		if (ran.length === 0) throw firstError.error;
+		const { winner, kept } = selectBest(ran, levels);
+		const winnerIndex = traces.findIndex((t) => t.id === winner);
+		const base = traces[0];
+		const trace = {
+			members: traces,
+			winner,
+			winnerIndex,
+			picked: winnerIndex > 0 && (base.status !== "ran" || traces[winnerIndex].outputHash !== base.outputHash),
+			totalMs: now() - start,
+			...budgetMs !== void 0 ? { budgetMs } : {},
+			...maxMembers !== void 0 ? { maxMembers } : {},
+			cut,
+			deterministic: !outOfTime,
+			kept
+		};
+		return {
+			output: outputs.get(winner),
+			winner,
+			trace
+		};
+	};
+	return {
+		id,
+		pick,
+		run: (input) => pick(input).output
+	};
+}
+export { DEFAULT_TOLERANCE, EDGE_DENSITY, EDGE_STEP_VERSION, EPS, JOINT_MEASURES, JOINT_MOVED_MIN, RECORD_EPS, RECORD_SCALE, SIDES, applyPack, boundsOf, canonicalJson, checkInput, compareMeasure, countObstacleHits, countOutside, countOverlaps, countPortsOffBorder, documentHash, edgeStep, exercised, fnv1a32, grow, marginSides, minEffectOf, mulberry32, outputGroups, outputHash, overlapOf, packHard, pickMoves, placedRect, portfolio, randomInt, rectInRegion, regionHitsRect, selectBest, sha256Hex, stepRandom, toLayoutRecord, toPackInput, translate, turnBox, turnMargin, turnPoint, turnPort, turnRegion, turnSide };
 
 //# sourceMappingURL=index.js.map