@sdeverywhere/runtime 0.2.6 → 0.2.8

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import { Result } from 'neverthrow';
 
+/** The name of a data source for external/static datasets, e.g., 'Ref', 'Constants'. */
+type SourceName = string;
 /** A variable name, as used in the modeling tool. */
 type VarName = string;
 /** A variable identifier, as used in model code generated by SDEverywhere. */
@@ -86,6 +88,10 @@ declare function createInputValue(varId: InputVarId, defaultValue: number, initi
 
 /** Indicates the type of error encountered when parsing an outputs buffer. */
 type ParseError = 'invalid-point-count';
+/** Type alias for a map that holds a `Series` instance for each output (or static) variable ID. */
+type SeriesMap = Map<OutputVarId, Series>;
+/** Type alias for a map that holds data for a given source name. */
+type DataMap = Map<SourceName, SeriesMap>;
 /**
  * A time series of data points for an output variable.
  */
@@ -173,6 +179,24 @@ declare class Outputs {
     getSeriesForVar(varId: OutputVarId): Series | undefined;
 }
 
+/**
+ * Specifies the constant value that will be used to override a constant in a
+ * generated model.
+ */
+interface ConstantDef {
+    /** The reference that identifies the constant variable to be modified. */
+    varRef: VarRef;
+    /** The new constant value. */
+    value: number;
+}
+/**
+ * Create a `ConstantDef` instance.
+ *
+ * @param varRef The reference to the constant variable to be modified.
+ * @param value The new constant value.
+ */
+declare function createConstantDef(varRef: VarRef, value: number): ConstantDef;
+
 /**
  * Specifies the data that will be used to set or override a lookup definition.
  */
@@ -210,6 +234,41 @@ declare function getEncodedVarIndicesLength(varSpecs: VarSpec[]): number;
  * @param varSpecs The `VarSpec` instances to encode.
  */
 declare function encodeVarIndices(varSpecs: VarSpec[], indicesArray: Int32Array): void;
+/**
+ * Return the lengths of the arrays that are required to store the constant values
+ * and indices for the given `ConstantDef` instances.
+ *
+ * @hidden This is not part of the public API; it is exposed here for use by
+ * the synchronous and asynchronous model runner implementations.
+ *
+ * @param constantDefs The `ConstantDef` instances to encode.
+ */
+declare function getEncodedConstantBufferLengths(constantDefs: ConstantDef[]): {
+    constantIndicesLength: number;
+    constantsLength: number;
+};
+/**
+ * Encode constant values and indices to the given arrays.
+ *
+ * @hidden This is not part of the public API; it is exposed here for use by
+ * the synchronous and asynchronous model runner implementations.
+ *
+ * @param constantDefs The `ConstantDef` instances to encode.
+ * @param constantIndicesArray The view on the constant indices buffer.
+ * @param constantsArray The view on the constant values buffer.
+ */
+declare function encodeConstants(constantDefs: ConstantDef[], constantIndicesArray: Int32Array, constantsArray: Float64Array): void;
+/**
+ * Decode constant values and indices from the given buffer views and return the
+ * reconstructed `ConstantDef` instances.
+ *
+ * @hidden This is not part of the public API; it is exposed here for use by
+ * the synchronous and asynchronous model runner implementations.
+ *
+ * @param constantIndicesArray The view on the constant indices buffer.
+ * @param constantsArray The view on the constant values buffer.
+ */
+declare function decodeConstants(constantIndicesArray: Int32Array, constantsArray: Float64Array): ConstantDef[];
 /**
  * Return the lengths of the arrays that are required to store the lookup data
  * and indices for the given `LookupDef` instances.
@@ -299,6 +358,17 @@ declare class ModelListing {
  * Additional options that can be passed to a `runModel` call to influence the model run.
  */
 interface RunModelOptions {
+    /**
+     * If defined, override the values for the specified constant variables.
+     *
+     * Note that constant overrides do not persist after the `runModel` call.  Because
+     * `initConstants` is called at the beginning of each `runModel` call, all constants
+     * are reset to their default values before each model run.  If you want to override
+     * constants, you must provide them in the options for each `runModel` call.  To
+     * reset constants to their original values, simply stop passing them in the options
+     * (or pass an empty array).
+     */
+    constants?: ConstantDef[];
     /**
      * If defined, override the data for the specified lookups and/or data variables.
      *
@@ -377,6 +447,11 @@ interface RunModelParams {
      * @param array The array that contains the output values.
      */
     storeOutputs(array: Float64Array): void;
+    /**
+     * Return an array containing constant overrides, or undefined if no constants were passed
+     * to the latest `runModel` call.
+     */
+    getConstants(): ConstantDef[] | undefined;
     /**
      * Return an array containing lookup overrides, or undefined if no lookups were passed to
      * the latest `runModel` call.
@@ -413,6 +488,8 @@ declare class BufferedRunModelParams implements RunModelParams {
      *   inputs
      *   outputs
      *   outputIndices
+     *   constants (values)
+     *   constantIndices
      *   lookups (data)
      *   lookupIndices
      */
@@ -430,6 +507,10 @@ declare class BufferedRunModelParams implements RunModelParams {
     private readonly outputs;
     /** The output indices section of the `encoded` buffer. */
     private readonly outputIndices;
+    /** The constant values section of the `encoded` buffer. */
+    private readonly constants;
+    /** The constant indices section of the `encoded` buffer. */
+    private readonly constantIndices;
     /** The lookup data section of the `encoded` buffer. */
     private readonly lookups;
     /** The lookup indices section of the `encoded` buffer. */
@@ -453,6 +534,7 @@ declare class BufferedRunModelParams implements RunModelParams {
     getOutputs(): Float64Array | undefined;
     getOutputsObject(): Outputs | undefined;
     storeOutputs(array: Float64Array): void;
+    getConstants(): ConstantDef[] | undefined;
     getLookups(): LookupDef[] | undefined;
     getElapsedTime(): number;
     storeElapsedTime(elapsed: number): void;
@@ -495,6 +577,7 @@ declare class ReferencedRunModelParams implements RunModelParams {
     private outputs;
     private outputsLengthInElements;
     private outputIndicesLengthInElements;
+    private constants;
     private lookups;
     /**
      * @param listing The model listing that is used to locate a variable that is referenced by
@@ -511,6 +594,7 @@ declare class ReferencedRunModelParams implements RunModelParams {
     getOutputs(): Float64Array | undefined;
     getOutputsObject(): Outputs | undefined;
     storeOutputs(array: Float64Array): void;
+    getConstants(): ConstantDef[] | undefined;
     getLookups(): LookupDef[] | undefined;
     getElapsedTime(): number;
     storeElapsedTime(elapsed: number): void;
@@ -758,6 +842,8 @@ interface JsModel {
     /** @hidden */
     setInputs(inputValue: (index: number) => number): void;
     /** @hidden */
+    setConstant(varSpec: VarSpec, value: number): void;
+    /** @hidden */
     setLookup(varSpec: VarSpec, points: Float64Array | undefined): void;
     /** @hidden */
     storeOutputs(storeValue: (value: number) => void): void;
@@ -796,7 +882,7 @@ declare function execJsModel(jsModel: JsModel): void;
  * @hidden This type is not part of the public API; it is exposed only for use in
  * tests in the runtime-async package.
  */
-type OnEvalAux = (vars: Map<VarId, number>, lookups: Map<VarId, JsModelLookup>) => void;
+type OnEvalAux = (vars: Map<VarId, number>, constants: Map<VarId, number> | undefined, lookups: Map<VarId, JsModelLookup>) => void;
 /**
  * @hidden This type is not part of the public API; it is exposed only for use in
  * tests in the runtime-async package.
@@ -810,6 +896,7 @@ declare class MockJsModel implements JsModel {
     private readonly initialTime;
     private readonly finalTime;
     private readonly vars;
+    private readonly constants;
     private readonly lookups;
     private fns;
     readonly onEvalAux: OnEvalAux;
@@ -829,6 +916,7 @@ declare class MockJsModel implements JsModel {
     setModelFunctions(fns: JsModelFunctions): void;
     setTime(time: number): void;
     setInputs(): void;
+    setConstant(varSpec: VarSpec, value: number): void;
     setLookup(varSpec: VarSpec, points: Float64Array | undefined): void;
     storeOutputs(storeValue: (value: number) => void): void;
     storeOutput(varSpec: VarSpec, storeValue: (value: number) => void): void;
@@ -874,7 +962,7 @@ declare function initWasmModel(wasmModule: WasmModule): RunnableModel;
  * @hidden This type is not part of the public API; it is exposed only for use in
  * tests in the runtime-async package.
  */
-type OnRunModel = (inputs: Float64Array, outputs: Float64Array, lookups: Map<VarId, JsModelLookup>, outputIndices?: Int32Array) => void;
+type OnRunModel = (inputs: Float64Array, outputs: Float64Array, constants: Map<VarId, number> | undefined, lookups: Map<VarId, JsModelLookup>, outputIndices?: Int32Array) => void;
 /**
  * @hidden This type is not part of the public API; it is exposed only for use in
  * tests in the runtime-async package.
@@ -892,6 +980,7 @@ declare class MockWasmModule implements WasmModule {
     private mallocOffset;
     private readonly allocs;
     private readonly lookups;
+    private readonly constants;
     readonly onRunModel: OnRunModel;
     constructor(options: {
         initialTime: number;
@@ -901,14 +990,14 @@ declare class MockWasmModule implements WasmModule {
         onRunModel: OnRunModel;
     });
     varIdForSpec(varSpec: VarSpec): VarId;
-    cwrap(fname: string): (varIndex: number, _subIndicesAddress: number, pointsAddress: number, numPoints: number) => void;
+    cwrap(fname: string): (inputsAddress: number, _inputIndicesAddress: number, outputsAddress: number, outputIndicesAddress: number, constantValuesAddress: number, constantIndicesAddress: number) => void;
     _malloc(lengthInBytes: number): number;
     _free(): void;
     private getHeapView;
 }
 
 /**
- * Abstraction that allows for running the wasm model on the JS thread
+ * Abstraction that allows for running a generated model on the JS thread
  * or asynchronously (e.g. in a Web Worker), depending on the implementation.
  */
 interface ModelRunner {
@@ -965,7 +1054,7 @@ declare function createRunnableModel(generatedModel: GeneratedModel): RunnableMo
 declare function createSynchronousModelRunner(generatedModel: GeneratedModel): ModelRunner;
 
 /**
- * A high-level interface that schedules running of the underlying `WasmModel`.
+ * A high-level interface that schedules the underlying `ModelRunner`.
  *
  * When one or more input values are changed, this class will schedule a model
  * run to be completed as soon as possible.  When the model run has completed,
@@ -994,14 +1083,127 @@ declare class ModelScheduler {
      */
     constructor(runner: ModelRunner, userInputs: InputValue[], outputs: Outputs);
     /**
-     * Schedule a wasm model run (if not already pending).  When the run is
+     * Schedule a model run (if not already pending).  When the run is
+     * complete, save the outputs and call the `onOutputsChanged` callback.
+     */
+    private runModelIfNeeded;
+    /**
+     * Run the model asynchronously using the current set of input values.
+     */
+    private runModelNow;
+}
+
+/**
+ * Defines a context that holds a distinct set of model inputs and outputs.
+ * These inputs and outputs are kept separate from those in other contexts,
+ * which allows an application to use the same underlying model instance
+ * with multiple sets of inputs and outputs.
+ */
+interface ModelContext {
+    /**
+     * Called when the outputs have been updated after a model run.
+     */
+    onOutputsChanged?: () => void;
+    /**
+     * Return the series data for the given model output variable or external
+     * dataset.
+     *
+     * @param varId The ID of the output variable associated with the data.
+     * @param sourceName The external data source name (e.g. "Ref"), or
+     * undefined to use the latest model output data from this context.
+     */
+    getSeriesForVar(varId: OutputVarId, sourceName?: SourceName): Series | undefined;
+}
+/**
+ * A high-level interface that schedules running of the underlying `ModelRunner`.
+ *
+ * This class is similar to the (single context) `ModelScheduler` class, except
+ * this one supports multiple contexts, each with its own distinct set of
+ * inputs and outputs.  This is useful for running the same underlying model
+ * instance with different sets of inputs and outputs.  For example, you can
+ * use this to show the outputs for multiple scenarios in a single graph, or
+ * multiple scenarios across different graphs.
+ *
+ * When input values are changed in one or more contexts, this class will schedule
+ * a model run for each changed context to be completed as soon as possible.
+ * When the model run has completed, the context's `onOutputsChanged` function
+ * is called to notify that new output data is available for that context.
+ *
+ * The `ModelRunner` is pluggable to allow for running the model synchronously
+ * (on the main JavaScript thread) or asynchronously (in a Web Worker or Node.js
+ * worker thread).
+ */
+declare class MultiContextModelScheduler {
+    private readonly runner;
+    /**
+     * An optional `Outputs` instance that will be reused for the initial context.  This will
+     * be set to undefined after it is used for the first context.
+     */
+    private initialOutputs?;
+    /** The second array that holds a stable copy of the user inputs. */
+    private currentInputs;
+    /** The contexts that hold distinct sets of inputs and outputs. */
+    private readonly contexts;
+    /** Whether a model run has been scheduled. */
+    private runNeeded;
+    /** Whether a model run is in progress. */
+    private runInProgress;
+    /**
+     * @param runner The model runner.
+     * @param options Additional options for the scheduler.
+     * @param options.initialOutputs An optional `Outputs` instance that will be reused
+     * for the initial context.  This is useful for saving memory when an `Outputs`
+     * instance was already created for, e.g., a initial baseline/reference run.
+     */
+    constructor(runner: ModelRunner, options?: {
+        initialOutputs?: Outputs;
+    });
+    /**
+     * Return true if the scheduler has started any model runs.
+     */
+    isStarted(): boolean;
+    /**
+     * Add a new context that holds a distinct set of model inputs and outputs.
+     * These inputs and outputs are kept separate from those in other contexts,
+     * which allows an application to use the same underlying model to run with
+     * multiple I/O contexts.
+     *
+     * Note that the contexts created before the first scheduled model run
+     * will inherit the data from `initialOutputs` passed to the constructor,
+     * but contexts created after that will initially have output values set
+     * to zero.
+     *
+     * @param inputs The input values, in the same order as in the spec file passed to `sde`.
+     * @param options Additional options for the context.
+     * @param options.externalData Additional data that is external to the model outputs.
+     * For example, this can contain data that was captured from an initial reference
+     * run, or other static data that is displayed in graphs alongside the model
+     * output data in graphs.
+     */
+    addContext(inputs: InputValue[], options?: {
+        externalData?: DataMap;
+    }): ModelContext;
+    /**
+     * Remove the given context from the set of contexts managed by the scheduler.
+     *
+     * @param context The context to remove.
+     */
+    removeContext(context: ModelContext): void;
+    /**
+     * Schedule a model run (if not already pending).  When the run is
      * complete, save the outputs and call the `onOutputsChanged` callback.
      */
-    private runWasmModelIfNeeded;
+    private runModelIfNeeded;
     /**
-     * Run the wasm model asynchronously using the current set of input values.
+     * Run the model asynchronously for all relevant contexts.
+     */
+    private runModelNow;
+    /**
+     * Run the model asynchronously using the current set of input values in the given context.
+     *
+     * @param context The context to use for the model run.
      */
-    private runWasmModelNow;
+    private runModelNowForContext;
 }
 
 /**
@@ -1018,4 +1220,4 @@ declare function perfNow(): unknown;
  */
 declare function perfElapsed(t0: unknown): number;
 
-export { BufferedRunModelParams, type GeneratedModel, type InputCallbacks, type InputValue, type InputVarId, type JsModel, type JsModelFunctionContext, type JsModelFunctions, type LookupDef, MockJsModel, MockWasmModule, ModelListing, type ModelListingSpecs, type ModelRunner, ModelScheduler, type OnEvalAux, type OnRunModel, type OutputVarId, Outputs, type ParseError, type Point, ReferencedRunModelParams, type RunModelOptions, type RunModelParams, type RunnableModel, Series, type VarId, type VarName, type VarRef, type VarSpec, type WasmModule, createInputValue, createLookupDef, createRunnableModel, createSynchronousModelRunner, decodeLookups, encodeLookups, encodeVarIndices, execJsModel, getEncodedLookupBufferLengths, getEncodedVarIndicesLength, getJsModelFunctions, initJsModel, initWasmModel, perfElapsed, perfNow };
+export { BufferedRunModelParams, type ConstantDef, type DataMap, type GeneratedModel, type InputCallbacks, type InputValue, type InputVarId, type JsModel, type JsModelFunctionContext, type JsModelFunctions, type LookupDef, MockJsModel, MockWasmModule, type ModelContext, ModelListing, type ModelListingSpecs, type ModelRunner, ModelScheduler, MultiContextModelScheduler, type OnEvalAux, type OnRunModel, type OutputVarId, Outputs, type ParseError, type Point, ReferencedRunModelParams, type RunModelOptions, type RunModelParams, type RunnableModel, Series, type SeriesMap, type SourceName, type VarId, type VarName, type VarRef, type VarSpec, type WasmModule, createConstantDef, createInputValue, createLookupDef, createRunnableModel, createSynchronousModelRunner, decodeConstants, decodeLookups, encodeConstants, encodeLookups, encodeVarIndices, execJsModel, getEncodedConstantBufferLengths, getEncodedLookupBufferLengths, getEncodedVarIndicesLength, getJsModelFunctions, initJsModel, initWasmModel, perfElapsed, perfNow };