Dizzy User Manual CompBio Group, Institute for Systems Biology Stephen Ramsey (sramsey at systemsbiology.org) Dizzy Version: 1.11.4,   2006/09/28

Contents

1. Introduction
   • About Dizzy
   • Publications
   • External Libraries
   • Acknowledgements
2. Getting Started
   • System Requirements
   • Tutorial
   • Sample Model Definition Files
3. Preliminary Concepts
   • Numeric Precision
   • Case Sensitivity
   • Symbol Names
   • Mathematical Expressions
   • Gillespie Stochastic Algorithm
   • Gillespie Tau-Leap Stochastic Algorithm
   • Gibson-Bruck Stochastic Algorithm
   • Deterministic simulation using ODEs
4. Model Elements
   • Parameters
   • Compartments
   • Species
   • Reactions
   • Reaction Rates
   • Multistep Reactions
   • Delayed Reactions
   • Models
5. Chemical Model Definition Language (CMDL)
   • Character Encoding
   • Symbol Values
   • Statements
   • File Inclusion
   • Comments
   • Exporter Plug-ins
   • Viewer Plug-Ins
   • Simulator Plug-Ins
   • Default Model Elements
   • Reaction Statements
   • Symbol Values and Expressions
   • Specifying Species Populations
   • Loops
   • Commands
   • Templates
   • Example CMDL model definition file
   • Symbol Names
6. Simulators
   • Simulator: gibson-bruck
   • Simulator: gillespie
   • Simulator: tauleap-complex
   • Simulator: tauleap-simple
   • Simulator: ODE-RK5-fixed
   • Simulator: ODE-RK5-adaptive
   • Simulator: ODEtoJava-dopr54-adaptive
   • Simulator: ODEtoJava-imex443-stiff
7. Systems Biology Markup Language (SBML)
8. Dizzy Systems Biology Workbench Interface
9. Dizzy Command-line Interface
10. Dizzy Programmatic Interface
11. Dizzy Graphical User Interface
    • Load a model definition file
    • Run a simulation
    • Plotting
    • Export model
    • Reload Model
    • View Model
    • Display in Cytoscape
    • View in human-readable format
    • Browse Help
12. Frequently asked Questions
13. Known Bugs and Limitations
14. Getting Help

Dizzy is a chemical kinetics simulation software package implemented in Java. It provides a model definition environment and various simulation engines for evolving a dynamical model from specified initial data. Stephen Ramsey in the laboratory of Hamid Bolouri at ISB. A model consists of a system of interacting chemical species, and the reactions through which they interact. The software can then be used to simulate the reaction kinetics of the system of interacting species. The software consists of the following elements:

1. a set of Java packages or "libraries" that constitute a Java application programming interface (or "API") for this software system.
2. a scripting engine that can be invoked from the command-line, to define a model and run simulations on the model, and to export a model to a different model definition language
3. an implementation of the Gillespie stochastic algorithm for simulating chemical reaction kinetics
4. an implementation of the Gibson-Bruck stochastic algorithm for simulating chemical reaction kinetics
5. an implementation of a deterministic (ODE-based) algorithm for simulating chemical reaction kinetics
6. a graphical user interface ("GUI") application that can be used to run simulations and export a model to a different model definition language
7. a Systems Biology Workbench (SBW) interface that allows the simulator to be invoked through the Systems Biology Workbench, using a model defined in the Systems Biology Markup Language
8. a graphical display feature that can display a graphical representation of a model using the Cytoscape system.

1. Systems Biology Markup Language ("SBML")

   The SBML standard is documented outside the scope of this document, at the aforementioned web site. The Dizzy system is able to read and write a subset of the SBML Level 1 specification. You can generate a model in SBML format by using the JDesigner software tool.

   The file extension of the SBML language is: ".xml"

2. Chemical Model Definition Language (CMDL)

   The Chemical Model Definition Language (CMDL) is the language understood "natively" by the Dizzy scripting engine.

   The file extension of the CMDL command language is: ".cmdl". The extension ".dizzy" is also recognized as indicating a CMDL file.

This document is the user manual for the Dizzy program. This manual applies to the following release version of the program:

release version:   1.11.4
release date:      2006/09/28

http://magnet.systemsbiology.net/software/Dizzy/docs/Overview.html

http://magnet.systemsbiology.net/software/Dizzy

http://magnet.systemsbiology.net/software/Dizzy/docs/VersionHistory.html

http://magnet.systemsbiology.net/software/Dizzy/docs/UserManual.html

http://magnet.systemsbiology.net/software/Dizzy/docs/UserManual.pdf

An article describing Dizzy has been published,

Ramsey S., Orrell D. and Bolouri H. Dizzy: stochastic simulation of large-scale genetic regulatory networks. J. Bioinf. Comp. Biol. 3(2) 415-436, 2005.

