BioNetGen 3

BioNetGen 3 is a Python-first, in-process rule-based modeling platform for biochemical reaction systems. It parses BNGL directly in C++, simulates with the bundled backend, and exposes models, results, scans, and exports as ordinary Python objects.

Install

pip install bionetgen

No Perl runtime is required for the default workflow.

Quickstart

importbionetgenmodel=bionetgen.load("models/simple_system.bngl")
result=model.simulate(method="ode", t_end=100)
result.plot()

Highlights

• C++ backend for parsing, network generation, ODE simulation, SSA, NFSim, PLA, and PSA.
• Parameter scanning in 1D and 2D, with serial or isolated parallel execution.
• Local sensitivity analysis with finite differences.
• Jupyter-friendly HTML reprs for models, simulation results, and scan results.
• SBML import through the atomizer bridge.
• Programmatic model construction without hand-writing BNGL.
• Direct export to BNGL, XML, SBML, MATLAB, LaTeX, and graph visualizations.

Migration From PyBioNetGen

If you are upgrading from PyBioNetGen or BNG2, start with docs/migration_guide.md.

Key differences:

• bionetgen.load() replaces bngmodel().
• model.simulate() replaces subprocess-based bionetgen.run() workflows.
• Results are NumPy-backed objects instead of .gdat files.
• Parameter scans and sensitivity analysis are first-class APIs.
• Perl, cement, distutils, pyparsing, and pylru are no longer required for the default path.

Performance

Benchmark data is generated by benchmarks/run_benchmarks.py and archived by nightly CI.

Model	C++ Parse	C++ Generate	C++ Simulate	Perl Total	100-pt Scan
simple_system	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact
egfr_net	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact
fceri_ji	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact	see benchmark artifact

API Overview

The primary object is model.

Method	Purpose
model.simulate(...)	Run ODE, SSA, NFSim, PLA, or PSA simulation
model.generate_network(...)	Expand the rule set into a reaction network
model.parameter_scan(...)	Scan one parameter across a value range
model.parameter_scan_2d(...)	Scan two parameters on a grid
model.sensitivity_analysis(...)	Compute normalized local sensitivities
model.contact_map(...)	Export a contact map graph
model.regulatory_graph(...)	Export a regulatory graph
model.rule_influence_graph(...)	Export a rule influence graph
model.reaction_network_graph(...)	Export a reaction network graph
model.ruleviz_pattern(...)	Export a rule pattern graph
model.ruleviz_operation(...)	Export a rule operation graph
model.process_graph(...)	Export a process graph
model.sbml_multi(...)	Export SBML Multi
model.write_xml(...)	Export BioNetGen XML
model.write_bngl(...)	Export BNGL text
model.write_sbml(...)	Export SBML from the generated network
model.write_matlab(...)	Export MATLAB code
model.write_latex(...)	Export LaTeX output

Top-level helpers:

importbionetgenmodel=bionetgen.load("models/simple_system.bngl")
scan=bionetgen.parameter_scan(model, parameter="k", min=0.01, max=10, n_points=20)
model2=bionetgen.from_sbml("tests/python/test/test_sbml.xml")
builder=bionetgen.ModelBuilder("MyModel")

CLI

bionetgen run MODEL.bngl --method ode --t-end 100
bionetgen scan MODEL.bngl --parameter k_on --min 0.01 --max 100 --n-points 50
bionetgen sensitivity MODEL.bngl --parameter k_on --observable AB
bionetgen visualize MODEL.bngl --type contact_map -o output.graphml
bionetgen check MODEL.bngl
bionetgen export MODEL.bngl --format sbml --output model.xml

See docs/cli_reference.md for the full command reference.

Build From Source

git clone <repo-url>cd BNG3
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
pip install -e .

If you only want the Python package, pip install -e . is usually enough; the build system compiles the extension as needed.

Citation

Please cite BioNetGen when using the platform in publications. See docs/index.md and the project website for current citation information.

License

MIT. See LICENSE.