@sdeverywhere/compile 0.7.32 → 0.7.34

package/README.md

@@ -1,6 +1,6 @@
 # @sdeverywhere/compile
 
-This package contains the core [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) compiler that takes a Vensim model as input and generates C code as output.
+This package contains the core [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) compiler that takes a Vensim or Stella model as input and generates JavaScript or C code as output.
 
 ## Quick Start
 
@@ -32,7 +32,7 @@ More usage details will be included here at a later time when the interfaces sta
 ## Documentation
 
 The `compile` package is currently treated as an implementation detail of the `cli` package.
-As such, there is no public API documentation at this time, but we hope to expose a public API once the interfaces stabilize.
+As such, there is no generated API documentation at this time, but we hope to expose a public API once the interfaces stabilize.
 
 ## License
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@sdeverywhere/compile",
-  "version": "0.7.32",
+  "version": "0.7.34",
   "description": "The core Vensim to C compiler for the SDEverywhere tool suite.",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@sdeverywhere/parse": "^0.1.5",
+    "@sdeverywhere/parse": "^0.1.6",
     "byline": "^5.0.0",
     "csv-parse": "^5.3.3",
     "fflate": "^0.8.3",
@@ -24,6 +25,8 @@
     "url": "https://github.com/climateinteractive/SDEverywhere/issues"
   },
   "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup",
     "lint": "eslint . --max-warnings 0",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
@@ -32,6 +35,6 @@
     "test": "vitest run",
     "test:watch": "vitest --hideSkippedTests",
     "test:ci": "vitest run",
-    "ci:build": "run-s lint prettier:check type-check test:ci"
+    "ci:build": "run-s clean lint prettier:check type-check build test:ci"
   }
 }

package/src/_shared/helpers.js

@@ -37,11 +37,18 @@ export function resetHelperState() {
   resetXlsxCache()
 }
 
