feat: allow for overriding constants at runtime

examples/sir/config/model.csv

@@ -1,2 +1,2 @@
-graph default min time,graph default max time,model dat files,bundle listing,custom lookups,custom outputs
-0,100,,false,false,false
+graph default min time,graph default max time,model dat files,bundle listing,custom constants,custom lookups,custom outputs
+0,100,,false,false,false,false

examples/template-jquery/config/model.csv

@@ -1,2 +1,2 @@
-graph default min time,graph default max time,model dat files,bundle listing,custom lookups,custom outputs
-0,100,,false,false,false
+graph default min time,graph default max time,model dat files,bundle listing,custom constants,custom lookups,custom outputs
+0,100,,false,false,false,false

examples/template-svelte/config/model.csv

@@ -1,2 +1,2 @@
-graph default min time,graph default max time,model dat files,bundle listing,custom lookups,custom outputs
-0,100,,false,false,false
+graph default min time,graph default max time,model dat files,bundle listing,custom constants,custom lookups,custom outputs
+0,100,,false,false,false,false

package.json

@@ -25,8 +25,9 @@
     "@playwright/test": "^1.56.1",
     "@typescript-eslint/eslint-plugin": "^8.46.0",
     "@typescript-eslint/parser": "^8.46.0",
-    "@vitest/browser": "^4.0.16",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/browser": "^4.0.17",
+    "@vitest/browser-playwright": "^4.0.17",
+    "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.37.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-eslint-comments": "^3.2.0",
@@ -42,7 +43,7 @@
     "typedoc": "0.25.0",
     "typedoc-plugin-markdown": "3.16.0",
     "typescript": "^5.2.2",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "pnpm": {
     "peerDependencyRules": {

packages/build/docs/interfaces/ModelSpec.md

@@ -53,6 +53,23 @@ if it is needed.
 
 ___
 
+### customConstants
+
+ `Optional` **customConstants**: `boolean` \| `string`[]
+
+Whether to allow constants to be overridden at runtime using `setConstant`.
+
+If undefined or false, the generated model will implement `setConstant`
+as a no-op, meaning that constants cannot be overridden at runtime.
+
+If true, all constants in the generated model will be available to be
+overridden.
+
+If an array is provided, only those variable names in the array will
+be available to be overridden.
+
+___
+
 ### customLookups
 
  `Optional` **customLookups**: `boolean` \| `string`[]

packages/build/docs/interfaces/ResolvedModelSpec.md

@@ -72,6 +72,23 @@ if it is needed.
 
 ___
 
+### customConstants
+
+ **customConstants**: `boolean` \| `string`[]
+
+Whether to allow constants to be overridden at runtime using `setConstant`.
+
+If false, the generated model will contain a `setConstant` function that
+throws an error, meaning that constants cannot be overridden at runtime.
+
+If true, all constants in the generated model will be available to be
+overridden.
+
+If an array is provided, only those variable names in the array will
+be available to be overridden.
+
+___
+
 ### customLookups
 
  **customLookups**: `boolean` \| `string`[]

packages/build/src/_shared/model-spec.ts

@@ -77,6 +77,20 @@ export interface ModelSpec {
    */
   bundleListing?: boolean
 
+  /**
+   * Whether to allow constants to be overridden at runtime using `setConstant`.
+   *
+   * If undefined or false, the generated model will implement `setConstant`
+   * as a no-op, meaning that constants cannot be overridden at runtime.
+   *
+   * If true, all constants in the generated model will be available to be
+   * overridden.
+   *
+   * If an array is provided, only those variable names in the array will
+   * be available to be overridden.
+   */
+  customConstants?: boolean | VarName[]
+
   /**
    * Whether to allow lookups to be overridden at runtime using `setLookup`.
    *
@@ -166,6 +180,20 @@ export interface ResolvedModelSpec {
    */
   bundleListing: boolean
 
+  /**
+   * Whether to allow constants to be overridden at runtime using `setConstant`.
+   *
+   * If false, the generated model will contain a `setConstant` function that
+   * throws an error, meaning that constants cannot be overridden at runtime.
+   *
+   * If true, all constants in the generated model will be available to be
+   * overridden.
+   *
+   * If an array is provided, only those variable names in the array will
+   * be available to be overridden.
+   */
+  customConstants: boolean | VarName[]
+
   /**
    * Whether to allow lookups to be overridden at runtime using `setLookup`.
    *

packages/build/src/build/impl/build-once.ts

@@ -76,8 +76,9 @@ export async function buildOnce(
       outputVarNames: modelSpec.outputVarNames,
       externalDatfiles: modelSpec.datFiles,
       bundleListing: modelSpec.bundleListing,
-      customLookups: modelSpec.customLookups,
-      customOutputs: modelSpec.customOutputs,
+      customConstants: modelSpec.customConstants || false,
+      customLookups: modelSpec.customLookups || false,
+      customOutputs: modelSpec.customOutputs || false,
       ...modelSpec.options
     }
     const specPath = joinPath(config.prepDir, 'spec.json')
@@ -220,6 +221,13 @@ function resolveModelSpec(modelSpec: ModelSpec): ResolvedModelSpec {
     outputSpecs = []
   }
 
+  let customConstants: boolean | VarName[]
+  if (modelSpec.customConstants !== undefined) {
+    customConstants = modelSpec.customConstants
+  } else {
+    customConstants = false
+  }
+
   let customLookups: boolean | VarName[]
   if (modelSpec.customLookups !== undefined) {
     customLookups = modelSpec.customLookups
@@ -241,6 +249,7 @@ function resolveModelSpec(modelSpec: ModelSpec): ResolvedModelSpec {
     outputs: outputSpecs,
     datFiles: modelSpec.datFiles || [],
     bundleListing: modelSpec.bundleListing === true,
+    customConstants,
     customLookups,
     customOutputs,
     options: modelSpec.options

packages/build/tests/build-prod/build-prod.spec.ts

@@ -101,6 +101,7 @@ describe('build in production mode', () => {
     expect(resolvedModelSpec!.outputs).toEqual([{ varName: 'Z' }])
     expect(resolvedModelSpec!.datFiles).toEqual([])
     expect(resolvedModelSpec!.bundleListing).toBe(false)
+    expect(resolvedModelSpec!.customConstants).toBe(false)
     expect(resolvedModelSpec!.customLookups).toBe(false)
     expect(resolvedModelSpec!.customOutputs).toBe(false)
   })
@@ -144,11 +145,12 @@ describe('build in production mode', () => {
     expect(resolvedModelSpec!.outputs).toEqual([{ varName: 'Z' }])
     expect(resolvedModelSpec!.datFiles).toEqual([])
     expect(resolvedModelSpec!.bundleListing).toBe(true)
+    expect(resolvedModelSpec!.customConstants).toBe(false)
     expect(resolvedModelSpec!.customLookups).toEqual(['lookup1'])
     expect(resolvedModelSpec!.customOutputs).toEqual(['output1'])
   })
 
-  it('should resolve model spec (when boolean is provided for customLookups and customOutputs)', async () => {
+  it('should resolve model spec (when boolean is provided for customConstants, customLookups, and customOutputs)', async () => {
     let resolvedModelSpec: ResolvedModelSpec
     const userConfig: UserConfig = {
       genFormat: 'c',
@@ -161,6 +163,7 @@ describe('build in production mode', () => {
           inputs: ['Y'],
           outputs: ['Z'],
           bundleListing: true,
+          customConstants: true,
           customLookups: true,
           customOutputs: true
         }
@@ -182,6 +185,7 @@ describe('build in production mode', () => {
     expect(result.value.exitCode).toBe(0)
     expect(resolvedModelSpec!).toBeDefined()
     expect(resolvedModelSpec!.bundleListing).toBe(true)
+    expect(resolvedModelSpec!.customConstants).toEqual(true)
     expect(resolvedModelSpec!.customLookups).toEqual(true)
     expect(resolvedModelSpec!.customOutputs).toEqual(true)
   })

packages/check-ui-shell/vitest.config.js

@@ -2,6 +2,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { defineConfig, mergeConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser-playwright'
 
 import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
 
@@ -36,7 +37,7 @@ export default defineConfig(() =>
               name: 'storybook',
               browser: {
                 enabled: true,
-                provider: 'playwright',
+                provider: playwright(),
                 headless: true,
                 instances: [{ browser: 'chromium' }]
               },

packages/cli/src/c/main.c

@@ -111,7 +111,7 @@ int main(int argc, char** argv) {
   double* outputBuffer = (double*)malloc(numOutputs * numSavePoints * sizeof(double));
 
   // Run the model with the sparse input arrays and output buffer
-  runModelWithBuffers(inputValues, inputIndices, outputBuffer, NULL);
+  runModelWithBuffers(inputValues, inputIndices, outputBuffer, NULL, NULL, NULL);
 
   if (!suppress_data_output) {
     if (raw_output) {

packages/cli/src/c/model.c

@@ -63,6 +63,39 @@ double getSaveper() {
   return _saveper;
 }
 
+/**
+ * Set constant overrides from the given buffers.
+ *
+ * The `constantIndices` buffer contains the variable indices and subscript indices
+ * for each constant to override. The format is:
+ *   [count, varIndex1, subCount1, subIndex1_1, ..., varIndex2, subCount2, ...]
+ *
+ * The `constantValues` buffer contains the corresponding values for each constant.
+ */
+void setConstantOverridesFromBuffers(double* constantValues, int32_t* constantIndices) {
+  if (constantValues == NULL || constantIndices == NULL) {
+    return;
+  }
+
+  size_t indexBufferOffset = 0;
+  size_t valueBufferOffset = 0;
+  size_t constantCount = (size_t)constantIndices[indexBufferOffset++];
+
+  for (size_t i = 0; i < constantCount; i++) {
+    size_t varIndex = (size_t)constantIndices[indexBufferOffset++];
+    size_t subCount = (size_t)constantIndices[indexBufferOffset++];
+    size_t* subIndices;
+    if (subCount > 0) {
+      subIndices = (size_t*)(constantIndices + indexBufferOffset);
+      indexBufferOffset += subCount;
+    } else {
+      subIndices = NULL;
+    }
+    double value = constantValues[valueBufferOffset++];
+    setConstant(varIndex, subIndices, value);
+  }
+}
+
 /**
  * Run the model, reading inputs from the given `inputs` buffer, and writing outputs
  * to the given `outputs` buffer.
@@ -90,21 +123,28 @@ double getSaveper() {
  * values.  See above for details on the expected format.
  */
 void runModel(double* inputs, double* outputs) {
-  runModelWithBuffers(inputs, NULL, outputs, NULL);
+  runModelWithBuffers(inputs, NULL, outputs, NULL, NULL, NULL);
 }
 
 /**
  * Run the model, reading inputs from the given `inputs` buffer, and writing outputs
  * to the given `outputs` buffer.
  *
+ * INPUTS
+ * ------
+ *
  * If `inputIndices` is NULL, the `inputs` buffer is assumed to have one double value
  * for each input variable, in exactly the same order as the variables are listed in
  * the spec file.
  *
  * If `inputIndices` is non-NULL, it specifies which inputs are being set:
- *   - inputIndices[0] is the count of inputs being specified
- *   - inputIndices[1..N] are the indices of the inputs to set
- *   - inputs[0..N-1] are the corresponding values
+ *   - inputIndices[0] is the count (C) of inputs being specified
+ *   - inputIndices[1...C] are the indices of the inputs to set (where each index
+ *     corresponds to the index of the input variable in the spec.json file)
+ *   - inputs[0...C-1] are the corresponding values
+ *
+ * OUTPUTS
+ * -------
  *
  * After each step of the run, the `outputs` buffer will be updated with the output
  * variables.  The `outputs` buffer needs to be at least as large as:
@@ -118,31 +158,59 @@ void runModel(double* inputs, double* outputs) {
  * outputs will begin, and so on.
  *
  * If `outputIndices` is non-NULL, it specifies which outputs are being stored:
- *   - outputIndices[0] is the count of output variables being stored
- *   - outputIndices[1..N] are the indices of the output variables to store (unlike
- *     `inputIndices`, these indices refer to the ones defined in the `{model}.json`
- *     listing file, NOT the list of output variables spec file)
- *   - outputs[0..N-1] are the corresponding values
+ *   - outputIndices[0] is the count (C) of output variables being stored
+ *   - outputIndices[1...] are the indices of the output variables to store, in
+ *     the following format:
+ *       [count, varIndex1, subCount1, subIndex1_1, ..., varIndex2, subCount2, ...]
+ *     where `count` is the number of variables to store, `varIndexN` is the index
+ *     of the variable to store (from the {model}.json listing file), `subCountN` is
+ *     the number of subscripts for that variable, and `subIndexN_M` is the index of
+ *     the subscript at the Mth position for that variable
+ *   - outputs[0...C-1] are the corresponding values
  *
- * @param inputs The buffer that contains the model input values.  If NULL,
- * no inputs will be set and the model will use the default values for all
- * constants as defined in the generated model.  If non-NULL, the buffer is
- * assumed to have one double value for each input variable.  The number of
- * values provided depends on `inputIndices`; see above for details on the
- * expected format of these two parameters.
- * @param inputIndices The optional buffer that specifies which input values
- * from the `inputs` buffer are being set.  See above for details on the
- * expected format.
- * @param outputs The required buffer that will receive the model output
- * values.  See above for details on the expected format.
- * @param outputIndices The optional buffer that specifies which output values
- * will be stored in the `outputs` buffer.  See above for details on the
- * expected format.
+ * CONSTANT OVERRIDES
+ * ------------------
+ *
+ * If `constants` and `constantIndices` are non-NULL, the provided constant values will
+ * override the default values for those constants as defined in the generated model.
+ *
+ * The `constantIndices` buffer specifies which constants are being overridden.  The
+ * format is the same as described above for `outputIndices`:
+ *   - constantIndices[0] is the count (C) of constants being overridden
+ *   - constantIndices[1...] are the indices of the constants to override, in the
+ *     following format:
+ *       [count, varIndex1, subCount1, subIndex1_1, ..., varIndex2, subCount2, ...]
+ *     where `count` is the number of constants to override, `varIndexN` is the index
+ *     of the variable to store (from the {model}.json listing file), `subCountN` is
+ *     the number of subscripts for that variable, and `subIndexN_M` is the index of
+ *     the subscript at the Mth position for that variable
+ *   - constants[0...C-1] are the corresponding values
+ *
+ * @param inputs The buffer that contains the model input values.  If NULL, no inputs
+ * will be set and the model will use the default values for all constants as defined
+ * in the generated model.  If non-NULL, the buffer is assumed to have one double value
+ * for each input variable.  The number of values provided depends on `inputIndices`;
+ * see above for details on the expected format of these two parameters.
+ * @param inputIndices The optional buffer that specifies which input values from the
+ * `inputs` buffer are being set.  See above for details on the expected format.
+ * @param outputs The required buffer that will receive the model output values.  See
+ * above for details on the expected format.
+ * @param outputIndices The optional buffer that specifies which output values will be
+ * stored in the `outputs` buffer.  See above for details on the expected format.
+ * @param constants An optional buffer that contains the values of the constants to
+ * override.  Pass NULL if not overriding any constants.  Each value in the buffer
+ * corresponds to the value of the constant at the corresponding index.
+ * @param constantIndices An optional buffer that contains the indices of the constants
+ * to override.  Pass NULL if not overriding any constants.  See above for details on
+ * the expected format.
  */
-void runModelWithBuffers(double* inputs, int32_t* inputIndices, double* outputs, int32_t* outputIndices) {
+void runModelWithBuffers(double* inputs, int32_t* inputIndices, double* outputs, int32_t* outputIndices, double* constants, int32_t* constantIndices) {
   outputBuffer = outputs;
   outputIndexBuffer = outputIndices;
   initConstants();
+  if (constants != NULL && constantIndices != NULL) {
+    setConstantOverridesFromBuffers(constants, constantIndices);
+  }
   if (inputs != NULL) {
     setInputs(inputs, inputIndices);
   }

packages/cli/src/c/sde.h

@@ -56,7 +56,7 @@ double getInitialTime(void);
 double getFinalTime(void);
 double getSaveper(void);
 void runModel(double* inputs, double* outputs);
-void runModelWithBuffers(double* inputs, int32_t* inputIndices, double* outputs, int32_t* outputIndices);
+void runModelWithBuffers(double* inputs, int32_t* inputIndices, double* outputs, int32_t* outputIndices, double* constants, int32_t* constantIndices);
 void run(void);
 void startOutput(void);
 void outputVar(double value);
@@ -66,6 +66,7 @@ void finish(void);
 void initConstants(void);
 void initLevels(void);
 void setInputs(double* inputValues, int32_t* inputIndices);
+void setConstant(size_t varIndex, size_t* subIndices, double value);
 void setLookup(size_t varIndex, size_t* subIndices, double* points, size_t numPoints);
 void evalAux(void);
 void evalLevels(void);