@sdeverywhere/check-core 0.1.5 → 0.1.6

package/dist/index.d.cts

@@ -109,26 +109,6 @@ interface OutputVar {
     /** The metadata for the related visuals/graphs in which this variable is used. */
     relatedItems?: RelatedItem[];
 }
-/**
- * Holds information about a subscript used in the model.
- */
-interface Subscript {
-    /** The subscript identifier, as used in SDE. */
-    id: string;
-    /** The subscript name, as used in Vensim. */
-    name: string;
-}
-/**
- * Holds information about a dimension (subscript family) used in the model.
- */
-interface Dimension {
-    /** The dimension identifier, as used in SDE. */
-    id: string;
-    /** The dimension name, as used in Vensim. */
-    name: string;
-    /** The set of subscripts in this dimension. */
-    subscripts: Subscript[];
-}
 /**
  * Holds information about a variable used in the model implementation.
  */
@@ -137,12 +117,12 @@ interface ImplVar {
     varId: VarId;
     /** The variable name, as used in the modeling tool. */
     varName: string;
-    /** The variable index, used by SDE to reference the value in the generated model. */
-    varIndex: number;
-    /** The set of dimensions for this variable. */
-    dimensions: Dimension[];
     /** The variable type (e.g. 'level', 'const'). */
     varType: string;
+    /** The variable index, used to reference the value in the generated model. */
+    varIndex: number;
+    /** The subscript index values, used to reference the value in the generated model. */
+    subscriptIndices?: number[];
 }
 
 /** The human-readable name for a group of inputs. */
@@ -151,8 +131,27 @@ type InputGroupName = string;
 type InputAliasName = string;
 /** The name for a custom input setting group. */
 type InputSettingGroupId = string;
-/** The human-readable name for a group of dataset. */
+/** The human-readable name for a group of datasets. */
 type DatasetGroupName = string;
+/**
+ * Describes a group of implementation variables.
+ */
+interface ImplVarGroup {
+    /** The group title. */
+    title: string;
+    /**
+     * The function name in the generated model that is associated with
+     * this group.  This can be used when displaying the group to change
+     * the appearance of the items in the section.
+     */
+    fn?: string;
+    /**
+     * The keys of the variables in this group (corresponding to the
+     * `implVars` map keys).  It is recommended to provide these in the
+     * order that the variables are evaluated in the generated model.
+     */
+    datasetKeys: DatasetKey[];
+}
 /**
  * Includes the properties needed to display a legend item in the UI.
  */