Please see the above PubMed hyperlink to access the article.

Please note that the SBMLReader.jar library is a modified version of the SBML-parsing code originally contained in the program SBMLValidate.jar. The package name has been changed also. This was done in order to minimize the potential for conflict in cases where the target installation computer already has an installation of SBMLValidate.jar from the Systems Biology Workbench (SBW).

The SBWCore.jar library distribution contains three external libraries: gnu-regexp, grace, and java_cup. For information about these libraries and to obtain the source code, please consult the various README.txt files within the subdirectories of the sbw-1.0.5/src/imported directory of the source archive for the SBWCore library, obtained at the link given above.

The odeToJava library is copyright Raymond Spiteri and Murray Patterson. It is provided with kind permission from Raymond Spiteri (Dalhousie University, Halifax, NS, Canada). The odeToJava library is not distributed in its original form with Dizzy. It has been modified from the version that is available from Netlib. Please use the odeToJava.jar library that is bundled with Dizzy, as it contains some features that are necessary in order to function correctly with Dizzy. The Netlib version of odeToJava is no longer compatible with Dizzy, without some slight modifications to the source code.

The jfreechart and jcommon libraries are used by Dizzy in order to generate graphical plots of simulation results. Please note that the public API for these libraries has changed in recent versions, in a non-backwards-compatible manner. It is necessary to use the (older) versions of these libraries (referenced above), that are provided with the Dizzy installation. If you download the latest version of the jfreechart and jcommon libraries from the JFree.org web site, they will not be compatible with Dizzy.

The Colt library is provided under the following license terms:

Copyright (c) 1999 CERN - European Organization for Nuclear Research.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose
is hereby granted without fee, provided that the above copyright notice appear in all copies and
that both that copyright notice and this permission notice appear in supporting
documentation.
CERN makes no representations about the suitability of this software for any purpose.
It is provided "as is" without expressed or implied warranty.

Dizzy depends on the Cytoscape program through the Java Network Launching Protocol (JNLP), which means that the Cytoscape program is not distributed with Dizzy. Instead, the Cytoscape program is loaded at run-time over the network, only when an application function is performed that depends on the Cytoscape program.

Many other individuals have contributed to the project, as well. In particular it should be noted that Dizzy makes extensive use of external libraries. The Dizzy system would not have been possible without the hard work and contributions of the authors of these libraries.

The Dizzy installer will install an executable for the Dizzy launcher program specifically designed for the operating system of the computer on which you are running the installer. This means that if you run the installer on a Windows computer, the Dizzy launcher that is installed will be a Windows executable. If there is a need to run Dizzy on multiple operating systems (e.g., in a dual-boot or heterogeneous network-file-system environment), Dizzy should be installed in a separate directory for each operating system. One exception applies: it is possible to install Dizzy on one operating system (e.g., Windows) and run it on a different operating system (e.g., Unix), if you run the command-line program and not the GUI.

Now that you have become acquainted with the simulation driver screen, the next step is to become acquainted with the CMDL model definition language, which permits rapid development of new models. To begin, let's define a simple model of a chemical system. This system will consist of the enzyme-substrate reaction:

   E
S ---> P

E + S ---> ES
ES    ---> E + S
ES    ---> E + P

A few notes about editing models: You may use the editor window in Dizzy, which is the white text box below the "file:" and "parser:" labels, to enter the model description as described below. Once you have entered the model description into the editor window, you may save the model description to a file by selecting "save as" from the "File" menu. Alternatively, you use your own text editor program (e.g., Notepad on Windows) to create the model definition file. In that case, you would use the "open" menu item under the "File" menu, to load the model definition file into Dizzy.

We will assume that the model definition file you are creating will be called "Model.cmdl". This file will define the species and chemical reactions that make up the model, as well as the kinetic parameters that will be used to simulate the reaction kinetics. The ".cmdl" file extension is important, so please type the file name exactly as shown. This helps the Dizzy program to recognize the file as an official "Dizzy model definition file", and to select the proper interpreter to load the file. The file should start out completely empty. Let's begin by defining the first of the three elementary reactions that make up the above model. We will be defining this model in the CMDL language for entering a model definition file, which is syntactically very close to the "Jarnac" language. At the top of the file, please enter the following lines of text, exactly as shown here:

E = 100.0;
S = 100.0;
ES = 0.0;
r1, E + S -> ES, 1.0;

r1, E + S -> ES,
                    1.0;

The commas in the reaction definition statement divide the statement into elements. We will explain each element in turn. In a reaction definition statement, the first element is optional, and defines the "name" of the reaction. This is just a symbolic name for the reaction, that does not affect the chemical kinetics of the model. There are rules governing allowed symbol names that apply to reaction names. The reaction name specified above was "r1", which is not very descriptive. Perhaps a more descriptive name would have been "enzyme_substrate_combine", as shown here:

