Chapter 5.  The User Interface

Table of Contents

Available Options
Sub Volume Geometry
Simulation Duration
Sparse Output
Visual Appearance
Deterministic mode
Starting from an old checkpoint
Making Sense of MesoRD Output
The OpenGL Visualiser

Available Options

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.

Figure 5.1.  The GUI on Windows XP

The GUI on Windows XP

Sub Volume Geometry

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.

Simulation Duration

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: 108).

-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).


This option will suppress starting of simulation all together. If you specify this option, all that will be done is model parsing.


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: 109).

-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).


This option will turn the full state checkpointing off.


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.

Sparse Output

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.


This will turn the sparse output format off (default for deterministic simulations).


This will turn the sparse output format on (default for stochastic simulations).

Visual Appearance

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.


This option will suppress launching of the OpenGL visualiser.


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).


This option will suppress launching of the progressbar.


This option will launch the progress bar once the simulation is started (default).

Deterministic mode

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.


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

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.

Starting from an old checkpoint

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.