@sdeverywhere/runtime 0.2.1 → 0.2.3

package/README.md

@@ -1,6 +1,16 @@
 # @sdeverywhere/runtime
 
-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).
+This package provides a simplified runtime API around a System Dynamics model as generated
+by the [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) transpiler.
+
+Note that the SDEverywhere transpiler can be configured to generate model code in different formats:
+
+- JavaScript code, which can be used directly without an extra compilation step, or
+- C code, which can be compiled to a more optimized WebAssembly (Wasm) module (this requires an extra tool called [Emscripten](https://emscripten.org); see the `@sdeverywhere/plugin-wasm` package for more details)
+
+The `@sdeverywhere/runtime` package presents a format-agnostic API that can be used to
+run your model, regardless of whether you generate a pure JavaScript model or a WebAssembly
+model.
 
 ## Quick Start
 
@@ -27,50 +37,58 @@ _NOTE:_ If you followed the "Quick Start" instructions and/or used the
 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`
+### 1. Import your generated model
 
-In your application, load the wasm module using the wrapper produced by
-Emscripten, then pass it to `initWasmModelAndBuffers`.
-This will create the `WasmModel` and `WasmBuffer` instances that will be
-used in the next step to initalize the `ModelRunner`.
+In your application, import the model file that was generated by the SDEverywhere
+transpiler.
+Depending on how you configured your project (for example, if you set a different
+`prepDir`), the generated model file may be in a different location than what is
+shown in this example, but the approach will generally be the same.
 
 ```ts
-import { initWasmModelAndBuffers, WasmModelInitResult } from '@sdeverywhere/runtime'
-import loadWasm from './generated/mymodel'
-
-// These are the same lists (and must be in the same order) as the spec file passed to `sde`.
-const inputVarNames = [] // from spec.json
-const outputVarNames = [] // from spec.json
-
-async function initWasmModel(): Promise<WasmModelInitResult> {
-  // Load the wasm module asynchronously
-  const wasmModule = await loadWasm()
-
-  // Initialize the wasm model and its associated buffers
-  return initWasmModelAndBuffers(wasmModule, inputVarNames.length, outputVarNames)
-}
+import loadGeneratedModel from './sde-prep/generated-model.js'
 ```
 
-### 2. Initialize the `ModelRunner`
+### 2. Initialize a `ModelRunner`
 
 The next step is to create a `ModelRunner` instance, which simplifies
 the process of running a `WasmModel` with a given set of inputs and
 parsing the outputs.
 The `ModelRunner` produces an `Outputs` instance that provides easy
 access to time series data for each output variable in the model.
-The `createWasmModelRunner` function is the simplest way to create
-a `ModelRunner` that works with your `WasmModel`:
+
+Note that SDEverywhere offers two implementations of the `ModelRunner`
+interface:
+
+- The `createSynchronousModelRunner` function creates a `ModelRunner`
+  that runs your generated model on the main JavaScript thread. This
+  is the simplest option and is sufficient for small models, but for
+  larger models that take longer to run, it may block the JavaScript
+  thread and cause your application to appear unresponsive.
+- The `spawnAsyncModelRunner` function (in the separate
+  `@sdeverywhere/runtime-async` package) provides an alternative
+  implementation of `ModelRunner` that runs your generated model in
+  a Web Worker or Node.js worker thread. This requires an extra
+  build-time step (see the `@sdeverywhere/plugin-worker` package),
+  but the benefit of an asynchronous runner is that the model can
+  run in a separate thread, which frees up the main thread for user
+  interface work and other computation.
+
+The following example demonstrates the use of the
+`createSynchronousModelRunner` function:
 
 ```ts
-import { createWasmModelRunner, createInputValue, Outputs } from '@sdeverywhere/runtime'
+import { createSynchronousModelRunner } from '@sdeverywhere/runtime'
+import loadGeneratedModel from './sde-prep/generated-model.js'
 
 async function main() {
-  // Initialize the `WasmModel` and `ModelRunner`
-  const wasmResult = await initWasmModel()
-  const modelRunner = createWasmModelRunner(wasmResult)
+  // Initialize the `ModelRunner`
+  const generatedModel = await loadGeneratedModel()
+  const modelRunner = createSynchronousModelRunner(generatedModel)
 
-  // Create a set of `InputValue` instances corresponding to the inputs in the spec.json file
-  const inputs = [createInputValue('_input1', 2), createInputValue('_input2', 10)] // etc
+  // Create an array that holds the model input values; these must be in the same order
+  // as the inputs that are specified in your `sde.config.js` or `spec.json` file
+  const inputs = [2, 10] // etc
 
   // Create an `Outputs` instance to hold the model outputs
   let outputs = modelRunner.createOutputs()
@@ -84,21 +102,28 @@ async function main() {
   console.log(`Temperature change in 2100: ${tempChangeIn2100}`)
 ```
 
-See the `@sdeverywhere/runtime-async` package for an alternative
-implementation of `ModelRunner` that allows for running a model in a Web
-Worker or Node.js worker thread.
-
 ### 3. Initialize a `ModelScheduler` (optional)
 
-If you build a more complex application with a user interface around a
-model, the `ModelScheduler` class takes care of automatically scheduling
-and running the model whenever there are changes to input variables:
+If you build a more complex application with a user interface around a model
+(especially with a responsive web framework such as Svelte, Vue, React, etc),
+the `ModelScheduler` class takes care of automatically scheduling and running
+the model whenever there are changes to input variables:
 
 ```ts
-import { ModelScheduler } from '@sdeverywhere/runtime'
+import { createInputValue, createSynchronousModelRunner, ModelScheduler } from '@sdeverywhere/runtime'
+import loadGeneratedModel from './sde-prep/generated-model.js'
 
 async function initModel() {
-  // Initialize the `WasmModel`, `ModelRunner`, inputs, and outputs as above
+  // Initialize the `ModelRunner`
+  const generatedModel = await loadGeneratedModel()
+  const modelRunner = createSynchronousModelRunner(generatedModel)
+
+  // Create an array of reactive `InputValue` instances; these must be in the same order
+  // as the inputs that are specified in your `sde.config.js` or `spec.json` file
+  const inputs = [createInputValue('_input1', 2), createInputValue('_input2', 0)] // etc
+
+  // Create a `ModelScheduler`
+  const outputs = modelRunner.createOutputs()
   const modelScheduler = new ModelScheduler(modelRunner, inputs, outputs)
 
   // Get notified when new output data is available
@@ -128,16 +153,18 @@ $ emcc \
 build/<mymodel>.c build/macros.c build/model.c build/vensim.c \
 -Ibuild -o ./output/<mymodel>.js -Wall -Os \
 -s STRICT=1 -s MALLOC=emmalloc -s FILESYSTEM=0 -s MODULARIZE=1 \
--s EXPORTED_FUNCTIONS="['_malloc','_getInitialTime','_getFinalTime','_getSaveper','_runModelWithBuffers']" \
+-s EXPORTED_FUNCTIONS="['_malloc','_free','_getInitialTime','_getFinalTime','_getSaveper','_setLookup','_runModelWithBuffers']" \
 -s EXPORTED_RUNTIME_METHODS="['cwrap']"
 ```
 
 Note that the generated module must export the following functions at minimum:
 
 - `_malloc`
+- `_free`
 - `_getInitialTime`
 - `_getFinalTime`
 - `_getSaveper`
+- `_setLookup`
 - `_runModelWithBuffers`
 - `cwrap`