Installation

Operating System

PyBNF can be installed on any recent Linux or macOS operating system.

PyBNF can also be installed on Windows, but functionality on Windows has been less extensively tested (in particular, Windows clusters and multicore workstations have not been tested).

Python

PyBNF requires an installation of Python version 3.11 or higher. This requirement is declared in the package metadata, so installers such as pip and uv will refuse to install PyBNF into unsupported Python environments with a clear Python-version error.

Linux and Mac

Python 3 comes built-in on many new Linux and Mac operating systems. To check if you have a supported Python 3, run the command python3 --version. This will print the version number, or will give an error if you don’t have Python 3. Confirm that the version is 3.11 or higher.

Also confirm that your Python 3 has the pip package manager, which is used to install PyBNF. Run the command python3 -m pip. This will give a help message if you have pip, or an error if not.

If you are missing python3 or pip, an easy way to get them is by installing the Anaconda Python distribution for Python v3.11 or higher. Instructions for installing on various platforms can be found on the Anaconda website.

Windows

Windows does not come with built-in Python, so it must be installed separately. Additionally, if BioNetGen will be used, Perl installation is required in the same environment as the python installation (i.e., the commands python and perl must both work on the same command line).

Our recommended configuration consists of installing Strawberry Perl and Anaconda Python 3.11 or higher. The Windows distribution of Anaconda includes the application “Anaconda Prompt”, which provides a command line. This is the command line that you should use whenever this documentation refers to the command line or terminal. After installing both Anaconda and Strawberry Perl, a system restart may be required for Anaconda Prompt to find the Perl installation.

For troubleshooting, or more advanced configuration, note that the requirement is to have both Python 3 and Perl on the current path. The current path can be checked with the command echo %PATH% and set (temporarily) with the command set PATH=[newpath], where [newpath] is a semicolon-delimited list of directories to search.

PyBNF

Installing from PyPI

Simply type the following in a terminal:

python3 -m pip install pybnf

Windows users running Anaconda Python 3 from “Anaconda Prompt” should instead type only pip install pybnf.

The above command will use your current version of Python 3 to install the most recent version of PyBNF released on the Python Package Index, along with all required dependencies. If your Python version is older than 3.11, pip will stop before installation and report that PyBNF requires Python 3.11 or higher.

Depending on your Python configuration, the above command may require root access and install PyBNF for all users on the computer. If you don’t want to do this, you may add the flag --user to the end of the command, to install without root access for only the current user.

Advanced Python users may consider installing PyBNF in a virtualenv (which also does not require root access) to avoid conflicts between PyBNF’s dependencies and other uses of Python on the computer.

Installing with uv

If uv is installed, PyBNF can be installed as an isolated command-line tool:

uv tool install pybnf

To run PyBNF once without keeping a tool installation, use:

uvx pybnf --help

As with pip, uv will select a Python version compatible with PyBNF or report that Python 3.11 or higher is required.

Installing from source

To use bleeding edge PyBNF, the source code may be found on GitHub at https://github.com/lanl/PyBNF . To use, simply download or clone the repository and run the following command in the repository’s root directory:

python3 -m pip install -e .

This also allows developers to modify the source code while still having access to the command line functionality anywhere in the filesystem.

With uv, the equivalent editable source setup is:

uv venv --python 3.12

uv pip install -e .

Optional features

Some capabilities pull in heavier dependencies and are packaged as optional extras, installed with the pybnf[extra] syntax (e.g. pip install pybnf[petab,arviz]). The core install stays lightweight; a feature whose extra is missing raises a clear install hint rather than a bare import error.

  • pybnf[petab] — PEtab v2 import/export, including the expression-valued observableFormula measurement models.

  • pybnf[jax] — the Hamiltonian Monte Carlo / NUTS reference sampler (job_type = hmc), which runs blackjax NUTS on the model’s JAX log-density.

  • pybnf[arviz] — the ArviZ InferenceData bridge for posterior analysis (LOO / WAIC / trace plots); see Model selection and posterior analysis.

  • pybnf[plot] — end-of-run plots, including the profile-likelihood panels.

  • pybnf[antimony] — Antimony model support (via BNGsim).

Installation of External Simulators

BNGsim

The BNGsim Python package is installed automatically as a PyBNF dependency. PyBNF uses BNGsim for supported in-process BNGL simulation paths when it is available, unless bngl_backend = bionetgen or PYBNF_NO_BNGSIM=1 is set. Use bngl_backend = bngsim to require BNGsim for BNGL simulations. PyBNF uses BNGsim for SBML models when sbml_backend = bngsim is configured.

BNGsim does not replace all uses of BioNetGen in PyBNF. BNGL workflows can still require BioNetGen so PyBNF can run BNG2.pl to prepare .net or XML simulator inputs.

BioNetGen

PyBNF is designed to work with simulators present in the BioNetGen software suite, version 2.3 or higher, available for download from the BioNetGen website. Note that for Linux distributions other than Ubuntu, the pre-built binary is unreliable, and it is necessary to rebuild BioNetGen from source. For Windows, Perl must be installed separately, as described above. The current BioNetGen distribution includes support for both network-based simulations and network-free simulations.

PyBNF will need to know the location of BioNetGen – specifically the location of the script BNG2.pl within the BioNetGen installation. This path can be included in the PyBNF configuration file with the bng_command key. A convenient alternative is to set the environment variable BNGPATH to the BioNetGen directory using the following command:

export BNGPATH=/path/to/bng2

where /path/to/bng2 is the path to the folder containing BNG2.pl, not including the “BNG2.pl” file name. This setting may be made permanent as of your next login, by copying above command into the file .bash_profile in your home directory.

On Windows systems, the equivalent commands are set BNGPATH=C:\path\to\bng2 to set on the current command line, and setx BNGPATH C:\path\to\bng2 to permanently set for all future command lines (but not the current one).

SBML

PyBNF runs simulations of SBML models using libroadrunner, which is installed automatically through pip as part of PyBNF installation.

To work with SBML files, it is useful to install software such as COPASI that is capable of reading and writing models in SBML format.