Installation

Operating System

PyBNF can be installed on any recent Linux or macOS operating system. Windows is not currently supported.

Python

PyBNF requires an installation of Python version 3.5 or higher. This should come built-in with most new Linux and Mac operating systems. However, we recommend installing the Anaconda Python distribution for Python v3.5 or higher. Installing Anaconda facilitates managing and installing Python packages as well as maintaining multiple Python environments. Instructions for installing on various platforms can be found on the Anaconda website.

PyBNF

The pip package manager is included with Anaconda and should be used to install PyBNF from the command line.

It is also possible to install pip alone without Anaconda. If you choose to do this, be sure your pip is associated with Python 3 (on some systems, this command is pip3).

Installing from PyPI

Simply type the following in a terminal:

pip install pybnf

The above command will install the most recent version of PyBNF released on the Python Package Index, along with all required dependencies.

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:

pip install -e .

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

(Optional) Logging configuration for remote machines

By default, PyBNF logs to the file bnf_timestamp.log to maintain a record of important events in the application. When running PyBNF on a cluster, some of the logs may be written while on a node distinct from the main thread. If these logs are desired, the user must configure the scheduler to retrieve these logs.

Upon installation of PyBNF, the dependencies dask and distributed should be installed. Installing them will create a .dask/ folder in the home directory with a single file: config.yaml. Open this file to find a logging: block containing information for how distributed outputs logs. Add the following line to the file, appropriately indented:

pybnf.algorithms.job: info

where info can be any string corresponding to a Python logging level (e.g. info, debug, warning)

Installation of External Simulators

BioNetGen

PyBNF is designed to work with simulators present in the BioNetGen software suite, version 2.3, 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. 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.

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.