enzyme_substrate_combine, E + S -> ES, 1.0;

enzyme_substrate_separate, ES -> E + S, 0.1;

r1, A + B -> C + D, 2.0;

P = a dt

An example of a reaction definition with a mathematical expression for the reaction rate is shown here:

A = 100.0;
B = 100.0;
C = 0.0;
D = 0.0;
F = 10.0;
G = 10.0;
r1, A + B -> C + D, F * G;

A = 100.0;
B = 100.0;
C = 0.0;
D = 0.0;
r1, A + B -> C + D, 100.0;

A = 100.0;
B = 100.0;
C = 0.0;
D = 0.0;
k = 0.1;
r1, A + B -> C + D, [k * (time + 1.0) * A * B];

Getting back to our previous model-building exercise, we have:

E = 100.0;
S = 100.0;
ES = 0.0;
enzyme_substrate_combine, E + S -> ES, 1.0;
enzyme_substrate_separate, ES -> E + S, 0.1;

Note that in defining a chemical reaction, the element specifying the reaction name is not required. If you do not specify a reaction name, a unique reaction name is automatically assigned to the reaction by Dizzy. The syntax for a reaction thus defined is:

A + B -> C + D, 2.0;

Now, let's define the third reaction, which takes the enzyme-substrate complex to the enzyme plus product,

make_product, ES -> E + P, 0.01;

P = 0.0;

E = 100.0;
S = 100.0;
P = 0.0;
ES = 0.0;
enzyme_substrate_combine, E + S -> ES, 1.0;
enzyme_substrate_separate, ES -> E + S, 0.1;
make_product, ES -> E + P, 0.01;

E = 100.0;
S = 100.0;
P = 0.0;
ES = 0.0;
enzyme_substrate_combine,    E + S -> ES,      1.0;
enzyme_substrate_separate,   ES    -> E + S,   0.1;
make_product,                ES    -> E + P,   0.01;

The final model definition file should look like this:

E = 100; S = 100; P = 0; ES = 0; enzyme_substrate_combine, E + S -> ES, 1.0; enzyme_substrate_separate, ES -> E + S, 0.1; make_product, ES -> E + P, 0.01;

Remember, whitespace is ignored by the Dizzy interpreter, so your spacing does not need to look exactly like the example shown above. Now, let's save this model definition file in your text editor. Now, let's open the model definition file in Dizzy, as shown above. Finally, let's select the "Simulate..." menu item from the "Tools" menu, and run a simulation. Select a stop time of 400.0, and specify an output type of "plot", and a "num samples" of 40. Select "P" as the species to view. Your simulation controller dialog box should look like this:

Now, run the simulation. You should see the familiar Michaelis-Menten type reaction kinetics appear in a plot window:

Note that the curve is not a perfect Michaelis-Menten kinetics. This is because we are running a stochastic simulation. The Gillespie algorithm introduces the noisy effects of low copy numbers of chemical species in the model. If we were to drastically increase the number of species (say, by a factor or 1000) in the model, the curve would become less noisy:

Note that the larger the initial copy number of the species in the model, the more computational time will be requird to simulate the model for a given (fixed) choice of "stop time". This means that in general, when running stochastic simulations you should start with small initial copy numbers for the species in your model, and determine the computational run-time, before attempting simulations with large initial species populations.

Symbol names are stored in a namespace. There are two types of namespaces, global and local. Normally, all symbol names reside in the global namespace. This applies to species names, reaction names, compartment names, and parameter names. This means that you cannot define a species X and a reaction X; their names would collide in the global namespace.

The local namespace applies only to a parameter that is defined only for a specific reaction (or reactions). Each reaction has a local namespace for its reaction-specific parameters. It is permissible to define a parameter X in the global namespace, and to also define a parameter X with a different value, in the local namespace for one or more reactions. In that case, the value associated with X for the specific reaction supersedes the value associated with X in the global namespace, for the purpose of evaluating the custom reaction rate expression for the reaction. This can be summarized by saying that a parameter defined locally supersedes a parameter defined globally, of the same name. The local namespace concept applies only to parameters. Note that defining parameters within the local namespace is not possible in the Chemical Model Definition Language.

Symbols are analogous to algebraic variables or symbols. Depending on the context, a symbol may represent the population or concentration of a chemical species, or it may represent a floating point parameter defined for a model or a chemical reaction. In the context of an expression, a symbol always has an associated numeric value. When a symbol appears in a mathematical expression, its associated numeric value is used in place of the symbol, for the purpose of evaluating the expression.

In the context of a mathematical expression, numeric literals are simply numbers, either floating point or integer. Note that within a mathematical expression one may use scientific notation (e.g., 1.2e-7 or 1.2e+7) to specify floating-point numeric literals. Alternatively, one may use constructions such as 1.2*10^7 and 1.2*10^(-7) to represent floating-point numeric literals (but in deferred-evaluation expressions, the latter method is less efficient than scientific notation using the "e" character shown above).

