bngsim

Embeddable simulation engine for biochemical reaction networks.

bngsim is a high-performance C++ simulation kernel with Python bindings that replaces BioNetGen's subprocess-based run_network driver. The library also includes two network-free simulators. It loads BioNetGen .net and .xml files, runs deterministic and stochastic simulations in-process, and returns results as NumPy arrays — no file I/O, no subprocess spawning, no Perl dependency.

Highlights

• Fast — in-process execution with the GIL released during simulation; thread-parallel batch sweeps
• No toolchain at runtime — import bngsim; no compilers, no BNGPATH, no Perl
• Modern SUNDIALS — v7.x CVODE/CVODES with re-entrant SUNContext
• Multi-format — loads BioNetGen .net and .xml, Antimony (.ant), and SBML (.xml) models SBML Test Suite results, plus rule-based BNGL (.bngl) via BNG2.pl with bngsim[bngl]
• Rich results — NumPy arrays, named observable access, pandas/xarray, HDF5 save/load
• Standards interchange — .net/cBNGL ⇄ SBML and SED-ML + OMEX packaging, every conversion verified faithful
• Gradient-ready — CVODES forward sensitivities, Fisher information
• Validated — matches run_network to ~10⁻¹² (ODE) and cross-checked against RoadRunner and the SBML semantic test suite

Installation

pip install bngsim

Prebuilt wheels ship for common platforms, with the sparse (KLU) solver bundled. See the installation guide for source builds, the KLU dependency, and optional extras.

Quickstart

import bngsim

# Load a model (BioNetGen .net/.xml, Antimony, or SBML) and run an ODE simulation
model = bngsim.Model.from_net("model.net")
sim = bngsim.Simulator(model, method="ode")
result = sim.run(t_span=(0.0, 100.0), n_points=1001)

result.time               # (1001,) NumPy array of time points
result.observables["A"]   # trajectory of observable "A"
result.dataframe          # pandas DataFrame of time + all observables

Other formats load through the sibling constructors — Model.from_sbml, Model.from_antimony, and their *_string variants.

Stochastic (method="ssa" / "psa"), network-free (NFsim / RuleMonkey), sensitivity analysis, steady-state, and events are all covered in the quickstart and user guide.

Documentation

Full documentation is hosted at bngsim.readthedocs.io and lives in docs/:

• Installation · Quickstart
• User guide — loading models, simulation, network-free, results, events, sensitivities, steady state, compiled RHS and its artifact cache, SBML/SED-ML/OMEX interchange
• Reference — API · expression language
• Architecture · benchmarks & validation

The package ships console scripts for model conversion (bngsim-sbml2net, bngsim-net2sbml, bngsim-sbml2bngl, bngsim-validate-conversion, bngsim-omex; see interchange) and bngsim-cache (equivalently python -m bngsim.cache), which reports on and prunes the compiled-artifact cache that codegen fills, which nothing empties on its own. See managing the artifact cache.

Benchmarks & validation

bngsim beats run_network on every SSA/PSA model measured (geometric-mean speedup ~8.7× SSA), agrees with libRoadRunner across the full BioModels ODE corpus, and scores 1577 Match on the SBML semantic test suite with zero wrong-but-plausible answers. The numbers, methodology, and reproducible harnesses are in benchmarks & validation, with the committed cross-engine snapshots under parity_checks/. To re-run the suites and reproduce the numbers — the pinned-fetch model, corpus provenance, tool versions, and a no-download smoke path — see REPRODUCING.md. The supported-construct matrix is in SUPPORT_MATRIX.md.

Those results are re-checked every night: a scheduled workflow runs the parity sweeps and alerts on any change in correctness or solver work (parity_checks/nightly/). To check whether a change of yours slowed bngsim down, benchmarks/perf_ab.py times two builds against each other on your machine (see Checking performance and parity).

Contributing

Build-from-source, test, and CI instructions are in CONTRIBUTING.md and the development docs. Release history is in CHANGELOG.md.

License

MIT. See LICENSE for the full text and the Triad/LANL copyright notice.

Third-party code and model/test-data corpora that BNGsim redistributes are listed, with their licenses, in NOTICE.

© 2026. Triad National Security, LLC. All rights reserved. This is a Los Alamos National Laboratory open-source release; LANL software release reference O5098.

Citation

If you use bngsim in your research, please cite:

Preprint coming soon!

Acknowledgments

BNGsim was developed and validated against RoadRunner, AMICI, COPASI, BioNetGen, and the SBML/DSMTS test suites. See ACKNOWLEDGMENTS.md for citations.