Say what is wrong when SBML names a reaction in an expression

[jcschaff]

Addresses the 961 half of #1981. 872 is a different bug — see below.

What was wrong

SBML lets a <ci> name a reaction, and doing so denotes that reaction's rate (L3V2 §3.4.3). VCell has no symbol for a reaction rate, so the reference survived translation as an ordinary name and nothing noticed until the finished BioModel bound its expressions:

Error binding global parameter 'rateOf_re15' to model: 're15' is either not found in your model or is not allowed to be used in the current context.

That names the reaction as if it were a typo, says nothing about rates, and points at the parameter rather than at the construct that is unsupported. The limitation is real; only the report was bad. Now:

Reaction rate reference: reaction 're37' is named in an expression, which in SBML denotes that reaction's rate. Reaction rates cannot be referenced in expressions in VCell at this time. Expression: 're37'

Correcting #1981: these are not the same bug

I claimed in #1981 that 872 and 961 looked like one importer bug. Having read both models, that was wrong:

model	expression references	mechanism
961	reaction re15	SBML reaction-rate reference — fixed here
872	species s4 in a global parameter's initialAssignment	maps to the species' initial concentration, which lives in the application (SimulationContext) scope; a Model-level parameter cannot see it, so AbstractNameScope.getRelativeScopePrefix() yields the UNRESOLVED. marker

872 is a name-scope problem, not a symbol-resolution one, and it is shared by a large number of models — the fault table already lists many UNRESOLVED.initConc / UNRESOLVED.Size entries. It needs its own change and is deliberately not in this PR.

Also: it is not the rateOf csymbol

Worth recording, since #1981's title suggested detecting rateOf. BIOMD0000000961 is a COPASI export whose parameters are merely named rateOf_re15; the actual construct is <ci>re15</ci> and the file contains no rateOf csymbol at all. Matching on the csymbol would never have fired.

Where the check lives

In getExpressionFromFormula, reached via ASTNode.getParentSBMLObject().getModel(). One check covers all thirteen call sites — kinetic laws, assignment/rate rules, initial assignments, events, stoichiometry math — with no signature changes.

It skips names that a containing kinetic law declares as local parameters: those are a separate SBML namespace and may shadow a reaction sid without referencing a rate. That was a false-positive path I could see in my own first draft.

The verdict leads and the expression trails deliberately — consumers truncate this message (BMDB_SBMLImportTest keeps 180 chars, and model 731's expression alone is ~150), so a message ending in the diagnosis got categorised UNCATEGORIZED. It also reads better in a log.

Three pre-existing test bugs, fixed because the regression could not be trusted without them

1. BMDB_SBMLImportTest.testCases() was pinned to one model. A leftover debug filter, && n==264, has restricted the whole 109-entry fault suite to a single model since 2025-04-09 (4e05dbff34) — about 16 months. 27 models run again. The committed model set is 29, so this pulls in no new downloads and no new network dependency.
2. Model 739's fault entry was dead code — it sat on the same physical line as model 731's trailing // comment, so it was commented out and never registered. Split onto its own line.
3. Model 596 removed from the fault table — it now imports cleanly. Its recorded cause was the nested-annotation ClassCastException fixed in jsbml 1.6.1-VCELL-4 (fix JSBML library processing errors for Annotations #1461), so the entry was stale as of that release.

Verification

run	result
BMDB_SBMLImportTest, filter restored, with this change	27 tests, 0 failures
same suite without the importer change (control)	1 failure — model 596 only
vcell-core Fast group, CI parallel flags	547 tests, 1 error (VCellDataTest poetry noise, environmental)

The control is the important one: no model went from passing to failing. 731 failed before and fails now — it just says why.

🤖 Generated with Claude Code