@mark1russell7/strategy-space 0.0.0-stage → 0.0.2

package/build/strategy-space.d.ts

@@ -0,0 +1,261 @@
+import { ClaimBreak } from "./claim.js";
+/** The schema of a strategy space. */
+export declare const STRATEGY_SPACE_SCHEMA = "strategy-space/1";
+/** The kind of a param: a whole number, a real number, one value of a list, or `true` and `false`. */
+export type ParamKind = "int" | "real" | "enum" | "bool";
+/** The value of one param in a config. */
+export type ParamValue = number | string | boolean;
+/** The condition of a conditional param: the param is active only when an earlier param of the same option has one of the values `in`. */
+export interface ParamWhen {
+  /** The name of an earlier param of the same option. */
+  readonly param: string;
+  /** The values of that param that make this param active. */
+  readonly in: readonly ParamValue[];
+}
+/** One param of a stage option, with its range. */
+export interface SpaceParam {
+  readonly name: string;
+  readonly kind: ParamKind;
+  /** The smallest value of an `int` or `real` param. */
+  readonly min?: number;
+  /** The largest value of an `int` or `real` param. */
+  readonly max?: number;
+  /** The step of the values from `min`. An `int` param has the step 1 by default. */
+  readonly step?: number;
+  /** The scale of the grid and of the samples. The scale `log` needs a `min` above 0. The default is `linear`. */
+  readonly scale?: "linear" | "log";
+  /** The values of an `enum` param. */
+  readonly values?: readonly (string | number)[];
+  /** The value that a config gets when it does not set the param. */
+  readonly default: ParamValue;
+  /** Without `when`, the param is active each time its option is chosen. */
+  readonly when?: ParamWhen;
+}
+/**
+ * The rule of the members of a meta option: a count from `min` to `max`. Members with `ordered: false` are sorted by their `configId`.
+ * With `min` and `max` 0, the option chooses its members from the input, so a config lists none. This form has no `pool` and no `view`.
+ */
+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 view of the items that the members get. With `bounds`, the option gives its members the bounding box of each item.
+   * Then a shape filter checks the members with the kind `rect`, and the option itself with the kinds of the input. Without `view`, the members get the kinds of the input.
+   */
+  readonly view?: "bounds";
+  /**
+   * With `true`, the option only chooses the output of one member, for example the best member by a score. It does not change that output.
+   * Such an option needs no operator. A meta option that changes the output of its members, for example a search over their layouts, is an operator.
+   */
+  readonly chooses?: boolean;
+}
+/** The inputs that an option supports. A missing field supports each value. */
+export interface OptionSupports {
+  /** The shape kinds of the boxes, as tags (for example `rect` or `circle`). Without it, the option supports each kind. */
+  readonly shape?: readonly string[];
+}
+/** One implementation of a stage. An option with `members` is a meta option: it chooses between whole configs, or wraps them. */
+export interface StageOption {
+  readonly id: string;
+  readonly params: readonly SpaceParam[];
+  readonly members?: MemberRule;
+  /** The inputs that the option supports. It describes the option, so it is not part of a config or of its id. */
+  readonly supports?: OptionSupports;
+  /**
+   * With `true`, the option gives its input with no change, for example the order of the input or no local search. It needs no operator.
+   * An identity option has no params and no members. The field describes the option, so it is not part of a config or of its id.
+   */
+  readonly identity?: boolean;
+}
+/** The known shape kinds of a check. Without `kinds`, each string that is not empty is a shape kind. */
+export interface KindOptions {
+  /** The list of the known shape kinds, for example `SHAPE_KIND_IDS` of `layout-contract`. A kind that is not in the list is a problem. */
+  readonly kinds?: readonly string[];
+}
+/** The shape kinds of the inputs of a check, a count or an enumeration. Without `shapes`, each option counts. */
+export interface ShapeFilter extends KindOptions {
+  /** The shape kinds of the input. Only the options that support each of these kinds count. */
+  readonly shapes?: readonly string[];
+}
+/** One stage of the pipeline of an engine. A config of an `optional` stage can have no option. */
+export interface SpaceStage {
+  readonly name: string;
+  readonly options: readonly StageOption[];
+  readonly optional?: boolean;
+}
+/** A reference to one option of a stage. The option `null` refers to an optional stage that a config does not use. */
+export interface OptionRef {
+  readonly stage: string;
+  readonly option: string | null;
+}
+/** A rule that keeps out invalid combinations. A config with the option `if` also has the option `then`, or does not have the option `then.not`. */
+export interface SpaceConstraint {
+  readonly if: OptionRef;
+  readonly then: OptionRef | {
+    readonly not: OptionRef;
+  };
+}
+/** The strategy space of an engine: the stages, the constraints and the named configs. `docs/STRATEGY-SPACE.md` tells the rules. */
+export interface StrategySpace {
+  readonly schema: typeof STRATEGY_SPACE_SCHEMA;
+  /** The name of the space. A config names the space with this value. */
+  readonly engine: string;
+  /** The version of the space. It is not part of a config or of its id. A record writes it. */
+  readonly version: string;
+  readonly stages: readonly SpaceStage[];
+  readonly constraints?: readonly SpaceConstraint[];
+  /** The named strategies of the engine, as points of the space. Old records stay comparable through them. */
+  readonly named?: Readonly<Record<string, StrategyConfig>>;
+  /** The spaces of a product space, from `productSpace`. A meta option of a part takes members of that part. */
+  readonly parts?: readonly StrategySpace[];
+}
+/** The choice of one stage in a config: an option, its params and, for a meta option, its members. */
+export interface StageChoice {
+  readonly option: string;
+  /** The values of the active params. A param that is not set gets its default. */
+  readonly params?: Readonly<Record<string, ParamValue>>;
+  /** The members of a meta option: configs of the same space, with no meta option. */
+  readonly members?: readonly StrategyConfig[];
+}
+/** One point of a strategy space. The value `null` of a stage tells that the config does not use the optional stage. */
+export interface StrategyConfig {
+  /** The `engine` of the space, without its version. */
+  readonly space: string;
+  readonly stages: Readonly<Record<string, StageChoice | null>>;
+}
+/** The count of the grid points of a space. */
+export interface SpaceSize {
+  /** The count of the configs without a meta option. */
+  readonly base: bigint;
+  /** The count of the configs with a meta option. The value is `null` when the count is more than `maxMeta`. */
+  readonly meta: bigint | null;
+}
+/** The options of `spaceSize`. */
+export interface SpaceSizeOptions extends ShapeFilter {
+  /** The count of the levels of each numeric param, a whole number of 1 or more. */
+  readonly levels: number;
+  /** The largest meta count that `spaceSize` gives. The default is `10n ** 18n`. */
+  readonly maxMeta?: bigint;
+}
+/** The options of a grid. The grid gives only the configs without a meta option. */
+export interface GridOptions extends ShapeFilter {
+  readonly mode: "grid";
+  readonly levels: number;
+  /** The largest count of configs. A larger grid causes a `RangeError`. The default is 100000. */
+  readonly limit?: number;
+}
+/** The options of a sample. */
+export interface SampleOptions extends ShapeFilter {
+  readonly mode: "sample";
+  /** 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, 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;
+  /**
+   * How a point keeps the constraints. With `reject` (the default), a point that breaks a constraint draws again.
+   * With `walk`, a point draws its stages from the largest to the smallest. Each stage draws only from the options that keep the constraints with the stages before it.
+   * The stages of `fixed` draw before the other stages.
+   * A space whose constraints reject most draws gets its sample with `walk`. The two values give different configs for one seed.
+   * A sample of `walk` is not uniform over the valid configs. Each option of the largest stage gets an equal share, whatever count of valid configs it has.
+   * Thus a mean over this sample is not a mean of the space.
+   */
+  readonly draw?: "reject" | "walk";
+  /**
+   * The options that each config of the sample has. A key is the name of a stage, and its value is the id of one option of that stage. The other stages draw as before.
+   * A stage of a product space has the name of its part before its own name, for example `pack.placement`.
+   * A fixed meta option needs `meta: "sample"`. A meta option of another stage of the same part goes out, because such an option replaces the fixed stage.
+   * A fixed option that the shape filter removes, or that the constraints forbid, gets a `RangeError` with the reason.
+   */
+  readonly fixed?: Readonly<Record<string, string>>;
+}
+/** The options of `enumerateSpace`. */
+export type EnumerateOptions = GridOptions | SampleOptions;
+/** 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 declare function paramProblem(param: SpaceParam, value: unknown): string | undefined;
+/** This function tells if a param is active for the values of the earlier params. A param without `when` is always active. */
+export declare function paramActive(param: SpaceParam, values: Readonly<Record<string, ParamValue>>): boolean;
+/** This function gives the stable form of a value of a param: a real number gets 12 significant digits, and `-0` becomes `0`. */
+export declare function paramValue(param: SpaceParam, value: ParamValue): ParamValue;
+/**
+ * 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.
+ * A member of an option with `view: "bounds"` gets the check with the kind `rect`.
+ */
+export declare function checkConfig(space: StrategySpace, config: StrategyConfig, options?: ShapeFilter): ClaimBreak[];
+/**
+ * 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.
+ * With `kinds`, a shape kind of a `supports` that is not in the list gives the claim `shape`.
+ */
+export declare function checkSpace(space: StrategySpace, kindOptions?: KindOptions): ClaimBreak[];
+/**
+ * This function gives the canonical form of a config: each stage of the space, the active params only, the defaults, and stable numbers.
+ * An unused optional stage is `null`. The members of an unordered meta option are sorted by their `configId`.
+ * It throws an `Error` for a config with a break of `checkConfig`.
+ */
+export declare function canonicalConfig(space: StrategySpace, config: StrategyConfig): StrategyConfig;
+/**
+ * This function gives the id of a config: the first 16 hex characters of the SHA-256 of `canonicalJson` of `canonicalConfig`.
+ * Two spellings of one config get one id. The version of the space is not part of the id.
+ */
+export declare function configId(space: StrategySpace, config: StrategyConfig): string;
+/**
+ * This function gives the grid values of one param, in increasing order. An `enum` gives its values, and a `bool` gives `false` and `true`.
+ * With 1 level, a numeric param gives its default. With k levels, it gives k points from `min` to `max` on its scale and step, without repeats.
+ */
+export declare function paramLevels(param: SpaceParam, levels: number): ParamValue[];
+/**
+ * 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 declare function spaceSize(space: StrategySpace, options: SpaceSizeOptions): SpaceSize;
+/**
+ * This function gives configs of a space, in their canonical form. Each config keeps the constraints. The result is deterministic.
+ *
+ * - The mode `grid` gives each grid point without a meta option, in a stable order. Stages, options and values go in the order of the space.
+ * - 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 `draw: "walk"`, each stage draws only from the options that keep the constraints with the stages before it. The largest stage keeps its equal strata.
+ * - 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.
+ * - A sample draws again when a point chooses a meta option without a member list. `spaceSize` gives such an option 0.
+ * - With `shapes`, a sample throws a `RangeError` when the space has no config for the kinds. The error names the stages without an option and the meta options without members.
+ * - With `fixed`, each config has the fixed option at each named stage. A fixed option that the space, the shape filter or the constraints do not permit gets a `RangeError` with the reason.
+ */
+export declare function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[];
+/**
+ * This function gives the shape kinds that a space accepts. The value comes from the `supports` of the options.
+ * A space accepts a kind when it has at least one config without a meta option on that kind.
+ * With `kinds`, it examines the kinds of that list, in its order. Without `kinds`, it examines the kinds that the `supports` of the space name, in the order of their first use.
+ */
+export declare function spaceShapeKinds(space: StrategySpace, options?: KindOptions): string[];
+/**
+ * This function joins configs of the parts of a product space into one config of the space `space`.
+ * The name of each stage gets the prefix `<space of the part>.`. The members of a meta option do not change.
+ */
+export declare function joinConfigs(space: string, parts: readonly StrategyConfig[]): StrategyConfig;
+/** This function gives the config of the part `engine` of a joint config. It throws a `RangeError` when no stage has the prefix `<engine>.`. */
+export declare function splitConfig(config: StrategyConfig, engine: string): StrategyConfig;
+/**
+ * This function joins two spaces, for example a packer and a router, into the space `name`. The stages of `a` and `b` get the prefixes `<a.engine>.` and `<b.engine>.`.
+ * The constraints get the same prefixes. The named configs are the pairs `<name of a>+<name of b>`. It throws a `RangeError` when the two engines have the same name.
+ */
+export declare function productSpace(a: StrategySpace, b: StrategySpace, name: string): StrategySpace;
+//# sourceMappingURL=strategy-space.d.ts.map