In the Dizzy system, mathematical expressions are described using a syntax similar to the C programming language. The basic operations permitted are:

addition

adding two symbols, numbers, or sub-expressions, such as A+B, or A+1.7, or 2+2

subtraction

computes the difference of two symbols, numbers, or sub-expressions, such as A-B, or A-1.7, or 2-2

multiplication

multiplying two symbols, numbers, or sub-expressions, such as A*B, or A*1.7, or 2*2

division

computes the quotient of two symbols, numbers, or sub-expressions, such as A/B, or A/1.7, or 2/2. The first operand is the dividend, and the second operator is the divisor.

modulo division

computes the remainder of the quotient of two symbols, numbers, or sub-expressions, such as A%B, or A%1.7, or 2%2. The first operand is the dividend, and the second operator is the divisor.

exponentiation

computes the exponent of two symbols, numbers, or sub-expressions, such as A^B, or A^1.7, or 2^2. The first operand is the value being exponentiated. The second operand is the exponent.

parentheses

represents a sub-expression whose value is to be computed, such as the sub-expression (B+C) appearing in the expression A+(B+C).

negation

computes the negative of a symbol, number, or sub-expression, such as -A, or -1.0, or -(A+B).

exp

Computes the value of the base of the natural logarithm, e, raised to the power of the (floating-point) argument.

ln

Computes the natual logarithm of the argument, which must be in the range (0, infinity).

sin

Computes the trigonometric sine of the argument. The argument is an angle, which must be specified in radians. Example: sin(A), sin(3.14159).

cos

Computes the trigonometric cosine of the argument. The argument is an angle, which must be specified in radians. Example: cos(A), cos(3.14159).

tan

Computes the trigonometric tangent of the argument. The argument is an angle, which must be specified in radians. Example: tan(A), tan(3.14159).

asin

Computes the trigonometric inverse sine of the argument. The argument is a dimensionless ratio, that must be within the range [-1,1]. The value returned is an angle, in radians. Example: asin(A), asin(0.5).

acos

Computes the trigonometric inverse cosine of the argument. The argument is a dimensionless ratio, that must be within the range [-1,1]. The value returned is an angle, in radians. Example: acos(A), acos(0.5).

atan

Computes the trigonometric inverse tangent of the argument. The argument is a dimensionless ratio. The value returned is an angle, in radians. Example: atan(A), acos(0.5).

abs

Computes the absolute value of the argument.

floor

Computes greatest integer value that is less than or equal to the floating-point argument. Example: floor(A), floor(1.7)

ceil

Computes the smallest integer value that is greater than or equal to the floating-point argument. Example: ceil(A), ceil(1.7)

sqrt

Computes the value of the square root of the argument. The argument must be nonnegative.

theta

Returns 0.0 if the argument is negative, or 1.0 if the argument is nonnegative (i.e., zero or positive)

min(X,Y)

Returns the smaller of expressions X and Y. This is a two-argument function.

max(X,Y)

Returns the larger of expressions X and Y. This is a two-argument function.

Please remember that all elements of the Dizzy system are case-sensitive, including the aforementioned built-in mathematical functions. Therefore an expression such as SIN(3.14) would not be recognized as referring to the sin trigonometric function. The expression would therefore be considered invalid, because the SIN function would not be recognized as a valid built-in function.

It is important to note that all expressions are evaluated using double-precision floating-point arithmetic. For functions that return an integer, such as the floor() function appearing in the expression A * floor(B), the integer result of floor(B) is converted to a double-precision floating-point number, before the result is used in evaluating the A * floor(B) expression.

The following are a few examples of valid mathematical expressions that have been used in Dizzy models:

10*(1/(1+exp(-0.0025*(-2000+time))))

alpha0 + (alpha + PY^n*alpha1)/(K^n + PY^n)

k * (A/(N*V)) * (B/(N*V))

Certain functions offered above, are not differentiable. This means that algorithms or features of Dizzy that rely on the Jacobian matrix of the model (the partial derivative of the time rate of change of the ith species in the model, with respect to the jth species), may not be used if you specify a model that contains one of these non-differentiable functions in an expression. An error will result if you attempt to use a feature that relies on the Jacobian, with a model containing a non-differentiable function. The non-differentiable functions are: theta(), ceil(), floor(), abs(), and the modulo division operator %. The features in Dizzy that rely on the Jacobian are the Tau-Leap simulators and the steady state fluctuations estimator (the latter relies on the Jacobian only in the case of an ODE-based simulator).

When specifying a mathematical expression, it is important to understand the distinction between immediate evaluation and deferred evaluation. An example of immediate evaluation is shown here:

A = 1.0;
B = A * 5.0;

