Installation Guide

From BioNetWiki

Jump to: navigation, search

Instructions for installing BioNetGen-2.x.x

Contents

Requirements

BioNetGen-2.x.x is written in the Perl language. The simulation back end, run_network, is written in C++. The PhiBPlot plotting utility, which is included in the PhiBPlot subdirectory of the distribution, is written in Java. RuleBender, a graphical IDE for BioNetGen, is available at rulebender.org.

Running BioNetGen requires:

  • Perl version 5.8 or above. This is usually installed on Mac OS X and Linux machines and under Windows if you are running Cygwin. An alternative Perl for Windows (and other platforms) can be downoaded from here.
  • Mac OS/X, Linux, Windows, or a platform with appropriate tools for compiling the simulation backend.

Installing the BioNetGen Distribution

  • Select the desired source code distribution from Source Code Distribution, e.g. BioNetGen-2.2.0-stable.zip.
  • Place the source distribution file in the location where your would like to install BioNetGen.
  • Unzip the source by typing unzip <file>.zip, where file is the name of the BioNetGen zip file.
  • If you are using a Linux, Mac, or Windows machine, a pre-compiled simulator is included in the distribution. If not, see compilation instructions.

Testing and Validation

To validate your installation, run the validation script:

 <BNGroot>/Validate/validate_examples.pl

Note that items in angle braces <like_this> indicate variables. Fill in the appropriate values when you type the command (Don't type the angle braces!)

In Windows it may be necessary to explicitly call the Perl interpretter, like this:

 perl.exe <BNGroot>\BNG2.pl <modelfile>.bngl

BioNetGen will write output to the current directory, so move to a directory where you want to store output files before running the validation script.

Some validations rely on statistical analysis of stochastic simulations. These validations will fail about 10% of the time due to statistical outliers and approximations used to calculate the analytic distribution. If you see a message like "..FAILED!! chi_square rejected the null hypothesis", try running the validation script on the failed test again. If the test validates most of the time, your installation is ok.

If more than a few tests fail, then there is probably a problem with your installation. Compiling the simulation back end may help. See the compiling instructions below.

Running BioNetGen

The main BioNetGen executable is the Perl script BNG2.pl in the root BioNetGen directory. BNG2 can be run from the command line by typing:

 <BNGroot>/BNG2.pl <modelfile>.bngl

To see a help menu with all the command line options, type:

 <BNGroot>/BNG2.pl -h

A few example models are included in the Models2 subdirectory. Use these as templates for your own models. To execute a sample model, type this:

 <BNGroot>/BNG2.pl <BNGroot>/Models2/<modelfile>.bngl

You should see some output like:

BioNetGen version 2.2.0
Reading from file ../BioNetGen-2.2.0-stable/Models2/toy-jim.bngl (level 0)
Read 16 parameters.
Read 5 species.
Adding P as allowed state of component Y of molecule K
Read 8 reaction rule(s).
Read 9 observable(s).
Iteration   0:     5 species      0 rxns  0.00e+00 CPU s
Iteration   1:     8 species      3 rxns  0.00e+00 CPU s
...

Versions prior to 2.1.8

The main executable script, BNG2.pl, was in the Perl2 subdirectory in versions prior to 2.2.0. To execute BioNetGen in these older versions, type this:

 <BNGroot>/Perl2/BNG2.pl <modelfile>.bngl

There are a few additional differences in older versions:

  • Help menu is not avialable
  • Default output directory is the same directory as the model file.

Documentation

See Documentation for a more comprehensive introduction to BioNetGen.

Compiling the simulator from source

2.2.0 and later

Pre-compiled binaries are available for more common platforms (Linux, Mac, Windows). To compile on your local system:

  • Go the Network3 subdirectory in the BioNetGen folder.
  • Configure the installation for your system.
  • Make and install the executable.
  cd <BNGroot>/Network3
  ./configure --disable-shared --prefix=<BNGroot>
  make
  make install

The executable is installed at <BNGroot>/bin/. For more information, see the INSTALL file in the Network3 subdirectory.

Prior to 2.2.0

This is optional you are running on a platform other than Windows, Mac OS X, or standard linux. Prerequisites are a working gcc compiler and the make utility.

  • cd to the root BioNetGen directory and type 'make'.
  • The main Makefile and the source code for the back end is in the Network2 directory, in case you encounter any problems.
Personal tools