XML
Cain stores models, methods, simulation output, and random number state
in an XML format. See the Cain XML File Format
section for the specification.
SBML
Cain can import and export SBML models. However, it has limited ability
to parse kinetic laws; complicated expressions may not parsed. In this case
you have to enter the propensity function in the Reaction Editor.
If the SBML model has reversible reactions, they will each be split into
two irreversible reactions. (The stochastic simulation algorithms only work
for irreversible reactions.) You will need to correct the propensity
functions. Also, only mass action
kinetic laws can be exported to SBML. Other kinetic laws are omitted.
Input for solvers.
For batch processing, you can export a text file for input to one of the
solvers. The solver inputs describe the model, the simulation method,
the random number state, and number of trajectories to generate.
The different categories of solvers require slightly different inputs.
However, the input for each of the solvers starts with the following:
<should print information> <number of species> <number of reactions> <list of initial amounts> <packed reactions> <list of propensity factors> <number of species to record> <list of species to record> <number of reactions to record> <list of reactions to record> <maximum allowed steps> <number of solver parameters> <list of solver parameters> <starting time>
To make the text processing easier and to make the files easier to read, each term in brackets occupies a single line. Note the following about the input fields:
<number of reactants> <index1> <stoichiometry1> ... <indexR> <stoichiometryR> <number of products> <index1> <stoichiometry1> ... <indexP> <stoichiometryP> <number of dependencies> <dependency1> ... <dependencyD>An empty set of reactants, products, or dependencies is indicated with a single zero.
Below are a couple examples of packed reactions (here we assume mass-action kinetic laws):
Next comes solver-specific data. There are four kinds of data that the various solvers generate:
<number of frames> <list of frame times>
<equilibration time> <recording time>
<number of frames> <list of frame times> <number of bins in histograms> <histogram multiplicity>
<equilibration time> <recording time> <number of bins in histograms> <histogram multiplicity>
Finally, one specifies the initial state of the Mersenne twister and the number of trajectories to generate.
<list of MT 19937 state> for each task: <number of trajectories>
The state of the Mersenne Twister 19937 is a list of 624, 32-bit unsigned integers followed by an array index that specifies the current position in the list. Thus the state is defined with 625 integers. When a solver is run in batch mode, the total number of trajectories is given on a single line. When Cain is driving the solvers, it repeatedly directs the solver to generate a small number of trajectories. In this way the GUI application can track the progress of the simulation and also manage multiple solver processes.
In Cain the solvers are grouped into five categories. Below we consider the specifics of the input data for each one.
Consider the following simple problem with one species and two reactions:
immigration 0 → X and death X → 0. Let the propensity
factors be 1 and 0.1, respectively. Let the initial population
of X be 10. We wish to use the direct method to simulate the process.
We let the system equilibrate for 100 seconds and then record the species
population and reaction counts for 20 seconds. We set the number of frames
to 11. Enter this model in Cain, set the number of trajectories to
2, and export it as a batch job with
the file name input.txt. To do this,
click the disk icon in the Launcher
panel. Below is the resulting data file (with most of the Mersenne Twister
state omitted.)
1 1 2 10 0 1 0 1 1 0 1 0 1.0 0.10000000000000001 1 0 2 0 1 0 0 0.0 11 100.0 102.0 104.0 106.0 108.0 110.0 112.0 114.0 116.0 118.0 120.0 1499117434 2949980591 ... 4162027047 3277342478 449 2
Solver output.
The different categories of solvers produce different output. Each
produce an information line that is either a blank line or a Python
dictionary that contains information about the method. If present, the
dictionary may be used to check consistency. This check is unecessary
when Cain is running simulations interactively, but is useful when
importing the results of batch jobs. When doing the latter the user
selects a model and method and then specifies files than contain
simulation output. By using the dictionary Cain can check that the
specified files actually correspond to the selected model and method.
Each format is specified below.
<dictionary of information> for each task: <number of trajectories> for each trajectory: <list of initial MT 19937 state> if successful: <blank line> <list of populations> <list of reaction counts> else: <error message> <list of final MT 19937 state>
<dictionary of information> for each task: <number of trajectories> for each trajectory: <list of initial MT 19937 state> if successful: <blank line> <list of initial amounts> <list of reaction indices> <list of reaction times> else: <error message> <list of final MT 19937 state>
for each task: <number of trajectories in task> <dictionary of information> if successful: <blank line> <total number of trajectories> <histogram multiplicity> for each frame: for each recorded species: <cardinality> <sumOfWeights> <mean> <summed second centered moment> <lower bound> <bin width> for each histogram: <list of weighted probabilities> else: <error message> <list of final MT 19937 state>
for each task: <number of trajectories in task> <dictionary of information> if successful: <blank line> <total number of trajectories> <histogram multiplicity> for each recorded species: <cardinality> <sumOfWeights> <mean> <summed second centered moment> <lower bound> <bin width> for each histogram: <list of weighted probabilities> else: <error message> <list of final MT 19937 state>
We can use the input file that we exported above to generate two trajectories with the direct method.
./solvers/HomogeneousDirect2DSearch.exe <input.txt >output.txtThe contents of the output file are shown below. The first line is blank. Again most of the Mersenne Twister state is omitted.
2 1499117434 2949980591 ... 4162027047 3277342478 449 15 13 10 10 11 8 7 8 9 10 9 102 97 105 102 106 106 108 108 112 111 113 115 115 118 116 118 119 120 121 121 122 123 78190480 1101697099 ... 623132007 3059824252 322 9 11 10 9 13 15 11 9 14 12 9 93 94 97 96 97 97 99 100 104 101 108 103 109 108 109 110 114 110 116 114 117 118 3440222609 2495225278 ... 3271950001 217431822 171