@sdeverywhere/runtime 0.2.7 → 0.2.8

package/dist/index.d.cts

@@ -179,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.
  */
@@ -216,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.
@@ -305,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.
      *
@@ -383,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.
@@ -419,6 +488,8 @@ declare class BufferedRunModelParams implements RunModelParams {
      *   inputs
      *   outputs
      *   outputIndices
+     *   constants (values)
+     *   constantIndices
      *   lookups (data)
      *   lookupIndices
      */
@@ -436,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. */
@@ -459,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;
@@ -501,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
@@ -517,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;
@@ -764,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;
@@ -802,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.
@@ -816,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;
@@ -835,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;
@@ -880,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.
@@ -898,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;
@@ -907,7 +990,7 @@ 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;
@@ -1137,4 +1220,4 @@ declare function perfNow(): unknown;
  */
 declare function perfElapsed(t0: unknown): number;
 
-export { BufferedRunModelParams, 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, 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 };

package/dist/index.d.ts

@@ -179,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.
  */
@@ -216,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.
@@ -305,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.
      *
@@ -383,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.
@@ -419,6 +488,8 @@ declare class BufferedRunModelParams implements RunModelParams {
      *   inputs
      *   outputs
      *   outputIndices
+     *   constants (values)
+     *   constantIndices
      *   lookups (data)
      *   lookupIndices
      */
@@ -436,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. */
@@ -459,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;
@@ -501,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
@@ -517,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;
@@ -764,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;
@@ -802,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.
@@ -816,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;
@@ -835,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;
@@ -880,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.
@@ -898,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;
@@ -907,7 +990,7 @@ 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;
@@ -1137,4 +1220,4 @@ declare function perfNow(): unknown;
  */
 declare function perfElapsed(t0: unknown): number;
 
-export { BufferedRunModelParams, 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, 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 };