+/**
+ * Format a model variable or subscript/dimension name into a valid C identifier.
+ *
+ * In the case where you have a full variable name that includes subscripts/dimensions
+ * (e.g., 'Variable name[DimA,B2]'), use `canonicalVensimName` to convert the base
+ * variable name and subscript/dimension parts to canonical form indepdendently.
+ *
+ * @param {import('./model-spec.js').VarName} name The variable name as used in the
+ * modeling tool.
+ * @return {import('./model-spec.js').VarId} The canonical variable identifier.
+ */
 export let canonicalName = name => {
-  // Format a model variable or subscript/dimension name into a valid C identifier.
-  // In the case where you have a full variable name that includes subscripts/dimensions
-  // (e.g., 'Variable name[DimA,B2]'), use `canonicalVensimName` to convert the
-  // base variable name and subscript/dimension parts to canonical form indepdendently.
   return canonicalId(name)
 }
 export let decanonicalize = name => {

package/src/_shared/model-spec.js

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 Climate Interactive / New Venture Fund
+
+/**
+ * A variable name as used in the modeling tool, for example `Some Var[DimA]` as used in
+ * a Vensim model.
+ *
+ * @typedef {string} VarName
+ */
+
+/**
+ * A variable identifier in the canonical format used internally by SDEverywhere, for
+ * example `_some_var`.  These are derived from a `VarName` by lowercasing the name and
+ * replacing special characters with underscores.
+ *
+ * @typedef {string} VarId
+ */
+
+/**
+ * A dimension (subscript range) identifier in the canonical format used internally by
+ * SDEverywhere, for example `_dima`.
+ *
+ * @typedef {string} DimId
+ */
+
+/**
+ * Describes a `dat` file that provides data for exogenous data variables in the model.
+ *
+ * This can either be:
+ *   - a plain file name (relative to the model directory), for example `data.dat`, or
+ *   - an object with a single key/value pair, where the key is a prefix that is prepended
+ *     to each variable name read from the file, and the value is the file name, for
+ *     example `{ "prefix ": "data.dat" }`.
+ *
+ * @typedef {string | { [varNamePrefix: string]: string }} DatFileSpec
+ */
+
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables that should
+ * be included in the model generated by SDEverywhere.
+ *
+ * This is the type of the object that is parsed from a `spec.json` file (as passed to the
+ * `sde generate` command using the `--spec` argument) and that is accepted by the
+ * `parseAndGenerate` function.
+ *
+ * All properties are optional.  If neither `inputVarNames` nor `outputVarNames` is
+ * provided, the generated model will include all variables from the model and will not
+ * allow any inputs to be set at runtime.
+ *
+ * @typedef {Object} ModelSpec
+ *
+ * @property {VarName[]} [inputVarNames] The input variables for the model, using the
+ * variable names as they appear in the modeling tool.
+ *
+ * When this is provided, only the listed variables can be set at runtime, and any
+ * variables that are not needed to compute the configured `outputVarNames` will be pruned
+ * from the generated model.
+ *
+ * @property {VarName[]} [outputVarNames] The output variables for the model, using the
+ * variable names as they appear in the modeling tool.
+ *
+ * It is customary to include `Time` as the first output variable.
+ *
+ * When this is provided, only the listed variables (plus the variables needed to compute
+ * them) will be included in the generated model.
+ *
+ * @property {DatFileSpec[]} [datFiles] The `dat` files that provide the data for exogenous
+ * data variables in the model.
+ *
+ * Each entry is resolved relative to the model directory (i.e., the directory that is
+ * passed using the `--datadir` argument, which defaults to the directory that contains the
+ * model file).
+ *
+ * @property {{ [dataTag: string]: string }} [directData] The mapping of data tag to
+ * Excel workbook file name, used to resolve the data for `GET DIRECT DATA`,
+ * `GET DIRECT CONSTANTS`, and `GET DIRECT LOOKUPS` calls in the model.
+ *
+ * Each key is the tag that appears in the model equation (for example, `?data`), and each
+ * value is the name of an `xlsx` file that is resolved relative to the model directory.
+ *
+ * @property {{ [dimName: string]: string }} [dimensionFamilies] The mapping of dimension
+ * name to family name, used when SDEverywhere cannot infer the family for a dimension
+ * from the model alone.
+ *
+ * Both the keys and the values use the dimension names as they appear in the modeling tool
+ * (they are converted to canonical form when the spec file is read).
+ *
+ * @property {{ [varId: VarId]: DimId | DimId[] }} [specialSeparationDims] The mapping of
+ * variable identifier to the dimension(s) on which that variable should be separated
+ * into one variable instance per subscript.
+ *
+ * Separating a variable is sometimes necessary to break a dependency cycle that would
+ * otherwise prevent the model from being evaluated.  Each value can be either a single
+ * dimension identifier or an array of dimension identifiers.
+ *
+ * @property {(DimId | DimId[])[]} [separateAllVarsWithDims] The dimensions for which all
+ * variables should be separated into one variable instance per subscript.
+ *
+ * This is a convenience alternative to `specialSeparationDims` that avoids the need to
+ * list each affected variable.  Each entry can be either a single dimension identifier or
+ * an array of dimension identifiers; a variable is separated only if every dimension in
+ * the entry appears on the left-hand side of its equation.
+ *
+ * @property {boolean} [bundleListing] Whether to bundle a model listing with the generated
+ * model.
+ *
+ * If undefined, defaults to false.
+ *
+ * When this is true, a model listing will be bundled with the generated model to allow the
+ * `runtime` package to resolve variables that are referenced by name or identifier.  This
+ * listing will increase the size of the generated model, so it is recommended to set this
+ * to true only if it is needed.
+ *
+ * @property {boolean | VarName[]} [customConstants] 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.
+ *
+ * @property {boolean | VarName[]} [customLookups] Whether to allow lookups to be
+ * overridden at runtime using `setLookup`.
+ *
+ * If undefined or false, the generated model will implement `setLookup` as a no-op,
+ * meaning that lookups cannot be overridden at runtime.
+ *
+ * If true, all lookups 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.
+ *
+ * @property {boolean | VarName[]} [customOutputs] Whether to allow for capturing the data
+ * for arbitrary variables at runtime (including variables that are not configured in the
+ * `outputVarNames` array).
+ *
+ * If undefined or false, the generated model will implement `storeOutput` as a no-op,
+ * meaning that the data for arbitrary variables cannot be captured at runtime.
+ *
+ * If true, all variables in the generated model will be available to be captured at
+ * runtime.
+ *
+ * If an array is provided, only those variable names in the array will be available to be
+ * captured at runtime.
+ *
+ * @property {DatFileSpec[]} [externalDatfiles] The `dat` files that provide the data for
+ * exogenous data variables in the model.
+ *
+ * DEPRECATED: Use `datFiles` instead.  This property is still honored (but is ignored if
+ * `datFiles` is also provided) and will be removed in a future release.
+ *
+ * @property {string} [name] An optional descriptive name for the model.
+ *
+ * This is not currently used by SDEverywhere, but is allowed (and is included in many
+ * existing `spec.json` files) as a way to document what the model is.
+ *
+ * @property {VarId[]} [inputVars] The input variable identifiers for the model, in
+ * canonical form.
+ *
+ * This is derived from `inputVarNames` while the model is being read, and is not intended
+ * to be set in a `spec.json` file.
+ *
+ * @property {VarId[]} [outputVars] The output variable identifiers for the model, in
+ * canonical form.
+ *
+ * This is derived from `outputVarNames` while the model is being read, and is not intended
+ * to be set in a `spec.json` file.
+ */
+
+// Note that this module only declares types (as JSDoc typedefs), so this empty export
+// is needed to make it a module (otherwise the typedefs would be declared globally).
+export {}

package/src/_shared/normalize-model-spec.js

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Climate Interactive / New Venture Fund
+
+/**
+ * Normalize the given model spec so that the rest of the compile package only needs
+ * to work with the preferred property names.
+ *
+ * Some `spec.json` properties have been renamed over time.  For each renamed property,
+ * this copies the value from the deprecated property to the preferred one, unless the
+ * preferred property is already defined (in which case the preferred one wins).  The
+ * deprecated properties are left in place so that the spec object is unchanged from
+ * the caller's point of view.
+ *
+ * Note that the given spec object is modified in place (and returned for convenience),
+ * which is consistent with how the spec object is treated elsewhere in this package.
+ * This function is idempotent, so it is safe to call it more than once on the same spec.
+ *
+ * @template {import('./model-spec.js').ModelSpec | undefined} T
+ * @param {T} spec The model spec to normalize, or undefined.
+ * @return {T} The same spec object that was provided.
+ */
+export function normalizeModelSpec(spec) {
+  if (spec === undefined) {
+    return spec
+  }
+
+  // The `externalDatfiles` property was renamed to `datFiles`
+  if (spec.datFiles === undefined && spec.externalDatfiles !== undefined) {
+    spec.datFiles = spec.externalDatfiles
+  }
+
+  return spec
+}

package/src/_shared/read-dat.js

@@ -5,14 +5,21 @@ import * as R from 'ramda'
 import B from './bufx.js'
 import { canonicalVensimName } from './helpers.js'
 
+/**
+ * The datasets read from external `dat` files, keyed by variable identifier.  Each
+ * dataset is a map of time to value.
+ *
+ * @typedef {Map<import('./model-spec.js').VarId, Map<number, number>>} ExtData
+ */
+
 /**
  * Read a Vensim `dat` file with static data and return a Map.
  * Each dataset consists of a key (the variable name in the canonical
  * format used by SDE) and a map of time/value pairs.
  *
- * @param pathname The absolute path to the dat file.
- * @param prefix An optional prefix string prepended to var names.
- * @return A Map containing the datasets.
+ * @param {string} pathname The absolute path to the dat file.
+ * @param {string} [prefix] An optional prefix string prepended to var names.
+ * @return {Promise<ExtData>} A promise that resolves with a Map containing the datasets.
  */
 export async function readDat(pathname, prefix = '') {
   let log = new Map()

package/src/generate/gen-code-c.js

@@ -1,12 +1,16 @@
 import * as R from 'ramda'
 
-import { asort, canonicalVensimName, lines, strlist, mapIndexed } from '../_shared/helpers.js'
+import { asort, canonicalVensimName, cdbl, lines, strlist, mapIndexed } from '../_shared/helpers.js'
 import { sub, allDimensions, allMappings, subscriptFamilies } from '../_shared/subscript.js'
 import Model from '../model/model.js'
 
 import { generateEquation } from './gen-equation.js'
 import { expandVarNames } from './expand-var-names.js'
 
+// The control variables are declared in `sde.h` and read by the support code in `model.c`,
+// so they always have to be emitted as mutable globals.
+const controlVarNames = new Set(['_final_time', '_initial_time', '_saveper', '_time_step'])
+
 export function generateC(parsedModel, opts) {
   return codeGenerator(parsedModel, opts).generate()
 }
@@ -17,6 +21,9 @@ let codeGenerator = (parsedModel, opts) => {
   let mode = ''
   // Set to true to output all variables when there is no model run spec.
   let outputAllVars = spec.outputVarNames === undefined || spec.outputVarNames.length === 0
+  // The constant variables that are emitted as C literals, keyed by variable name; see
+  // `resolveLiteralConstVars` below.
+  let literalConstVars = new Map()
   // Function to generate a section of the code
   let generateSection = R.map(v => {
     return generateEquation(v, mode, extData, directData, modelDirname, 'c')
@@ -37,6 +44,9 @@ let codeGenerator = (parsedModel, opts) => {
       // Do not generate output, but leave the results of model analysis.
     }
     if (operations.includes('generateC')) {
+      // Decide which constants can be emitted as C literals; this must happen before any
+      // code is generated, since it affects both the declaration and the init sections.
+      resolveLiteralConstVars()
       // Generate code for each variable in the proper order.
       let code = emitDeclCode()
       code += emitInitLookupsCode()
@@ -48,6 +58,130 @@ let codeGenerator = (parsedModel, opts) => {
     }
   }
 
+  //
+  // Constant folding
+  //
+
+  /**
+   * Determine which constant variables can be emitted as C literals (`static const double
+   * _x = 2.0;`) instead of as mutable globals that are assigned in `initConstants`.
+   *
+   * The point is to let the C compiler see the values.  When a constant is a mutable global,
+   * every use of it has to be compiled as a load of an unknown quantity; when it is a literal,
+   * the compiler can fold it into the expressions that use it.  The largest effect by far is
+   * that `pow(x, e)` calls where `e` is a named constant with a value like 2, 0.5, or 1 get
+   * strength-reduced into multiplies and `sqrt`.
+   *
+   * That strength reduction is also why this is opt-in: `x*x` and `sqrt(x)` are correctly
+   * rounded while `pow` is not, so results can change in the last few digits.  For En-ROADS
+   * the largest observed relative difference is ~1e-13 (and the new value is usually the more
+   * accurate one), but it is enough to change bit-exact regression baselines.  Set
+   * `SDE_NONPUBLIC_EMIT_CONST_LITERALS=1` to enable.
+   *
+   * Only unsubscripted constants with a plain numeric value qualify.  Input variables are
+   * excluded (they are assigned by `setInputs` on each run), as are constants that can be
+   * overridden with `setConstant`, the control variables (which are declared in `sde.h`), and
+   * constants that come from a `GET DIRECT CONSTANTS` call.
+   */
+  function resolveLiteralConstVars() {
+    literalConstVars = new Map()
+
+    if (process.env.SDE_NONPUBLIC_EMIT_CONST_LITERALS !== '1') {
+      // Skip this optimization if not explicitly enabled
+      return
+    }
+
+    if (spec.customConstants === true) {
+      // Any constant can be overridden at runtime, so none of them can be emitted as literals
+      return
+    }
+
+    let customConstantVarNames = []
+    if (Array.isArray(spec.customConstants)) {
+      // The developer might specify a variable name that includes subscripts, but we will
+      // ignore the subscript part and only match on the base name
+      customConstantVarNames = spec.customConstants.map(varName => canonicalVensimName(varName.split('[')[0]))
+    }
+
+    for (const v of Model.constVars()) {
+      if (v.subscripts.length > 0) {
+        // Skip subscripted constants.  Some Vensim functions (`ALLOCATE AVAILABLE`,
+        // `VECTOR SORT ORDER`, `INVERT MATRIX`, etc) take array arguments as `double*`, and a
+        // `static const double[]` cannot be passed to those.  Emitting a constant array as a
+        // literal would require tracking which arrays are passed by address, so for now we only
+        // handle the scalar case.
+        continue
+      }
+      if (controlVarNames.has(v.varName)) {
+        // Skip the control variables (`INITIAL TIME`, `FINAL TIME`, `TIME STEP`, and `SAVEPER`).
+        // These are declared as `extern` in `sde.h` and read by `model.c`, so they must remain
+        // mutable globals with external linkage.
+        continue
+      }
+      if (Model.isInputVar(v.varName)) {
+        // Skip input variables.  These are assigned by `setInputs` on every run, so their value
+        // is not fixed at compile time.
+        continue
+      }
+      if (customConstantVarNames.includes(v.varName)) {
+        // Skip constants that the developer declared as overridable with `setConstant`; like
+        // inputs, these can be assigned at runtime.
+        continue
+      }
+      if (v.directConstArgs) {
+        // Skip constants that get their value from a `GET DIRECT CONSTANTS` call.  Those values
+        // are read from an external data file at init time, so they are not known here.
+        continue
+      }
+      const rhs = v.parsedEqn?.rhs
+      if (rhs?.kind !== 'expr') {
+        // Skip constants that don't have a simple expression on the right-hand side
+        continue
+      }
+      const value = constNumberValue(rhs.expr)
+      if (value === undefined) {
+        // Skip constants whose right-hand side doesn't resolve to a number.  An arithmetic
+        // expression (even one over numbers only, like `2*3`) is emitted as generated code in
+        // `initConstants` rather than as a value we can write out here.
+        continue
+      }
+      literalConstVars.set(v.varName, cdbl(value))
+    }
+  }
+
+  /**
+   * Return the numeric value of the given expression, or undefined if it is not a number.
+   *
+   * This looks through parentheses and unary plus/minus operators, so an equation like
+   * `x = -(1.5)` resolves to -1.5.  These are the only expressions that are reduced here;
+   * folding arithmetic (`2*3` and the like) would mean computing the value in JavaScript
+   * instead of letting the C compiler do it, which we avoid.
+   *
+   * @param {*} expr The expression to evaluate.
+   * @returns {number | undefined} The numeric value of the expression, or undefined if the
+   * expression is not a (possibly negated) number.
+   */
+  function constNumberValue(expr) {
+    switch (expr?.kind) {
+      case 'number':
+        return expr.value
+      case 'parens':
+        return constNumberValue(expr.expr)
+      case 'unary-op': {
+        if (expr.op !== '-' && expr.op !== '+') {
+          return undefined
+        }
+        const childValue = constNumberValue(expr.expr)
+        if (childValue === undefined) {
+          return undefined
+        }
+        return expr.op === '-' ? -childValue : childValue
+      }
+      default:
+        return undefined
+    }
+  }
+
   // Each code section follows in an outline of the generated model code.
 
   //
@@ -56,7 +190,7 @@ let codeGenerator = (parsedModel, opts) => {
   function emitDeclCode() {
     mode = 'decl'
     return `#include "sde.h"
-
+${literalConstSection()}
 // Model variables
 ${declSection()}
 
@@ -112,12 +246,9 @@ bool data_initialized = false;
 
   function emitInitConstantsCode() {
     mode = 'init-constants'
-    return chunkedFunctions(
-      'initConstants',
-      Model.constVars(),
-      '  // Initialize constants.',
-      '  initLookups();\n  initData();'
-    )
+    // Skip the constants that are emitted as literals in the declaration section
+    const constVars = R.reject(v => literalConstVars.has(v.varName), Model.constVars())
+    return chunkedFunctions('initConstants', constVars, '  // Initialize constants.', '  initLookups();\n  initData();')
   }
 
   function emitInitLevelsCode() {
@@ -336,7 +467,20 @@ ${section(chunk)}
       asort,
       lines
     )
-    return decls(Model.allVars()) + fixedDelayDecls + depreciationDecls
+    // Skip the constants that are emitted as literals in `literalConstSection`
+    const vars = R.reject(v => literalConstVars.has(v.varName), Model.allVars())
+    return decls(vars) + fixedDelayDecls + depreciationDecls
+  }
+  function literalConstSection() {
+    // Emit a definition for each constant that is emitted as a C literal (see
+    // `resolveLiteralConstVars`).  Note that this includes the section heading and a
+    // leading blank line so that the whole section disappears when there are no such
+    // constants.
+    if (literalConstVars.size === 0) {
+      return ''
+    }
+    const defs = [...literalConstVars].map(([varName, value]) => `static const double ${varName} = ${value};`)
+    return `\n// Constants\n${lines(asort(defs))}\n`
   }
   function internalVarsSection() {
     // Declare internal variables to run the model.

package/src/generate/gen-code.js

@@ -4,23 +4,21 @@ import { generateJS } from './gen-code-js.js'
 /**
  * Generate code from the given parsed model.
  *
- * @param {*} parsedModel The parsed model structure.
+ * @param {import('../parse-and-generate.js').ParsedModel} parsedModel The parsed model structure.
  * @param {Object} opts The options that control code generation.
- * @param {Object} opts.spec The parsed `spec.json` object.
- * @param {string[]} opts.operations The array of operations to perform.
- * - If it has 'generateC', the generated C code will be written to `buildDir`.
- * - If it has 'generateJS', the generated JS code will be written to `buildDir`.
- * - If it has 'printRefIdTest', reference identifiers will be printed to the console.
- * - If it has 'convertNames', no output will be generated, but the results of model
- *   analysis will be available.
- * @param {Map<string, any>} opts.extData The map of datasets from external `.dat` files.
- * @param {Map<string, any>} opts.directData The mapping of dataset name used in a
+ * @param {import('../_shared/model-spec.js').ModelSpec} opts.spec The parsed `spec.json` object.
+ * @param {import('../parse-and-generate.js').GenerateOperation[]} opts.operations The array
+ * of operations to perform.
+ * @param {import('../_shared/read-dat.js').ExtData} [opts.extData] The map of datasets from
+ * external `.dat` files.
+ * @param {Map<string, any>} [opts.directData] The mapping of dataset name used in a
  * `GET DIRECT DATA` call (e.g., `?data`) to the tabular data contained in the loaded
  * data file.
- * @param {string} opts.modelDirname The absolute path to the directory containing data
+ * @param {string} [opts.modelDirname] The absolute path to the directory containing data
  * (dat, xlsx, csv) files that are referenced by the model.  This path is used for
  * resolving data files for `GET DIRECT SUBSCRIPT` calls.
- * @returns A string containing the generated code.
+ * @param {string} [opts.varname] The variable name passed to the `sde causes` command.
+ * @returns {string} A string containing the generated code.
  */
 export function generateCode(parsedModel, opts) {
   // Note that the two `generate` functions perform the same steps (other than the

package/src/generate/gen-expr.js

@@ -483,7 +483,7 @@ function generateLevelInit(callExpr, ctx) {
   const fnId = callExpr.fnId
 
   // Get the index of the argument holding the initial value expression
-  let initialArgIndex = 0
+  let initialArgIndex
   switch (fnId) {
     case '_ACTIVE_INITIAL':
     case '_INTEG':

package/src/index.js

@@ -1,14 +1,21 @@
 // Copyright (c) 2022 Climate Interactive / New Venture Fund
 
+//
+// Note that the types below are declared (as JSDoc typedefs) alongside the code that
+// defines and uses them.  We use `export *` here rather than re-declaring each typedef
+// so that the generated declarations refer to a single definition of each type.
+//
+export * from './_shared/model-spec.js'
+
 // XXX: For now we re-export the preprocess function from the parse package
 // mainly for use by the cli package (so that we don't need to have the cli
 // package directly depend on the parse package)
 export { preprocessVensimModel } from '@sdeverywhere/parse'
 
 export { canonicalName } from './_shared/helpers.js'
-export { readDat } from './_shared/read-dat.js'
+export * from './_shared/read-dat.js'
 export { generateCode } from './generate/gen-code.js'
-export { parseAndGenerate, parseModel, printNames } from './parse-and-generate.js'
+export * from './parse-and-generate.js'
 
 import { resetHelperState } from './_shared/helpers.js'
 import { resetSubscriptsAndDimensions } from './_shared/subscript.js'
@@ -29,8 +36,12 @@ export function resetState() {
 /**
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the Vensim model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
  */
-export function parseInlineVensimModel(mdlContent /*: string*/, modelDir /*?: string*/) /*: ParsedModel*/ {
+export function parseInlineVensimModel(mdlContent, modelDir) {
   // For tests that parse inline model text, in the case of the legacy parser, don't run
   // the preprocess step, and in the case of the new parser (which implicitly runs the
   // preprocess step), don't sort the definitions.  This makes it easier to do apples
@@ -41,8 +52,12 @@ export function parseInlineVensimModel(mdlContent /*: string*/, modelDir /*?: st
 /**
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the XMILE model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
  */
-export function parseInlineXmileModel(mdlContent /*: string*/, modelDir /*?: string*/) /*: ParsedModel*/ {
+export function parseInlineXmileModel(mdlContent, modelDir) {
   return parseModel(mdlContent, 'xmile', modelDir)
 }
 
@@ -50,6 +65,6 @@ export function parseInlineXmileModel(mdlContent /*: string*/, modelDir /*?: str
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
  */
-export function getModelListing() /*: string*/ {
+export function getModelListing() {
   return Model.jsonList()
 }

package/src/model/reduce-variables.js

@@ -49,14 +49,22 @@ export function reduceVariables(variables, inputVarIds, mode) {
       return
     }
 
-    // Add this variable to the set of active ones
-    // TODO: Allow cycle if the current LHS is referenced on the RHS
-    // const baseVarId = v.parsedEqn.lhs.varId
-    // if (baseVarId !== currentLhsBaseVarId) {
+    // Stop if this variable is already being reduced further up the call stack, which means
+    // it takes part in a dependency cycle.  This is normal and expected: every stock and flow
+    // feedback loop is a cycle (a level's rate refers to a variable that reads the level), and
+    // a variable that holds its own value from the previous time step (`SAMPLE IF TRUE`)
+    // refers to itself.  Leaving the variable unreduced here is safe.  The caller
+    // (`resolveVarRef`) only substitutes a referenced variable when its reduced RHS is a
+    // single number, and a variable that takes part in a cycle refers to at least one other
+    // variable, so its RHS can never be a single number.  The cycle simply stops the reduction
+    // from propagating any further along that path.  Note that a cycle that is a genuine error
+    // in the model (a simultaneous equation between two aux variables, say) is still reported:
+    // `sortVarsOfType` detects it during the dependency sort and reports the whole chain.
     if (activelyReducingRefIds.has(v.refId)) {
-      throw new Error(`Cycle detected when reducing variables: ${v.refId}`)
+      return
     }
-    // }
+
+    // Add this variable to the set of active ones
     activelyReducingRefIds.add(v.refId)
 
     // We currently have two options for reducing variables.  The less aggressive

package/src/parse-and-generate.js

@@ -6,6 +6,7 @@ import { parseVensimModel, parseXmileModel } from '@sdeverywhere/parse'
 
 import B from './_shared/bufx.js'
 import { readXlsx } from './_shared/helpers.js'
+import { normalizeModelSpec } from './_shared/normalize-model-spec.js'
 import { readDat } from './_shared/read-dat.js'
 import { printSubscripts } from './_shared/subscript.js'
 import { cName } from './_shared/var-names.js'
@@ -13,6 +14,34 @@ import Model from './model/model.js'
 import { getDirectSubscripts } from './model/read-subscripts.js'
 import { generateCode } from './generate/gen-code.js'
 
+/**
+ * The kind of model that is being parsed.
+ *
+ * @typedef {'vensim' | 'xmile'} ModelKind
+ */
+
+/**
+ * A parsed tree representation of a model, along with the kind of model that was parsed.
+ *
+ * @typedef {Object} ParsedModel
+ * @property {ModelKind} kind The kind of model that was parsed.
+ * @property {import('@sdeverywhere/parse').Model} root The root of the parsed model AST.
+ */
+
+/**
+ * An operation that can be performed by `parseAndGenerate`.
+ *
+ * - `generateC` writes the generated C code to the build directory.
+ * - `generateJS` writes the generated JS code to the build directory.
+ * - `printVarList` writes variables and subscripts to txt and json files under the build
+ *   directory.
+ * - `printRefIdTest` prints reference identifiers to the console.
+ * - `printRefGraph` prints the variable dependency graph to the console.
+ * - `convertNames` generates no output, but makes the results of model analysis available.
+ *
+ * @typedef {'generateC' | 'generateJS' | 'printVarList' | 'printRefIdTest' | 'printRefGraph' | 'convertNames'} GenerateOperation
+ */
+
 /**
  * Parse a Vensim or XMILE model and generate C code.
  *
@@ -27,27 +56,30 @@ import { generateCode } from './generate/gen-code.js'
  *   analysis will be available.
  *
  * @param {string} input The preprocessed Vensim or XMILE model text.
- * @param {string} modelKind The kind of model to parse, either 'vensim' or 'xmile'.
- * @param {*} spec The model spec (from the JSON file).
- * @param {string[]} operations The set of operations to perform; can include 'generateC', 'generateJS',
- * 'printVarList', 'printRefIdTest', 'convertNames'.  If the array is empty, the model will be
- * read but no operation will be performed.
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {import('./_shared/model-spec.js').ModelSpec} spec The model spec (from the JSON file).
+ * @param {GenerateOperation[]} operations The set of operations to perform.  If the array is
+ * empty, the model will be read but no operation will be performed.
  * @param {string} modelDirname The absolute path to the directory containing data (dat, xlsx, csv)
  * files that are referenced by the model.  These files will be resolved relative to this directory.
  * @param {string} modelName The model name (without the mdl extension).
  * @param {string} buildDir The output directory where the C or list files will be written.
  * @param {string} [varname] The variable name passed to the 'sde causes' command.
- * @return A string containing the generated C code.
+ * @return {Promise<string>} A promise that resolves with the generated C or JS code.
  */
 export async function parseAndGenerate(input, modelKind, spec, operations, modelDirname, modelName, buildDir, varname) {
+  // Resolve any deprecated property names in the spec so that we only need to
+  // consult the preferred names below
+  normalizeModelSpec(spec)
+
   // Read time series from external DAT files into a single object.
-  // externalDatfiles is an array of either filenames or objects
-  // giving a variable name prefix as the key and a filename as the value.
+  // `datFiles` is an array of either filenames or objects giving a variable
+  // name prefix as the key and a filename as the value.
   let extData = new Map()
-  if (spec.externalDatfiles) {
-    for (let datfile of spec.externalDatfiles) {
+  if (spec.datFiles) {
+    for (let datfile of spec.datFiles) {
       let prefix = ''
-      let filename = ''
+      let filename
       if (typeof datfile === 'object') {
         prefix = Object.keys(datfile)[0]
         filename = datfile[prefix]
@@ -110,8 +142,9 @@ export async function parseAndGenerate(input, modelKind, spec, operations, model
  *
  * This is used only to implement the `sde names` command.
  *
- * @param namesPathname The path to the file containing variables names.
- * @param operation Either 'to-c' or 'to-vensim'.
+ * @param {string} namesPathname The path to the file containing variables names.
+ * @param {'to-c' | 'to-vensim'} operation The conversion to perform.
+ * @return {void}
  */
 export function printNames(namesPathname, operation) {
   let lines = B.lines(B.read(namesPathname))
@@ -130,15 +163,13 @@ export function printNames(namesPathname, operation) {
 /**
  * Read and parse the given model text and return the parsed model structure.
  *
- * TODO: Fix return type
- *
  * @param {string} input The string containing the model text.
- * @param {string} modelKind The kind of model to parse, either 'vensim' or 'xmile'.
- * @param {string} modelDir The absolute path to the directory containing data (dat, xlsx, csv)
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {string} [modelDir] The absolute path to the directory containing data (dat, xlsx, csv)
  * files that are referenced by the model.  These files will be resolved relative to this directory.
  * @param {Object} [options] The options that control parsing.
- * @param {boolean} options.sort Whether to sort definitions alphabetically in the preprocess step.
- * @return {*} A parsed tree representation of the model.
+ * @param {boolean} [options.sort] Whether to sort definitions alphabetically in the preprocess step.
+ * @return {ParsedModel} A parsed tree representation of the model.
  */
 export function parseModel(input, modelKind, modelDir, options) {
   if (modelKind === 'vensim') {