@sdeverywhere/compile 0.7.31 → 0.7.33

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') {
@@ -472,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':
@@ -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/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/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