An example of deferred evaluation is shown her:

A = 1.0;
B = [A * 5.0];

Important note about time-dependent expressions:
Although it is technically possible to define a rate law or other expression that has an explicit time dependence through the use of the reserved symbol "time", this practice is discouraged when using the stochastic simulators. This is because the stochastic simulators are based on a mathematical theory of reaction kinetics in which the time-invariance of the reaction parameters is a priori assumed. The time reserved symbol is intended solely for use with the ODE simulators. A very slowly-varying time dependence for some expression in a model, may be compatible with the stochastic simulators, to the extent that on the time scale for any reaction to occur, the expression is effectively time-translation-invariant.

The Dizzy system provides a Java implementation of the Gillespie algorithm, for which more information is available in the Javadoc documentation. This implementation uses the "direct method" variant of Gillespie's algorithm.

The Gillespie Tau-Leap algorithm is a method for obtaining approximate solutions for the stochastic kinetics of a coupled set of chemical reactions. An dimensionless relative tolerance "epsilon" controls the amount of error (as compared to the Gillespie Direct method) permitted in the solution, by scaling the maximum allowed "leap time" which is recomputed after each iteration of the algorithm. The leap time is the amount by which the time is stepped forward during the iteration. The number of times each reaction in the model occured during the leap time is computed as the result of a Poisson stochastic process. Species populations are adjusted in accordance with the number of times each reaction occurred during the leap time interval. In the limit as the epsilon parameter is set to zero, the Tau-Leap algorithm should agree precisely with the results of the Gillespie Direct algorithm. For complex models with a significant separation of time scales, this algorithm may potentially be much faster than the Gillespie Direct algorithm.

The Tau-Leap algorithm is described in:

D. T. Gillespie and L. R. Petzold, "Improved Leap-Size Selection for Accelerated Stochastic Simulation", J. Chem. Phys. 119, 8229-8234 (2003).

Two implementations of the Tau-Leap algorithm are provided with Dizzy The first is called "tauleap-simple". It is intended for use with models that are entirely composed of elementary reactions, that is, reactions with rate laws that are simple mass-action kinetics. The second is called "tauleap-complex". It is intended for use with models that contain custom algebraic rate expressions.

A parameter is a name-value pair that may be referenced symbolically (i.e., by its name) in mathematical expressions. The value is always a numeric (floating-point) value. The parameter name must be a valid symbol name.

A parameter can be associated with a model, in which case it can be referenced in the custom rate expression for any chemical reaction associated with the model; in addition, it can be referenced in the species population expression for any boundary species within the model.

A compartment is an abstraction for a named region of space that has a fixed volume. The contents of this volume are assumed to be well-stirred, so that chemical species do not have concentration gradients within this volume. Every species must be assigned to a compartment. The volume of the compartment can be used to compute the concentration of the species, from the number of molecules (population) of the species in the compartment.

By default, species defined in the Chemical Model Definition Language are associated with a default compartment "univ" This compartment has unit volume.

A non-default compartment can be defined by a symbol definition as shown here:

c1 = 1.0;

S @ c1;

c1 = 1.0;
S = 100.0;
S @ c1;

A dynamical species (called a "floating" species in SBML) is a species whose population is affected by reactions in which it participates. For example, if a reaction takes species X as a reactant, and does not produce species X as a product, then when this reaction occurs, the population of species X is decremented by one. The dynamical species is the most commonly used species type, and it is the default species type for species in the Dizzy system.

A boundary species is a species whose population is externally specified as a boundary condition for the simulation. The population of a boundary species is not affected by the occurrence of reactions in which the species participates. In this sense, a boundary species is not "dynamical". The population of a boundary species can be set to a constant, or a more complex time-dependent function. The details of how to define the population of a boundary species will be discussed further below.

Occasionally it is desirable to create a model in which a given species can reside in more than one compartment. This is accomplished in the Dizzy system by defining two different species with similar (but still distinct) names, and assigning each species to a different compartment. For example, one might define two different species named "SpeciesX_cytoplasm" and "SpeciesX_nucleus", representing the instances of chemical species "X" in the cytoplasm and nucleus, respectively.

Please note that there is a restriction on the initial population that can be specified for dynamical species. This particular limitation only affects stochastic simulations.

The above discussion assumes that species participating in reactions are dynamical species. As described above in the species section, a species can also be defined as a "boundary" species. In this case, the population of the species is not dynamical but instead a boundary condition of the system. As an illustration, suppose that species X is declared as a boundary species. Even if species X were to appear in a reaction as a reactant, such as in the reaction X + A -> B, the population of species X would not be affected by the occurrence of this reaction. This is mostly useful for defining a species whose role in a system is as an externally applied "signal" or "input". Note that special notation is used to describe a boundary species in the Chemical Model Definition Language (CMDL), as described below.

