Skip to content
lanlPublic

Latest commit

 

History

3,549 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BNGsim

BNGsim

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.

For AI agents

  • bngsim.agent_guide() returns a one-page guide for the installed version, with no network. python -m bngsim guide prints it, and python -m bngsim skill prints it as a SKILL.md file.
  • 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.examples has small models with exact solutions, to try BNGsim with no model file and check its answers. bngsim.ModelBuilder builds a model in Python, and bngsim.Model.from_biomodels("BIOMD0000000010") loads a BioModels entry by its id.
  • The docs have an llms.txt index.

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 concern label. 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.

Installation

pip install bngsim

Wheels 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.

A first run

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_points counts 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 pass run(..., start="initial"). result.started_from says which start a run had, and a run that restarts the clock on the last run's end state raises a bngsim.LiveStartWarning.
  • A stochastic run draws a fresh seed unless you pass one. result.seed is the seed that was used.

The quickstart covers the other loaders, stochastic runs, steady states and sensitivities.

Documentation

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

Console scripts convert models between formats (see interchange) and manage the compiled-code cache (bngsim-cache).

Benchmarks & validation

Correctness and efficiency results will be in bngsim-benchmarks.

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 has been validated against RoadRunner, AMICI, COPASI, BioNetGen, and the SBML/DSMTS test suites. See ACKNOWLEDGMENTS.md for citations.

Releases

Packages

Used by

Contributors

Languages