@sdeverywhere/runtime 0.2.0 → 0.2.2

package/README.md

@@ -1,13 +1,30 @@
 # @sdeverywhere/runtime
 
-This package provides a simplified API around a system dynamics model that
-has been produced by [SDEverywhere](https://github.com/climateinteractive/SDEverywhere)
-and compiled to a WebAssembly (Wasm) module via [Emscripten](https://emscripten.org).
+This package provides a simplified API around a System Dynamics model as generated by [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) and compiled to a WebAssembly (Wasm) module via [Emscripten](https://emscripten.org).
+
+## Quick Start
+
+The best way to get started with SDEverywhere is to follow the [Quick Start](https://github.com/climateinteractive/SDEverywhere#quick-start) instructions.
+If you follow those instructions, the `@sdeverywhere/runtime` package will be added to your project automatically, in which case you can skip the next section and jump straight to the ["Usage"](#usage) section below.
+
+## Install
+
+```sh
+# npm
+npm install @sdeverywhere/runtime
+
+# pnpm
+pnpm add @sdeverywhere/runtime
+
+# yarn
+yarn add @sdeverywhere/runtime
+```
 
 ## Usage
 
-NOTE: If you use the `@sdeverywhere/create` package, most of the initialization
-steps listed below are already handled for you in the generated `core` package,
+_NOTE:_ If you followed the "Quick Start" instructions and/or used the
+`@sdeverywhere/create` package to generate your project, the initialization
+steps listed below are already implemented for you in the generated `core` package,
 and you can work directly with a `ModelRunner` and/or `ModelScheduler` instance.
 
 ### 1. Initialize the `WasmModel`

package/dist/index.cjs

@@ -1,7 +1,21 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,39 +29,75 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
 
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  ModelListing: () => ModelListing,
   ModelScheduler: () => ModelScheduler,
   Outputs: () => Outputs,
   Series: () => Series,
   WasmBuffer: () => WasmBuffer,
   WasmModel: () => WasmModel,
+  createFloat64WasmBuffer: () => createFloat64WasmBuffer,
   createInputValue: () => createInputValue,
+  createInt32WasmBuffer: () => createInt32WasmBuffer,
   createWasmModelRunner: () => createWasmModelRunner,
   initWasmModelAndBuffers: () => initWasmModelAndBuffers,
   perfElapsed: () => perfElapsed,
-  perfNow: () => perfNow
+  perfNow: () => perfNow,
+  updateOutputIndices: () => updateOutputIndices
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/wasm-model/wasm-buffer.ts
 var WasmBuffer = class {
-  constructor(wasmModule, numElements) {
+  /**
+   * @param wasmModule The `WasmModule` used to initialize the memory.
+   * @param byteOffset The byte offset within the wasm heap.
+   * @param heapArray The array view on the underlying heap buffer.
+   */
+  constructor(wasmModule, byteOffset, heapArray) {
     this.wasmModule = wasmModule;
-    const sizeOfFloat64 = 8;
-    const lengthInBytes = numElements * sizeOfFloat64;
-    this.byteOffset = wasmModule._malloc(lengthInBytes);
-    const float64Offset = this.byteOffset / sizeOfFloat64;
-    this.heapArray = wasmModule.HEAPF64.subarray(float64Offset, float64Offset + numElements);
+    this.byteOffset = byteOffset;
+    this.heapArray = heapArray;
   }
+  /**
+   * @return An `ArrType` view on the underlying heap buffer.
+   */
   getArrayView() {
     return this.heapArray;
   }
+  /**
+   * @return The raw address of the underlying heap buffer.
+   * @hidden This is intended for use by `WasmModel` only.
+   */
   getAddress() {
     return this.byteOffset;
   }
+  /**
+   * Dispose the buffer by freeing the allocated heap memory.
+   */
   dispose() {
     if (this.heapArray) {
       this.wasmModule._free(this.byteOffset);
@@ -56,9 +106,29 @@ var WasmBuffer = class {
     }
   }
 };
+function createInt32WasmBuffer(wasmModule, numElements) {
+  const elemSizeInBytes = 4;
+  const lengthInBytes = numElements * elemSizeInBytes;
+  const byteOffset = wasmModule._malloc(lengthInBytes);
+  const elemOffset = byteOffset / elemSizeInBytes;
+  const heapArray = wasmModule.HEAP32.subarray(elemOffset, elemOffset + numElements);
+  return new WasmBuffer(wasmModule, byteOffset, heapArray);
+}
+function createFloat64WasmBuffer(wasmModule, numElements) {
+  const elemSizeInBytes = 8;
+  const lengthInBytes = numElements * elemSizeInBytes;
+  const byteOffset = wasmModule._malloc(lengthInBytes);
+  const elemOffset = byteOffset / elemSizeInBytes;
+  const heapArray = wasmModule.HEAPF64.subarray(elemOffset, elemOffset + numElements);
+  return new WasmBuffer(wasmModule, byteOffset, heapArray);
+}
 
 // src/wasm-model/wasm-model.ts
+var indicesPerOutput = 4;
 var WasmModel = class {
+  /**
+   * @param wasmModule The `WasmModule` that provides access to the native functions.
+   */
   constructor(wasmModule) {
     function getNumberValue(funcName) {
       const wasmGetValue = wasmModule.cwrap(funcName, "number", []);
@@ -67,24 +137,59 @@ var WasmModel = class {
     this.startTime = getNumberValue("getInitialTime");
     this.endTime = getNumberValue("getFinalTime");
     this.saveFreq = getNumberValue("getSaveper");
+    try {
+      this.maxOutputIndices = getNumberValue("getMaxOutputIndices");
+    } catch (e) {
+      this.maxOutputIndices = 0;
+    }
     this.numSavePoints = Math.round((this.endTime - this.startTime) / this.saveFreq) + 1;
-    this.wasmRunModel = wasmModule.cwrap("runModelWithBuffers", null, ["number", "number"]);
+    this.wasmRunModel = wasmModule.cwrap("runModelWithBuffers", null, ["number", "number", "number"]);
   }
-  runModel(inputs, outputs) {
-    this.wasmRunModel(inputs.getAddress(), outputs.getAddress());
+  /**
+   * Run the model, using inputs from the `inputs` buffer, and writing outputs into
+   * the `outputs` buffer.
+   *
+   * @param inputs The buffer containing inputs in the order expected by the model.
+   * @param outputs The buffer into which the model will store output values.
+   * @param outputIndices The buffer used to control which variables are written to `outputs`.
+   */
+  runModel(inputs, outputs, outputIndices) {
+    this.wasmRunModel(inputs.getAddress(), outputs.getAddress(), (outputIndices == null ? void 0 : outputIndices.getAddress()) || 0);
   }
 };
 function initWasmModelAndBuffers(wasmModule, numInputs, outputVarIds) {
   const model = new WasmModel(wasmModule);
-  const inputsBuffer = new WasmBuffer(wasmModule, numInputs);
-  const outputsBuffer = new WasmBuffer(wasmModule, outputVarIds.length * model.numSavePoints);
+  const inputsBuffer = createFloat64WasmBuffer(wasmModule, numInputs);
+  const outputVarCount = Math.max(outputVarIds.length, model.maxOutputIndices);
+  const outputsBuffer = createFloat64WasmBuffer(wasmModule, outputVarCount * model.numSavePoints);
+  let outputIndicesBuffer;
+  if (model.maxOutputIndices > 0) {
+    outputIndicesBuffer = createInt32WasmBuffer(wasmModule, model.maxOutputIndices * indicesPerOutput);
+  }
   return {
     model,
     inputsBuffer,
     outputsBuffer,
+    outputIndicesBuffer,
     outputVarIds
   };
 }
+function updateOutputIndices(indicesArray, outputVarSpecs) {
+  var _a;
+  if (indicesArray.length < outputVarSpecs.length * indicesPerOutput) {
+    throw new Error("Length of indicesArray must be large enough to accommodate the given outputVarSpecs");
+  }
+  let offset = 0;
+  for (const outputVarSpec of outputVarSpecs) {
+    const subCount = ((_a = outputVarSpec.subscriptIndices) == null ? void 0 : _a.length) || 0;
+    indicesArray[offset + 0] = outputVarSpec.varIndex;
+    indicesArray[offset + 1] = subCount > 0 ? outputVarSpec.subscriptIndices[0] : 0;
+    indicesArray[offset + 2] = subCount > 1 ? outputVarSpec.subscriptIndices[1] : 0;
+    indicesArray[offset + 3] = subCount > 2 ? outputVarSpec.subscriptIndices[2] : 0;
+    offset += indicesPerOutput;
+  }
+  indicesArray.fill(0, offset);
+}
 
 // src/model-runner/inputs.ts
 function createInputValue(varId, defaultValue, initialValue) {
@@ -108,21 +213,43 @@ function createInputValue(varId, defaultValue, initialValue) {
 
 // src/model-runner/outputs.ts
 var import_neverthrow = require("neverthrow");
-var Series = class {
+var Series = class _Series {
+  /**
+   * @param varId The ID for the output variable (as used by SDEverywhere).
+   * @param points The data points for the variable, one point per time increment.
+   */
   constructor(varId, points) {
     this.varId = varId;
     this.points = points;
   }
+  /**
+   * Return the Y value at the given time.  Note that this does not attempt to interpolate
+   * if there is no data point defined for the given time and will return undefined in
+   * that case.
+   *
+   * @param time The x (time) value.
+   * @return The y value for the given time, or undefined if there is no data point defined
+   * for the given time.
+   */
   getValueAtTime(time) {
     var _a;
     return (_a = this.points.find((p) => p.x === time)) == null ? void 0 : _a.y;
   }
+  /**
+   * Create a new `Series` instance that is a copy of this one.
+   */
   copy() {
-    const pointsCopy = this.points.map((p) => ({ ...p }));
-    return new Series(this.varId, pointsCopy);
+    const pointsCopy = this.points.map((p) => __spreadValues({}, p));
+    return new _Series(this.varId, pointsCopy);
   }
 };
 var Outputs = class {
+  /**
+   * @param varIds The output variable identifiers.
+   * @param startTime The start time for the model.
+   * @param endTime The end time for the model.
+   * @param saveFreq The frequency with which output values are saved (aka `SAVEPER`).
+   */
   constructor(varIds, startTime, endTime, saveFreq = 1) {
     this.varIds = varIds;
     this.startTime = startTime;
@@ -139,6 +266,32 @@ var Outputs = class {
       this.varSeries[i] = new Series(varId, points);
     }
   }
+  /**
+   * The optional set of specs that dictate which variables from the model will be
+   * stored in this `Outputs` instance.  If undefined, the default set of outputs
+   * will be stored (as configured in `varIds`).
+   * @hidden This is not yet part of the public API; it is exposed here for use
+   * in experimental testing tools.
+   */
+  setVarSpecs(varSpecs) {
+    if (varSpecs.length !== this.varIds.length) {
+      throw new Error("Length of output varSpecs must match that of varIds");
+    }
+    this.varSpecs = varSpecs;
+  }
+  /**
+   * Parse the given raw float buffer (produced by the model) and store the values
+   * into this `Outputs` instance.
+   *
+   * Note that the length of `outputsBuffer` must be greater than or equal to
+   * the capacity of this `Outputs` instance.  The `Outputs` instance is allowed
+   * to be smaller to support the case where you want to extract a subset of
+   * the time range in the buffer produced by the model.
+   *
+   * @param outputsBuffer The raw outputs buffer produced by the model.
+   * @param rowLength The number of elements per row (one element per save point).
+   * @return An `ok` result if the buffer is valid, otherwise an `err` result.
+   */
   updateFromBuffer(outputsBuffer, rowLength) {
     const result = parseOutputsBuffer(outputsBuffer, rowLength, this);
     if (result.isOk()) {
@@ -147,6 +300,11 @@ var Outputs = class {
       return (0, import_neverthrow.err)(result.error);
     }
   }
+  /**
+   * Return the series for the given output variable.
+   *
+   * @param varId The ID of the output variable (as used by SDEverywhere).
+   */
   getSeriesForVar(varId) {
     const seriesIndex = this.varIds.indexOf(varId);
     if (seriesIndex >= 0) {
@@ -209,6 +367,8 @@ function createWasmModelRunner(wasmResult) {
   const inputsArray = inputsBuffer.getArrayView();
   const outputsBuffer = wasmResult.outputsBuffer;
   const outputsArray = outputsBuffer.getArrayView();
+  const outputIndicesBuffer = wasmResult.outputIndicesBuffer;
+  const outputIndicesArray = outputIndicesBuffer == null ? void 0 : outputIndicesBuffer.getArrayView();
   const rowLength = wasmModel.numSavePoints;
   let terminated = false;
   const runModelSync = (inputs, outputs) => {
@@ -216,8 +376,16 @@ function createWasmModelRunner(wasmResult) {
     for (const input of inputs) {
       inputsArray[i++] = input.get();
     }
+    const outputSpecs = outputs.varSpecs;
+    let useIndices;
+    if (outputIndicesArray && outputSpecs !== void 0 && outputSpecs.length > 0) {
+      updateOutputIndices(outputIndicesArray, outputSpecs);
+      useIndices = true;
+    } else {
+      useIndices = false;
+    }
     const t0 = perfNow();
-    wasmModel.runModel(inputsBuffer, outputsBuffer);
+    wasmModel.runModel(inputsBuffer, outputsBuffer, useIndices ? outputIndicesBuffer : void 0);
     outputs.runTimeInMillis = perfElapsed(t0);
     outputs.updateFromBuffer(outputsArray, rowLength);
     return outputs;
@@ -247,13 +415,121 @@ function createWasmModelRunner(wasmResult) {
   };
 }
 
+// src/model-runner/model-listing.ts
+var ModelListing = class {
+  constructor(modelJsonString) {
+    this.varSpecs = /* @__PURE__ */ new Map();
+    const modelJson = JSON.parse(modelJsonString);
+    const dimensions = /* @__PURE__ */ new Map();
+    for (const dimInfo of modelJson.dimensions) {
+      const dimId = dimInfo.name;
+      const subscripts = [];
+      for (let i = 0; i < dimInfo.value.length; i++) {
+        subscripts.push({
+          id: dimInfo.value[i],
+          // name: dimInfo.modelValue[i]
+          index: i
+        });
+      }
+      dimensions.set(dimId, {
+        id: dimId,
+        // name: dimInfo.modelName,
+        subscripts
+      });
+    }
+    function dimensionForId(dimId) {
+      const dim = dimensions.get(dimId);
+      if (dim === void 0) {
+        throw new Error(`No dimension info found for id=${dimId}`);
+      }
+      return dim;
+    }
+    const baseVarIds = /* @__PURE__ */ new Set();
+    for (const v of modelJson.variables) {
+      const baseVarId = varIdWithoutSubscripts(v.varName);
+      if (!baseVarIds.has(baseVarId)) {
+        const dimIds = v.families || [];
+        const dimensions2 = dimIds.map(dimensionForId);
+        if (dimensions2.length > 0) {
+          if (dimensions2.length > 3) {
+            throw new Error("Variables with more than 3 dimensions not currently supported");
+          }
+          const dimSubs = [];
+          for (const dim of dimensions2) {
+            dimSubs.push(dim.subscripts);
+          }
+          const combos = cartesianProductOf(dimSubs);
+          for (const combo of combos) {
+            const subs = combo.map((sub) => sub.id).join(",");
+            const subIndices = combo.map((sub) => sub.index);
+            const fullVarId = `${baseVarId}[${subs}]`;
+            this.varSpecs.set(fullVarId, {
+              varIndex: v.varIndex,
+              subscriptIndices: subIndices
+            });
+          }
+        } else {
+          this.varSpecs.set(baseVarId, {
+            varIndex: v.varIndex
+          });
+        }
+        baseVarIds.add(baseVarId);
+      }
+    }
+  }
+  /**
+   * Create a new `Outputs` instance that uses the same start/end years as the given "normal"
+   * `Outputs` instance but is prepared for reading the specified internal variables from the model.
+   *
+   * @param normalOutputs The `Outputs` that is used to access normal output variables from the model.
+   * @param varIds The variable IDs to include with the new `Outputs` instance.
+   */
+  deriveOutputs(normalOutputs, varIds) {
+    const varSpecs = [];
+    for (const varId of varIds) {
+      const varSpec = this.varSpecs.get(varId);
+      if (varSpec !== void 0) {
+        varSpecs.push(varSpec);
+      } else {
+        console.warn(`WARNING: No output var spec found for id=${varId}`);
+      }
+    }
+    const newOutputs = new Outputs(varIds, normalOutputs.startTime, normalOutputs.endTime, normalOutputs.saveFreq);
+    newOutputs.varSpecs = varSpecs;
+    return newOutputs;
+  }
+};
+function varIdWithoutSubscripts(fullVarId) {
+  const bracketIndex = fullVarId.indexOf("[");
+  if (bracketIndex >= 0) {
+    return fullVarId.substring(0, bracketIndex);
+  } else {
+    return fullVarId;
+  }
+}
+function cartesianProductOf(arr) {
+  return arr.reduce(
+    (a, b) => {
+      return a.map((x) => b.map((y) => x.concat([y]))).reduce((v, w) => v.concat(w), []);
+    },
+    [[]]
+  );
+}
+
 // src/model-scheduler/model-scheduler.ts
 var ModelScheduler = class {
+  /**
+   * @param runner The model runner.
+   * @param userInputs The input values, in the same order as in the spec file passed to `sde`.
+   * @param outputs The structure into which the model outputs will be stored.
+   */
   constructor(runner, userInputs, outputs) {
     this.runner = runner;
     this.userInputs = userInputs;
     this.outputs = outputs;
+    /** Whether a model run has been scheduled. */
     this.runNeeded = false;
+    /** Whether a model run is in progress. */
     this.runInProgress = false;
     const afterSet = () => {
       this.runWasmModelIfNeeded();
@@ -266,6 +542,10 @@ var ModelScheduler = class {
       this.currentInputs.push(createSimpleInputValue(userInput.varId));
     }
   }
+  /**
+   * Schedule a wasm model run (if not already pending).  When the run is
+   * complete, save the outputs and call the `onOutputsChanged` callback.
+   */
   runWasmModelIfNeeded() {
     this.runNeeded = true;
     if (this.runInProgress) {
@@ -277,26 +557,31 @@ var ModelScheduler = class {
       }, 0);
     }
   }
-  async runWasmModelNow() {
-    var _a;
-    for (let i = 0; i < this.userInputs.length; i++) {
-      this.currentInputs[i].set(this.userInputs[i].get());
-    }
-    try {
-      this.outputs = await this.runner.runModel(this.currentInputs, this.outputs);
-      (_a = this.onOutputsChanged) == null ? void 0 : _a.call(this, this.outputs);
-    } catch (e) {
-      console.error(`ERROR: Failed to run model: ${e.message}`);
-    }
-    if (this.runNeeded) {
-      this.runNeeded = false;
-      setTimeout(() => {
-        this.runWasmModelNow();
-      }, 0);
-    } else {
-      this.runNeeded = false;
-      this.runInProgress = false;
-    }
+  /**
+   * Run the wasm model asynchronously using the current set of input values.
+   */
+  runWasmModelNow() {
+    return __async(this, null, function* () {
+      var _a;
+      for (let i = 0; i < this.userInputs.length; i++) {
+        this.currentInputs[i].set(this.userInputs[i].get());
+      }
+      try {
+        this.outputs = yield this.runner.runModel(this.currentInputs, this.outputs);
+        (_a = this.onOutputsChanged) == null ? void 0 : _a.call(this, this.outputs);
+      } catch (e) {
+        console.error(`ERROR: Failed to run model: ${e.message}`);
+      }
+      if (this.runNeeded) {
+        this.runNeeded = false;
+        setTimeout(() => {
+          this.runWasmModelNow();
+        }, 0);
+      } else {
+        this.runNeeded = false;
+        this.runInProgress = false;
+      }
+    });
   }
 };
 function createSimpleInputValue(varId) {
@@ -314,15 +599,19 @@ function createSimpleInputValue(varId) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ModelListing,
   ModelScheduler,
   Outputs,
   Series,
   WasmBuffer,
   WasmModel,
+  createFloat64WasmBuffer,
   createInputValue,
+  createInt32WasmBuffer,
   createWasmModelRunner,
   initWasmModelAndBuffers,
   perfElapsed,
-  perfNow
+  perfNow,
+  updateOutputIndices
 });
 //# sourceMappingURL=index.cjs.map