In the built-in method of defining a reaction rate, one specifies a numeric reaction parameter. The units of the reaction parameter depend on the reaction rate species mode attribute of the model with which the reaction is associated.

If the model's reaction rate species mode is molecules (the default), the reaction parameter represents the numeric reaction probability density per unit time, per distinct combination of reactant molecules. The reaction rate is then obtained by first computing the number of distinct combinations of reactant molecules (which depends on the populations of the various reactant species), and multiplying this number by the reaction parameter for the reaction. The result is the reaction rate.

If the model's reaction rate species mode is concentration, the reaction parameter represents the kinetic constant for the reaction, in units of inverse molar concentration to the power of the number of reactant species, per unit time. In this case, the concentration of each reactant species is computed, and the concentrations are multiplied together (with suitable exponentiation for a reactant species that has a stoichiometry greater than one). The result is then multiplied by the reaction parameter, to produce the reaction rate.

In the custom expression method of defining a reaction rate, one specifies a textual reaction rate expression. This expression is a mathematical expression involving symbols, arithmetic operators, and simple built-in mathematical functions. Symbols can be species names or parameters. A species name appearing in the expression represents either the number of molecules of the species, or the species concentration, depending on the reaction rate species mode of the model with which the reaction is associated. The custom expression method is less desirable than the built-in method, due to the computational overhead of evaluating the mathematical expression for each reaction event during the simulation of the model.

The Dizzy system allows for defining an N-step process as a single composite "reaction". This is an experimental feature that still needs further testing before it can be considered reliable. As a more reliable and better-tested alternative, consider using the delayed reaction construct.

A multistep reaction assumed to consist of N irreversible elementary reactions that are chained together, as shown here:

S0 -> S1 -> S2 -> S3 -> S4 -> ... -> SN

S0 -> S1, k; S1 -> S2, k; ...

1. each reaction step has precisely one reaction and one product
2. all the reactions have the same elementary rate value (which may not be a custom expression)
3. the reactions are chained together as shown above

S0 -> S1, k, steps: N;

Multistep reactions are useful for simulating processes such as transcription and translation, in which a long sequence of individual reaction steps transforms the system from an initial state ("polymerization complex") to a final state ("completed transcript").

In the Dizzy system, a model is a collection of one or more reactions, together with all of the chemical species involved in the reactions, and any parameters defined for the model or the reactions. In addition, a model contains all of the compartments with which the species are associated. A model also incorporates the initial species populations.

A model has an important attribute called the reaction rate species mode. This attribute controls how a given species contributes to a reaction rate. It has two possible values, molecules and concentration. Each will be defined in turn.

In the molecules reaction rate species mode, the contribution of any given species to a reaction rate is always computed using the number of molecules of the species. In the case of the default method of computing the reaction rate, this means that the reaction rate is computed as the product of the number of distinct combinations of reactant molecules, and the reaction parameter. The molecules reaction rate species mode is the default.

In the concentration reaction rate species mode, the contribution of a given species to a reaction rate is computed using the molar concentration of the species (number of moles of the species, divided by the volume of the compartment).

All CMDL files are required text files in UTF-8 encoding, which includes comments. This is to ensure uniform behavior of the Dizzy parser on all platforms, regardless of the default character encoding used in the particular locale. In particular, Red Hat Linux distributions subsequent to version 8, employ UTF-8 encoding as the default character encoding; therefore, care must be used to avoid embedding non-UTF-8 characters within a CMDL file.

A fundamental concept in the CMDL language is the symbol value. A symbol value is an assocation between a symbol name and a value. A value may be defined as a mathematical expression, in which case it is immediately evaluated and the resulting floating point value is associated with the symbol. Or, the value may be defined as a bracketed mathematical expression (enclosed in square brackets), in which case the expression itself is stored and associated with the symbol name. The former type of value (immediately evaluated expression) is akin to a numeric macro. The latter type of value (expression with deferred evaluation) is similar to a symbolic function definition in Mathematica.

As mentioned previously, symbol names must be unique. This means that you cannot use the same symbol name for two different purposes. For example, it is illegal to define both a species "S" and a compartment "S". All elements of the Dizzy system (reaction names, species names, compartment names, and parameter names) live in the same "namespace", and so each element must have a globally unique name.

In the CMDL, compartments, species, and parameters all start out as symbol value definitions like this:

S = 1.0;

r1, A + S -> C + D, 1.0;

comp = 2.0;

S @ comp;

The Dizzy system has a framework of plug-ins for exporting an Dizzy model to different file formats. Each exporter plug-in has an exporter alias defined. The default exporter is the exporter for Systems Biology Markup Language (SBML). The SBML exporter has the exporter alias "markup-language" (quotes not included). The full list of exporters is defined here:

markup-language

Exports a model instance to SBML.

human-readable

Exports a human-readable textual representation of the model.

