@sdeverywhere/compile 0.7.31 → 0.7.32

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@sdeverywhere/compile",
-  "version": "0.7.31",
+  "version": "0.7.32",
   "description": "The core Vensim to C compiler for the SDEverywhere tool suite.",
   "type": "module",
   "main": "./src/index.js",
   "dependencies": {
-    "@sdeverywhere/parse": "^0.1.4",
+    "@sdeverywhere/parse": "^0.1.5",
     "byline": "^5.0.0",
     "csv-parse": "^5.3.3",
     "fflate": "^0.8.3",

package/src/_shared/xlsx.js

@@ -278,10 +278,22 @@ function getAttr(attrs, name) {
   return end < 0 ? undefined : attrs.slice(start, end)
 }
 
+/**
+ * Normalize line endings the way a conformant XML parser (and SheetJS) does:
+ * `\r\n` and lone `\r` both become `\n`. Applied after entity decoding so a
+ * CR encoded as `&#13;` is normalized too.
+ *
+ * @param {string} s The text to normalize.
+ * @returns The normalized string.
+ */
+function normalizeEol(s) {
+  return s.indexOf('\r') === -1 ? s : s.replace(/\r\n?/g, '\n')
+}
+
 /**
  * Decode the standard XML entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`,
  * `&apos;`) along with numeric character references (`&#NN;` and `&#xNN;`)
- * in the given text. Returns the input unchanged when no entities are present.
+ * in the given text, and normalize line endings to `\n`.
  *
  * @param {string} s The raw text from an XML element body or attribute.
  * @returns The decoded string.
@@ -289,20 +301,22 @@ function getAttr(attrs, name) {
 function decodeXmlText(s) {
   // Fast path: most cell text contains no entities, so skip the regex chain
   if (s.indexOf('&') === -1) {
-    return s
+    return normalizeEol(s)
   }
 
   // Decode the named entities, then decimal and hex numeric refs, and finally
   // `&amp;` — leaving `&amp;` last avoids accidentally producing `&lt;` etc.
   // from a literal `&amp;lt;` in the source
-  return s
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)))
-    .replace(/&amp;/g, '&')
+  return normalizeEol(
+    s
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
+      .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)))
+      .replace(/&amp;/g, '&')
+  )
 }
 
 //
@@ -392,6 +406,19 @@ function parseWorkbookRels(xml) {
   return rels
 }
 
+/**
+ * Extract the text content of the `<v>` element in a cell body, tolerating
+ * attributes on the tag (e.g. `<v xml:space="preserve">`). Returns undefined
+ * when there is no `<v>` element (e.g. an uncalculated formula cell).
+ *
+ * @param {string} body The inner XML of a `<c>` element.
+ * @returns The raw text between `<v...>` and `</v>`, or undefined.
+ */
+function getVText(body) {
+  const m = /<v\b[^>]*>([\s\S]*?)<\/v>/.exec(body)
+  return m ? m[1] : undefined
+}
+
 /**
  * Scan a worksheet's XML and build a sparse cell map shaped like the SheetJS
  * worksheet object: `{ [cellRef]: { v }, '!ref': 'A1:Z99' }`. Skips empty
@@ -429,16 +456,7 @@ function parseSheetXml(xml, sharedStrings) {
     const t = getAttr(attrs, 't')
 
     let value
-    if (t === 's') {
-      // Shared string: <v>N</v> where N indexes sharedStrings
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      const idx = parseInt(body.slice(vStart + 3, vEnd), 10)
-      value = sharedStrings[idx]
-    } else if (t === 'inlineStr') {
+    if (t === 'inlineStr') {
       // Inline string: <is><t>...</t></is>
       const tStart = body.indexOf('<t')
       if (tStart < 0) {
@@ -447,38 +465,35 @@ function parseSheetXml(xml, sharedStrings) {
       const tOpenEnd = body.indexOf('>', tStart)
       const tEnd = body.indexOf('</t>', tOpenEnd)
       value = decodeXmlText(body.slice(tOpenEnd + 1, tEnd))
-    } else if (t === 'str') {
-      // Formula result as string: <v>...</v>
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      value = decodeXmlText(body.slice(vStart + 3, vEnd))
-    } else if (t === 'b') {
-      // Boolean: <v>0</v> or <v>1</v>
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      value = body.charCodeAt(vStart + 3) === 49 // '1'
     } else if (t === 'e') {
       // Error cell, skip
       continue
     } else {
-      // Numeric (t === 'n' or absent). Skip any <f> formula tag and read the
-      // cached <v> value. If <v> is missing (e.g. an uncalculated formula),
-      // skip the cell so the caller's missing-cell handling kicks in.
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
+      // The remaining cell types carry their value in a <v> element, which
+      // may have attributes (e.g. <v xml:space="preserve">). If <v> is
+      // missing (e.g. an uncalculated formula), skip the cell so the
+      // caller's missing-cell handling kicks in.
+      const vText = getVText(body)
+      if (vText === undefined) {
         continue
       }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      const num = +body.slice(vStart + 3, vEnd)
-      if (Number.isNaN(num)) {
-        continue
+      if (t === 's') {
+        // Shared string: <v>N</v> where N indexes sharedStrings
+        value = sharedStrings[parseInt(vText, 10)]
+      } else if (t === 'str') {
+        // Formula result as string: <v>...</v>
+        value = decodeXmlText(vText)
+      } else if (t === 'b') {
+        // Boolean: <v>0</v> or <v>1</v>
+        value = vText.charCodeAt(0) === 49 // '1'
+      } else {
+        // Numeric (t === 'n' or absent)
+        const num = +vText
+        if (Number.isNaN(num)) {
+          continue
+        }
+        value = num
       }
-      value = num
     }
 
     // Store the cell under its A1 ref, matching the SheetJS sheet shape

package/src/generate/gen-equation.js

@@ -128,6 +128,9 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
     }
   }
 
+  // Keep a buffer of code that will be included before all subscript loops
+  const preLoopLines = []
+
   // Keep a buffer of code that will be included before the innermost loop
   const preInnerLoopLines = []
 
@@ -145,6 +148,7 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
     cLhs,
     loopIndexVars,
     arrayIndexVars,
+    emitPreLoop: s => preLoopLines.push(s),
     emitPreInnerLoop: s => preInnerLoopLines.push(s),
     emitPreFormula: s => preFormulaLines.push(s),
     emitPostFormula: s => postFormulaLines.push(s),
@@ -161,7 +165,7 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
   }
 
   // Combine all lines of comments and code into a single array
-  return [comment, ...openLoops, ...preFormulaLines, formula, ...postFormulaLines, ...closeLoops]
+  return [comment, ...preLoopLines, ...openLoops, ...preFormulaLines, formula, ...postFormulaLines, ...closeLoops]
 }
 
 /**

package/src/generate/gen-expr.js

@@ -369,6 +369,9 @@ function generateFunctionCall(callExpr, ctx) {
     //
     //
 
+    case '_INVERT_MATRIX':
+      return generateInvertMatrixCall(callExpr, ctx)
+
     case '_VECTOR_ELM_MAP':
       return generateVectorElmMapCall(callExpr, ctx)
 
@@ -382,10 +385,18 @@ function generateFunctionCall(callExpr, ctx) {
     //
 
     case '_ALLOCATE_AVAILABLE':
+    case '_DEMAND_AT_PRICE':
+    case '_SUPPLY_AT_PRICE':
       if (ctx.outFormat === 'js') {
         throw new Error(`${callExpr.fnName} function not yet implemented for JS code gen`)
       }
-      return generateAllocateAvailableCall(callExpr, ctx)
+      return generateAllocationFunctionCall(callExpr, ctx)
+
+    case '_FIND_MARKET_PRICE':
+      if (ctx.outFormat === 'js') {
+        throw new Error(`FIND MARKET PRICE function not yet implemented for JS code gen`)
+      }
+      return generateFindMarketPriceFunctionCall(callExpr, ctx)
 
     case '_ALLOCATE_BY_PRIORITY':
       if (ctx.outFormat === 'js') {
@@ -875,19 +886,89 @@ function generateVectorSortOrderCall(callExpr, ctx) {
 }
 
 /**
- * Generate C/JS code for an `ALLOCATE AVAILABLE` function call.
+ * Generate C/JS code for an `INVERT MATRIX` function call.
+ *
+ * The function inverts the entire 2D matrix argument at once, so the call is emitted
+ * once before the LHS subscript loops are opened, and the per-element expression reads
+ * from the resulting temporary.
  *
  * @param {*} callExpr The function call expression from the parsed model.
  * @param {GenExprContext} ctx The context used when generating code for the expression.
  * @return {string} The generated C/JS code.
  */
-function generateAllocateAvailableCall(callExpr, ctx) {
+function generateInvertMatrixCall(callExpr, ctx) {
+  // Process the matrix argument
+  const matrixArg = callExpr.args[0]
+  if (matrixArg.kind !== 'variable-ref') {
+    throw new Error(`INVERT MATRIX argument 'matrix' must be a variable reference`)
+  }
+  const matrixSubIds = matrixArg.subscriptRefs?.map(subRef => subRef.subId) || []
+  if (matrixSubIds.length !== 2) {
+    throw new Error(`INVERT MATRIX argument 'matrix' must be a 2D matrix variable`)
+  }
+
+  // The result fills the entire LHS variable, so the LHS must be a square 2D matrix
+  const lhsSubIds = ctx.variable.subscripts
+  if (lhsSubIds.length !== 2) {
+    throw new Error(`The LHS of an equation with INVERT MATRIX must have two dimensions`)
+  }
+  const rowDimId = lhsSubIds[0]
+  const colDimId = lhsSubIds[1]
+  const matrixSize = sub(colDimId).size
+  if (sub(rowDimId).size !== matrixSize) {
+    throw new Error(`The LHS of an equation with INVERT MATRIX must be a square matrix`)
+  }
+
+  // Process the size argument.  When it resolves to a constant at code gen time (e.g., a
+  // numeric literal or an `ELMCOUNT` call), verify that it matches the LHS dimension size,
+  // since the generated code always inverts the full LHS-sized matrix.
+  const nArg = generateExpr(callExpr.args[1], ctx)
+  const staticN = Number.parseFloat(nArg)
+  if (!Number.isNaN(staticN) && staticN !== matrixSize) {
+    throw new Error(
+      `The size argument for INVERT MATRIX (${staticN}) must match the LHS dimension size (${matrixSize})`
+    )
+  }
+
+  // Generate the code that is emitted before the entire block (before any loops are opened)
+  const tmpVarId = newTmpVarName()
+  switch (ctx.outFormat) {
+    case 'c':
+      ctx.emitPreLoop(`  double* ${tmpVarId} = _INVERT_MATRIX((double*)${matrixArg.varId}, ${matrixSize});`)
+      break
+    case 'js':
+      ctx.emitPreLoop(`  let ${tmpVarId} = fns.INVERT_MATRIX(${matrixArg.varId}, ${matrixSize});`)
+      break
+    default:
+      throw new Error(`Unhandled output format '${ctx.outFormat}'`)
+  }
+
+  // Generate the RHS expression used in the inner loop.  The C runtime function returns
+  // a flat array in row-major order, while the JS one returns a nested array.
+  const rowIndexVar = ctx.loopIndexVars.index(rowDimId)
+  const colIndexVar = ctx.loopIndexVars.index(colDimId)
+  if (ctx.outFormat === 'c') {
+    return `${tmpVarId}[${rowIndexVar} * ${matrixSize} + ${colIndexVar}]`
+  } else {
+    return `${tmpVarId}[${rowIndexVar}][${colIndexVar}]`
+  }
+}
+
+/**
+ * Generate C/JS code for an allocation function call.
+ * This includes `_ALLOCATE_AVAILABLE`, `_DEMAND_AT_PRICE`, and `_SUPPLY_AT_PRICE`.
+ *
+ * @param {*} callExpr The function call expression from the parsed model.
+ * @param {GenExprContext} ctx The context used when generating code for the expression.
+ * @return {string} The generated C/JS code.
+ */
+function generateAllocationFunctionCall(callExpr, ctx) {
   function validateArg(index, name) {
     const arg = callExpr.args[index]
     if (arg.kind === 'variable-ref') {
       return arg
     } else {
-      throw new Error(`ALLOCATE AVAILABLE argument '${name}' must be a variable reference`)
+      throw new Error(`${callExpr.fnName} argument '${name}' must be a variable reference`)
     }
   }
 
@@ -896,8 +977,9 @@ function generateAllocateAvailableCall(callExpr, ctx) {
   function cVarRefWithoutLastIndices(arg, count) {
     const varRef = ctx.cVarRef(arg)
     const origIndexParts = Model.splitRefId(varRef).subscripts
-    if (origIndexParts < count) {
-      throw new Error(`ALLOCATE AVAILABLE argument '${arg}' should have at least ${count} subscripts`)
+    if (origIndexParts.length < count) {
+      const plural = count === 1 ? '' : 's'
+      throw new Error(`${callExpr.fnName} argument '${arg.varName}' should have at least ${count} subscript${plural}`)
     }
     const newIndexParts = origIndexParts.slice(0, -count)
     if (newIndexParts.length > 0) {
@@ -918,11 +1000,10 @@ function generateAllocateAvailableCall(callExpr, ctx) {
   const ppArg = validateArg(1, 'pp')
   const ppRef = cVarRefWithoutLastIndices(ppArg, 2)
 
-  // Process the avail argument; include any subscripts
-  const availArg = validateArg(2, 'avail')
-  const availRef = ctx.cVarRef(availArg)
+  // Process the avail argument; include any subscripts. The avail arg can be any expression.
+  const availArg = generateExpr(callExpr.args[2], ctx)
 
-  // The `ALLOCATE AVAILABLE` function iterates over the last subscript in its first arg.
+  // Allocation functions iterate over the last subscript in its first arg.
   // The `readEquation` process will have already verified that the last dimension matches
   // the last dimension for the LHS.
   const allocDimId = reqArg.subscriptRefs[reqArg.subscriptRefs.length - 1].subId
@@ -934,13 +1015,14 @@ function generateAllocateAvailableCall(callExpr, ctx) {
   switch (ctx.outFormat) {
     case 'c':
       ctx.emitPreInnerLoop(
-        `  double* ${tmpVarId} = _ALLOCATE_AVAILABLE(${reqRef}, (double*)${ppRef}, ${availRef}, ${numRequesters});`
+        `  double* ${tmpVarId} = ${callExpr.fnId}(${reqRef}, (double*)${ppRef}, ${availArg}, ${numRequesters});`
       )
       break
     case 'js':
-      ctx.emitPreInnerLoop(
-        `  let ${tmpVarId} = fns.ALLOCATE_AVAILABLE(${reqRef}, ${ppRef}, ${availRef}, ${numRequesters});`
-      )
+      // TODO: Implement allocation functions for JS
+      // ctx.emitPreInnerLoop(
+      //   `  let ${tmpVarId} = ${fnRef(callExpr.fnId, ctx)}(${reqRef}, ${ppRef}, ${availArg}, ${numRequesters});`
+      // )
       break
     default:
       throw new Error(`Unhandled output format '${ctx.outFormat}'`)
@@ -972,8 +1054,9 @@ function generateAllocateByPriorityCall(callExpr, ctx) {
   function cVarRefWithoutLastIndices(arg, count) {
     const varRef = ctx.cVarRef(arg)
     const origIndexParts = Model.splitRefId(varRef).subscripts
-    if (origIndexParts < count) {
-      throw new Error(`ALLOCATE BY PRIORITY argument '${arg}' should have at least ${count} subscripts`)
+    if (origIndexParts.length < count) {
+      const plural = count === 1 ? '' : 's'
+      throw new Error(`ALLOCATE BY PRIORITY argument '${arg.varName}' should have at least ${count} subscript${plural}`)
     }
     const newIndexParts = origIndexParts.slice(0, -count)
     if (newIndexParts.length > 0) {
@@ -1032,6 +1115,77 @@ function generateAllocateByPriorityCall(callExpr, ctx) {
   return `${tmpVarId}[${allocDimId}[${allocLoopIndexVar}]]`
 }
 
+/**
+ * Generate C/JS code for a `FIND MARKET PRICE` function call.
+ *
+ * @param {*} callExpr The function call expression from the parsed model.
+ * @param {GenExprContext} ctx The context used when generating code for the expression.
+ * @return {string} The generated C/JS code.
+ */
+function generateFindMarketPriceFunctionCall(callExpr, ctx) {
+  function validateArg(index, name) {
+    const arg = callExpr.args[index]
+    if (arg.kind === 'variable-ref') {
+      return arg
+    } else {
+      throw new Error(`${callExpr.fnName} argument '${name}' must be a variable reference`)
+    }
+  }
+
+  // Given a C/JS variable reference string (e.g., '_var[i][j]'), return that
+  // string without the last N array index parts
+  function cVarRefWithoutLastIndices(arg, count) {
+    const varRef = ctx.cVarRef(arg)
+    const origIndexParts = Model.splitRefId(varRef).subscripts
+    if (origIndexParts.length < count) {
+      throw new Error(`${callExpr.fnName} argument '${arg}' should have at least ${count} subscripts`)
+    }
+    const newIndexParts = origIndexParts.slice(0, -count)
+    if (newIndexParts.length > 0) {
+      return `${arg.varId}${newIndexParts.map(x => `[${x}]`).join('')}`
+    } else {
+      return arg.varId
+    }
+  }
+
+  // Process the demand quantities argument.  Only include subscripts up until the last one;
+  // the implementation function will iterate over the demand quantities array.
+  const demandQtysArg = validateArg(0, 'demandQtys')
+  const demandQtysRef = cVarRefWithoutLastIndices(demandQtysArg, 1)
+
+  // Process the demand profiles argument.  Only include subscripts up until the
+  // second to last one; the implementation function will iterate over the priority
+  // profile array.
+  const demandProfilesArg = validateArg(1, 'demandProfiles')
+  const demandProfilesRef = cVarRefWithoutLastIndices(demandProfilesArg, 2)
+
+  // The `FIND MARKET PRICE` implementation sums total demand over all demanders.
+  // When the subscript is an individual index (the Vensim convention of passing the
+  // first element of the array), the count is the size of the index's family dimension;
+  // when it is a dimension (possibly a subdimension), the count is that dimension's size.
+  const demandSubId = demandQtysArg.subscriptRefs[demandQtysArg.subscriptRefs.length - 1].subId
+  const numDemanders = isIndex(demandSubId) ? sub(sub(demandSubId).family).size : sub(demandSubId).size
+
+  // Process the supply quantities argument.  Only include subscripts up until the last one;
+  // the implementation function will iterate over the supply quantities array.
+  const supplyQtysArg = validateArg(2, 'supplyQtys')
+  const supplyQtysRef = cVarRefWithoutLastIndices(supplyQtysArg, 1)
+
+  // Process the supply profiles argument.  Only include subscripts up until the
+  // second to last one; the implementation function will iterate over the priority
+  // profile array.
+  const supplyProfilesArg = validateArg(3, 'supplyProfiles')
+  const supplyProfilesRef = cVarRefWithoutLastIndices(supplyProfilesArg, 2)
+
+  // The `FIND MARKET PRICE` implementation sums total supply over all suppliers.
+  // The count is determined the same way as for demanders above.
+  const supplySubId = supplyQtysArg.subscriptRefs[supplyQtysArg.subscriptRefs.length - 1].subId
+  const numSuppliers = isIndex(supplySubId) ? sub(sub(supplySubId).family).size : sub(supplySubId).size
+
+  // Generate the RHS expression
+  return `_FIND_MARKET_PRICE(${demandQtysRef}, (double*)${demandProfilesRef}, ${supplyQtysRef}, (double*)${supplyProfilesRef}, ${numDemanders}, ${numSuppliers})`
+}
+
 /**
  * Recursively traverse the given expression and call the function when visiting a variable ref.
  *

package/src/model/analyze-cycles.js

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Climate Interactive / New Venture Fund
+
+import { isDimension, isIndex, sub } from '../_shared/subscript.js'
+
+import Model from './model.js'
+
+/**
+ * Analyze the dependency cycle clusters reported by toposort and find variables that
+ * could be separated into individual index instances to break the cycles.  A false
+ * cycle can appear when a variable keeps a dimension for which the variables it
+ * references are defined (or separated) element by element.  The whole-array variable
+ * then depends on all elements of its references, merging the otherwise independent
+ * dependency chains of each element into a single node.  Separating the variable on
+ * that dimension restores the element-level dependency structure that Vensim uses
+ * when it orders equations.
+ *
+ * Each cycle cluster is a strongly connected component of the dependency graph.
+ * For each variable v in a cluster, propose separating v on a dimension D when a
+ * successor of v in the cluster carries an individual index in the family of D and
+ * a predecessor of v in the cluster references v by an individual element of D
+ * (so that the separation actually removes the edge into the other elements of v).
+ * If no candidate satisfies the predecessor condition, fall back to the candidates
+ * that satisfy the successor condition alone.
+ *
+ * @param {Array} cycles The cycle clusters (strongly connected components), where each
+ * cluster is an array of the ref IDs of the variables that it contains.
+ * @param {Map} outgoingEdges A map of each ref ID to the set of ref IDs that it depends on.
+ * @returns {Map} A map from variable name to the set of dimension IDs to separate on.
+ */
+export function separationCandidatesForCycles(cycles, outgoingEdges) {
+  const candidates = new Map()
+  const looseCandidates = new Map()
+  const addCandidate = (map, varName, dimId) => {
+    let dimIds = map.get(varName)
+    if (!dimIds) {
+      dimIds = new Set()
+      map.set(varName, dimIds)
+    }
+    dimIds.add(dimId)
+  }
+  // The set of (variable name, family) pairs accepted as candidates so far; a variable
+  // that will be separated on a family satisfies the predecessor condition for the
+  // variables it references, so acceptance is iterated to a fixpoint below
+  const acceptedFamilies = new Set()
+  for (const scc of cycles) {
+    const inScc = new Set(scc)
+    // Build a predecessor map for the nodes in this cluster
+    const predsOf = new Map(scc.map(refId => [refId, []]))
+    for (const refId of scc) {
+      for (const succ of outgoingEdges.get(refId) || []) {
+        if (inScc.has(succ)) {
+          predsOf.get(succ).push(refId)
+        }
+      }
+    }
+    // Collect the possible (v, D) pairs for this cluster
+    const sccLooseCandidates = []
+    for (const refId of scc) {
+      const v = Model.varWithRefId(refId)
+      if (!v || !v.subscripts || v.subscripts.length === 0) {
+        continue
+      }
+      // Find the families of the individual indices carried by the successors
+      // of this node within the cluster
+      const succIndexFamilies = new Set()
+      for (const succ of outgoingEdges.get(refId) || []) {
+        if (inScc.has(succ)) {
+          for (const subId of Model.splitRefId(succ).subscripts) {
+            if (isIndex(subId)) {
+              succIndexFamilies.add(sub(subId).family)
+            }
+          }
+        }
+      }
+      for (const subId of v.subscripts) {
+        if (isDimension(subId) && succIndexFamilies.has(sub(subId).family)) {
+          // Skip the candidate when every predecessor references this variable
+          // exclusively through a marked full dimension (e.g., `SUM(x[DimA!])`):
+          // such references span all elements regardless of separation, so
+          // separating this variable can never narrow the incoming edges
+          const familyId = sub(subId).family
+          const possiblyNarrowing = predsOf.get(refId).some(predRefId => {
+            const pv = Model.varWithRefId(predRefId)
+            if (!pv) {
+              return false
+            }
+            const refKinds = elementRefKinds(pv, v.varName, familyId)
+            return refKinds.elementRef || refKinds.fullDimRef || !refKinds.markedFullDimRef
+          })
+          if (possiblyNarrowing) {
+            sccLooseCandidates.push({ refId, v, dimId: subId })
+          }
+        }
+      }
+    }
+    // Accept the candidates that satisfy the predecessor condition, iterating to a
+    // fixpoint since accepting one variable can qualify the variables it references
+    const sccAccepted = new Set()
+    let changed
+    do {
+      changed = false
+      for (const c of sccLooseCandidates) {
+        if (sccAccepted.has(c)) {
+          continue
+        }
+        const familyId = sub(c.dimId).family
+        const predQualifies = predRefId => {
+          const pv = Model.varWithRefId(predRefId)
+          if (!pv) {
+            return false
+          }
+          const refKinds = elementRefKinds(pv, c.v.varName, familyId)
+          if (refKinds.markedFullDimRef) {
+            // The predecessor operates on all elements in the family (e.g., in a
+            // `SUM` expression), so separating this variable does not narrow the edge
+            return false
+          }
+          if (refKinds.elementRef) {
+            // The predecessor references this variable by an individual element
+            // (or through a subdimension, which Vensim maps element by element)
+            return true
+          }
+          if (refKinds.fullDimRef) {
+            // The predecessor references this variable through the full dimension;
+            // that reference narrows to an element when the predecessor itself is
+            // (or will be) separated on the same family
+            if (pv.subscripts?.some(s => isIndex(s) && sub(s).family === familyId)) {
+              return true
+            }
+            return acceptedFamilies.has(`${pv.varName}|${familyId}`)
+          }
+          return false
+        }
+        if (predsOf.get(c.refId).some(predQualifies)) {
+          sccAccepted.add(c)
+          acceptedFamilies.add(`${c.v.varName}|${familyId}`)
+          addCandidate(candidates, c.v.varName, c.dimId)
+          changed = true
+        }
+      }
+    } while (changed)
+    if (sccAccepted.size === 0) {
+      // No candidate in this cluster satisfied the predecessor condition, so fall
+      // back to the candidates that satisfied the successor condition alone
+      for (const c of sccLooseCandidates) {
+        addCandidate(looseCandidates, c.v.varName, c.dimId)
+      }
+    }
+  }
+  if (candidates.size > 0) {
+    return candidates
+  }
+  return looseCandidates
+}
+
+/**
+ * Examine how the given variable's parsed equation references the named variable
+ * in subscript positions of the given family.
+ *
+ * @param {*} referencingVar The `Variable` instance whose equation is examined.
+ * @param {string} varName The name (in canonical form) of the referenced variable.
+ * @param {string} familyId The ID of the subscript family of interest.
+ * @returns {object} An object with three flags:
+ * - `elementRef` is set when a reference uses an individual index or a subdimension
+ *   (Vensim maps subdimension references element by element, as in the common
+ *   `x[current pass] = f(x[preceeding pass])` iteration idiom)
+ * - `fullDimRef` is set when a reference uses the full dimension for the family
+ * - `markedFullDimRef` is set when a reference uses the full dimension marked for
+ *   vector operations (e.g., `SUM(x[DimA!])`), which always spans all elements
+ */
+function elementRefKinds(referencingVar, varName, familyId) {
+  const kinds = { elementRef: false, fullDimRef: false, markedFullDimRef: false }
+  const visit = node => {
+    if (node === null || typeof node !== 'object') {
+      return
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit)
+      return
+    }
+    if (node.kind === 'variable-ref' && node.varId === varName && node.subscriptRefs) {
+      for (const subRef of node.subscriptRefs) {
+        // Remove the mark from a marked dimension (e.g., `_dima!`)
+        const marked = subRef.subId.includes('!')
+        const subId = subRef.subId.replace('!', '')
+        const s = sub(subId)
+        if (s?.family !== familyId) {
+          continue
+        }
+        if (isIndex(subId) || s.size < sub(familyId).size) {
+          kinds.elementRef = true
+        } else if (marked) {
+          kinds.markedFullDimRef = true
+        } else {
+          kinds.fullDimRef = true
+        }
+      }
+    }
+    for (const key of Object.keys(node)) {
+      visit(node[key])
+    }
+  }
+  const eqn = referencingVar.parsedEqn
+  if (eqn?.rhs?.kind === 'expr') {
+    visit(eqn.rhs.expr)
+  }
+  return kinds
+}

package/src/model/model.js

@@ -3,7 +3,7 @@ import * as R from 'ramda'
 import { canonicalVarId, toPrettyString } from '@sdeverywhere/parse'
 
 import B from '../_shared/bufx.js'
-import { decanonicalize, isIterable, strlist, vlog, vsort } from '../_shared/helpers.js'
+import { decanonicalize, isIterable, resetHelperState, strlist, vlog, vsort } from '../_shared/helpers.js'
 import {
   addIndex,
   allAliases,
@@ -11,11 +11,13 @@ import {
   indexNamesForSubscript,
   isDimension,
   isIndex,
+  resetSubscriptsAndDimensions,
   sub,
   subscriptFamilies
 } from '../_shared/subscript.js'
 import { cName } from '../_shared/var-names.js'
 
+import { separationCandidatesForCycles } from './analyze-cycles.js'
 import { expandVar } from './expand-var-instances.js'
 import { readEquation, resolveXmileDimensionWildcards } from './read-equations.js'
 import { readDimensionDefs } from './read-subscripts.js'
@@ -60,6 +62,12 @@ function resetModelState() {
  * Note that this function currently does not return anything and instead stores the parsed subscript
  * definitions in the `subscript` module and the parsed/analyzed variables in this module.
  *
+ * After a full read, the variables are sorted in dependency order (and the sorted lists are cached
+ * for later use by code generation and variable listings).  A false cyclic dependency detected
+ * during sorting (one that Vensim's element-by-element evaluation order would not produce) is
+ * repaired by separating the variables identified by the cycle analysis and re-reading the model,
+ * as if those variables had been listed in `specialSeparationDims` in the spec file.
+ *
  * TODO: FIX TYPE
  * @param {*} parsedModel The parsed model structure.
  * @param {*} spec The parsed `spec.json` object.
@@ -71,6 +79,70 @@ function resetModelState() {
  * @param {*} [opts] An optional object used by tests to stop the read process after a specific phase.
  */
 function read(parsedModel, spec, extData, directData, modelDirname, opts) {
+  const maxAttempts = 20
+  for (let attempt = 1; ; attempt++) {
+    try {
+      readModel(parsedModel, spec, extData, directData, modelDirname, opts)
+      if (
+        opts?.stopAfterReadSubscripts ||
+        opts?.stopAfterResolveSubscripts ||
+        opts?.stopAfterReadVariables ||
+        opts?.stopAfterAnalyze
+      ) {
+        // The read was stopped early (used by tests), so skip the dependency sorting
+        return
+      }
+      // Sort the variables in dependency order now so that any cyclic dependency is
+      // detected here; the sorted lists are cached for later use
+      auxVars()
+      levelVars()
+      initVars()
+      return
+    } catch (e) {
+      if (!e.cycles || !spec || attempt >= maxAttempts) {
+        throw e
+      }
+      if (process.env.SDE_PRINT_CYCLES === '1') {
+        console.error(`Cycle found on attempt ${attempt}:\n${e.cycle.join(' →\n')}\n`)
+      }
+      // Find variables in the cycle clusters that can be separated to break the cycles
+      const candidates = separationCandidatesForCycles(e.cycles, e.outgoingEdges)
+      const specialSeparationDims = spec.specialSeparationDims || {}
+      let addedDims = false
+      for (const [varName, dimIds] of candidates) {
+        let dims = specialSeparationDims[varName] || []
+        if (!Array.isArray(dims)) {
+          dims = [dims]
+        }
+        for (const dimId of dimIds) {
+          if (!dims.includes(dimId)) {
+            dims.push(dimId)
+            addedDims = true
+            if (process.env.SDE_PRINT_CYCLES === '1') {
+              console.error(`Breaking a dependency cycle by separating ${varName} on dimension ${dimId}`)
+            }
+          }
+        }
+        specialSeparationDims[varName] = dims
+      }
+      if (!addedDims) {
+        // The cycle analysis did not find any new separations, so the cycle cannot
+        // be broken this way; report it to the user
+        throw e
+      }
+      spec.specialSeparationDims = specialSeparationDims
+      // Reset the model state and read the model again with the added separations
+      resetHelperState()
+      resetSubscriptsAndDimensions()
+      resetModelState()
+    }
+  }
+}
+
+/**
+ * Perform a single pass of the model read process (see `read` above).
+ */
+function readModel(parsedModel, spec, extData, directData, modelDirname, opts) {
   // Some arrays need to be separated into variables with individual indices to
   // prevent eval cycles. They are manually added to the spec file.
   let specialSeparationDims = spec.specialSeparationDims

package/src/model/read-equations.js

@@ -508,6 +508,10 @@ function visitFunctionCall(v, callExpr, context) {
         argModes[2] = 'init'
         break
 
+      case '_DEMAND_AT_PRICE':
+        validateCallArgs(callExpr, 3)
+        break
+
       case '_DEPRECIATE_STRAIGHTLINE':
         validateCallDepth(callExpr, context)
         validateCallArgs(callExpr, 4)
@@ -522,6 +526,10 @@ function visitFunctionCall(v, callExpr, context) {
         argModes[2] = 'init'
         break
 
+      case '_FIND_MARKET_PRICE':
+        validateCallArgs(callExpr, 4)
+        break
+
       case '_GAME':
         validateCallDepth(callExpr, context)
         validateCallArgs(callExpr, 1)
@@ -587,6 +595,11 @@ function visitFunctionCall(v, callExpr, context) {
         argModes[1] = 'init'
         break
 
+      case '_INVERT_MATRIX':
+        validateCallDepth(callExpr, context)
+        validateCallArgs(callExpr, 2)
+        break
+
       case '_NPV':
         validateCallArgs(callExpr, 4)
         addFnReference = false
@@ -612,6 +625,10 @@ function visitFunctionCall(v, callExpr, context) {
         generateSmoothVariables(v, callExpr, context)
         break
 
+      case '_SUPPLY_AT_PRICE':
+        validateCallArgs(callExpr, 3)
+        break
+
       case '_TREND':
         validateCallArgs(callExpr, 3)
         addFnReference = false
@@ -847,25 +864,27 @@ function visitFunctionCall(v, callExpr, context) {
       if (callExpr.fnId === '_WITH_LOOKUP' && index > 1) {
         // XXX: For `WITH LOOKUP` calls, only process the first argument; need to generalize this
         break
-      } else if (callExpr.fnId === '_ALLOCATE_AVAILABLE' && index === 1) {
-        // Handle the second (`pp` or priority profile) argument of `ALLOCATE AVAILABLE` calls
+      } else if (
+        (callExpr.fnId === '_ALLOCATE_AVAILABLE' && index === 1) ||
+        (callExpr.fnId === '_DEMAND_AT_PRICE' && index === 1) ||
+        (callExpr.fnId === '_SUPPLY_AT_PRICE' && index === 1) ||
+        (callExpr.fnId === '_FIND_MARKET_PRICE' && (index === 1 || index === 3))
+      ) {
+        // Handle the second (`pp` or priority profile) argument of allocation function calls
         // specially.  An example call with a 2D `pp` looks like this:
         //   shipments[branch] = ALLOCATE AVAILABLE(demand[branch], priority[branch,ptype], avail) ~~|
         // Or a 3D `pp` with a dimension:
         //   shipments[item,branch] = ALLOCATE AVAILABLE(demand[branch], priority[item,branch,ptype], avail) ~~|
         // Or a 3D `pp` with a specific subscript:
         //   shipments[branch] = ALLOCATE AVAILABLE(demand[branch], priority[item1,branch,ptype], avail) ~~|
-        // Vensim requires passing a reference with `ptype` as the last subscript, but the function
-        // implementation uses the `ppriority` and `pwidth` values (the `ptype` is currently assumed
-        // to be 3).  Therefore we need to add references to all variants of the variable, not just
-        // the ones for `ptype`.
+        // Vensim requires passing a reference with `ptype` as the last subscript.
         if (argExpr.kind !== 'variable-ref') {
-          throw new Error(`ALLOCATE AVAILABLE argument 'pp' must be a variable reference`)
+          throw new Error(`${callExpr.fnName} argument 'pp' must be a variable reference`)
         }
         // TODO: Throw an error if the last dimension of arg0 does not match last dimension of LHS
         // TODO: Throw an error if the second-to-last dimension of arg1 does not match last dimension of LHS
         // TODO: Throw an error if the last subscript of arg1 does not have the "shape" of a `ppriority` dimension
-        // TODO: Throw an error if the `ptype` value is not 3
+        // TODO: Throw an error if the `ptype` value is unsupported
         // Get the RHS subscript/dimension IDs
         const rhsVarBaseRefId = argExpr.varId
         const rhsVarSubIds = argExpr.subscriptRefs?.map(subRef => subRef.subId) || []

package/src/model/read-variables.js

@@ -120,22 +120,27 @@ function variablesForEquation(eqn, specialSeparationDims, separateAllVarsWithDim
       let separationDims = specialSeparationDims[baseVarId] || []
       if (!Array.isArray(separationDims)) {
         separationDims = [separationDims]
+      } else {
+        // Copy the array so that the spec object is not mutated below
+        separationDims = [...separationDims]
       }
-      // Alternatively, if the variable was not in `specialSeparationDims`, separate
-      // on dims from `separateAllVarsWithDims` if the var matches one of the dim lists.
-      if (separationDims.length === 0) {
-        for (let dimList of separateAllVarsWithDims) {
-          // Technically we allow each entry in the spec array to be either a single
-          // dim ID string or an array of dim IDs, so convert to array if needed
-          if (!Array.isArray(dimList)) {
-            dimList = [dimList]
-          }
-          // The list entry from the spec is only considered a match if every dimension
-          // in the spec list appears on the LHS
-          if (dimList.every(dim => subIds.includes(dim))) {
-            separationDims = dimList
-            break
+      // Additionally, separate on dims from `separateAllVarsWithDims` if the var
+      // matches one of the dim lists.
+      for (let dimList of separateAllVarsWithDims) {
+        // Technically we allow each entry in the spec array to be either a single
+        // dim ID string or an array of dim IDs, so convert to array if needed
+        if (!Array.isArray(dimList)) {
+          dimList = [dimList]
+        }
+        // The list entry from the spec is only considered a match if every dimension
+        // in the spec list appears on the LHS
+        if (dimList.every(dim => subIds.includes(dim))) {
+          for (const dim of dimList) {
+            if (!separationDims.includes(dim)) {
+              separationDims.push(dim)
+            }
           }
+          break
         }
       }
       positionsToExpand = subscriptPositionsToExpand(subIds, exceptSubIdSets, separationDims, variable.modelFormula)

package/src/model/toposort.js

@@ -42,7 +42,19 @@ function toposort(nodes, edges) {
       } catch (_) {
         nodeRep = ''
       }
-      throw new Error('Found cyclic dependency during toposort:\n' + [...predecessors].join(' →\n') + ' →' + nodeRep)
+      var chain = [...predecessors]
+      var error = new Error('Found cyclic dependency during toposort:\n' + chain.join(' →\n') + ' →' + nodeRep)
+      // Attach the cycle itself (the portion of the dependency chain from the first
+      // occurrence of the repeated node) so that callers can analyze it.
+      error.cycle = chain.slice(chain.indexOf(node))
+      // Also attach all cycle clusters in the graph (the strongly connected components
+      // with more than one node, plus any single node that depends on itself) along
+      // with the graph edges so that callers can analyze every cycle at once.
+      error.cycles = stronglyConnectedComponents(nodes, outgoingEdges).filter(
+        scc => scc.length > 1 || (outgoingEdges.get(scc[0]) || new Set()).has(scc[0])
+      )
+      error.outgoingEdges = outgoingEdges
+      throw error
     }
 
     if (!nodesHash.has(node)) {
@@ -70,6 +82,76 @@ function toposort(nodes, edges) {
   }
 }
 
+/**
+ * Find the strongly connected components of the graph using an iterative form of
+ * Tarjan's algorithm (iterative to avoid stack overflow on the deep dependency
+ * chains found in large models).
+ *
+ * @param {Array} nodes The nodes in the graph.
+ * @param {Map} outgoingEdges A map of each node to the set of nodes that it points to.
+ * @returns {Array} An array of strongly connected components, where each component is
+ * an array of the nodes that it contains.
+ */
+function stronglyConnectedComponents(nodes, outgoingEdges) {
+  var index = 0
+  var nodeIndex = new Map()
+  var lowlink = new Map()
+  var onStack = new Set()
+  var stack = []
+  var sccs = []
+  for (var start of nodes) {
+    if (nodeIndex.has(start)) {
+      continue
+    }
+    var frames = [{ node: start, edges: null, i: 0, child: undefined }]
+    while (frames.length > 0) {
+      var frame = frames[frames.length - 1]
+      var node = frame.node
+      if (frame.edges === null) {
+        // First visit to this node
+        nodeIndex.set(node, index)
+        lowlink.set(node, index)
+        index++
+        stack.push(node)
+        onStack.add(node)
+        frame.edges = Array.from(outgoingEdges.get(node) || [])
+      } else if (frame.child !== undefined) {
+        // Returning from a child visit
+        lowlink.set(node, Math.min(lowlink.get(node), lowlink.get(frame.child)))
+        frame.child = undefined
+      }
+      var descended = false
+      while (frame.i < frame.edges.length) {
+        var w = frame.edges[frame.i++]
+        if (!nodeIndex.has(w)) {
+          frame.child = w
+          frames.push({ node: w, edges: null, i: 0, child: undefined })
+          descended = true
+          break
+        } else if (onStack.has(w)) {
+          lowlink.set(node, Math.min(lowlink.get(node), nodeIndex.get(w)))
+        }
+      }
+      if (descended) {
+        continue
+      }
+      // All edges have been visited, so the node is complete
+      if (lowlink.get(node) === nodeIndex.get(node)) {
+        var scc = []
+        var member
+        do {
+          member = stack.pop()
+          onStack.delete(member)
+          scc.push(member)
+        } while (member !== node)
+        sccs.push(scc)
+      }
+      frames.pop()
+    }
+  }
+  return sccs
+}
+
 function uniqueNodes(arr) {
   var res = new Set()
   for (var i = 0, len = arr.length; i < len; i++) {