package/build/strategy-space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-space.d.ts","names":[],"sources":["../src/strategy-space.ts"],"mappings":";;qBAMa;;YASD;;YAGA;;iBAGK;;WAEN;;WAEA,aAAa;;;iBAIP;WACN;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,SAAS;;WAET,OAAO;;;;;;iBAOD;WACN;WACA;WACA;;;;;;WAMA,0BAA0B;;;;;WAK1B;;;;;WAKA;;;iBAIM;;WAEN;;;iBAIM;WACN;WACA,iBAAiB;WACjB,UAAU;;WAEV,WAAW;;;;;WAKX;;;iBAIM;;WAEN;;;iBAIM,oBAAoB;;WAE1B;;;iBAIM;WACN;WACA,kBAAkB;WAClB;;;iBAIM;WACN;WACA;;;iBAIM;WACN,IAAI;WACJ,MAAM;aAAuB,KAAK;;;;iBAI5B;WACN,eAAe;;WAEf;;WAEA;WACA,iBAAiB;WACjB,uBAAuB;;WAEvB,QAAQ,SAAS,eAAe;;WAEhC,iBAAiB;;;iBAIX;WACN;;WAEA,SAAS,SAAS,eAAe;;WAEjC,mBAAmB;;;iBAIb;;WAEN;WACA,QAAQ,SAAS,eAAe;;;iBAI1B;;WAEN;;WAEA;;;iBAIM,yBAAyB;;WAE/B;;WAEA;;;iBAIM,oBAAoB;WAC1B;WACA;;WAEA;;;iBAIM,sBAAsB;WAC5B;;WAEA;WACA;;WAEA;;WAEA;;;;;;;;;WASA;;;;;;;WAOA,QAAQ,SAAS;;;YAIhB,mBAAmB,cAAc;;wBAiD7B,aAAa,OAAO,YAAY;;wBAKhC,YAAY,OAAO,YAAY,QAAQ,SAAS,eAAe;;wBAK/D,WAAW,OAAO,YAAY,OAAO,aAAa;;;;;;;;;wBAqRlD,YAAY,OAAO,eAAe,QAAQ,gBAAgB,UAAS,cAAmB;;;;;;;;wBAWtF,WAAW,OAAO,eAAe,cAAa,cAAmB;;;;;;wBA4EjE,gBAAgB,OAAO,eAAe,QAAQ,iBAAiB;;;;;wBAU/D,SAAS,OAAO,eAAe,QAAQ;;;;;wBA4CvC,YAAY,OAAO,YAAY,iBAAiB;;;;;;;wBA6JhD,UAAU,OAAO,eAAe,SAAS,mBAAmB;;;;;;;;;;;;;;wBA8U5D,eAAe,OAAO,eAAe,SAAS,mBAAmB;;;;;;wBAkCjE,gBAAgB,OAAO,eAAe,UAAS;;;;;wBAU/C,YAAY,eAAe,gBAAgB,mBAAmB;;wBAO9D,YAAY,QAAQ,gBAAgB,iBAAiB;;;;;wBAWrD,aAAa,GAAG,eAAe,GAAG,eAAe,eAAe"}