@@ -233,6 +232,8 @@ interface ModelSpec {
     outputVars: Map<DatasetKey, OutputVar>;
     /** The map of all variables (both internal and exported) in this version of the model. */
     implVars: Map<DatasetKey, ImplVar>;
+    /** The groupings of internal/implementation variables in this version of the model. */
+    implVarGroups?: ImplVarGroup[];
     /** The custom input variable aliases defined for this model. */
     inputAliases?: Map<InputAliasName, VarId>;
     /** The custom input variable groups defined for this model. */
@@ -289,15 +290,204 @@ interface NamedBundle {
     bundle: Bundle;
 }
 /**
- * Represents a bundle that has had its model initialized.
+ * Represents a bundle that has had its model instances initialized.
  */
 interface LoadedBundle {
     /** The name of the bundle, for example, "Current" or "Baseline". */
     name: string;
     /** The version of the bundle. */
     version: number;
-    /** The initialized model. */
-    model: BundleModel;
+    /** The spec for the bundled model. */
+    modelSpec: ModelSpec;
+    /**
+     * The initialized model instances for this bundle.  If `concurrency` was specified
+     * in the config, then there will be that number of model instances in this array,
+     * otherwise there will be one instance.
+     */
+    models: BundleModel[];
+}
+
+/**
+ * A terse representation of a subscript.
+ */
+interface EncodedSubscript {
+    /** The subscript name (e.g., "Sub1"). */
+    n: string;
+    /** The subscript identifier (e.g., "_sub1"). */
+    i: string;
+}
+/**
+ * A terse representation of a variable without subscripts.
+ */
+interface EncodedVariable {
+    /** The variable name (corresponds to the base part of `ImplVar.varName` without subscripts). */
+    n: string;
+    /** The variable identifier (corresponds to the base part of `ImplVar.varId` without subscripts). */
+    i: string;
+    /** The variable index (corresponds to `ImplVar.varIndex`). */
+    x: number;
+}
+/**
+ * A terse representation of a variable type.
+ */
+type EncodedVarType = string;
+/**
+ * A terse representation of a variable instance as a flat array.
+ *
+ * Format: [t, v, si0, si1, ..., sx0, sx1, ...]
+ * - Element 0: The index of the associated `EncodedVarType` element in the `varTypes` array (corresponds to `ImplVar.varType`).
+ * - Element 1: The index of the associated `EncodedVariable` element in the `variables` array.
+ * - Elements 2+: If subscripts are present, first all subscript element indices, then all subscript indices:
+ *   - Elements 2 to (2 + n - 1): The indices of the associated `EncodedSubscript` elements in the `subscripts` array.
+ *   - Elements (2 + n) to (2 + 2n - 1): The subscript index values (corresponds to `ImplVar.subscriptIndices`).
+ */
+type EncodedVarInstance = number[];
+/**
+ * The encoded representation of impl variables that eliminates redundancy.
+ */
+interface EncodedImplVars {
+    subscripts: EncodedSubscript[];
+    variables: EncodedVariable[];
+    varTypes: EncodedVarType[];
+    varInstances: {
+        [key: string]: EncodedVarInstance[];
+    };
+}
+/**
+ * Encode impl variable metadata into a more efficient format.
+ *
+ * This is used to reduce the size of a bundle by eliminating redundancy in variable/subscript
+ * names and identifiers.  The `varInstances` object in the model listing JSON generated by the
+ * compiler includes verbose information for each variable instance.  This function puts that
+ * information into a more efficient format that can be bundled as a normal JavaScript object
+ * in the model-check bundle file, and then decoded and expandedwhen the bundle is loaded.
+ *
+ * @param input The input structure mapping keys to ImplVar arrays.
+ * @returns The encoded representation.
+ */
+declare function encodeImplVars(input: {
+    [key: string]: ImplVar[];
+}): EncodedImplVars;
+/**
+ * Decode impl variables from the efficient format back to the original structure.
+ *
+ * @param encoded The encoded representation.
+ * @returns The original structure mapping keys to `ImplVar` arrays.
+ */
+declare function decodeImplVars(encoded: EncodedImplVars): {
+    [key: string]: ImplVar[];
+};
+
+interface CheckOptions {
+    /** The strings containing check tests in YAML format. */
+    tests: string[];
+}
+interface CheckConfig {
+    /** The loaded bundle being checked. */
+    bundle: LoadedBundle;
+    /** The strings containing check tests in YAML format. */
+    tests: string[];
+}
+
+type TaskKey = string;
+type TaskExecutorKey = string;
+interface BundleModels {
+    L?: BundleModel;
+    R: BundleModel;
+}
+/**
+ * Base interface for all tasks in the unified system.
+ */
+interface Task {
+    /** Unique key for this task instance. */
+    key: TaskKey;
+    /** The task kind. */
+    kind: string;
+    /** Process the task using the given models. */
+    process(models: BundleModels): Promise<void>;
+}
+/**
+ * Executes a single task using a set of `BundleModel` instances.
+ */
+interface TaskExecutor {
+    /**
+     * Execute the given task using the set of `BundleModel` instances
+     * associated with this executor.
+     *
+     * @param task The task to execute.
+     * @return A promise that resolves when the task is complete.
+     */
+    execute(task: Task): Promise<void>;
+}
+/**
+ * A unified task queue that can process multiple kinds of tasks concurrently
+ * while ensuring that BundleModel instances are never accessed concurrently.
+ * This replaces the need for multiple separate TaskQueue instances.
+ */
+declare class TaskQueue {
+    private readonly executors;
+    /** The single instance. */
+    private static instance;
+    /** The queue of task keys, most recent at front. */
+    private readonly taskKeyQueue;
+    /** The map of tasks. */
+    private readonly taskMap;
+    /** The idle event listeners. */
+    private readonly idleListeners;
+    /** Whether tasks are being processed. */
+    private processing;
+    /** Whether `shutdown` has been called. */
+    private stopped;
+    /**
+     * @param executors The map of available task executors.
+     */
+    constructor(executors: Map<TaskExecutorKey, TaskExecutor>);
+    /**
+     * Initialize the shared `TaskQueue` instance.
+     *
+     * @param executors The map of available task executors.
+     */
+    static initialize(executors: Map<TaskExecutorKey, TaskExecutor>): void;
+    /**
+     * Get the shared `TaskQueue` instance.
+     */
+    static getInstance(): TaskQueue;
+    /**
+     * Add a task to the queue.
+     *
+     * @param task The task to add.
+     */
+    addTask(task: Task): void;
+    /**
+     * Cancel a task.
+     *
+     * @param taskKey The key of the task to cancel.
+     */
+    cancelTask(taskKey: TaskKey): void;
+    /**
+     * Add an idle listener.
+     *
+     * @param listener The listener to add.
+     */
+    onIdle(listener: (error?: Error) => void): void;
+    /**
+     * Remove an idle listener.
+     *
+     * @param listener The listener to remove.
+     */
+    removeIdleListener(listener: (error?: Error) => void): void;
+    /**
+     * Notify the idle listeners.
+     *
+     * @param error The error to notify the listeners with.
+     */
+    private notifyIdle;
+    /**
+     * Shutdown the task queue, cancelling all pending tasks.
+     */
+    shutdown(): void;
+    private processTasksIfNeeded;
+    private processNextTasks;
 }
 
 type CheckDataRequestKey = string;
@@ -306,15 +496,27 @@ type CheckDataRequestKey = string;
  * of a check/predicate.
  */
 declare class CheckDataCoordinator {
-    readonly bundleModel: BundleModel;
     private readonly taskQueue;
-    constructor(bundleModel: BundleModel);
+    constructor(taskQueue: TaskQueue);
     requestDataset(requestKey: CheckDataRequestKey, scenarioSpec: ScenarioSpec, datasetKey: DatasetKey, onResponse: (dataset: Dataset) => void): void;
     cancelRequest(key: CheckDataRequestKey): void;
 }
+/**
+ * Create a `CheckDataCoordinator` instance using the shared task queue.
+ */
+declare function createCheckDataCoordinator(): CheckDataCoordinator;
+/**
+ * @hidden This is not part of the public API; it is exposed only for use in tests.
+ */
+declare function createCheckDataCoordinatorForTests(bundleModel: BundleModel): CheckDataCoordinator;
 
-type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
-
+/** Spec type that allows for matching a check by group and test name. */
+interface CheckNameSpec {
+    /** The name of a check group. */
+    groupName: string;
+    /** The name of a check test. */
+    testName: string;
+}
 type CheckPredicateTimeSingle = number;
 type CheckPredicateTimeRange = [number, number];
 interface CheckPredicateTimeOptions {
@@ -325,20 +527,6 @@ interface CheckPredicateTimeOptions {
 }
 type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
 
-interface CheckResultErrorInfo {
-    kind: 'unknown-dataset' | 'unknown-input' | 'unknown-input-group' | 'empty-input-group';
-    name: string;
-}
-interface CheckResult {
-    status: 'passed' | 'failed' | 'error';
-    message?: string;
-    failValue?: number;
-    failOp?: CheckPredicateOp;
-    failRefValue?: number;
-    failTime?: number;
-    errorInfo?: CheckResultErrorInfo;
-}
-
 type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
 interface CheckDataset {
     /** The key for the matched dataset; can be undefined if no dataset matched. */
@@ -392,9 +580,25 @@ interface CheckDataRef {
     dataset: CheckDataset;
 }
 
+type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
+
+interface CheckResultErrorInfo {
+    kind: 'unknown-dataset' | 'unknown-input' | 'unknown-input-group' | 'empty-input-group';
+    name: string;
+}
+interface CheckResult {
+    status: 'passed' | 'failed' | 'error' | 'skipped';
+    message?: string;
+    failValue?: number;
+    failOp?: CheckPredicateOp;
+    failRefValue?: number;
+    failTime?: number;
+    errorInfo?: CheckResultErrorInfo;
+}
+
 type CheckKey = number;
 
-type CheckStatus = 'passed' | 'failed' | 'error';
+type CheckStatus = 'passed' | 'failed' | 'error' | 'skipped';
 interface CheckPredicateOpConstantRef {
     kind: 'constant';
     value: number;
@@ -457,17 +661,6 @@ declare function datasetMessage(dataset: CheckDatasetReport, bold: StyleFunc): s
  */
 declare function predicateMessage(predicate: CheckPredicateReport, bold: StyleFunc): string;
 
-interface CheckOptions {
-    /** The strings containing check tests in YAML format. */
-    tests: string[];
-}
-interface CheckConfig {
-    /** The loaded bundle being checked. */
-    bundle: LoadedBundle;
-    /** The strings containing check tests in YAML format. */
-    tests: string[];
-}
-
 /**
  * A simplified/terse version of `CheckPredicateReport` that matches the
  * format of the JSON objects emitted by the CLI in terse mode.
@@ -479,15 +672,15 @@ interface CheckPredicateSummary {
 /**
  * A simplified/terse version of `CheckReport` that matches the
  * format of the JSON objects emitted by the CLI in terse mode.
- * This only contains predicate summaries for checks that have a status
- * of 'failed' or 'error'.
+ * This contains predicate summaries for checks that have a status
+ * of 'failed', 'error', or 'skipped'.
  */
 interface CheckSummary {
     predicateSummaries: CheckPredicateSummary[];
 }
 /**
- * Convert a full `CheckReport` to a simplified `CheckSummary` that only includes
- * failed/errored checks.
+ * Convert a full `CheckReport` to a simplified `CheckSummary` that includes
+ * failed, errored, and skipped checks.
  *
  * @param checkReport The full check report.
  * @return The converted check summary.
@@ -499,9 +692,10 @@ declare function checkSummaryFromReport(checkReport: CheckReport): CheckSummary;
  *
  * @param checkConfig The config used to reconstruct the check test structure.
  * @param checkSummary The simplified check summary.
+ * @param skipChecks The checks that were skipped when the original report was created.
  * @return The converted check report.
  */
-declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary): CheckReport | undefined;
+declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary, skipChecks?: CheckNameSpec[]): CheckReport | undefined;
 
 type ComparisonDatasetName = string;
 type ComparisonDatasetSource = string;
@@ -633,6 +827,13 @@ interface ComparisonScenarioRefSpec {
     /** The optional subtitle that is used instead of the referenced scenario's subtitle. */
     subtitle?: ComparisonScenarioSubtitle;
 }
+/** Spec type that allows for matching a comparison scenario by title and subtitle. */
+interface ComparisonScenarioTitleSpec {
+    /** The title of a comparison scenario. */
+    title: string;
+    /** The subtitle of a comparison scenario. */
+    subtitle?: string;
+}
 type ComparisonScenarioGroupId = string;
 type ComparisonScenarioGroupTitle = string;
 /**
@@ -1034,9 +1235,17 @@ declare function diffDatasets(datasetL: Dataset | undefined, datasetR: Dataset |
  * a `ComparisonTestSummary` only includes the `maxDiff` value.
  */
 interface ComparisonTestReport {
+    /** The key of the scenario that was compared. */
     scenarioKey: ComparisonScenarioKey;
+    /** The key of the dataset that was compared. */
     datasetKey: DatasetKey;
-    diffReport: DiffReport;
+    /** The diff report for the comparison, or undefined if the test was skipped. */
+    diffReport?: DiffReport;
+    /**
+     * The diff report for the baseline scenario (all inputs at default), or undefined if this
+     * report is for the baseline scenario itself.
+     */
+    baselineDiffReport?: DiffReport;
 }
 /**
  * A simplified/terse version of `ComparisonTestReport` that is used when writing
@@ -1050,7 +1259,13 @@ interface ComparisonTestSummary {
     /** Short for `datasetKey`. */
     d: DatasetKey;
     /** Short for `maxDiff`. */
-    md: number;
+    md?: number;
+    /** Short for `avgDiff`. */
+    ad?: number;
+    /** Short for `maxDiff` relative to baseline `maxDiff`. */
+    mdb?: number;
+    /** Short for `avgDiff` relative to baseline `avgDiff`. */
+    adb?: number;
 }
 /**
  * The roll-up report that contains the results of all individual comparison tests.
@@ -1100,8 +1315,8 @@ type ComparisonGroupRoot = ComparisonDataset | ComparisonScenario;
 interface ComparisonGroupScores {
     /** The total number of comparisons (sample size) for this group. */
     totalDiffCount: number;
-    /** The sum of the `maxDiff` values for each threshold bucket. */
-    totalMaxDiffByBucket: number[];
+    /** The sum of the diff values for the active sort mode (e.g., `maxDiff`, `avgDiff`) for each threshold bucket. */
+    totalDiffByBucket: number[];
     /** The number of comparisons that fall into each threshold bucket. */
     diffCountByBucket: number[];
     /** The percentage of comparisons that fall into each threshold bucket. */
@@ -1142,12 +1357,13 @@ interface ComparisonGroupSummariesByCategory {
      */
     onlyInRight: ComparisonGroupSummary[];
     /**
-     * Groups with one or more comparisons that have non-zero `maxDiff` scores; the groups
-     * will be sorted by `maxDiff`, with higher scores at the front of the array.
+     * Groups with one or more comparisons that have non-zero diff scores; the groups
+     * will be sorted by the diff score according to the active sort mode, with higher
+     * scores at the front of the array.
      */
     withDiffs: ComparisonGroupSummary[];
     /**
-     * Groups where all comparisons have `maxDiff` scores of zero (no differences between
+     * Groups where all comparisons have diff scores of zero (no differences between
      * "left" and "right").
      */
     withoutDiffs: ComparisonGroupSummary[];
@@ -1282,6 +1498,15 @@ interface ComparisonReportSummarySection {
      * it will be initially collapsed.
      */
     initialState?: 'collapsed' | 'expanded' | 'expanded-if-diffs';
+    /**
+     * Whether the items in the section are stable, i.e., not changing from run to run.  If
+     * undefined, defaults to false.  This can be used to group items in the filter panel.
+     * Set it to true if the group contains a stable set of rows where the order does not
+     * change between runs.  Set it to false (or leave it undefined) if the group contains
+     * rows that have a different order between runs (for example, "Scenarios producing
+     * differences").
+     */
+    stable?: boolean;
 }
 /**
  * Describes an item (box) in the comparison report detail view.
@@ -1347,10 +1572,15 @@ interface ComparisonOptions {
     /** The left-side ("baseline") bundle being compared. */
     baseline: NamedBundle;
     /**
-     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
-     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
+     * The array of thresholds used to color differences.  Defaults to [1, 5, 10]
+     * which will use buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
      */
-    thresholds: number[];
+    thresholds?: number[];
+    /**
+     * The array of ratio thresholds used to color differences when relative sorting is
+     * active.  Defaults to [1, 2, 3] which will use buckets of 0, 0-1, 1-2, 2-3, and >3.
+     */
+    ratioThresholds?: number[];
     /**
      * The requested comparison scenario and view specifications.  These can be
      * specified in YAML or JSON files, or using `Spec` objects.
@@ -1367,10 +1597,15 @@ interface ComparisonConfig {
     /** The loaded right-side ("current") bundle being compared. */
     bundleR: LoadedBundle;
     /**
-     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
+     * The array of thresholds used to color differences.  For example, [1, 5, 10] will use
      * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
      */
     thresholds: number[];
+    /**
+     * The array of ratio thresholds used to color differences when relative sorting is
+     * active.  For example, [1, 2, 3] will use buckets of 0, 0-1, 1-2, 2-3, and >3.
+     */
+    ratioThresholds: number[];
     /** The set of resolved scenarios that will be compared. */
     scenarios: ComparisonScenarios;
     /** The set of resolved datasets that will be compared. */
@@ -1386,16 +1621,43 @@ type ComparisonDataRequestKey = string;
  * Coordinates loading of data in parallel from two models.
  */
 declare class ComparisonDataCoordinator {
-    readonly bundleModelL: BundleModel;
-    readonly bundleModelR: BundleModel;
     private readonly taskQueue;
-    constructor(bundleModelL: BundleModel, bundleModelR: BundleModel);
-    private processDatasetRequest;
-    private processGraphDataRequest;
-    requestDatasetMaps(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
-    requestGraphData(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
+    constructor(taskQueue: TaskQueue);
+    /**
+     * Request datasets from the two models.
+     *
+     * @param requestKey The unique key for the request.
+     * @param sourceL The source of the first ("left") dataset.  If "left", the datasets will
+     * be fetched from the "left" bundle's model, otherwise they will be fetched from the
+     * "right" bundle's model.
+     * @param scenarioSpecL The scenario used for the first ("left") model of the comparison.
+     * @param sourceR The source of the second ("right") dataset.  If "left", the datasets
+     * will be fetched from the "left" bundle's model, otherwise they will be fetched from
+     * the "right" bundle's model.
+     * @param scenarioSpecR The scenario used for the second ("right") model of the comparison.
+     * @param graphId The keys of the datasets to be fetched.
+     * @param onResponse The callback that will be called with the dataset maps.
+     */
+    requestDatasetMaps(requestKey: ComparisonDataRequestKey, sourceL: 'left' | 'right', scenarioSpecL: ScenarioSpec, sourceR: 'left' | 'right', scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
+    /**
+     * Request graph data from the two models.
+     *
+     * @param requestKey The unique key for the request.
+     * @param sourceL The source of the first ("left") dataset.  If "left", the datasets will
+     * be fetched from the "left" bundle's model, otherwise they will be fetched from the
+     * "right" bundle's model.
+     * @param scenarioSpecL The scenario used for the first ("left") model of the comparison.
+     * @param sourceR The source of the second ("right") dataset.  If "left", the datasets
+     * will be fetched from the "left" bundle's model, otherwise they will be fetched from
+     * the "right" bundle's model.
+     * @param scenarioSpecR The scenario used for the second ("right") model of the comparison.
+     * @param graphId The ID of the graph for which data will be fetched.
+     * @param onResponse The callback that will be called with the graph data.
+     */
+    requestGraphData(requestKey: ComparisonDataRequestKey, sourceL: 'left' | 'right', scenarioSpecL: ScenarioSpec, sourceR: 'left' | 'right', scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
     cancelRequest(key: ComparisonDataRequestKey): void;
 }
+declare function createComparisonDataCoordinator(): ComparisonDataCoordinator;
 
 type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
 interface GraphComparisonMetadataReport {
@@ -1440,6 +1702,19 @@ declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleG
  * @return The terse summary.
  */
 declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
+/**
+ * Convert a full `ComparisonTestReport` to a terse `ComparisonTestSummary`.  This will
+ * return undefined if the test has a zero `maxDiff` value.
+ *
+ * @param r The full comparison test report.
+ * @param baselineMaxDiff The max diff for the baseline scenario, or undefined if not available.
+ * @param baselineAvgDiff The avg diff for the baseline scenario, or undefined if not available.
+ * @return The terse comparison test summary.
+ */
+declare function testSummaryFromReport(r: ComparisonTestReport, baselineMaxDiff: number | undefined, baselineAvgDiff: number | undefined): ComparisonTestSummary | undefined;
+
+/** The available sort modes for categorizing comparison groups. */
+type ComparisonSortMode = 'max-diff' | 'avg-diff' | 'max-diff-relative' | 'avg-diff-relative';
 
 /**
  * Compute the overall scores for the given group of comparison test summaries.
@@ -1447,8 +1722,9 @@ declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport)
  * @param testSummaries The comparison test summaries to consider.
  * @param thresholds The array of thresholds that determine the buckets into which
  * the scores will be summarized.
+ * @param sortMode The sort mode to determine which field to use for scoring.
  */
-declare function getScoresForTestSummaries(testSummaries: ComparisonTestSummary[], thresholds: number[]): ComparisonGroupScores;
+declare function getScoresForTestSummaries(testSummaries: ComparisonTestSummary[], thresholds: number[], sortMode: ComparisonSortMode): ComparisonGroupScores;
 
 /**
  * Given a set of terse test summaries (which only includes summaries for tests with non-zero `maxDiff`
@@ -1456,25 +1732,18 @@ declare function getScoresForTestSummaries(testSummaries: ComparisonTestSummary[
  *
  * @param comparisonConfig The comparison configuration.
  * @param terseSummaries The set of terse test summaries.
+ * @param sortMode The sort mode to determine which field to use for scoring.
  */
-declare function categorizeComparisonTestSummaries(comparisonConfig: ComparisonConfig, terseSummaries: ComparisonTestSummary[]): ComparisonCategorizedResults;
+declare function categorizeComparisonTestSummaries(comparisonConfig: ComparisonConfig, terseSummaries: ComparisonTestSummary[], sortMode: ComparisonSortMode): ComparisonCategorizedResults;
 
 /**
- * Additional options that are passed to `getConfigOptions`.  These can be used to customize
- * the `ConfigOptions`, for example, if the `simplifyScenarios` flag is true, a reduced set
- * of tests can be provided in the `ConfigOptions` so that the tests run faster in a local
- * development situation.
+ * Additional options that are passed to `getConfigOptions`.
  */
 interface ConfigInitOptions {
     /** If defined, overrides the displayed name of the baseline ("left") bundle. */
     bundleNameL?: string;
     /** If defined, overrides the displayed name of the current ("right") bundle. */
     bundleNameR?: string;
-    /**
-     * A hint that the user wants tests to run faster.  If true, you can return a
-     * configuration that runs a smaller subset of tests than normal.
-     */
-    simplifyScenarios?: boolean;
 }
 /**
  * The user-specified options used by the library to resolve and initialize a `Config` instance.
@@ -1493,6 +1762,21 @@ interface ConfigOptions {
      * The model comparison options.
      */
     comparison?: ComparisonOptions;
+    /**
+     * The number of model instances to initialize for each bundle.
+     *
+     * If undefined, the default behavior will be used, which is to initialize a single
+     * model instance for each bundle.
+     *
+     * If you set this to a value greater than 1, it will allow multiple pairs of model
+     * instances to be run concurrently.  For example, if the number of CPU cores is 8,
+     * setting this to 4 will allow 4 pairs of model instances to be run concurrently,
+     * using all available cores.
+     *
+     * If you set this to 0, the implementation will automatically choose a value based on
+     * the number of available CPU cores (i.e., the number of cores divided by 2).
+     */
+    concurrency?: number;
 }
 /**
  * The resolved configuration for check and comparison tests.
@@ -1506,22 +1790,89 @@ interface Config {
 
 declare function createConfig(options: ConfigOptions): Promise<Config>;
 
-declare class PerfRunner {
-    readonly bundleModelL: BundleModel;
-    readonly bundleModelR: BundleModel;
-    private readonly mode;
-    private readonly taskQueue;
+type CancelRunPerf = () => void;
+interface RunPerfCallbacks {
     onComplete?: (reportL: PerfReport, reportR: PerfReport) => void;
     onError?: (error: Error) => void;
-    constructor(bundleModelL: BundleModel, bundleModelR: BundleModel, mode?: 'serial' | 'parallel');
-    start(): void;
 }
+interface RunPerfOptions {
+    /** The mode to run the performance tests (default is 'serial'). */
+    mode?: 'serial' | 'parallel';
+    /** The number of warmups for each perf run (default is 5). */
+    warmupCount?: number;
+    /** The number of times to run the model for each perf run (default is 100). */
+    runCount?: number;
+}
+/**
+ * Run performance tests on the bundle models.
+ *
+ * @param callbacks The callbacks that will be notified.
+ * @param options The options for the performance run.
+ * @return A function that will cancel the process when invoked.
+ */
+declare function runPerf(callbacks: RunPerfCallbacks, options?: RunPerfOptions): CancelRunPerf;
+
+/**
+ * The report for a single trace comparison between two datasets.
+ *
+ * TODO: This is basically the same as `DiffReport`, except that it preserves the
+ * diff points.  Maybe we can combine them and make the points array an opt-in thing.
+ */
+interface TraceDatasetReport {
+    datasetKey: DatasetKey;
+    validity: DiffValidity;
+    points: Map<number, DiffPoint>;
+    minValue: number;
+    maxValue: number;
+    avgDiff: number;
+    minDiff: number;
+    maxDiff: number;
+    maxDiffPoint: DiffPoint;
+}
+/**
+ * The roll-up report that contains the results of the trace comparisons
+ * for all datasets.
+ */
+interface TraceReport {
+    datasetReports: Map<DatasetKey, TraceDatasetReport>;
+}
+
+type CancelRunTrace = () => void;
+interface RunTraceCallbacks {
+    onComplete?: (traceReport: TraceReport) => void;
+    onError?: (error: Error) => void;
+}
+interface TraceCompareToBundleOptions {
+    kind: 'compare-to-bundle';
+    bundleSide0: 'left' | 'right';
+    scenarioSpec0: ScenarioSpec;
+    bundleSide1: 'left' | 'right';
+    scenarioSpec1: ScenarioSpec;
+}
+interface TraceCompareToExtDataOptions {
+    kind: 'compare-to-ext-data';
+    extData: DatasetMap;
+    bundleSide: 'left' | 'right';
+    scenarioSpec: ScenarioSpec;
+}
+type TraceOptions = TraceCompareToBundleOptions | TraceCompareToExtDataOptions;
+/**
+ * Perform a trace run, comparing all datasets from the requested models.
+ *
+ * @param modelSpec The model spec that provides the datasets to be compared (usually from the "right" bundle).
+ * @param callbacks The callbacks that will be notified.
+ * @param options Options to control how the trace is run.
+ * @return A function that will cancel the process when invoked.
+ */
+declare function runTrace(modelSpec: ModelSpec, callbacks: RunTraceCallbacks, options: TraceOptions): CancelRunTrace;
 
 /**
  * The report for a single run of the full check+comparison test suite.
  */
 interface SuiteReport {
+    /** The check report. */
     checkReport: CheckReport;
+    /** The comparison report (only defined if comparisons were enabled). */
     comparisonReport?: ComparisonReport;
 }
 /**
@@ -1532,7 +1883,13 @@ interface SuiteReport {
  * when there are many reported differences.
  */
 interface SuiteSummary {
+    /** The date and time the suite was run (in ISO 8601 format, as generated by `Date.toISOString`). */
+    date: string;
+    /** The time in milliseconds that it took to run the suite. */
+    elapsed: number;
+    /** The check summary. */
     checkSummary: CheckSummary;
+    /** The comparison summary (only defined if comparisons were enabled). */
     comparisonSummary?: ComparisonSummary;
 }
 
@@ -1543,8 +1900,16 @@ interface RunSuiteCallbacks {
     onError?: (error: Error) => void;
 }
 interface RunSuiteOptions {
-    /** Set to true to reduce the number of scenarios generated for a `matrix`. */
-    simplifyScenarios?: boolean;
+    /**
+     * The check tests to skip.  Note that checks are matched by group and name
+     * (case insensitive).
+     */
+    skipChecks?: CheckNameSpec[];
+    /**
+     * The comparison scenarios to skip.  Note that scenarios are matched by
+     * title and subtitle (case insensitive).
+     */
+    skipComparisonScenarios?: ComparisonScenarioTitleSpec[];
 }
 /**
  * Run the full suite of checks and comparisons defined in the given configuration.
@@ -1561,8 +1926,9 @@ declare function runSuite(config: Config, callbacks: RunSuiteCallbacks, options?
  * failed/errored checks or comparisons with differences.
  *
  * @param suiteReport The full suite report.
+ * @param elapsedMillis The time in milliseconds that it took to run the suite.
  * @return The converted suite summary.
  */
-declare function suiteSummaryFromReport(suiteReport: SuiteReport): SuiteSummary;
+declare function suiteSummaryFromReport(suiteReport: SuiteReport, elapsedMillis: number): SuiteSummary;
 
-export { type AllInputsSpec, type Bundle, type BundleGraphData, type BundleGraphDatasetSpec, type BundleGraphId, type BundleGraphSpec, type BundleGraphView, type BundleModel, CheckDataCoordinator, type CheckDataRequestKey, type CheckDatasetReport, type CheckGroupReport, type CheckKey, type CheckPredicateOp, type CheckPredicateOpConstantRef, type CheckPredicateOpDataRef, type CheckPredicateOpRef, type CheckPredicateReport, type CheckPredicateSummary, type CheckPredicateTimeOptions, type CheckPredicateTimeRange, type CheckPredicateTimeSingle, type CheckPredicateTimeSpec, type CheckReport, type CheckResult, type CheckResultErrorInfo, type CheckScenario, type CheckScenarioError, type CheckScenarioInputDesc, type CheckScenarioReport, type CheckStatus, type CheckSummary, type CheckTestReport, type ComparisonCategorizedResults, type ComparisonConfig, ComparisonDataCoordinator, type ComparisonDataRequestKey, type ComparisonDataset, type ComparisonDatasetName, type ComparisonDatasetOptions, type ComparisonDatasetSource, type ComparisonDatasetSpec, type ComparisonDatasets, type ComparisonGraphGroup, type ComparisonGraphGroupId, type ComparisonGraphGroupRefSpec, type ComparisonGraphGroupSpec, type ComparisonGraphId, type ComparisonGraphsArraySpec, type ComparisonGraphsPresetSpec, type ComparisonGroup, type ComparisonGroupKey, type ComparisonGroupKind, type ComparisonGroupRoot, type ComparisonGroupScores, type ComparisonGroupSummariesByCategory, type ComparisonGroupSummary, type ComparisonOptions, type ComparisonPlot, type ComparisonReport, type ComparisonReportDetailItem, type ComparisonReportDetailRow, type ComparisonReportOptions, type ComparisonReportSummaryRow, type ComparisonReportSummarySection, type ComparisonResolverError, type ComparisonResolverInvalidValueError, type ComparisonResolverUnknownInputError, type ComparisonResolverUnknownInputSettingGroupError, type ComparisonScenario, type ComparisonScenarioAllInputsSettings, type ComparisonScenarioGroup, type ComparisonScenarioGroupId, type ComparisonScenarioGroupRefSpec, type ComparisonScenarioGroupSpec, type ComparisonScenarioGroupTitle, type ComparisonScenarioId, type ComparisonScenarioInput, type ComparisonScenarioInputAtPositionSpec, type ComparisonScenarioInputAtValueSpec, type ComparisonScenarioInputName, type ComparisonScenarioInputPosition, type ComparisonScenarioInputSettings, type ComparisonScenarioInputSpec, type ComparisonScenarioInputState, type ComparisonScenarioKey, type ComparisonScenarioPresetMatrixSpec, type ComparisonScenarioRefSpec, type ComparisonScenarioSettings, type ComparisonScenarioSpec, type ComparisonScenarioSubtitle, type ComparisonScenarioTitle, type ComparisonScenarioWithAllInputsSpec, type ComparisonScenarioWithDistinctInputsSpec, type ComparisonScenarioWithInputsSpec, type ComparisonScenarioWithSettingGroupSpec, type ComparisonScenarios, type ComparisonSpecs, type ComparisonSpecsSource, type ComparisonSummary, type ComparisonTestReport, type ComparisonTestSummary, type ComparisonUnresolvedScenarioGroupRef, type ComparisonUnresolvedScenarioRef, type ComparisonUnresolvedView, type ComparisonView, type ComparisonViewBox, type ComparisonViewBoxSpec, type ComparisonViewGraphOrder, type ComparisonViewGraphsSpec, type ComparisonViewGroup, type ComparisonViewGroupSpec, type ComparisonViewGroupTitle, type ComparisonViewGroupWithScenariosSpec, type ComparisonViewGroupWithViewsSpec, type ComparisonViewItemSubtitle, type ComparisonViewItemTitle, type ComparisonViewRow, type ComparisonViewRowSpec, type ComparisonViewRowSubtitle, type ComparisonViewRowTitle, type ComparisonViewSpec, type ComparisonViewSubtitle, type ComparisonViewTitle, type Config, type ConfigInitOptions, type ConfigOptions, type DataSource, type Dataset, type DatasetGroupName, type DatasetKey, type DatasetMap, type DatasetsResult, type DiffPoint, type DiffReport, type DiffValidity, type Dimension, type GraphComparisonDatasetReport, type GraphComparisonMetadataReport, type GraphComparisonReport, type GraphInclusion, type ImplVar, type InputAliasName, type InputGroupName, type InputId, type InputPosition, type InputSetting, type InputSettingGroupId, type InputSettingsSpec, type InputVar, type LegendItem, type LinkItem, type LoadedBundle, type ModelSpec, type NamedBundle, type OutputVar, type PerfReport, PerfRunner, PerfStats, type PositionSetting, type RelatedItem, type RunSuiteCallbacks, type RunSuiteOptions, type ScenarioSpec, type ScenarioSpecUid, type SourceName, type Subscript, type SuiteReport, type SuiteSummary, type ValueSetting, type VarId, categorizeComparisonTestSummaries, checkReportFromSummary, checkSummaryFromReport, comparisonSummaryFromReport, createConfig, datasetMessage, diffDatasets, diffGraphs, getScoresForTestSummaries, predicateMessage, runSuite, scenarioMessage, suiteSummaryFromReport };
+export { type AllInputsSpec, type Bundle, type BundleGraphData, type BundleGraphDatasetSpec, type BundleGraphId, type BundleGraphSpec, type BundleGraphView, type BundleModel, type CancelRunPerf, type CancelRunSuite, type CancelRunTrace as CancelTrace, type CheckConfig, CheckDataCoordinator, type CheckDataRef, type CheckDataRefKey, type CheckDataRequestKey, type CheckDataset, type CheckDatasetError, type CheckDatasetReport, type CheckGroupReport, type CheckKey, type CheckNameSpec, type CheckOptions, type CheckPredicateOp, type CheckPredicateOpConstantRef, type CheckPredicateOpDataRef, type CheckPredicateOpRef, type CheckPredicateReport, type CheckPredicateSummary, type CheckPredicateTimeOptions, type CheckPredicateTimeRange, type CheckPredicateTimeSingle, type CheckPredicateTimeSpec, type CheckReport, type CheckResult, type CheckResultErrorInfo, type CheckScenario, type CheckScenarioError, type CheckScenarioInputDesc, type CheckScenarioReport, type CheckStatus, type CheckSummary, type CheckTestReport, type ComparisonCategorizedResults, type ComparisonConfig, ComparisonDataCoordinator, type ComparisonDataRequestKey, type ComparisonDataset, type ComparisonDatasetName, type ComparisonDatasetOptions, type ComparisonDatasetSource, type ComparisonDatasetSpec, type ComparisonDatasets, type ComparisonGraphGroup, type ComparisonGraphGroupId, type ComparisonGraphGroupRefSpec, type ComparisonGraphGroupSpec, type ComparisonGraphId, type ComparisonGraphsArraySpec, type ComparisonGraphsPresetSpec, type ComparisonGroup, type ComparisonGroupKey, type ComparisonGroupKind, type ComparisonGroupRoot, type ComparisonGroupScores, type ComparisonGroupSummariesByCategory, type ComparisonGroupSummary, type ComparisonOptions, type ComparisonPlot, type ComparisonReport, type ComparisonReportDetailItem, type ComparisonReportDetailRow, type ComparisonReportOptions, type ComparisonReportSummaryRow, type ComparisonReportSummarySection, type ComparisonResolverError, type ComparisonResolverInvalidValueError, type ComparisonResolverUnknownInputError, type ComparisonResolverUnknownInputSettingGroupError, type ComparisonScenario, type ComparisonScenarioAllInputsSettings, type ComparisonScenarioGroup, type ComparisonScenarioGroupId, type ComparisonScenarioGroupRefSpec, type ComparisonScenarioGroupSpec, type ComparisonScenarioGroupTitle, type ComparisonScenarioId, type ComparisonScenarioInput, type ComparisonScenarioInputAtPositionSpec, type ComparisonScenarioInputAtValueSpec, type ComparisonScenarioInputName, type ComparisonScenarioInputPosition, type ComparisonScenarioInputSettings, type ComparisonScenarioInputSpec, type ComparisonScenarioInputState, type ComparisonScenarioKey, type ComparisonScenarioPresetMatrixSpec, type ComparisonScenarioRefSpec, type ComparisonScenarioSettings, type ComparisonScenarioSpec, type ComparisonScenarioSubtitle, type ComparisonScenarioTitle, type ComparisonScenarioTitleSpec, type ComparisonScenarioWithAllInputsSpec, type ComparisonScenarioWithDistinctInputsSpec, type ComparisonScenarioWithInputsSpec, type ComparisonScenarioWithSettingGroupSpec, type ComparisonScenarios, type ComparisonSortMode, type ComparisonSpecs, type ComparisonSpecsSource, type ComparisonSummary, type ComparisonTestReport, type ComparisonTestSummary, type ComparisonUnresolvedScenarioGroupRef, type ComparisonUnresolvedScenarioRef, type ComparisonUnresolvedView, type ComparisonView, type ComparisonViewBox, type ComparisonViewBoxSpec, type ComparisonViewGraphOrder, type ComparisonViewGraphsSpec, type ComparisonViewGroup, type ComparisonViewGroupSpec, type ComparisonViewGroupTitle, type ComparisonViewGroupWithScenariosSpec, type ComparisonViewGroupWithViewsSpec, type ComparisonViewItemSubtitle, type ComparisonViewItemTitle, type ComparisonViewRow, type ComparisonViewRowSpec, type ComparisonViewRowSubtitle, type ComparisonViewRowTitle, type ComparisonViewSpec, type ComparisonViewSubtitle, type ComparisonViewTitle, type Config, type ConfigInitOptions, type ConfigOptions, type DataSource, type Dataset, type DatasetGroupName, type DatasetKey, type DatasetMap, type DatasetsResult, type DiffPoint, type DiffReport, type DiffValidity, type EncodedImplVars, type EncodedSubscript, type EncodedVarInstance, type EncodedVarType, type EncodedVariable, type GraphComparisonDatasetReport, type GraphComparisonMetadataReport, type GraphComparisonReport, type GraphInclusion, type ImplVar, type ImplVarGroup, type InputAliasName, type InputGroupName, type InputId, type InputPosition, type InputSetting, type InputSettingGroupId, type InputSettingsSpec, type InputVar, type LegendItem, type LinkItem, type LoadedBundle, type ModelSpec, type NamedBundle, type OutputVar, type PerfReport, PerfStats, type PositionSetting, type RelatedItem, type RunPerfCallbacks, type RunPerfOptions, type RunSuiteCallbacks, type RunSuiteOptions, type ScenarioSpec, type ScenarioSpecUid, type SourceName, type SuiteReport, type SuiteSummary, type RunTraceCallbacks as TraceCallbacks, type TraceCompareToBundleOptions, type TraceCompareToExtDataOptions, type TraceDatasetReport, type TraceOptions, type TraceReport, type ValueSetting, type VarId, categorizeComparisonTestSummaries, checkReportFromSummary, checkSummaryFromReport, comparisonSummaryFromReport, createCheckDataCoordinator, createCheckDataCoordinatorForTests, createComparisonDataCoordinator, createConfig, datasetMessage, decodeImplVars, diffDatasets, diffGraphs, encodeImplVars, getScoresForTestSummaries, predicateMessage, runPerf, runSuite, runTrace, scenarioMessage, suiteSummaryFromReport, testSummaryFromReport };