[jcschaff]

libvcell can now generate the math of rule-based applications. VCell expands an application's reaction rules into a reaction network with BioNetGen (perl <vcell.installDir>/bionetgen/BNG2.pl), which libvcell didn't have.

Until now:

• vcml_to_ode_input fell back to the stored math (0.0.21);
• vcml_to_vcml and the other model-building calls failed. pyvcell writes every model through vcml_to_vcml, so rule-based models couldn't be built or edited there.

What's bundled

• libvcell/vcell_install/bionetgen/: the Perl part of BioNetGen 2.9.3 (MIT, the current upstream release), 1.6 MB.
  • It's BNG2.pl and Perl2/, copied unchanged from the official BioNetGen-2.9.3-linux.tar.gz. Its README.md records the source and sha256; the mac release is identical, and the win release differs only in line endings.
  • Network generation doesn't use BioNetGen's compiled simulators, so bin/ is left out.
  • Pre-commit excludes the directory, so the files stay byte-identical to the release.
• Runtime requirement on macOS/Linux: perl on the PATH. macOS and most Linux distributions have it.
• Windows: a standalone BNG2.exe, so no Perl is needed. VCell's Windows code always launches bionetgen/win64Standalone/BNG2.exe, never perl BNG2.pl; this PR's first CI run failed on exactly that (CreateProcess error=2).
  • The exe is new: packed from the bundled MIT 2.9.3 by scripts/pack_bionetgen.sh, with PAR::Packer, the tool VCell's own 2.3.0 exe was built with. It embeds a Perl interpreter. VCell's old 2.3.0 exe is GPLv3 and isn't used.
  • Packing: pp -I Perl2 with every module named, because BNG2.pl looks for Perl2/ next to itself.
  • Smoke test: the script runs the packed exe on a small model, with no Perl modules from outside it, and checks that a network comes out.
  • Prototyped on macOS: the packed binary generates the same network as perl BNG2.pl (BioNetGen's egfr_net, 4,177 lines).
  • CI: the Windows jobs of main.yml and on-release-main.yml install PAR::Packer and pack the exe before the build. The step is cached on a hash of the BioNetGen files and the script, so the slow install only runs when they change.
  • Packaging: the exe is git-ignored and included in the wheel. build.py warns on Windows if it's missing; rule-based models then use their stored math.

How it's wired

• Python: the package sets LIBVCELL_VCELL_INSTALL_DIR to libvcell/vcell_install (_internal/native_utils.py). A value already in the environment wins.
• Java: BioNetGenSupport.configure(), called first in every model-building method, turns that variable into vcell.installDir. Each native call runs in a fresh isolate, so the setting is made per call.
• vcml_to_ode_input regenerates a rule-based application with the bundled BioNetGen. It falls back to the stored math only if that fails, for example with no perl or a BioNetGen timeout, and names the reason: "<input file>; stored math (rule-based application: BioNetGen could not regenerate its reaction network: <why>)".
• Build: build.py and scripts/local_build_native.sh record with the variable set, so native-image covers the BioNetGen path. The recording log shows executeBNG() as perl script.

Does 2.9.3 behave like VCell's 2.3.0?

VCell's own copy (vcell_submodule/bionetgen) is 2.3.0, under GPLv3. 2.9.3 is MIT. To check they agree, I regenerated every rule-based model with an ODE simulation in a 2,730-model VCell corpus (109 models) with both versions and compared the solver input:

	Models
Byte-identical solver input from 2.3.0 and 2.9.3	103
Fail identically with both	6: unit errors and invalid sizes in the models, and two BioNetGen timeouts
Behave differently	0

The README asks for this check to be repeated before moving to a newer release.

Tests

• Java: a new test regenerates the public rule-based model 100992568 with the bundled BioNetGen. The stored-math test still covers running without it. SolverEntrypointsTest gives 24/24.
• Python: one test regenerates through the native library and solves the result. It needs perl, or the packed exe on Windows. A second test forces the fallback by pointing the variable at a directory with no BioNetGen, and checks the message. 29/29 pass on a fresh native build.
• make check is clean.

pyproject.toml is at 0.0.22. The wheel lists libvcell/vcell_install/** explicitly.

🤖 Generated with Claude Code