Table of Contents
MesoRD comes with two different user interfaces, that both accomplish approximately the same thing. The graphical user interface as shown in Figure 5.1, “ The GUI on Windows XP™ ” has not been implemented on all supported platforms yet. The command-line interface is more efficient to use, but may be intimidating to users not accustomed to it. Since version 0.3, MesoRD also has a command line interface for Windows. The synopsis for the mesord executable is as follows:
mesord
[-C its
] [-c secs
] [[-l] | [-L]] [-d molecs
] [[-g] | [-G]] [-h] [-i its
] [-I scale
] [[-p] | [-P]] [-q size
] [[-s] | [-S]] [-t secs
] [-V] [-D] [-T secs
] [-r tol
] [-x its
] [-m method
] [-o line#
] [[-e] | [-E]] {model
}
The last argument is the name of the SBML
file that contains the model definition. Most other individual
options are discussed further below. The options that will only
be mentioned here are h
, which prints a short
help message to standard out, and V
which
prints version information to standard out before exiting
normally. Note that MesoRD supports
long option names on platform which have the
getopt_long
function. Check the output of
mesord -h if in doubt.
MesoRD will build the geometry of the system using fixed size sub volumes. Theoretically, there are several differently shaped sub volumes one could use for this construction. Currently, MesoRD only knows about one kind of sub volume: the cube.
To give physically reasonable results the size of the cubic subvolume must meet some criteria that are described in Chapter 6, Rates and state changes in MesoRD . However practically the most important criteria is the result of the simulations should not change if the size of the artificial subvolume changes a little. Thus we suggest that you run your simulations with doubled and halved subvolume size to make sure the result does not depend on the artificial discretisation.
-q size
Tells MesoRD to build the
geometry using cubic sub volume of with the given size.
Note that the size has to be given with a valid unit. All
units specified in the model definition that evaluate to
multiples of metres are valid units in this context. If the
unit um
from the section called “
Units
” is in the model definition,
the following will build the geometry using cubic sub
volumes with side 0.1 micrometres:
... -q 0.1 um ...
Default subvolume size is 10^{-7} metres.
Any simulation is typically run until a certain termination criterion is met. One could imagine implementing all kinds of complicated convergence criteria. We have been very unimaginative with our termination criteria: a simulation is run either a certain number of iterations or a certain number of simulation seconds. Simulation is terminated when either of these conditions are met. There is one trick with setting the maximal number of simulation iterations: it may very well occur that the number of simulations one would want to run will not fit into a C long integer type. This may turn into a problem, especially on 32-bit architectures. Thus, the maximal number of iterations must be specified using a multiplier and a scale. The maximal number of iterations is then interpreted as the multiplier times ten to the power of the scale.
-i its
This option will specify the multiplier for the number of iterations to run. (Default: 10^{8}).
-I scale
This option will specify the scale for the number of iterations to run. (Default: 5).
-t secs
This option will specify the duration of the simulation using the clock of the simulated system. Note that this time is different from the wall clock time. (Default: 100 seconds).
-s
This option will suppress starting of simulation all together. If you specify this option, all that will be done is model parsing.
-S
This option will make sure that the system is actually simulated (default).
A checkpoint is a dump of the current state of the system. There are two types of checkpointing in MesoRD: Full state checkpointing and compartment state checkpointing. In full state checkpointing the whole state of the system, i.e. the number of molecules in the different subvolumes is append to several files, as further discussed in the section called “ Making Sense of MesoRD Output ”. If the whole state is saved, it is possible to restart the a simulation from this point in time. In compartment state checkpointing the number of molecules of different species are saved for each compartment.
-C its
This option will control how many iterations will pass
between checkpoints. The system is checkpointed whenever
its
iterations have passed since the last
checkpoint. (Default: 10^{9}).
-c secs
This option will control how many seconds will pass between
checkpoints. The system is checkpointed whenever
secs
seconds have passed since the last
checkpoint. Note that this time is measured with respect to
the simulation system clock, not the wall clock.
(Default 1 second).
-l
This option will turn the full state checkpointing off.
-L
This option will turn the full state checkpointing on (default).
Note that if both its
and
secs
are greater than zero,
MesoRD will checkpoint whenever
its
iterations or
secs
seconds have passed since the last
checkpoint. Since checkpoints can consume much disk space and are
quite expensive in terms of running time, this may not be
desirable.
In stochastic simulations there will be a high number of empty subvolumes, especially if the number of molecules is low, therefore MesoRD has the possibility to write the full state checkpoints in a sparse format. The format of the files is described in the section called “ Making Sense of MesoRD Output ”. Note: The deterministic simulation mode has no support for the sparse format, weird this might happen if you use them together.
-e
This will turn the sparse output format off (default for deterministic simulations).
-E
This will turn the sparse output format on (default for stochastic simulations).
MesoRD contains a few visual elements. The most prominent of these is the visualiser, which enables real-time viewing of the system. Using the visualiser it is possible to see whether the simulation does what one would expect and it thus enables debugging of model definitions. The visualiser is not intended for any accurate analysis of simulation results. The visualiser is also not necessary for the simulation per se, and since it consumes a fair share of available resources, its use is optional. If you have a poor graphics card, you are therefore recommended to use the visualiser only for debugging the SBML file. To make optimal use of the visualiser you should have a fast dual processor machine with a high end graphics card.
The least prominent visual element is the progress bar. The progress bar displays the current iteration number and the the current simulation time. The progress bar also enables clean, premature termination of a simulation.
-g
This option will suppress launching of the OpenGL visualiser.
-G
This option will launch the OpenGL visualiser once the simulation is started (default).
-d molecs
This option will control how many molecules are rendered in
one sub volume. For cubic sub volumes,
molecs
is the number of molecules that
will fit along one each dimension of the sub volume. The
total number of molecules rendered in a cubic sub volume is
thus molecs
to the power of three (default 2).
-p
This option will suppress launching of the progressbar.
-P
This option will launch the progress bar once the simulation is started (default).
MesoRD will run a mean-field simulation of the model when the deterministic mode is selected. There are a few numerical integration methods to choose among. All of them will require a time step for each iteration. The implicit methods will in addition require some parameters for the equation solver.
-D
This will turn on the deterministic simulations in MesoRD. When this flag is set the sparse output format should not be used at all. It should also be noted that the visualiser will give very misleading information ^{[15]} since the visualiser is plotting integer number of molecules and the deterministic simulations are using a continuous description of the molecule numbers (default: the simulation mode is set to stochastic).
-T secs
This option will specify how large the time step will be for each iteration. The time step should always be given in seconds. Small time steps give more stable and accurate simulations but may on the other hand take very long time. The implicit methods (see deterministic models) can usually handle larger time steps but are also more time consuming in each step. (Default 0.0001).
-r tol
When using implicit methods (see deterministic methods) a
system of equations is solved in each time step. This option
specify a cut-off limit for the iterative method used to
solve this system of equations. The iterative method exits
if the norm of the residual, r = Ax - b, from the equation
system Ax = b is smaller then tol
.
(Default: 10^{-7}).
-x its its
The variable its
specify the maximum
number of iteration used when solving the system of
equations. If the cutoff tolerance is not reached within
its
MesoRD
will print an error message. (Default: 100).
-m method
This will specify which method to use in deterministic simulation. The available methods found in Figure 5.2, “ The available deterministic methods ” (default RungeKutta4).
... -m RungeKutta4 ...
Figure 5.2. The available deterministic methods
Methods | |
---|---|
Euler | First order accuracy explicit method. |
EulerBackward | An unconditionally stable implicit method of first-order accuracy |
Trapezoid | An unconditionally stable implicit method of second-order accuracy |
RungeKutta4 | The fourth-order Runge Kutta scheme. An explicit method. |
BDF2 | Implicit linear multi-step method, implemented in two steps. |
A simulation can be resumed from an old full state checkpoint assuming that the SBML .xml file is read from a directory where a previous simulation has been run with the same geometry and discretisation and that all old checkpointing files are still present. (default this feature is turn off).
The output files in the directory will overwrite the old simulation data that is used for to define to start state, i.e. make a copy of your old simulation data before starting from an old checkpoint.
-o line#
Settings the line#
will start the
simulation in the state that can be found at checkpoint
number line#
.
... -o 234 ...
Note: You cannot start a deterministic simulation from a previous stochastic simulation that has been stored in the sparse format. You cannot start a stochastic simulation from a previous deterministic simulation, since there is not an integer number of molecules in the different subvolumes. If you try this there will be no warnings, just strange output from your new simulation.
^{[15] } More then usual, that is.