orrell-column-format

Exports a model instance to a numeric-column-format used at Institute for Systems Biology for certain software tools. Only models that do not contain any expressions may be exported to this format.

command-language

Exports a model instance to the Chemical Model Definition Language (CMDL) format.

cytoscape

Display the model in Cytoscape

human-readable

Display the model in human-readable format.

gillespie

An implementation of the Gillespie stochastic algorithm for modeling the reaction kinetics. This algorithm is described in the article

ODE

An implementation of an ODE-based deterministic simulator of the reaction kinetics. The implementation is based on a 5th-order Runge-Kutta integrator with an adaptive stepsize controller.

• A model is created, with model name "model". The model name can be modified with the "#model" statement.
• A compartment is created, with name "univ" and volume of 1.0 liters

The default "model" in the CMDL language has a reaction rate species mode of "molecules". In order to use a reaction rate species mode of "concentration", it is presently necessary to use the programmatic interface to Dizzy.

• a dynamical species A, in the default compartment
• a dynamical species B, in the default compartment
• a dynamical species C, in the default compartment
• a dynamical species D, in the default compartment
• a reaction creation_of_c_d, in which species A and B participate as reactants, and in which species C and D are products.
• the reaction rate of the creation_of_c_d reaction is computed using the built-in method, with a reaction parameter of 1.0.

A + B -> C + D,  1.0;

In many cases, it is desirable to specify a custom reaction rate, rather than using the built-in method of computing the reaction rate. To specify a custom reaction rate, the reaction rate element should be defined as a string data type. This is accomplished by substituting a bracketed mathematical expression. In the example of the above reaction, one might write:

creation_of_c_d,  A + B -> C + D,  [2.0 * A * B];

It should be emphasized that the CMDL parser determines which type of reaction rate computation method to use, based on whether or not the reaction rate is specified using square brackets. As explained above, if the rate expression is not bounded by square brackets, the parser will use the built-in reaction rate computation method. If the rate expression is bounded by square brackets, the parser will assume that the reaction rate computation method is a custom rate.

Note that specifying a custom reaction rate using a mathematical expression (in square brackets) has a significant drawback, relative to using the built-in method of computing the reaction rate. The custom reaction rate is more expensive to compute, in terms of the number of CPU instructions per reaction event in the simulation.

Often, a single value will be used frequently throughout a model definition file. For example, a reaction rate parameter of 1.0 may be used for many reactions in a given model definition file. This can make it tedious to modify the parameter once the model definition file has been written. The symbol value construct makes it easier to centralize definition of numeric values in the model definition file. One can define a symbol such as this:

k = 1.0;

This symbol may be referenced in any subsequent mathematical expression in the model definition file. For example, we may define a reaction whose rate is "2.0 * k":

creation_of_c_d,  A + B -> C + D,  2.0 * k;

In addition, the "k" symbol may be referenced in a deferred-evaluation mathematical expression, in which case "k" is evaluated as a model parameter (this works because the "k" symbol will be added to the model as a parameter, if it is not used as a species or compartment anywhere in the model):

creation_of_c_d,  A + B -> C + D,  [2.0 * k * A * B];

In the above example, the rate of reaction "creation_of_c_d" is defined as the expression "2.0 * k * A * B", as a deferred evaluation expression. This means that each time the rate needs to be computed, this expression is used. This is sometimes referred to as a "custom rate expression", to distinguish it from the built-in (combinatoric) method of computing the reaction rate based on a floating-point reaction parameter.

A mathematical expression may also be embedded within a symbol name using a double-quote syntax, as shown here:

k1 = 1.0;
"my_reaction[2.0 * k1]", A + B -> C + D, 1.0;

k1 = 1.0;
"my_reaction2", A + B -> C + D, 1.0;

k1 = 1.0;
"k[ 2.0 * k1 ]" = 1.0;

k1 = 1.0;
k2 = 1.0;

The mathematical expression facility allows for using the special symbol time to include simulation time. As an illustration, consider the following exmple reaction definition:

my_reaction, A + B -> C + D, [2.0 * A * B * time^0.5];

In addition to the time symbol, there is a special symbol Navo that defines the Avogadro constant. This is occasionally useful if you have a numeric macro that you wish to specify in terms of moles. For example:

k = 3.6 * 10^(-45);
my_reaction, A + B -> C + D, [k * N * A * N * B];

#model

The "#model" command sets the model name, as shown here:

#model "mymodel";

If the model name is not explicitly set using this command, a default model name will be used. The Dizzy program uses the default model name "model". The rules for parsing the model name are the same as for parsing other symbol names.

#include

For information, refer to the section on file inclusion.

#define

The "#define" command is a template definition. For more information, please refer to the section on templates.

#ref

The "#ref" command is a template reference. For more information, please refer to the section on templates.

