A simulator for biochemical reaction networks, as a Python library.
BNGsim simulates models written in SBML, Antimony and the BioNetGen language
(BNGL). It integrates a model as ordinary differential equations or runs it as
an exact stochastic simulation. A rule-based model can also be run network-free,
with NFsim or RuleMonkey, from the XML that BioNetGen writes. The same Model,
Simulator and Result objects serve every format. A model is loaded once and
simulated in-process, and each run returns NumPy arrays.
It also computes forward sensitivities, finds steady states, runs parameter
scans and batches on parallel threads, and converts models between formats.
For BioNetGen users, it replaces run_network.
PyBioNetGen and
PyBNF use BNGsim.
- When to use BNGsim: what it does and doesn't do, alternatives, and tips.
- What BNGsim does: features, engines, and what sets it apart.
bngsim.agent_guide()returns a one-page guide for the installed version, with no network.python -m bngsim guideprints it, andpython -m bngsim skillprints it as aSKILL.mdfile.- A call that uses names from libRoadRunner, Tellurium, SciPy or pandas, or
from BNGL actions (
setParameter,t_end,n_steps), raises an error that names the BNGsim call to use. The guide also translates from AMICI, COPASI and PySB. - BNGsim refuses models it can't simulate correctly, and says why.
bngsim.exampleshas small models with exact solutions, to try BNGsim with no model file and check its answers.bngsim.ModelBuilderbuilds a model in Python, andbngsim.Model.from_biomodels("BIOMD0000000010")loads a BioModels entry by its id.- The docs have an
llms.txtindex.
Status: alpha (0.x). BNGsim is checked every night against BioNetGen, libRoadRunner, AMICI and the SBML test suite, but it is early software, and bugs that give a wrong answer without an error are still open. They carry the
correctness concernlabel. Before you rely on a result for a new model, check it against a second engine or a tighter tolerance, and please report what you find.
pip install bngsimWheels ship for common platforms. Some features need an extra, such as
bngsim[antimony] or bngsim[bngl], and sensitivities need a C compiler. See
the installation guide.
This runs as written after pip install bngsim. It writes a two-species network
to a file so that there is something to load. Put your own SBML, Antimony or BNGL
file in its place.
from pathlib import Path
import bngsim
# A -> B at rate k, in BioNetGen's network (.net) format.
Path("model.net").write_text(
"""\
begin parameters
1 k 0.5
end parameters
begin species
1 A() 100
2 B() 0
end species
begin reactions
1 1 2 k
end reactions
begin groups
1 A 1
2 B 2
end groups
""",
encoding="utf-8",
)
# Model.load reads .net, SBML (.xml, .sbml), Antimony (.ant) and BNGL (.bngl).
model = bngsim.Model.load("model.net")
sim = bngsim.Simulator(model, method="ode")
result = sim.run(t_span=(0.0, 10.0), n_points=101)
result.time # (101,) NumPy array of time points
result.observables["A"] # trajectory of observable "A"
result.species # (101, 2) array, columns in model.species_names order
print(round(float(result.observables["A"][-1]), 4)) # 0.6738, which is 100 * exp(-5)Three rules worth knowing from the start:
n_pointscounts the first point. 101 points over(0, 10)are 0.1 apart.- An ODE or stochastic run continues from the state the last one on that model
ended in. Call
model.reset()to start again from the initial state, or passrun(..., start="initial").result.started_fromsays which start a run had, and a run that restarts the clock on the last run's end state raises abngsim.LiveStartWarning. - A stochastic run draws a fresh seed unless you pass one.
result.seedis the seed that was used.
The quickstart covers the other loaders, stochastic runs, steady states and sensitivities.
Full documentation is hosted at bngsim.readthedocs.io
and lives in docs/:
- Installation · Quickstart · When to use BNGsim · What BNGsim does
- 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
- For AI agents: the agent guide,
also returned by
bngsim.agent_guide(), andllms.txt - Architecture · benchmarks & validation
Console scripts convert models between formats (see
interchange)
and manage the compiled-code cache (bngsim-cache).
Correctness and efficiency results will be in bngsim-benchmarks.
Build-from-source, test, and CI instructions are in
CONTRIBUTING.md
and the development docs.
Release history is in
CHANGELOG.md.
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.
If you use BNGsim in your research, please cite:
Preprint coming soon!
BNGsim has been validated against RoadRunner, AMICI, COPASI, BioNetGen, and the SBML/DSMTS test suites. See ACKNOWLEDGMENTS.md for citations.