simgi-0.2: doc/simgi.html
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>simgi - A Stochastic Gillespie Simulator for Molecular Systems</title>
<meta name="author" content="Markus Dittrich" />
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left{
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right {
clear: right ;
float: right ;
margin-left: 1em }
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: left }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="simgi-a-stochastic-gillespie-simulator-for-molecular-systems">
<h1 class="title">simgi - A Stochastic Gillespie Simulator for Molecular Systems</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Markus Dittrich</td></tr>
<tr class="field"><th class="docinfo-name">email:</th><td class="field-body">haskelladdict at users dot sourceforge dot net</td>
</tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.2 (12/01/2009)</td></tr>
</tbody>
</table>
<div class="section" id="contents">
<h1>Contents</h1>
<ol class="arabic simple">
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#status">Status</a></li>
<li><a class="reference internal" href="#download">Download</a></li>
<li><a class="reference internal" href="#compilation">Compilation</a></li>
<li><a class="reference internal" href="#simgi-model-generation-language-sgl">Simgi Model Generation Language (SGL)</a></li>
<li><a class="reference internal" href="#example-input-files">Example Input Files</a></li>
<li><a class="reference internal" href="#bugs">Bugs</a></li>
</ol>
</div>
<div class="section" id="introduction">
<h1>Introduction</h1>
<p><strong>simgi</strong> is a fairly simple and straightforward stochastic simulator
based on Gillespie's <a class="footnote-reference" href="#id4" id="id1">[1]</a> direct method. <strong>simgi</strong> is implemented in
pure Haskell, command line driven and comes with a flexible simulation
description language called <a class="reference internal" href="#simgi-model-generation-language-sgl">Simgi Model Generation Language (SGL)</a>.
<strong>simgi</strong> uses a fast 64 bit implementation of the Mersenne Twister
algorithm as random number source.</p>
</div>
<div class="section" id="status">
<h1>Status</h1>
<p>The 0.2 release of <strong>simgi</strong> provides a fully functional simulator
which has been tested on several model systems some of which were
fairly large.</p>
</div>
<div class="section" id="download">
<h1>Download</h1>
<p>The current release of simgi can be downloaded <a class="reference external" href="http://sourceforge.net/project/platformdownload.php?group_id=260550">here</a>.</p>
</div>
<div class="section" id="compilation">
<h1>Compilation</h1>
<p>Compilaton of <strong>simgi</strong> requires</p>
<ul class="simple">
<li><a class="reference external" href="http://haskell.org/ghc/">>=ghc-6.10</a></li>
<li><a class="reference external" href="http://gmplib.org/">>=gmp-4.3</a></li>
<li><a class="reference external" href="http://hackage.haskell.org/package/mersenne-random-pure64">>=mersenne-random-pure64</a></li>
</ul>
<p>To compile the documentation (not required), you will also need</p>
<ul class="simple">
<li><a class="reference external" href="http://docutils.sourceforge.net/">>=docutils-0.5</a></li>
<li>latex, e.g., tetex or texlive</li>
</ul>
<p>Building of <strong>simgi</strong> can be done either via</p>
<ul class="simple">
<li>the standard <tt class="docutils literal">make, make check, make install</tt></li>
<li>or via cabal</li>
</ul>
</div>
<div class="section" id="simgi-model-generation-language-sgl">
<h1>Simgi Model Generation Language (SGL)</h1>
<p><strong>simgi</strong> simulations are described via <a class="reference internal" href="#simgi-model-generation-language-sgl">Simgi Model Generation Language
(SGL)</a>. The corresponding simulation input files typically have an <em>.sgl</em>
extension, but this is not enforced by the <strong>simgi</strong> simulation
engine.</p>
<p>A SGL file consists of zero or more descriptor blocks of the form</p>
<pre class="literal-block">
def <block name>
<block content>
end
</pre>
<p>The formatting of the input files is very flexible. In
particular, neither newlines <a class="footnote-reference" href="#id5" id="id2">[2]</a> nor extraneous whitespace matter.
Hence, the above SGL block could have also been written on a single line.
However, it is strongly recommended to stick to a consistent and
"visually simple" layout to aid in "comprehending" the underlying
model. Also, it is important to point out that <strong>simgi</strong>'s parser is
case sensitive.</p>
<p><strong>Comments</strong> can be added to the SGL file and are parsed according to
the Haskell language specs</p>
<ul class="simple">
<li>simple line comments begin with a <tt class="docutils literal"><span class="pre">--</span></tt> token and treat everything
until the next newline as a comment, including valid SGL commands.
Hence, SGL blocks containing line comments need to be separated by
newlines in order to be parsed correctly.</li>
<li>block comments begin with a <tt class="docutils literal">{-</tt> token and end with a <tt class="docutils literal"><span class="pre">-}</span></tt>
token. Everything within a comment block is ignored by the parser
and block comments can be nested.</li>
</ul>
<p><strong>Expression Statements</strong> are an important and useful part of SGL.
<tt class="docutils literal">Expression statements</tt> are enclosed in curly braces and can contain
any mathematical expression involving doubles, the simulation time
(via the keyword <tt class="docutils literal">TIME</tt>), as well as the values of any variable or
molecule count. The values of time, molecule counts and variables
are evaluated at run time and represent the instantaneous values at the
time at which the expression is evaluated.
<tt class="docutils literal">Expressions statements</tt> can contain any
arithmetic expression involving the standard operators "+", "-", "*", "/", "^"
(exponentiation), and the mathematical functions <tt class="docutils literal">sqrt, exp, log, log2, log10, sin,
cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, acosh, atanh,
erf, erfc, abs</tt>.</p>
<p>Internally, <tt class="docutils literal">expression statements</tt> are converted into a compute stack
in RPN format which is evaluated at run-time. Even though this
procedure is fairly efficient, there is some numerical overhead
incurred at each iteration and the use of complicated rate
expressions should therefore be avoided if possible.</p>
<p>Below is a list of all SGL blocks available for describing simulations.
Presently, the order of blocks matters and should be exactly the same
in which they are described below. Several SGL blocks are
optional and are marked as such below.</p>
<p>Currently, the SGL specs define the following block types with their
respective block commands and block content:</p>
<p><strong>parameter block:</strong> <tt class="docutils literal"><block name></tt> = <em>parameters</em></p>
<blockquote>
<p>The purpose of the parameter block is to describe the global
simulation parameters. The following parameters are currently
supported:</p>
<dl class="docutils">
<dt><em>time</em> = <tt class="docutils literal">Double</tt></dt>
<dd>Maximum simulation time in seconds. Default is 0.0 s.</dd>
<dt><em>outputBuffer</em> = <tt class="docutils literal">Integer</tt></dt>
<dd><p class="first">Output will be kept in memory and written to the output file and
stdout every <em>outputBuffer</em> iterations. Larger values should
result in faster simulations but require more system memory.
Default is to write output every 10000 iterations.</p>
<p class="last">Note: <em>outputBuffer</em> only affects how often output is written to
the output file, not how much output is actually generated during a
simulation (see outputFreq parameter).</p>
</dd>
<dt><em>outputFreq</em> = <tt class="docutils literal">Integer</tt></dt>
<dd>Iteration frequency with which output is generated. Default is every 1000
iterations. Please note that output is written to the output file in batches of
<em>outputBuffer</em>.</dd>
<dt><em>systemVol</em> = <tt class="docutils literal">Double</tt></dt>
<dd>Volume of the simulation system in liters. This is needed to
properly compute the reaction rates in molar units. If rates
should rather be interpreted as reaction propensities (like
in <a class="footnote-reference" href="#id4" id="id3">[1]</a>) please set <em>systemVol = nil</em>. Default is a system
volume of 1.0 liter.</dd>
<dt><em>outputFile</em> = <tt class="docutils literal">Quoted String</tt></dt>
<dd>Name of the output file. This is the only required parameter
in the parameter section. If not given, the simulation will
terminate.</dd>
</dl>
</blockquote>
<p><strong>variable block:</strong> <tt class="docutils literal"><block name></tt> = <em>variables</em></p>
<blockquote>
<p>This block consist of a list of pairs of the form</p>
<pre class="literal-block">
String = <variable expression>
</pre>
<p>where <tt class="docutils literal">String</tt> is the variable name, and <tt class="docutils literal"><variable expression></tt>
is either a <tt class="docutils literal">Double</tt> or an <tt class="docutils literal">expression statement</tt> as defined above.
Variables can be used in any other <tt class="docutils literal">expression statement</tt> in the
SGL file including reaction rate definitions. Please make sure to
not define a variable in terms of itself to avoid infinite recursion.</p>
</blockquote>
<p><strong>molecule block:</strong> <tt class="docutils literal"><block name></tt> = <em>molecules</em></p>
<blockquote>
<p>This block consist of a list of pairs of the form</p>
<pre class="literal-block">
String = Integer
</pre>
<p>giving the name of each molecule and the number of molecules
present initially. For example, the following molecule definition
block defines molecules <tt class="docutils literal">A</tt> and <tt class="docutils literal">B</tt> with initial numbers of
100 and 200, respectively</p>
<pre class="literal-block">
def molecules
A = 100
B = 200
end
</pre>
<p><strong>NOTE</strong>: Please do not use any of the predefined mathematical
functions or defined variables (including <tt class="docutils literal">TIME</tt>) as
molecule names since this will lead to undefined behavior.</p>
</blockquote>
<p><strong>reaction block</strong>: <tt class="docutils literal"><block name></tt> = <em>reactions</em></p>
<blockquote>
<p>This block describes the reactions between molecules defined in
the molecule block. Reactions are specified via</p>
<pre class="literal-block">
<reactants> -> <products> | <rate expression> |
</pre>
<p>Here, <tt class="docutils literal"><reactants></tt> and <tt class="docutils literal"><products></tt> are of the form</p>
<pre class="literal-block">
Integer String + Integer String + .....
</pre>
<p>In this expression, <tt class="docutils literal">String</tt> is a molecule name
as defined in the molecule block and <tt class="docutils literal">Integer</tt> an optional
integer specifying the stoichiometry. If <tt class="docutils literal">Integer</tt> is not
explicitly given, it is assumed to be 1.</p>
<p>The <tt class="docutils literal"><rate expression></tt> can either be a fixed value of type
<tt class="docutils literal">Double</tt> or an <tt class="docutils literal">expression statement</tt> as defined above.</p>
<p>Below is an example reaction block for the two molecules <tt class="docutils literal">A</tt> and
<tt class="docutils literal">B</tt> defined above:</p>
<pre class="literal-block">
define reactions
2A + B -> A | 10.0e-5 |
B -> A | {2.0e-5 * A * exp(-0.5*TIME)} |
end
</pre>
<p>In the first reaction, 2 <tt class="docutils literal">A</tt> molecules react with one <tt class="docutils literal">B</tt> to
yield another <tt class="docutils literal">A</tt> at a rate of 10.0e-5. The second
reaction describes a decay of <tt class="docutils literal">B</tt> back to <tt class="docutils literal">A</tt> at a rate
that is computed based on the instantaneous number of <tt class="docutils literal">A</tt>
molecules present and which decays exponentially with simulation
time.</p>
</blockquote>
<p><strong>event block</strong>: <tt class="docutils literal"><block name></tt> = <em>events</em></p>
<blockquote>
<p>An event block allows one to specify events which will occur during
the simulation. Each event consists of a <tt class="docutils literal"><trigger expression></tt> and
an associated set of <tt class="docutils literal"><action expressions></tt>.
Events are specified via</p>
<pre class="literal-block">
{ <trigger expression> } => { <action expression> }
</pre>
<p>Here, <tt class="docutils literal">trigger expression</tt> is of the form</p>
<pre class="literal-block">
<trigger primitive> [ <boolean operator> <trigger primitive>]
</pre>
<p>with <tt class="docutils literal"><trigger primitive></tt> defined by</p>
<pre class="literal-block">
<expression statement> relational operator <expression statement>
</pre>
<p>Each <tt class="docutils literal"><trigger primitive></tt> contains two <tt class="docutils literal">expression statements</tt>
as defined above and a <tt class="docutils literal">relational operator</tt> which can be
any of <tt class="docutils literal">>=</tt>, <tt class="docutils literal"><=</tt>, <tt class="docutils literal">==</tt>, <tt class="docutils literal">></tt>, and <tt class="docutils literal"><</tt>. Hence, each
<tt class="docutils literal"><trigger primitive></tt> evaluates to either <tt class="docutils literal">true</tt> or <tt class="docutils literal">false</tt>.</p>
<p>Several <tt class="docutils literal"><trigger primitives></tt> can be chained together via the
<tt class="docutils literal"><boolean operators></tt> <tt class="docutils literal">&&</tt> and <tt class="docutils literal">||</tt> to yield a final boolean
value of <tt class="docutils literal">true</tt> or <tt class="docutils literal">false</tt>.</p>
<p>If the <tt class="docutils literal"><trigger expression></tt> evaluates to true during an
iteration, the associated <tt class="docutils literal"><action expressions></tt> is executed
during the same timestep.</p>
<p><tt class="docutils literal"><action expression></tt> consists of a semi-colon separated list of
assignments</p>
<pre class="literal-block">
String = <assignment expression> [; String = <assignment expression>]
</pre>
<p>where <tt class="docutils literal">String</tt> is a molecule or variable name and
<tt class="docutils literal"><expression></tt> either a <tt class="docutils literal">Double</tt> or an <tt class="docutils literal">expression statement</tt>.</p>
<p><strong>NOTE</strong>: Since molecule counts are integer values assignments
to molecule counts in <tt class="docutils literal"><action expression></tt> will be converted
to an integer value via <tt class="docutils literal">floor</tt>.</p>
</blockquote>
<p><strong>output block</strong>: <tt class="docutils literal"><block name></tt> = <em>output</em></p>
<blockquote>
<p>This block consists of a simple list of variable and molecule
names that will be streamed to the output file in the same order:</p>
<pre class="literal-block">
[ name1, name2, name3, .... ]
</pre>
</blockquote>
</div>
<div class="section" id="example-input-files">
<h1>Example Input Files</h1>
<p>Below are several example input files detailing the use of SGL:</p>
<ul class="simple">
<li><a class="reference external" href="model_files/volterra.sgl">Lotka-Volterra Model</a></li>
<li><a class="reference external" href="model_files/brusselator.sgl">Brusselator Model</a></li>
<li><a class="reference external" href="model_files/oregonator.sgl">Oregonator Model</a></li>
</ul>
<p>These are also available in the <em>Models/</em> sub-directory in the source tree.</p>
</div>
<div class="section" id="bugs">
<h1>Bugs</h1>
<p>Please report all bugs and feature requests to
<haskelladdict at users dot sourceforge dot net>.</p>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> Daniel T. Gillespie (1977). "Exact Stochastic Simulation of Coupled Chemical Reactions". The Journal of Physical Chemistry 81 (25): 2340-2361</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>An exception to this rule are line comments starting with <tt class="docutils literal"><span class="pre">--</span></tt> which ingnore everything until the next newline.</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>