NFsim: The Network Free Stochastic Simulator

v1.08

Overview

NFsim is a generalized stochastic reaction network simulator designed to handle systems with a large (or even infinite) state space. It has a number of features that make it ideal for handling large and complex biochemical systems, such as functionally defined rate laws and reactions that depend on local context. NFsim is designed to operate with the BioNetGen Language (http://bionetgen.org/). The new version of BNG is able to generate an XML encoded form of the BNG Language, which NFsim can take as input.

For more details on setting up, running, and getting output from an NFsim simulation see the User Manual. The User Manual also has additional information for new developers. The manual is available online along with examples here: http://www.nfsim.org

Command Line Argument List

Arguments can be provided to NFsim through the command line. Below is a partial list of the available commands and a brief description of what they do. For more details, see the NFsim user manual.

-help = outputs a helpful message to the console

-xml [filename] = specifies the xml file to read

-sim [Duration in sec] = specifies the length of time to simulate the system

-oSteps [num of steps] = specifies the number of times to output during the simulation

-eq [Duration in sec] = specifies the length of time to equilibrate before simulating

-o [filename] = specifies the name of the output file

-v = verbose output when reading an xml file and building a system

-b = output in binary (faster, but output is not human readable)

-utl [integer] = universal traversal limit, see manual

-notf = disables On the Fly Observables, see manual

-cb = turn on complex bookkeeping, see manual

-gml [integer] = sets maximal number of molecules, per any MoleculeType, see manual

Developers

To begin developing and extending NFsim, the best place to start looking is in the src/NFtest/simple_system directory. Here you'll find two files, simple_system.hh and simple_system.cpp. Together, this code specifies a simple enzymatic type reaction that is completely hard coded. This will give you an idea of the basic classes and functions used to define, initialize, run, and output a simulation. From there, you can dive into the specific classes and functions that you need to work with. Details about how to run the simple_system example are given in these files.

All of the other main classes are defined in the NFcore namespace and are found in the NFcore directory and the NFreactions directory. The NFcore directory contains the basic structure of the simulation engine while the NFreactions directory contains the classes associated with actually executing rules and transforming molecules. NFinput contains what's needed for the xml parser (built using the TinyXML package) and the command line parser. NFutil also contains a nice implementation of the Mersenne Twister random number generator which should be used for all random number generation in NFsim. NFoutput is more sparse as it deals only with handling the more complicated output required of groups and complexes. (Basic outputting is handled easily with the System and Observable classes in the NFcore namespace).

Another note for developers: class functions and member variables are generally well commented in the header file in which they are declared. So if you are lost in some source file, and you think there aren't any comments, be sure to check the header file before you ask for help.

Authors & Acknowledgments

The NFsim code was written and developed by Michael Sneddon with help from James Faeder and Thierry Emonet. James Faeder wrote the original extended BioNetGen code that can output XML encodings of the BNGL and contains the functional rate law syntax.

A number of other people have helped in getting NFsim to where it is today, either by aiding in the concepts of the design, testing the implementation, adding some features to the code, or by suggesting improvements.

A partial list of these people include:

Garrit Jentsch, William Pontius, Oleksii Sliusarenko, Justin Hogg, Christopher Henry, Fangfang Xia, Ryan Gutenkunst,

---