Note that in the CMDL, a species symbol appearing in a reaction rate expression can mean one of two things, depending on the reaction rate species mode of the model with which the reaction is associated. For a reaction rate species mode of "molecules" (the default), the symbols A and B in the reaction rate mathematical expression refer to the numeric populations of species A and B, respectively. For a reaction rate species mode of "concentration", the symbols A and B in the reaction rate mathematical expression refer to the molar concentrations of species A and B, respectively.

Simulators

A stochastic simulator implemented using the Gibson-Bruck algorithm.

A stochastic simulator implemented using the algorithm.

An approximate accelerated stochastic simulator implemented using the Gillespie Tau-Leap algorithm. This implementation is intended for complex models in which the Jacobian matrix is very computationally expensive to compute, and therefore the Jacobian matrix is evaluated first, and then the "mu" and "sigma" functions are computed using the pre-computed Jacobian matrix. Although this method is N-squared in the number of species, it is faster when the Jacobian is very complicated.

An approximate accelerated stochastic simulator implemented using the Gillespie Tau-Leap algorithm. This implementation is intended for models in which the Jacobian matrix is easy to compute (basically the elements of the Jacobian are at most linear in the species concentration), and so no pre-evaluation of the Jacobian matrix is done. The "sigma" and "mu" functions are pre-computed symbolically. This avoids the N-squared dependence on the number of species. This method scales well when the number of species gets large, as compared to the "tauleap-complex" method.

The Dizzy system provides a deterministic simulator for reaction kinetics, in which the system is modeled as a set of coupled ordinary differential equations (ODEs). The simulator alias for this simulator is "ODE-RK5-fixed". The differential equations are solved using a finite difference method, specifically the 5th-order Runge-Kutta algorithm with a fixed stepsize. The step size must be specified by the user, as a fraction of the total time interval for the simulation. The accuracy of this simulator's solution will depend on the size of the time-step fraction that is specified.

Note about disabling error checking:You may delete the maximumum absolute and/or relative error tolerances in the simulation launcher screen, in order to run the simulator with no absolute and/or relative error checking. This feature is currently only available for the fixed-stepsize Runge-Kutta integrator.

The Dizzy system provides a deterministic simulator for reaction kinetics, in which the system is modeled as a set of coupled ordinary differential equations (ODEs). The simulator alias for this simulator is "ODE-RK5-adaptive". The differential equations are solved using a finite difference method, specifically the 5th-order Runge-Kutta algorithm with an adaptive stepsize controller. The step-size controller is based on an error estimation formula that is accurate to 4th order. The user must specify the tolerances for relative and absolute errors, as well as the initial step size (as a fraction of the total time interval of the simulation).

A deterministic simulator implemented by Murray Patterson and Raymond Spiteri, as a part of the "odeToJava" package. This simulator is a 5/4 Dormand-Prince ODE solver with adaptive step-size control.

A deterministic simulator implemented by Murray Patterson and Raymond Spiteri, as a part of the "odeToJava" package. This simulator is an implicit-explicit ODE solver with step doubling. This simulator works well for models with a high degree of stiffness. However, please see the issue with interpolation in the imex443 solver.

This section describes the Systems Biology Markup Language. The systems biology markup language is an XML-based document specification for defining a model instance for a system of interacting chemical species. The specification for SBML can be found at the home page of the Systems Biology Workbench Development Group. Dizzy is capable of reading a model in SBML Level 1 format, Versions 1 and 2. Dizzy can export a model to SBML Level 1, Version 2.

The Dizzy system is capable of importing a model instance from an SBML document, and exporting a model instance (defined through a different language) to an SBML document. Some features of the Dizzy system cannot be exported to an SBML document. In particular, a boundary species whose population is a mathematical expression defining a function of time, cannot be exported to SBML. Similarly, certain SBML constructs will not be imported into the Dizzy system, namely, unit definitions. The Dizzy system can import SBML documents with either of two systems of units:

• Initial species populations specified in moles; Reaction rates specified using expressions in which species symbols represent molar concentration
• Initial species populations specified in molecules; Reaction rates specified using expressions in which species symbols represent number of molecules

Dizzy has an interface to the Systems Biology Workbench (SBW) system. This makes it possible to access the simulation engine for Dizzy using the cross-language remote procedure invocation capabilities of SBW. Note that this section of the Dizzy user manual assumes you are familiar with the architecture and terminology of the Systems Biology Workbench system. For a good overview of these concepts and terminology, please refer to the Introduction to the Systems Biology Workbench document, available at the SBW Project home page. Please note: The SBW interface in Dizzy is compatible only with SBW versions 2.2.1 or newer, and not with the 1.X.X versions. The interface to SBW offered by Dizzy includes a SBW module "org.systemsbiology.chem.sbw.gui" (this is the SBW Unique Module Name, not a Java class name), which a single SBW service asim. The display name