Network-free simulation of energy-based (eBNGL) models via load-time rule expansion

[akutuva21]

Summary

Implements network-free simulation of energy-based rule-based models (eBNGL) in NFsim. Energy rules using the Arrhenius rate law are automatically expanded at model-load time into conventional BasicRxnClass rules with pre-computed rate constants, following the algorithm in Sekar (2015, Chapter 3). This eliminates any runtime energy computation or rejection sampling overhead while maintaining exact thermodynamic consistency (detailed balance).

This is, to our knowledge, the first implementation of network-free energy-based simulation in any rule-based modeling framework.

Background

Energy-based BioNetGen (eBNGL) allows modelers to specify cooperative interactions via energy patterns and Arrhenius rate laws, with free energy computed from pattern matches. Previously, eBNGL models could only be simulated after full network generation (ODE/SSA in BNG2), because computing reaction rates requires knowledge of both reactants and products — information unavailable in a network-free simulator until after the reaction fires.

Sekar (2015) proved that only energy pattern embeddings overlapping the reaction center contribute to ΔG (Corollary 3.3-43), enabling each energy rule to be expanded into a finite set of conventional rules with analytically pre-computed rates. This PR implements that algorithm directly in NFsim's C++ input pipeline.

Reference

Sekar, J. A. P. (2015). Rule-based Modeling of Cell Signaling: Advances in Model Construction, Visualization and Simulation. PhD Dissertation, University of Pittsburgh. Chapter 3: Energy-based Models and Network-free Simulation.

Implementation

New files

File	Purpose
src/NFcore/energyPattern.hh	EnergyPatternInfo, EnergyFunction, expansion algorithm, context condition extraction
src/NFcore/energyPattern.cpp	Sekar expansion: find relevant patterns, enumerate context combinations, compute Arrhenius rates
src/NFinput/NFinput_energy.hh	Declarations for XML parsing and reaction creation
src/NFinput/NFinput_energy.cpp	Parses from XML, builds expanded BasicRxnClass instances with refined TemplateMolecule patterns
test/testSuite/v40.bngl	Minimal eBNGL test model (A-B binding with cooperative X context)
test/testSuite/v40.xml	Hand-crafted XML for v40 (BNG2 writeXML() does not yet emit eBNGL)
validate/basicModels/v40.bngl	Reference BNGL for validation suite

Thermodynamic consistency verified: k_fwd/k_rev = exp(-ΔG/RT) for all variants, confirming detailed balance is exactly preserved.

Known limitations

• Binding rules only: State-change rule expansion is stubbed but not yet context-aware
• Hand-crafted XML required: BNG2's writeXML() does not yet emit <ListOfEnergyPatterns> or type="Arrhenius" rate laws — requires corresponding BNG2 patch
• Bimolecular rate scaling: A consistent factor-of-2 offset in absolute stochastic rates vs. analytical prediction (likely numberPerQuantityUnit / volume convention); does not affect thermodynamic ratios
• No blockSameComplexBinding for expanded rules: Intra-complex binding blocking not yet wired for Arrhenius rules

How to test

cd build && cmake .. && make
./NFsim -xml ../test/testSuite/v40.xml -sim 0.001 -oSteps 1 -v

Verify that 4 expanded rules are created (2 forward + 2 reverse) and the reported rates match the analytical predictions above.