Difference between revisions of "The Magrathea Manual: Building Coordinated Agent Models"

From irefindex
 
(51 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
==The Magrathea Manual Contents==
 +
 +
[[The Magrathea Manual: Coordinated Agent Modelling Explained]]
 +
 +
[[The Magrathea Manual: Coordinated Agent Modelling By Example]]
 +
 +
[[The Magrathea Manual: Building Coordinated Agent Models]]
 +
 +
[[Magrathea Installation and Use]]
 +
 +
[[Example model files for Magrathea]]
 +
 +
 
==Making models==
 
==Making models==
  
Line 9: Line 22:
 
=== A simple example ===
 
=== A simple example ===
  
An example model.txt file is shown below in Figure 1.
+
An example model.txt file is shown below in the Figure below ('''An example model.txt file for Magrathea''').
  
 
The model.txt file is a text file and must be called “model.txt”.
 
The model.txt file is a text file and must be called “model.txt”.
Line 16: Line 29:
 
Any text in the file after the line
 
Any text in the file after the line
  
 +
<pre>
 
EOF
 
EOF
 +
</pre>
  
 
will be ignored.
 
will be ignored.
Line 22: Line 37:
 
There are two types of sections in a model file.  A section used to describe a type of molecule and create instances of that molecule type at the beginning of the simulation begins with the line:
 
There are two types of sections in a model file.  A section used to describe a type of molecule and create instances of that molecule type at the beginning of the simulation begins with the line:
  
 +
<pre>
 
[moleculeType]  
 
[moleculeType]  
 +
</pre>
  
 
and ends with the line
 
and ends with the line
  
 +
<pre>
 
[/moleculeType]
 
[/moleculeType]
 +
</pre>
  
 
A section that is used to describe a coordinator type and create instances of that coordinator at the beginning of the simulation begins with the line:
 
A section that is used to describe a coordinator type and create instances of that coordinator at the beginning of the simulation begins with the line:
  
 +
<pre>
 
[coordinatorType]
 
[coordinatorType]
 +
</pre>
  
 
and ends with the line
 
and ends with the line
  
 +
<pre>
 
[/coordinatorType]
 
[/coordinatorType]
 +
</pre>
 +
 +
=== Key-value format ===
 +
 +
Each line in these two sections types encodes a separate piece of information as a key-value pair.  So, for instance, members of the first molecule type are labeled “a” as indicated by the line
 +
 +
<pre>
 +
label a
 +
</pre>
 +
 +
In this line “label” is the key and “a” is the value.  Keys and their values are separated by white-spaces.  There may be several values specified for a given key.  The key is always the first block of text on a line. 
  
 
=== An example model.txt file for Magrathea ===
 
=== An example model.txt file for Magrathea ===
 
+
The following model file is explained in the next section.
 
<pre>
 
<pre>
 
###########
 
###########
Line 74: Line 107:
 
</pre>
 
</pre>
  
 
+
===A brief description of the example model.txt file===
=== Key-value format ===
 
 
 
Each line in these two sections types encodes a separate piece of information as a key-value pair.  So, for instance, members of the first molecule type are labeled “a” as indicated by the line
 
 
 
label a
 
 
 
In this line “label” is the key and “a” is the value.  Keys and their values are separated by white-spaces.  There may be several values specified for a given key.  The key is always the first block of text on a line. 
 
A brief description of the example model.txt file
 
  
 
The above example model file, specifies a simulation that has two molecule types and one coordinator type.
 
The above example model file, specifies a simulation that has two molecule types and one coordinator type.
Line 125: Line 150:
  
 
Screen shot of a simulation resulting from the example model.txt file
 
Screen shot of a simulation resulting from the example model.txt file
Insert screen shot here
+
 
 +
 
 +
[[Image:simple_example.jpg|800x800px]]
  
 
== Describing molecule types ==
 
== Describing molecule types ==
Line 157: Line 184:
  
 
=== Molecule parameters ===
 
=== Molecule parameters ===
 +
 +
 +
====Appearances====
  
 
{|border="1" cellpadding="2"  
 
{|border="1" cellpadding="2"  
Line 228: Line 258:
 
| example||color .81 .60 .21
 
| example||color .81 .60 .21
 
|}
 
|}
Notes: A color may be specified by the user for drawing molecules of this molecule type.
+
Notes: A color may be specified by the user for drawing molecules of this molecule type.  Color is specified as a vector of Red, Green and Blue percentages (expressed as a decimal).  See http://www.december.com/html/spec/colorper.html for a list of RGB percentage codes.
  
  
Line 296: Line 326:
 
Notes: Opacity can be set to some value below 1 in order to make the molecule somewhat transparent.  This allows the user to see through molecules of a certain type that might otherwise block views to other parts of the simulation.
 
Notes: Opacity can be set to some value below 1 in order to make the molecule somewhat transparent.  This allows the user to see through molecules of a certain type that might otherwise block views to other parts of the simulation.
  
 
+
====Neighborhood====
 
{|border="1" cellpadding="2"  
 
{|border="1" cellpadding="2"  
 
| align="center" style="background:yellow" colspan="2"|'''show-neighbor-lines'''
 
| align="center" style="background:yellow" colspan="2"|'''show-neighbor-lines'''
Line 304: Line 334:
 
| format||show-neighbor-lines [1,0]
 
| format||show-neighbor-lines [1,0]
 
|-
 
|-
| description||A Boolean flag indicating that lines are to be drawn between the molecule and its neighbor (as determined by the molecule’s neighborhood-size).
+
| description||A Boolean flag indicating that lines are to be drawn between the molecule and its neighbor (as determined by the molecule’s ).
 
|-
 
|-
 
| required||no
 
| required||no
Line 322: Line 352:
 
| format||neighborhood-size [float]
 
| format||neighborhood-size [float]
 
|-
 
|-
| description||A description of the molecule’s neighborhood size.
+
| description||The radius of the molecule’s neighborhood size.
 
|-
 
|-
 
| required||no
 
| required||no
Line 352: Line 382:
 
If dynamic-neighborhood-sizing is set to 1 (TRUE) then the molecule’s neighborhood size will increase by 1 unit per simulation iteration until all of its channels are occupied by some coordinator.  Values other than 1 are interpreted as 0 (FALSE).
 
If dynamic-neighborhood-sizing is set to 1 (TRUE) then the molecule’s neighborhood size will increase by 1 unit per simulation iteration until all of its channels are occupied by some coordinator.  Values other than 1 are interpreted as 0 (FALSE).
  
 
+
====Feature-state pairs====
 
{|border="1" cellpadding="2"  
 
{|border="1" cellpadding="2"  
 
| align="center" style="background:yellow" colspan="2"|'''feature'''
 
| align="center" style="background:yellow" colspan="2"|'''feature'''
Line 376: Line 406:
 
simply indicates that there is some feature (with id 234 and label Tyr234) that can exist in one of many multiple states (see feature-state below).  For protein molecules, amino acids numbers could be used as feature identifiers for their corresponding amino acids; however, this is not required.  Any integer may be used for a feature identifier so long as that integer is used only once for any given molecule.
 
simply indicates that there is some feature (with id 234 and label Tyr234) that can exist in one of many multiple states (see feature-state below).  For protein molecules, amino acids numbers could be used as feature identifiers for their corresponding amino acids; however, this is not required.  Any integer may be used for a feature identifier so long as that integer is used only once for any given molecule.
  
N.B. features and feature-values are not used by Magrathea right now, but may be used in future to present information to the user.  They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).
+
N.B. features and feature-states (below) are not used by magrathea right now, but may be used in future to present information to the user.  They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).
  
  
Line 401: Line 431:
 
Note: features and feature-values are not used by Magrathea, but may be used in future to present information to the user.  They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).
 
Note: features and feature-values are not used by Magrathea, but may be used in future to present information to the user.  They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).
  
 
+
====Coordinators====
 
{|border="1" cellpadding="2"  
 
{|border="1" cellpadding="2"  
 
| align="center" style="background:yellow" colspan="2"|'''coordinator'''
 
| align="center" style="background:yellow" colspan="2"|'''coordinator'''
Line 426: Line 456:
  
 
would be used to specify a molecule type that could pair (mutually exclusively) with either coordinator 3 or 4 using channel 1 and (at the same time) could pair with coordinator 5 using channel 2.
 
would be used to specify a molecule type that could pair (mutually exclusively) with either coordinator 3 or 4 using channel 1 and (at the same time) could pair with coordinator 5 using channel 2.
The abstract ideas of channels and coordinator are more thoroughly explained in previous sections of this manual.
+
 
  
  
Line 444: Line 474:
 
| example||resident-compartment-type 4
 
| example||resident-compartment-type 4
 
|}
 
|}
Notes: Spherical point coordinators may be used to represent compartments.  At the beginning of a simulation, any molecules found inside a coordinator compartment will be kicked out unless this flag has been set indicating that the molecule may reside in that compartment type (the coordinator id is used to specify the compartment type).  If a molecule is a resident of a compartment, it will move randomly within the space of that compartment until it encounters the inside face of the compartment.  Collisions with the inside face of a compartment will result in the molecule being repelled (contained) back towards the center of the compartment.
+
Notes: Spherical point coordinators may be used to represent compartments.  At the beginning of a simulation, any molecules found inside a coordinator compartment will be kicked out unless this flag has been set indicating that the molecule may reside in that compartment type (the coordinator type id is used to specify the compartment type).  If a molecule is a resident of a compartment, it will move randomly within the space of that compartment until it encounters the inside face of the compartment.  Collisions with the inside face of a compartment will result in the molecule being repelled (contained) back towards the center of the compartment.
  
 
It is very important that the isSizeDynamic flag be set to 1 for coordinators that are used to represent compartments.  If not, the size and shape of the coordinator rendered in the simulation is meaningless (it is drawn only to mark the point-location of the coordinator).  When isSizeDynamic is TRUE, the coordinator is drawn as a sphere and its size reflects the radius of the imaginary sphere around the coordinator centre that maintains the offset distance of member molecules from the coordinator.  This offset distance is also used to determine whether molecules are inside or outside the compartment.
 
It is very important that the isSizeDynamic flag be set to 1 for coordinators that are used to represent compartments.  If not, the size and shape of the coordinator rendered in the simulation is meaningless (it is drawn only to mark the point-location of the coordinator).  When isSizeDynamic is TRUE, the coordinator is drawn as a sphere and its size reflects the radius of the imaginary sphere around the coordinator centre that maintains the offset distance of member molecules from the coordinator.  This offset distance is also used to determine whether molecules are inside or outside the compartment.
 +
 +
====Molecular Rules====
 +
Note: For the most part, rules should be encoded using Coordinator Rules.  However, there are special cases where rules need to be specified for '''single molecules that are not associated with a coordinator'''.  In these cases, Molecular Rules can be used.
  
  
Line 452: Line 485:
 
| align="center" style="background:yellow" colspan="2"|'''[rule] …[/rule]'''
 
| align="center" style="background:yellow" colspan="2"|'''[rule] …[/rule]'''
 
|-
 
|-
| key||See below.  Multiple keys are associated with this subsection including id, if, then, and parameters
+
| key||See below.  Multiple keys are associated with this subsection including id, if, competitve-with, then, and parameters
 
|-
 
|-
 
| format||
 
| format||
Line 490: Line 523:
 
</pre>
 
</pre>
 
|}
 
|}
 +
 +
Notes: The [rule] … [/rule] subsection of molecules is used to define events that occur to a single molecule.  Multiple rule subsections may be associated with one molecule.  Each rule is defined using multiple lines with keywords id, if, competitive-with, then and parameters.  These keywords and their line formats are described below.
 +
 +
In general, each rule has:
 +
 +
1)  an identifier that is unique to the molecule
 +
 +
2) a set of prerequisite conditions (specified by if lines) that must be met in order for
 +
 +
3) some set of events (specified by then lines) that will occur with some probability according to
 +
 +
4) a set of parameters specified on one or more parameter lines.
 +
 +
 +
See [[Example_model_files_for_Magrathea#Example 6.5| this example]] for an example model file that uses molecule rules.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] id [/rule]'''
 +
|-
 +
| key||id
 +
|-
 +
| format||id [integer]
 +
|-
 +
| description||Used to identify a rule for a molecule
 +
|-
 +
| required||yes
 +
|-
 +
| default value||there are no default rules
 +
|-
 +
| example||id 1
 +
|}
 +
Notes: The id line is an integer identifier for a rule.  It must be the first line of the rule subsection and it must be unique to the rules defined for the molecule to which it belongs.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] if [/rule]'''
 +
|-
 +
| key||if
 +
|-
 +
| format||if [string]
 +
|-
 +
| description||Used to define a prerequisite condition for some event.  The precondition is expressed as the molecule id with or without some feature-state specification
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default values
 +
|-
 +
| example||if 2.1.1
 +
|}
 +
Notes: The if line is used to define a prerequisite condition for some event.  The precondition is expressed as the molecule id with or without some feature-state specification. The line contains a single value that is a dot delimited list of integers.  For example,
 +
 +
<pre>
 +
if 2.1.1.2.4
 +
</pre>
 +
 +
This dot-delimited condition is of the form specified in the next table.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:grey" colspan="3"|'''if line format'''
 +
|-
 +
| position||Meaning and possible values||Example
 +
|-
 +
| 1||Required molecule type (an integer corresponding to a molecule type id).  See “id” key under [moleculeType]||2
 +
|-
 +
| 2 + 2n||Feature identifier specified by some integer.||1
 +
|-
 +
| 3 + 2n||Required state of feature (previous position) specified by some integer. ||1
 +
|}
 +
Note: n is an integer from 0, 1, 2… specifying a feature-state condition (see explanation below).
 +
 +
So the first three numbers in the example above
 +
 +
<pre>
 +
if 2.1.1
 +
</pre>
 +
 +
mean that the rule applies for each copy of molecule type 2, with feature 1 in state 1.  And the following 2.4 (positions 4 - 5) would indicate that the molecule must have feature 2 in state 4.
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] competitive-with [/rule]'''
 +
|-
 +
| key||competitive-with
 +
|-
 +
| format||competitive-with [integer]
 +
|-
 +
| description||Used to point out that the present rule and the rule having the specified id cannot occur simultaneously.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default values
 +
|-
 +
| example||competitive-with 1
 +
|}
 +
Notes: The competitive-with line specifies the identifier for a rule that is competitive to the current rule. That means that the rule including this line and the rule having the specified id can not occur simultaneously, even if the specified conditions in the if line were met, so the algorithm will choose one of them or neither of them, but never both. This is useful when having molecules that can follow different reactions.
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] then [/rule]'''
 +
|-
 +
| key||then
 +
|-
 +
| format||then [string, integer] [string] [string, integer]
 +
|-
 +
| description||Used to define events that occur to a given molecule
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default events
 +
|-
 +
| example||then 1 is-destroyed
 +
|}
 +
Notes:The then line is used to define events that may occur to a given molecule if the condition defined by the if line is met.  There are several different possibilities for this line that are differentiated by the second string value.  They are:
 +
 +
<pre>
 +
then 6.1 is-created-at-location-of 6
 +
</pre>
 +
 +
In this case, 1 instance of molecule type 6 is created at the same location of the molecule.
 +
 +
<pre>
 +
then 1 is-destroyed
 +
</pre>
 +
 +
In this case, the current molecule (1) is destroyed.
 +
 +
<pre>
 +
then 1 changes-state-to 1.2
 +
</pre>
 +
 +
In this case, the current molecule (tag 1) will change state according to the state description 1.2 (feature 1 changes state to state 2). Multiple feature–state changes may be specified on one line; i.e., 1.2.4.5.6.33 means that feature 1 assumes state 2, feature 4 assumes state 5 and feature 6 assumes state 33. 
 +
 +
<pre>
 +
then 1 changes-colour-to .1:.32:.11
 +
</pre>
 +
 +
In this case, the molecule will change to the colour specified by .1:.32:.11 (the colons separate three float values in the RGB colour description; i.e. .1 .32 .11).
 +
 +
Currently, translocations are not supported as events for molecule rules (as they are for coordinator rules).
 +
 +
The reader should note carefully that there are minor but important differences between this format and that format used for then lines in coordinators (which have tags).
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] parameters [/rule]'''
 +
|-
 +
| key||parameters
 +
|-
 +
| format||parameters [string] [float]
 +
|-
 +
| description||Used to define parameters for the event under consideration
 +
|-
 +
| required||no
 +
|-
 +
| default value||parameters p 1.0
 +
|-
 +
| example||parameters kf 0.07
 +
|}
 +
Notes: The parameters line is used to specify the value of the parameters for the event that will occur.  The string value will represent the identifier for that parameter while the float value will represent the probability for the event to take place given that all conditions were met. The default parameters value is 1.0, meaning that events will occur if all conditions are met.
 +
 +
 +
 +
====Instantiation====
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''instantiate'''
 +
|-
 +
| key||instantiate
 +
|-
 +
| format||see below
 +
|-
 +
| description||Creates instances of molecules and assigns locations in the
 +
|-
 +
| simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default instantiations of molecule types
 +
|-
 +
| example||instantiate 4 random spherical volume 10 15 10 10
 +
|-
 +
|}
 +
Notes:
 +
The instantiate line is the last line listed for a molecule type description.  This line creates instances of molecules and assigns them positions within the simulation.  The instantiation line is composed of up to 14 white-space delimited fields.  These fields and their formats are described in the table below, Specific examples of their use are described next.
 +
 +
The simplest case is to create one or more molecules at some determined point in space using the line:
 +
 +
<pre>
 +
instantiate 1 determined point - 10 15 10
 +
</pre>
 +
 +
This will create 1 molecule at a determined point (i.e. non-random) in the simulation with coordinates 10 15 10.
 +
 +
However, a set of molecules could also be created and given random locations within the volume of a sphere using
 +
 +
<pre>
 +
instantiate 4 random spherical volume 10 15 9 5
 +
</pre>
 +
 +
Here, 10 15 9 specifies the x,y,z coordinates for the centre of the sphere and 5 specifies the radius of the sphere.
 +
 +
The molecules could also be distributed on the surface of the sphere (instead of within its volume) using the line:
 +
 +
<pre>
 +
instantiate 4 random spherical surface 10 15 9 5
 +
</pre>
 +
 +
Or the distribution could be applied to a plane using:
 +
 +
<pre>
 +
instantiate 100 random planar - 10 15 22 5 0 1 0
 +
</pre>
 +
 +
Here 10 15 22 specifies the position of the plane in space, 5 represents the maximum distance from this point that the molecules will be distributed to (radius) and 0 1 0 describes a normal to the plane.  In a breve simulation, a normal of 1 0 0 points up along the x axis, a normal of
 +
0 1 0 points along the y axis and a normal of 0 0 1 points along the z axis in the positive direction.  The – in field 5 is used as a placeholder since the centres of the molecules will be aligned with the plane and neither “volume” nor “surface” apply.
 +
 +
 +
Lastly, a distribution may be applied to the surface or volume of a cylinder using
 +
 +
<pre>
 +
instantiate 100 random cylindrical volume 10 15 22 5 0 1 0 35
 +
</pre>
 +
 +
Here, 10 15 22 specifies the centre of the base of the cylinder.  0 1 0 specifies a normal vector to the base of the cylinder.  5 is the radius of the cylinder and 35 is the height of the cylinder.
 +
 +
Feature-state information may also be specified at the time of instantiation using a feature.state vector in the fourteenth field of the instantiate line.  For example:
 +
 +
<pre>
 +
instantiate 10 random spherical volume 10 15 10 1 - - - - 1.1.2.0
 +
</pre>
 +
 +
will set feature 1 to state 1 and feature 2 to state 0 for this set of molecules.  See feature and feature-state above.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:lightgrey" colspan="4"|'''Format of the instantiation line'''
 +
|-
 +
!position
 +
!possible values
 +
!colspan="2"|description
 +
|-
 +
| 1
 +
|instantiate
 +
|colspan="2"|This is the key that indicates an instantiation description is to follow.
 +
|-
 +
| 2
 +
|integer
 +
|colspan="2"|Number of instances to be created.
 +
|-
 +
| 3
 +
|random determined
 +
|colspan="2"|New instances may be distributed randomly or at a determined location in space.
 +
|-
 +
| 4
 +
|point
 +
planar
 +
 +
spherical
 +
 +
cylindrical
 +
 +
|colspan="2"|New instances are assigned some determined “point” location or a random location in a plane, sphere or cylinder.
 +
|-
 +
| 5
 +
|volume
 +
 +
surface
 +
 +
-
 +
 +
|colspan="2"|Where the random distribution is specified for a solid, new instances may be distributed within the volume or on the surface of that solid. A – is used if the value is not applicable.
 +
|-
 +
| 6
 +
|float
 +
|x coordinate
 +
|rowspan=3|
 +
x, y and z specify the position of either:
 +
 +
a determined point in space or
 +
 +
the centre of a plane or
 +
 +
the centre of a sphere or
 +
 +
the centre of a cylinder’s base
 +
 +
(depending on the value given in
 +
field 4)
 +
 +
|-
 +
| 7||float||y coordinate
 +
|-
 +
| 8||float||z coordinate
 +
|-
 +
| 9
 +
|float
 +
|colspan="2"|radius if field 4 is planar, spherical or cylindrical
 +
|-
 +
| 10
 +
|float
 +
|x coordinate
 +
|rowspan=3|
 +
x, y and z specify vector corresponding to a normal to a plane or to the base of a cylinder (depending on the value given in field 4).
 +
|-
 +
| 11||float||y coordinate
 +
|-
 +
| 12||float||z coordinate
 +
|-
 +
| 13
 +
|float
 +
|colspan="2"|length if field 4 specifies a cylinder
 +
|-
 +
| 14
 +
|string
 +
|colspan="2"|
 +
State information for the molecule.  A series of two numbers (separated by dots) is used to specify the features and their states for the molecules being instantiated (see feature and feature-state above).  For example, 1.0.2.3 indicates that feature 1 is in state 0 and feature 2 is in state 3.
 +
|}
 +
 +
 +
'''Using multiple instantiate lines'''
 +
 +
Multiple instantiate lines may be used for creating multiple distributions of the same molecule (or coordinator) type at different locations within the simulation.  Features of the molecule type may be altered between instantiate lines (see below for an example); the last description of a feature listed will be applied to the next instantiation.  For example:
 +
 +
<pre>
 +
[moleculeType]
 +
id 1
 +
label molecule_a
 +
color .81 .60 .21
 +
shape Sphere 1
 +
draw-as-point 0
 +
opacity 1
 +
show-neighbor-lines 0
 +
neighborhood-size 5
 +
dynamic-neighborhood-sizing 0
 +
coordinator 1 3
 +
instantiate 10 random spherical volume 10 30 10 5
 +
color .99 .99 .99
 +
instantiate 4 random spherical volume 10 20 10 5
 +
[/moleculeType]
 +
</pre>
 +
 +
The above moleculeType description will create 14 molecules of type 1; however,
 +
4 of the molecules will have a generally different starting location and a different color.
 +
 +
 +
 +
==Describing coordinator types==
 +
 +
An example coordinator type description is given below in the Figure.
 +
Each of the key-value entry lines are described in a separate table below.
 +
 +
=== An example coordinator type description ===
 +
 +
<pre>
 +
[coordinatorType]
 +
id 4
 +
label lipid_raft_assembly
 +
color .81 .60 .21
 +
draw-as-point 0
 +
opacity 0.1
 +
geometricType point
 +
shape Cube .2 .2 .2
 +
isCompartment 0
 +
orientation vertex 0 1 0 pointing-at 0 1 0
 +
isCreationDynamic 1
 +
isMobile 1
 +
isSizeDynamic 1
 +
molecule 2 1000
 +
instantiate 0 random spherical volume 10 18 10 1
 +
[rule]
 +
id 1
 +
if 1.1.1
 +
if 2.2.1
 +
then 6.1 is-created-at-location-of 1
 +
then 1 is-destroyed
 +
then 1 changes-state-to 1.2
 +
then 1 changes-colour-to .1:.32:.11
 +
then 1 translocates-to-compartment-of-molecule 2
 +
parameters p 1
 +
[/rule]
 +
[/coordinatorType]
 +
</pre>
 +
 +
=== Coordinator parameters ===
 +
 +
====Appearances====
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''id'''
 +
|-
 +
| key||id
 +
|-
 +
| format||id [integer]
 +
|-
 +
| description||A unique identifier for this coordinator type
 +
|-
 +
| required||yes
 +
|-
 +
| default value||not applicable
 +
|-
 +
| example||id 1
 +
|}
 +
Notes: Id is usually the first key-value pair specified for a coordinatorType.  This id is used to uniquely refer to this coordinator type in other parts of the model file.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''label'''
 +
|-
 +
| key||label
 +
|-
 +
| format||label [string]
 +
|-
 +
| description||A label for the coordinator type.
 +
|-
 +
| required||no
 +
|-
 +
| default value||coordinator
 +
|-
 +
| example||label complex_ab
 +
|}
 +
Notes: The label line allows the user to give a name to all coordinators of this coordinator type.  The name will not appear during the simulation unless the user clicks on the coordinator during the simulation. Including spaces in a coordinator type name will truncate the name at the space. 
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''color'''
 +
|-
 +
| key||color
 +
|-
 +
| format||color [0…1] [0…1] [0…1]
 +
|-
 +
| description||A description of the color used to draw this coordinator type.
 +
|-
 +
| required||no
 +
|-
 +
| default value||some randomly chosen color
 +
|-
 +
| example||color .81 .60 .21
 +
|}
 +
Notes: A color may be specified by the user for drawing coordinators of this coordinator type.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''draw-as-point'''
 +
|-
 +
| key||draw-as-point
 +
|-
 +
| format||draw-as-point [1 or 0]
 +
|-
 +
| description||A Boolean flag indicating that the coordinator is to be drawn as a point.
 +
|-
 +
| required||no
 +
|-
 +
| default value||draw-as-point 0
 +
|-
 +
| example||draw-as-point 1
 +
|}
 +
Notes: If draw–as-point is set to 1 (TRUE) then the coordinator will appear in the simulation as a point.  The radius will still be as specified in the shape line.  This flag is used to speed up the simulation by reducing the amount of required rendering.  It may also be used to hide coordinator types that are not of interest to the user.  Values other than 1 are interpreted as 0 (FALSE).
 +
 +
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''opacity'''
 +
|-
 +
| key||opacity
 +
|-
 +
| format||opacity [0…1]
 +
|-
 +
| description||A description of how opaque the coordinator should appear (where 0 is transparent and 1 is totally opaque).
 +
|-
 +
| required||no
 +
|-
 +
| default value||opacity 1
 +
|-
 +
| example||opacity 0.1
 +
|}
 +
Notes: Opacity can be set to some value below 1 in order to make it somewhat transparent.  This allows the user to see through coordinators of a certain type that might otherwise block views to other parts of the simulation.  This is particularly useful when the coordinator is used to describe a compartment in which molecules of interest are residing.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''geometricType'''
 +
|-
 +
| key||geometricType
 +
|-
 +
| format||geometricType [point or plane or line]
 +
|-
 +
| description||Specifies if the coordinator is a point, plane or line.
 +
|-
 +
| required||no
 +
|-
 +
| default value||geometricType point
 +
|-
 +
| example||geometricType plane
 +
|}
 +
Notes:  Coordinators come in three geometric types; point, plane and line.  This geometricType dictates how a member molecule will move if it joins the coordinator. 
 +
 +
If a molecule joins a point coordinator, it will move towards the centre of the shape that is used to mark the coordinators position (see shape below).  As molecules join the coordinator, the coordinator will grow into an imaginary sphere.  The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules.  All member molecules will maintain some distance from the centre of the coordinator such that they will be on the surface of this sphere.  Non-member molecules that collide with the outside surface of a point coordinator will be deflected away from the coordinator.  Non-member molecules that are resident to a compartment defined by a point coordinator (see resident-compartment-type under moleculeType) will be deflected towards the interior of the coordinator. 
 +
 +
If a molecule joins a plane coordinator, it will move to the closest point on the surface of the plane described under shape.  For example:
 +
 +
<pre>
 +
shape Cube 99 .2 100
 +
</pre>
 +
 +
Once the molecules reaches this “plane”, it will move randomly in the plane.  The molecule’s distance from the centre of the plane will be constrained by the z dimension of the plane (in the above case, it will remain within 100/2 = 50 units of the centre of the plane. A plane coordinator could be used to represent a section of membrane.  In this case, the settings
 +
 +
<pre>
 +
orientation vertex 0 1 0 pointing-at 0 1 0
 +
isCreationDynamic 0
 +
isMobile 0
 +
isSizeDynamic 0
 +
</pre>
 +
 +
will also be used (see below) to (a) specify the orientation of the membrane, (b) to ensure that the membrane is never destroyed during the simulation, (c) to keep the membrane immobile during the simulation and (d) to maintain the size of the membrane section respectively.
 +
 +
Non-member molecules that collide with the outside surface of a plane coordinator will be deflected away from the plane.
 +
 +
Lines coordinators must be described using the “Cube” shape (see below), where the first coordinate will represent the length of the line and the other two coordinates will be a width and height that allow us to see the line. For example:
 +
 +
<pre>
 +
shape Cube 60 .4 .4
 +
</pre>
 +
 +
If a molecule joins a Line coordinator, it will move to the closest point on that line and move randomly along that line. Its motion along the line will be constrained to the length of the line. A Line coordinator could be used to represent cytoskeleton filaments (actin filaments, intermediate filaments, microtubules).
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''shape'''
 +
|-
 +
| key||shape
 +
|-
 +
| format
 +
|shape Sphere [float] [float]
 +
 +
shape Cube [float] [float] [float]
 +
|-
 +
| description||A description of the shape used to draw this coordinator type.
 +
|-
 +
| required||no
 +
|-
 +
| default value||Cube 1.0 1.0 1.0
 +
|-
 +
| example||shape Sphere 0.1
 +
|-
 +
| example||shape Sphere 0.5
 +
|-
 +
| example||shape Cube 100 0.2 101
 +
|}
 +
 +
Notes:  Two shapes may be used to draw a coordinator: a sphere or a cube. Point coordinators can be represented as either a sphere or a cube.  Plane and Line coordinators must always be represented as Cubes.
 +
 +
Point coordinators are usually drawn as a sphere.  Only one additional float value must be given to specify the radius of the sphere.  Point coordinators may optionally be drawn as a Cube so they are more easily distinguished from molecules.  The point coordinator will appear as this shape and size regardless of how many molecules join it.  However, the molecules will be offset from the centre of the coordinator by some distance such that they will appear to be assembled on the surface of an imaginary sphere surrounding the point coordinator.  The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules.  If the line
 +
 +
<pre>
 +
isSizeDynamic 1
 +
</pre>
 +
 +
is included, the size of the coordinator will grow (starting from its initial radius) to match this imaginary sphere. ''It is very important'' to set this flag in those cases where a point coordinator represents a compartment.  If isSizeDynamic is set to 1, the user should choose to represent the point coordinator as a Sphere and not a Cube. 
 +
 +
Plane coordinators are drawn as Cubes where the x, y and z coordinates are interpreted as length, thickness and width.  Thickness (y) is present only for the purposes of visualizing the plane and member molecules will move in the xz plane regardless of the value of y.  Note that the z coordinate is interpreted as a radius from the centre of the coordinator; member molecules cannot move past this radial boundary.  Planes may be oriented to some normal using the orientation line. 
 +
 +
Line coordinators use a Cube shape as well. The x dimension will be interpreted as length while the y and z dimension will be used to make the line visible. This does not mean that lines along the x axis are the only possibility. Lines may be oriented to any direction using the orientation line.
 +
 +
If the line
 +
 +
<pre>
 +
isSizeDynamic 1
 +
</pre>
 +
 +
is included, the size of the coordinator will grow by adding the diameter of each new molecule member to the length of the line.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''isCompartment'''
 +
|-
 +
| key||isCompartment
 +
|-
 +
| format||isCompartment [0,1]
 +
|-
 +
| description||Indicates whether this coordinator represents a compartment or barrier within a compartment.
 +
|-
 +
| required||no
 +
|-
 +
| default value||isCompartment 0
 +
|-
 +
| example||isCompartment 1
 +
|}
 +
Notes:  A spherical coordinator may be used to represent a compartment that molecules can reside in and that molecules can translocate into and out of.  A planar coordinator also acts as a barrier that molecules can translocate across.  In either of these cases, the line
 +
 +
<pre>
 +
isCompartment 1
 +
</pre>
 +
 +
should be included.
 +
 +
Molecules that are part of these compartment coordinators will have a feature (feature id 99999) set to the coordinator type id when they become assembled with the coordinator.  This allows rules to be written that specify that a molecule must be part of some compartment coordinator in order to participate in some rule.  See rule below for examples.
 +
 +
A molecule should only belong to one coordinator that is a compartment.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''orientation'''
 +
|-
 +
| key||orientation
 +
|-
 +
| format||orientation vertex [vector] pointing-at [vector]
 +
|-
 +
| description||Specifies the orientation of a plane or line coordinator.
 +
|-
 +
| required||no
 +
|-
 +
| default value||orientation vertex 0 1 0 pointing-at 0 1 0
 +
|-
 +
| example||orientation vertex 0 1 0 pointing-at 1 0 0
 +
|}
 +
Notes:  Orientation is used in combination with plane and line coordinators. By default, a plane coordinators shape will be positioned in the xz plane and a lines shape will be positioned in the x axis.  This can be altered by pointing the plane or line along some other normal using the line: 
 +
 +
<pre>
 +
orientation vertex 0 1 0 pointing-at 1 0 0
 +
</pre>
 +
 +
where 0 1 0 is some vertex on (relative to) the shape used to draw the coordinator.  The vertex is used in combination with the coordinators position to create a vector.  This vector is then “pointed at” some point in the simulation space (specified here as 1 0 0).  The example above will orient the plane so its surface “points” or is orthogonal to the x axis.  Multiple instances of a plane coordinator can be created with altered orientations to make a box like structure representing the simulation boundaries like this:
 +
 +
<pre>
 +
[coordinatorType]
 +
id 10
 +
label simulation-container
 +
color .383 .466 .561
 +
opacity 0.1
 +
geometricType plane
 +
shape Cube 100 .2 100
 +
neighborhood-size 10
 +
isCreationDynamic 0
 +
isMobile 0
 +
#west wall
 +
orientation vertex 0 1 0 pointing-at 1 0 0
 +
instantiate 1 determined point  - 0 50 50
 +
#east wall
 +
orientation vertex 0 1 0 pointing-at -1 0 0
 +
instantiate 1 determined point  - 100 50 50
 +
#north wall
 +
orientation vertex 0 1 0 pointing-at 0 0 1
 +
instantiate 1 determined point  - 50 50 0
 +
#south wall
 +
orientation vertex 0 1 0 pointing-at 0 0 -1
 +
instantiate 1 determined point  - 50 50 100
 +
[/coordinatorType]
 +
</pre>
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''isCreationDynamic'''
 +
|-
 +
| key||isCreationDynamic
 +
|-
 +
| format||isCreationDynamic [0,1]
 +
|-
 +
| description||A Boolean flag specifying whether the creation (and destruction) of the coordinator is dynamic.
 +
|-
 +
| required||no
 +
|-
 +
| default value||isCreationDynamic 1
 +
|-
 +
| example||isCreationDynamic 0
 +
|}
 +
Notes:  Point coordinators that are used to represent complexes of molecules or single interactions are normally dynamically created; i.e., they are not instantiated by an instantiate line at the beginning of the simulation.  Instead, they are created as member molecules of the coordinator as those molecules detect one another within one-another’s neighborhoods.  Such a coordinator will only form if at least two member molecules are present to nucleate its formation.  If a coordinator forms and subsequently loses members such that it has only one or no members, it destroys itself.  This is the default behaviour of all point, plane and line coordinators.  If the line,
 +
 +
<pre>
 +
isCreationDynamic 0
 +
</pre>
 +
 +
is included, then only those coordinators that are instantiated at the beginning of the simulation will be created and they will persist throughout the simulation (i.e. they cannot be destroyed).  This setting is commonly used for plane coordinators used to represent membranes.  Note that all values other than 1 will be treated as zero (FALSE).
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''isMobile'''
 +
|-
 +
| key||isMobile
 +
|-
 +
| format||isMobile [0,1]
 +
|-
 +
| description||A Boolean flag specifying whether the coordinator is allowed to move during the simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value||isMobile 1
 +
|-
 +
| example||isMobile 0
 +
|}
 +
Notes:
 +
Point coordinators that are used to represent complexes of molecules or single interactions are normally mobile; i.e., at each iteration they move to some position that is central (average) to the positions of all member molecules.
 +
 +
Plane coordinators (used to represent membranes) and Line coordinators (used to represent cytoskeleton) are usually created once at the beginning of the simulation at some point in space. Using the line
 +
 +
<pre>
 +
isMobile 0
 +
</pre>
 +
 +
will ensure that the plane coordinator remains in this position for the duration of the simulation.  Note that all values other than 1 will be treated as zero (FALSE).
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''isSizeDynamic'''
 +
|-
 +
| key||isSizeDynamic
 +
|-
 +
| format||isSizeDynamic [0,1]
 +
|-
 +
| description||A Boolean flag specifying whether the size of the coordinator can change. 
 +
|-
 +
| required||no
 +
|-
 +
| default value||isSizeDynamic 0
 +
|-
 +
| example||isSizeDynamic 1
 +
|}
 +
Notes:
 +
Point coordinators that are used to represent complexes of molecules or single interactions are normally statically sized; i.e., the initial size specified at the beginning of the simulation (under shape) is maintained throughout the simulation.  In these cases, the shape of the coordinator is used only to mark the position of the coordinator.  However, in cases where a point coordinator is used to represent a compartment, the size of the coordinator can be used to represent the boundaries of that compartment. Member molecules of the compartment coordinator will be offset from the centre of the coordinator by some distance such that they will appear to be assembled in the surface of an imaginary sphere surrounding the point coordinator.  The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules.  If the line
 +
 +
<pre>
 +
isSizeDynamic 1
 +
</pre>
 +
 +
is included, the size of the coordinator will grow (starting from its initial radius) to match this imaginary sphere.  This flag is essential for compartment coordinators if they are to include or exclude molecules because the coordinator shape handles collisions with all molecules and determines whether they should be kept outside or inside the compartment.
 +
 +
Plane and line coordinators can also make use of this flag.  As molecules are added to a plane coordinator, the surface area of the plane will increase to account for the added cross-sectional area of the molecule. In a line coordinator, the length of the line will increase an amount equal to the diameter of each recently added molecule.
 +
 +
====Molecules====
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''molecule'''
 +
|-
 +
| key||molecule
 +
|-
 +
| format||molecule [integer] [integer] [integer]
 +
|-
 +
| description||A description of the potential member molecules for the coordinator along with their stoichiometries and whether their assembly into this coordinator is unconditional.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default molecule assignments but the third value (whether assembly into this coordinator is unconditional) has a default value of 1 if it is not specified
 +
|-
 +
| example||molecule 1 2
 +
|}
 +
Notes:  A set of potential member molecules is specified using one or more molecule lines.  Each line lists a moleculeType identifier (see id under moleculeType) and then a maximum allowed stochiometry for that molecule type.  So for example, the line
 +
 +
<pre>
 +
molecule 1 2
 +
</pre>
 +
 +
allows for up to two instances of moleculeType 1 to join the coordinator.
 +
 +
The above line is equivalent to
 +
 +
<pre>
 +
molecule 1 2 1
 +
</pre>
 +
 +
Because the third value has a default value of one if not specified.  This value (either 1 or 0) indicates whether the molecule type can assemble unconditionally into the coordinator (default is 1; meaning yes).
 +
However, if the line is
 +
 +
<pre>
 +
molecule 1 2 0
 +
</pre>
 +
 +
then the assembly of the molecule is dependent on the presence of other molecules (that must co-assemble with the molecule or that must already be present as members of the coordinator in order for the molecule to assemble .  This dependency is described by a rule (see below).
 +
 +
====Coordinator Rules====
 +
 +
Note: For the most part, rules should be encoded using Coordinator Rules.  However, there are special cases where rules need to be specified for '''single molecules that are not associated with a coordinator'''.  In these cases, Molecular Rules can be used (see above).
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] …[/rule]'''
 +
|-
 +
| key||See below.  Multiple keys are associated with this subsection including id, time, if, competitve-with, then, and parameters
 +
|-
 +
| format||
 +
<pre>
 +
[rule]
 +
id [integer]
 +
time [float] optional
 +
if [string]
 +
.
 +
.
 +
competitive-with [integer]
 +
.
 +
.
 +
then [string or integer] [string] [string or integer]
 +
.
 +
.
 +
parameters [string] [float]
 +
.
 +
.
 +
[/rule]
 +
</pre>
 +
|-
 +
| description||Used to define events that occur between members of a coordinator.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default rules
 +
|-
 +
| example||
 +
<pre>
 +
[rule]
 +
id 1
 +
if 1.1.1
 +
competitive-with 2
 +
then 1 is-destroyed
 +
parameters p 0.001
 +
[/rule]
 +
</pre>
 +
|}
 +
 +
The [rule] … [/rule] subsection of coordinators is used to define events that occur between member molecules of a coordinator.  Multiple rule subsections may be associated with one coordinator.  Each rule is defined using multiple lines with keywords
 +
id, if, competitive-with, then and parameters.  These keywords and their line formats are described below.  In general, each rule has
 +
 +
1)  an identifier that is unique to the coordinator
 +
 +
2) a set of prerequisite conditions (specified by if lines) that must be met in order for
 +
 +
3) some set of events (specified by then lines) that will occur with some probability defined by
 +
 +
4) a set of parameters specified on one or more parameter lines.
 +
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] id [/rule]'''
 +
|-
 +
| key||id
 +
|-
 +
| format||id [integer]
 +
|-
 +
| description||Used to identify a rule for a coordinator
 +
|-
 +
| required||yes
 +
|-
 +
| default value||not applicable
 +
|-
 +
| example||id 1
 +
|}
 +
Notes: The id line defines a single integer identifier for a rule.  It must be the first line of the rule subsection and it must be unique to the rules defined for the coordinator of which it is a part.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] time [/rule]'''
 +
|-
 +
| key||time
 +
|-
 +
| format||time [float]
 +
|-
 +
| description||Used to identify a time when the rule should be considered.
 +
|-
 +
| required||no
 +
|-
 +
| default value||none - the event will be executed once the conditions are met (see if lines below)
 +
|-
 +
| example||time 1.000000
 +
|}
 +
Notes: The event will be executed at a specific time if the conditions are met at that time (see if line below).  If no conditions are specified, then the rule will be executed at that time.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] if [/rule]'''
 +
|-
 +
| key||if
 +
|-
 +
| format||if [string]
 +
|-
 +
| description||Used to define a prerequisite condition for some event.  The precondition is expressed as a set of molecules(s) of some type in some state that must be members of the coordinator (either already assembled or unassembled).
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default values
 +
|-
 +
| example||if 1.1.1.0
 +
|}
 +
Notes: The if line is used to define a prerequisite condition for some event.  The precondition is expressed as a set of molecules(s) of some type in some state that must be assembled members of the coordinator. The line contains a single value that is a dot delimited list of integers.  For example,
 +
 +
<pre>
 +
if 34.2.1.1.3.4.0.8.6
 +
</pre>
 +
 +
This dot-delimited condition is of the form:
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:grey" colspan="3"|'''if line format'''
 +
|-
 +
| position||Meaning and possible values||Example
 +
|-
 +
| 1||An integer that serves as a tag to identify this set of condition meeting molecules.  This tag may  be used in “then” lines for the rule (see below).||34
 +
|-
 +
| 2||Required molecule type (an integer corresponding to a molecule type id).  See “id” key under [moleculeType]||2
 +
|-
 +
| 3||Required stoichiometry of molecules meeting this condition (some integer).||1
 +
|-
 +
| 4
 +
|Either 1 or 0.
 +
 +
The molecule must already be an assembled member of the coordinator (1) or it may be only be an unassembled member (0).  An explanation of “assembled” and “unassembled is given below.
 +
|1
 +
|-
 +
| 5 + 3n||The following two numbers indicate a feature-state match that must be met (1) or that must not be met (0).||1
 +
|-
 +
| 6 + 3n||Feature identifier specified by some integer.||3
 +
|-
 +
| 7 + 3n||Required state of feature (previous position) specified by some integer. ||4
 +
|}
 +
 +
Notes:  n is an integer from 0, 1, 2… specifying a feature state condition (see explanation below).
 +
 +
So the first four numbers in the example above
 +
 +
<pre>
 +
if 34.2.1.1
 +
</pre>
 +
 +
mean that 1 copy of molecule type 2 must be assembled (1) as part of the coordinator in order for this rule to be considered.  This molecule is assigned the “tag” identifier of 34 for use in the then line (see below).  In addition, a repeating series of three numbers may be appended to specify the required state of the molecule.  For example, in
 +
 +
<pre>
 +
if 34.2.1.1.1.3.4.0.8.6
 +
</pre>
 +
 +
the appended 1.3.4  (at positions 5 to 7) would indicate that the molecule must have (1) feature 3 in state 4.  And the following 0.8.6 (positions 8 -10) would indicate that the molecule must NOT have (0) feature 8 in state 6.
 +
 +
Molecules can be in one of three states with respect to the coordinator (not to be confused with states of molecule features).  The three sates are:
 +
 +
1) UNASSEMBLED – meaning that the molecule is a potential member of the coordinator but it is not yet assembled as part of the coordinator nor is it ASSEMBLING.
 +
 +
2) ASSEMBLING  – meaning that the molecule is a member of the coordinator but it is not yet assembled as part of the coordinator but is in the process of  ASSEMBLING (i.e. moving under the influence of the coordinator towards the coordinator).
 +
 +
3) ASSEMBLED – meaning that the molecule has been moved into position by the coordinator and has reached the offset distance of the coordinator as defined by the coordinator and its member molecules.
 +
 +
For example, freely-diffusing potential members of a protein complex may become members of a new or existing coordinator but will be UNASSEMBLED with the point coordinator representing the complex until they meet some set of conditions required for assembly into the complex.  Once these conditions are met, they will begin assembly (ASSEMBLING) as they move into position around a coordinator (the position of a coordinator is defined as the midpoint between all ASSEMBLED or ASSEMBLING member molecules). 
 +
 +
In practice, a look-ahead function considers potential molecules for a coordinator and only adds them if they have the ability to begin assembly.  If they do not meet conditions required for assembly, they are not added to the coordinator (or used to generate a new coordinator).  If molecules are assigned as members of a coordinator and are then found to be unable to begin assembly (i.e. they are found to be UNASSEMBLED at the end of the iteration), they are removed from the coordinator and made available to the simulation so that they can help form new coordinators or join existing coordinators.
 +
 +
The ASSEMBLING member molecules will cease movement towards the coordinator once they reach some offset distance from the coordinator (that is, for example, defined as a sphere around the coordinator whose surface area is equivalent to the sum of the cross-sectional areas of the member molecules).
 +
 +
There is one special feature id (99999) that is reserved for holding compartment information.  Molecules that are part of a planar or spherical coordinator that represent a compartment or compartment boundary (see isCompartment above) have their feature 99999 set to the identifier of the coordinator type once they become assembled with that coordinator.  In addition, molecules that reside within a spherical coordinator have their  feature 99999 set to the identifier of the coordinator type once they translocate into that coordinator or if they start in that compartment at the beginning of the simulation (see resident-compartment-type under moleculeType)
 +
 +
This feature-value pair is used when describing rules that use translocations (see below).
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] competitive-with [/rule]'''
 +
|-
 +
| key||competitive-with
 +
|-
 +
| format||competitive-with [integer]
 +
|-
 +
| description||Used to point out that the present rule and the rule having the specified id can not occur simultaneously.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default values
 +
|-
 +
| example||competitive-with 1
 +
|}
 +
Notes: The competitive-with line specifies the identifier for a rule that is competitive to the current rule. That means that the rule including this line and the rule having the specified id can not occur simultaneously, even if the specified conditions in the if line were met, so the algorithm will choose one of them or neither of them, but never both. This is useful when having coordinators that can follow different reactions.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] then [/rule]'''
 +
|-
 +
| key||then
 +
|-
 +
| format||then [string or integer] [string] [string or integer]
 +
|-
 +
| description||Used to define events that occur as a result of interactions between members molecules
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default events
 +
|-
 +
| example||then 1 is-destroyed
 +
|}
 +
Notes:
 +
 +
The then line is used to define events that occur (if some set of molecules in some state are assembled members of a coordinator as defined by the if lines).  There are several different possibilities for this line that are differentiated by the second string value.  They are:
 +
 +
<pre>
 +
then 3 begins-assembly
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 3 (molecules meeting some condition defined by a preceding “if” line) are allowed to begin assembly with the coordinator. 
 +
 +
<pre>
 +
then 6.1 is-created-at-location-of 1
 +
</pre>
 +
 +
In this case, 1 instance of molecule type 6 is created at the location of the molecule with tag 1 (see tags under “if” lines).  State information can be specified for the molecule that is to be newly created; for example, 6.1.2.3 would create 1 instance of molecule 6 with feature 2 in state 3.
 +
 +
<pre>
 +
then 1 is-destroyed
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 1 (see tags under “if” lines) is destroyed.
 +
 +
<pre>
 +
then 1 changes-state-to 1.2
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 1 (see tags under “if” lines) will change state according to the state description 1.2 (feature 1 changes state to state 2). Multiple feature–state changes may be specified on one line; i.e., 1.2.4.5.6.33 means that feature 1 assumes state 2, feature 4 assumes state 5 and feature 6 assumes state 33. 
 +
 +
<pre>
 +
then 1 changes-colour-to .1:.32:.11
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 1 (see tags under “if” lines) will change to the colour specified by .1:.32:.11 (the colons separate three float values in the RGB colour description; i.e. .1 .32 .11).
 +
 +
<pre>
 +
then 1 translocates-into-compartment-of-molecule 2
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 1 (see tags under “if” lines) will be translocated into the compartment that the molecule with tag 2 is a member of.  This compartment is a point coordinator where
 +
 +
<pre>
 +
isCompartment 1
 +
isSizeDynamic 1
 +
</pre>
 +
 +
has been specified.
 +
 +
The molecule with tag 2 is a mediator of the translocation and resides in the surface (membrane) of the compartment.
 +
Use of this translocation event is usually accompanied by an if line that first checks that the translocating molecule is outside the compartment and the mediating molecule is assembled with the surface of the compartment.  See the file
 +
[[Example_model_files_for_Magrathea#Example 6.3]] for an example model.
 +
 +
Do not use to '''translocate-into-compartment ''' across a planar coordinator representing a membrane boundary.  Instead use '''translocate-past-molecule''' (below).
 +
 +
<pre>
 +
then 1 translocates-outof-compartment-of-molecule 2
 +
</pre>
 +
 +
Similar to translocates-into-compartment-of-molecule except the translocated molecule is moved out of the compartment instead of into. 
 +
 +
Use of this translocation event is usually accompanied by an if line that first checks that the translocating molecule is inside the compartment and the mediating molecule is assembled with the surface of the compartment.  The translocating molecule has its resident compartment information altered accordingly.
 +
 +
See the file [[Example_model_files_for_Magrathea#Example 6.3]] for an example model.
 +
 +
Do not use to '''translocate-outof-compartment''' across a planar coordinator representing a membrane boundary.  Instead use '''translocate-past-molecule''' (below).
 +
 +
<pre>
 +
then 1 translocates-past-molecule 2
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 1 (see tags under “if” lines) will be translocated across some membrane boundary (represented by a planar coordinator) that molecule 2 is a part of.  This planar coordinator has been defined using the line
 +
 +
<pre>
 +
isCompartment 1
 +
</pre>
 +
 +
The molecule with tag 2 is a mediator of the translocation and resides in the surface (membrane) of the coordinator.
 +
Use of this translocation event is usually accompanied by an ''if'' line that first checks that the mediating molecule is assembled with the surface of the compartment.  The translocated molecule moves to the other side of the boundary.  There is no change made to the translocating molecule’s resident compartment information. 
 +
See the file [[Example_model_files_for_Magrathea#Example 6.3]] for an example model. 
 +
 +
Do not use to '''translocate-past-molecule''' across a point coordinator representing a compartment.  Instead use '''translocate-(into/outof)-compartment-of-molecule''' (above).
 +
 +
<pre>
 +
then 3 leaves-coordinator
 +
</pre>
 +
 +
In this case, the molecule(s) with tag 3 (molecules meeting some condition defined by a preceding if line) will leave the coordinator. 
 +
 +
 +
<pre>
 +
then 1.5 is-instantiated spherical surface - - - 1.0 - - - - 1.1
 +
</pre>
 +
 +
This format is used to create new molecules with respect to the position of coordinator and does not require any other molecules to position the newly formed molecules (c.f. "is-created-at-location-of").  It is intended to be used in combination with a timed event (see time above).
 +
 +
"1.5" means that five instances of molecule type 1 are to be created.
 +
 +
"spherical surface - - - 1.0 - - - - 1.3 -" means that the instantiation will occur on (random) locations on the surface of a sphere with radius 1.0 (with respect to the coordinator's centre) and that the new molecules will have their feature 1 set to state 3.  This section of the line corresponds to the "instantiation line" format (see above).  Dashes (-) correspond to options of the instantiaton line that do not apply in this case and are not supported.  New molecules will be assigned to the compartment in which they are created. "point" may also be used in place of "spherical"; planar and cylindrical are currently not supported.  "surface" may be replaced by "volume".  See the "instantiation line" format above.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''[rule] parameters [/rule]'''
 +
|-
 +
| key||parameters
 +
|-
 +
| format||parameters [string] [float]
 +
|-
 +
| description||Used to define parameters for the event under consideration
 +
|-
 +
| required||no
 +
|-
 +
| default value||parameters p 1.0
 +
|-
 +
| example||parameters kf 0.07
 +
|}
 +
Notes:
 +
The parameters line is used to specify the value of the parameters for the event that will occur.  The string value will represent the id for that parameter while the float value will represent the probability for the event to take place given that all conditions were met. The default parameters value is 1.0, meaning that events will occur if all conditions are met.
 +
 +
 +
====Instantiation====
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''instantiate'''
 +
|-
 +
| key||instantiate
 +
|-
 +
| format||see “instantiate” line description above under the section for describing molecules
 +
|-
 +
| description||Creates instances of coordinators and assigns locations in the simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value||there are no default instantiations of coordinator types
 +
|-
 +
| example|| instantiate 1 determined point - 10 15 100
 +
|}
 +
Notes:
 +
Instantiation of coordinators is handled with an instantiate line that has the same format as the instantiate line for molecules (see above under moleculeType) except that coordinators have neither features nor states.
 +
 +
The instantiate line is optional and so may be omitted. This is quite often the case especially for point coordinators representing interactions or complexes that are dynamically created by their member molecules.
 +
 +
 +
==simulation==
 +
The simulation section is entirely optional (none of the parameters in this section are mandatory because they all have default values that are set by magrathea).  However, specifying parameters in this section, allows the user to override default options that alter the running of the simulation itself.
 +
 +
An example of a simulation description is given in the Figure below. Each of the key-value entry lines are described in a separate section below.
 +
 +
===An example simulation description===
 +
 +
<pre>
 +
[simulation]
 +
produce-visual-output 1
 +
camera-at-from 10 10 0 0 1 30
 +
light-source 0 20 20
 +
background-color 0 0 0
 +
movie-length 10
 +
simulation-length 100
 +
time-step .01
 +
move-realistically 1
 +
[/simulation]
 +
</pre>
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''produce-visual-output'''
 +
|-
 +
| key||produce-visual-output
 +
|-
 +
| format|| produce-visual-output [0,1]
 +
|-
 +
| description||Should visual output be generated
 +
|-
 +
| required||no
 +
|-
 +
| default value||produce-visual-output 1
 +
|-
 +
| example ||produce-visual-output 0
 +
|}
 +
 +
Notes: This should only be set to zero to prevent magrathea from trying to call visual libraries that may not be present in some environments (say on a Linux cluster node).  This will prevent proper camera positioning, light positioning and movie making although an image may still appear in the breve simulation window.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''camera-at-from'''
 +
|-
 +
| key||camera-at-from
 +
|-
 +
| format||camera-at-from [x y z x y z]
 +
|-
 +
| description||Set up the camera.
 +
|-
 +
| required||no
 +
|-
 +
| default value||camera-at-from 20 20 0 1 5 50
 +
|-
 +
| example || camera-at-from 10 10 0 0 1 30
 +
|}
 +
 +
Notes: The first x,y,z vector describes the camera target.  The second vector describes the camera position.
 +
Vector values must be separated by spaces.  Vector values can be floats.  produce-visual-output must be set to 1.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''light-source'''
 +
|-
 +
| key||light-source
 +
|-
 +
| format||light-source [x y z]
 +
|-
 +
| description||Set up the light-source
 +
|-
 +
| required||no
 +
|-
 +
| default value||light-source 20 20 20
 +
|-
 +
| example ||light-source 0 20 20
 +
|}
 +
 +
Notes: The vector of x, y z floats describes the position of the light source in the simulation.  produce-visual-output must be set to 1.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''background-color'''
 +
|-
 +
| key||background-color
 +
|-
 +
| format||background-color [0...1] [0...1] [0...1]
 +
|-
 +
| description||Background color for the simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value|| background will be sky-blue
 +
|-
 +
| example ||background-color 0.1 0.1 0.1
 +
|}
 +
 +
Notes: This can be set to change the color of the "sky" in the simulation.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''movie-length'''
 +
|-
 +
| key||movie-length
 +
|-
 +
| format||movie-length [float]
 +
|-
 +
| description||Length of the movie. 
 +
|-
 +
| required||no
 +
|-
 +
| default value||movie-length 5.0
 +
|-
 +
| example ||movie-length 100
 +
|}
 +
 +
Notes: Set the length of the simulation to be captured to simulation.mpeg. produce-visual-output must be set to 1.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''simulation-length'''
 +
|-
 +
| key||simulation-length
 +
|-
 +
| format||simulation-length [float]
 +
|-
 +
| description||Is there a time-limit on the simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value||simulation-length 0
 +
|-
 +
| example ||simulation-length 20
 +
|}
 +
 +
Notes: If this is set to zero, the simulation will not end.  Otherwise, the simulation will end after the specified number of seconds of simulation time.  As of breve 2.7.2 and magrathea 1.67, the simulation may not end gracefully and may require restarting breve. Default setting is recommended.
 +
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''time-step'''
 +
|-
 +
| key||time-step
 +
|-
 +
| format||time-step [float]
 +
|-
 +
| description||Time-step.
 +
|-
 +
| required||no
 +
|-
 +
| default value||time-step 0.1
 +
|-
 +
| example ||time-step 0.01
 +
|}
 +
 +
Notes: This value is used to call the controller methods setIntegrationStep and setIterationStep. 
 +
See http://spiderland.org/documentation/steveclasses/Control.html. The default setting is recommended.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''move-realistically'''
 +
|-
 +
| key||move-realistically
 +
|-
 +
| format||move-realistically [0,1]
 +
|-
 +
| description||Animation or simulation.
 +
|-
 +
| required||no
 +
|-
 +
| default value||move-realistically 0
 +
|-
 +
| example ||move-realistically 1
 +
|}
 +
 +
Notes: This setting determines how molecules will move.  A default value of zero will render animations.  A value of one (1) will cause molecules to move according to brownian dynamics. The default setting is recommended.  Not all features of magrathea are supported for move-realistically 1.
 +
 +
==The counter==
 +
 +
The counter section allows the user to specify the simulation entities that should be counted during the simulation. The result is a plain text file, whose columns represent the variables (time and each specified molecular species) and whose rows store each value of the time series.  The file is called “output.txt” by default and is placed in the same directory as the breve executable.
 +
 +
An example of counter description is given in the Figure below. Each of the key-value entry lines are described in a separate section below.
 +
 +
===An example counter description===
 +
 +
 +
<pre>
 +
[count]
 +
counter-type specified
 +
molecule-to-count 1.1.1.0.2.63
 +
molecule-to-count 2.1.1.1.2.63
 +
molecule-to-count 3.2.1.1.1.1
 +
molecule-to-count 4.1.1.1.3.5
 +
molecule-to-count 5.1.1.0.2.63.1.3.5
 +
molecule-to-count 6.1.1.0.2.63.1.3.5.1.1.1
 +
[/count]
 +
</pre>
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''counter-type'''
 +
|-
 +
| key||counter-type
 +
|-
 +
| format||counter-type [nothing, type, specified]
 +
|-
 +
| description||Specify the type of counter.
 +
|-
 +
| required||no
 +
|-
 +
| default value||nothing
 +
|-
 +
| example
 +
|counter-type specified
 +
 +
counter-type type
 +
 +
counter-type nothing
 +
|}
 +
 +
Notes: The line:
 +
 +
<pre>
 +
counter-type nothing
 +
</pre>
 +
 +
indicates that no counting will be done during the simulation. If counter-type is set to nothing, all information in the molecule-to-count line will be ignored.
 +
 +
The line:
 +
 +
<pre>
 +
counter-type type
 +
</pre>
 +
 +
indicates that instances of each molecule type will be counted during the simulation, regardless of their feature-state description.
 +
 +
The line:
 +
 +
<pre>
 +
counter-type specified
 +
</pre>
 +
 +
indicates that molecule instances will be counted during the simulation according to some specified molecule type and feature-state description. If counter-type is set to specified, the information in the molecule-to-count line will be used as such specification.
 +
 +
The counter types are mutually exclusive, so having more than one  counter-type line is not allowed. In cases where the user needs to count certain molecules including their features and states together with other molecules without features or states, that could be done using the '''specified''' option.
 +
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:yellow" colspan="2"|'''molecule-to-count'''
 +
|-
 +
| key||molecule-to-count
 +
|-
 +
| format||molecule-to-count [string]
 +
|-
 +
| description||Specify the molecule type to count (and features and states, when possible).
 +
|-
 +
| required||no
 +
|-
 +
| default value||none
 +
|-
 +
| example
 +
|molecule-to-count 4
 +
 +
molecule-to-count 1.1.1.0.2.63
 +
 +
molecule-to-count 2.1.1.1.2.63
 +
 +
molecule-to-count 5.1.1.0.2.63.1.3.5
 +
|}
 +
Notes:  When working with '''counter-type''' ''type'', the  molecule-to-count line uses the format:
 +
 +
<pre>
 +
molecule-to-count [moleculeTypeId]
 +
</pre>
 +
 +
For example:
 +
 +
<pre>
 +
molecule-to-count 4
 +
</pre>
 +
 +
When working with '''counter-type''' ''specified'', the '''molecule-to-count''' line uses a dot-delimited format, as explained below.
 +
 +
{|border="1" cellpadding="2"
 +
| align="center" style="background:lightgrey" colspan="3"|'''dot-delimited format for describing molecules'''
 +
|-
 +
| position||Meaning and possible values||Example
 +
|-
 +
| 1||An integer that serves as a tag to identify this type of molecule.||1
 +
|-
 +
| 2||Required molecule type (an integer corresponding to a molecule type id).  See “id” key under [moleculeType]||1
 +
|-
 +
| 3
 +
|Either 1 or 0.
 +
 +
The molecule must already be an assembled member of the coordinator (1) or it may only be an unassembled member (0).
 +
So far this position is ignored, but it must be specified in order to avoid errors.
 +
|1
 +
|-
 +
| 4 + 3n||The following two numbers indicate a feature-state match that must be met (1) or that must not be met (0).||0
 +
|-
 +
| 5 + 3n||Feature identifier specified by some integer.||2
 +
|-
 +
| 6 + 3n||Required state of feature (previous position) specified by some integer. ||63
 +
|}
 +
Notes:  n is an integer from {0, 1, 2,…} specifying a feature-state pair.
 +
 +
As an example, the line
 +
 +
<pre>
 +
molecule-to-count 4.1.1.0.2.63.1.3.5
 +
</pre>
 +
 +
indicates a molecule type to count that is tagged '4' and has a molecule type with id 1 and assembled to the coordinator (1), which does not have (0) feature 2 in state 63 and does (1) have feature 3 in state 5. Molecules that met all these conditions will be counted as the same specified species (with tag 4 in the output file).
 +
 +
In principle, any number of molecule-to-count lines can be added. Each specified species will occupy a column of the output file.

Latest revision as of 13:00, 20 April 2010

The Magrathea Manual Contents

The Magrathea Manual: Coordinated Agent Modelling Explained

The Magrathea Manual: Coordinated Agent Modelling By Example

The Magrathea Manual: Building Coordinated Agent Models

Magrathea Installation and Use

Example model files for Magrathea


Making models

The model.txt file

Magrathea opens a file called “model.txt” at the beginning of a simulation. Information is read from the file to populate the simulation with molecules and coordinators. The properties of different types of molecules and coordinators are specified in the model.txt file along with the number and positions of all of the starting molecules and coordinators. The sections below describe the format of the model.txt file.


A simple example

An example model.txt file is shown below in the Figure below (An example model.txt file for Magrathea).

The model.txt file is a text file and must be called “model.txt”. Lines beginning with # are comments and are ignored. Blank lines are ignored. Any text in the file after the line

EOF

will be ignored.

There are two types of sections in a model file. A section used to describe a type of molecule and create instances of that molecule type at the beginning of the simulation begins with the line:

[moleculeType] 

and ends with the line

[/moleculeType]

A section that is used to describe a coordinator type and create instances of that coordinator at the beginning of the simulation begins with the line:

[coordinatorType]

and ends with the line

[/coordinatorType]

Key-value format

Each line in these two sections types encodes a separate piece of information as a key-value pair. So, for instance, members of the first molecule type are labeled “a” as indicated by the line

label a

In this line “label” is the key and “a” is the value. Keys and their values are separated by white-spaces. There may be several values specified for a given key. The key is always the first block of text on a line.

An example model.txt file for Magrathea

The following model file is explained in the next section.

###########
#ab complex
###########

[moleculeType]
id 1
label a
color .81 .60 .21
shape Sphere 1
neighborhood-size 5
coordinator 1 3
instantiate 10 random spherical volume 10 30 10 10
[/moleculeType]

[moleculeType]
id 2        
label b
color 0.67 0.08 0.37
shape Sphere 1
neighborhood-size 5
coordinator 1 3
instantiate 4 random spherical volume 10 15 10 10
[/moleculeType]

[coordinatorType]
id 3
label a-b-complex
shape Cube 1 1 1
molecule 1 1
molecule 2 1
[/coordinatorType]

EOF

A brief description of the example model.txt file

The above example model file, specifies a simulation that has two molecule types and one coordinator type.

Each molecule of type “1” has a label of “a”, has some specified color, is drawn as a sphere, can detect neighboring molecules within a 5 unit radius and can be coordinated by some coordinator type 3 on channel 1. These ideas are encoded by the lines

id 1
label a
color .81 .60 .21
shape Sphere 1
neighborhood-size 5
coordinator 1 3

The simulation begins with 10 instances of this molecule type distributed randomly throughout some specified spherical volume. This is encoded by the line:

instantiate 10 random spherical volume 10 30 10 10

The second molecule type has a label of “b”, is also drawn as a sphere with a different color. The simulation begins with only four instances of this molecule type that are also distributed in a spherical volume at a separate location in the simulation. Both molecules a and b can be coordinated by coordinator type 3 on channel 1 (as specified in the line):

coordinator 1 3

for both molecule a and b.


There is only one type of coordinator in this simulation. It has an id of 3 and is labeled “a-b-complex”. The simulation does not begin with any instances of this coordinator type. Instead, an instance of this coordinator type will be created once an instance of molecule “a” and an instance of molecule “b” diffuse within one another’s “neighborhood distance” during the simulation. The coordinator will then appear between the two molecules as a cube. The coordinator has two molecule type members (each with a stoichiometry of 1) as indicated by the lines:

molecule 1 1
molecule 2 1

Once the two molecules become a part of this coordinator, they will move towards the coordinator (at some position between where the two molecules started) and remain there.

A screen shot of the resulting simulation is shown below in the Figure below. The remainder of this section of the manual shows exactly how molecule and coordinator types can be specified.


Screen shot of a simulation resulting from the example model.txt file


simple example.jpg

Describing molecule types

An example molecule type description is given below in Figure 3. Each of the key-value entry lines are described in a separate section below. For each key-value pair, a format is given. Square brackets indicate types of values that must are to be inserted into the line by the user (i.e., either a float (like 0.1), an integer (like 200) or a string value (like myComplex).


An example molecule type description

[moleculeType]
id 1
label molecule_a
color .81 .60 .21
shape Sphere 1
draw-as-point 0
opacity 1
show-neighbor-lines 0
neighborhood-size 5
dynamic-neighborhood-sizing 0
feature 234 Tyr234
feature-state 234 0 unphosphorylated
feature-state 234 1 phosphorylated
coordinator 1 3
resident-compartment-type 4
instantiate 10 random spherical volume 10 30 10 10
[/moleculeType]

Molecule parameters

Appearances

id
key id
format id [integer]
description A unique identifier for this molecule type
required yes
default value not applicable
example id 1

Notes: id is usually the first key-value pair specified for a moleculeType. This id is used to refer to this molecule type in other key-value pairs of the model file.


label
key label
format label [string]
description A label for the molecule type.
required no
default value molecule
example label molecule_a

Notes: The label line allows the user to give a name to all molecules of this molecule type. The name will not appear during the simulation unless show-label is set to TRUE (see below). Including spaces in a molecule type name will truncate the name at the space.


show-label
key show-label
format show-label [1 or 0]
description Boolean to determine if label should be shown.
required no
default value 0
example show-label 1

Notes: See label (above). All other values besides “1” will be interpreted as FALSE.


color
key color
format color [0…1] [0…1] [0…1]
description A description of the color used to draw this molecule type.
required no
default value some randomly chosen color
example color .81 .60 .21

Notes: A color may be specified by the user for drawing molecules of this molecule type. Color is specified as a vector of Red, Green and Blue percentages (expressed as a decimal). See http://www.december.com/html/spec/colorper.html for a list of RGB percentage codes.


shape
key shape
format shape Sphere [float] [float]
or
shape Cube [float] [float] [float]
description A description of the shape used to draw this molecule type.
required no
default value Sphere 1.0
example shape Sphere 0.5
example shape Sphere 0.5 2
example shape Cube 1.0 2.0 3.5

Notes:

Two shapes may be used to draw a molecule, a sphere or a cube.

If a Sphere is chosen, at least one additional float value must be given to specify the radius of the sphere. A second, optional float value may be given to specify the “effective radius” of the molecule. “Effective radius” is used to maintain distances between “molecules” that act as compartment markers. Compartment markers are used in place of representing all of the molecules that are really present in a membrane. They can be thought of as representing a single molecule at the center of a circular collection of molecules where the radius of the circle is the “effective radius”. Compartment markers will maintain a distance from one another equivalent to (er1 + er2) where er1 and er2 are the effective radii of compartment markers 1 and 2. Other molecules (non compartment markers) will maintain a distance from compartment markers of (r1 + r2) where r1 and r2 are the radii of the compartment marker and the molecule respectively. A second float value must be specified after the shape key in order for the molecule to behave as a compartment marker.


draw-as-point
key draw-as-point
format draw-as-point [1 or 0]
description A Boolean flag indicating that the molecule is to be drawn as a point.
required no
default value draw-as-point 0
example draw-as-point 1

Notes: If draw–as-point is set to 1 (TRUE) then the molecule will appear in the simulation as a point. The radius and effective radius will still be as specified in the shape line. This flag is used to speed up the simulation by reducing the amount of required rendering. It may also be used to hide molecule types that are not of interest to the user. Values other than 1 are interpreted as 0 (FALSE).

opacity
key opacity
format opacity [0…1]
description A description of how opaque the molecule should appear (where 0 is transparent and 1 is totally opaque).
required no
default value opacity 1
example opacity 0.1

Notes: Opacity can be set to some value below 1 in order to make the molecule somewhat transparent. This allows the user to see through molecules of a certain type that might otherwise block views to other parts of the simulation.

Neighborhood

show-neighbor-lines
key show-neighbor-lines
format show-neighbor-lines [1,0]
description A Boolean flag indicating that lines are to be drawn between the molecule and its neighbor (as determined by the molecule’s ).
required no
default value show-neighbor-lines 0
example show-neighbor-lines 1

Notes: If show-neighbor-lines is set to 1 (TRUE) then lines will appear between the molecule and its neighbors. This can be useful when debugging a simulation. Values other than 1 are interpreted as 0 (FALSE).


neighborhood-size
key neighborhood-size
format neighborhood-size [float]
description The radius of the molecule’s neighborhood size.
required no
default value neighborhood-size 1.0
example neighborhood-size 2.5

Notes: The neighborhood-size is a float value that specifies the radius of a sphere that has the same centre as the molecule. This value specifies how far the molecule “looks” when finding other neighbor molecules. When a molecule is looking for neighboring coordinators, it will only consider coordinators within this radius AND any coordinators of neighboring molecules.


dynamic-neighborhood-sizing
key dynamic-neighborhood-sizing
format dynamic-neighborhood-sizing [1,0]
description A Boolean flag indicating if this molecule is to use dynamic-neighborhood-sizing.
required no
default value dynamic-neighborhood-sizing 0
example dynamic-neighborhood-sizing 1

Notes: If dynamic-neighborhood-sizing is set to 1 (TRUE) then the molecule’s neighborhood size will increase by 1 unit per simulation iteration until all of its channels are occupied by some coordinator. Values other than 1 are interpreted as 0 (FALSE).

Feature-state pairs

feature
key feature
format feature [integer] [string]
description A feature is described using a feature identifier and a label. Each feature may have one of multiple possible states. These possible states are described using the feature-state line.
required no
default value There are no default values
example feature 234 Tyr234

Notes: A molecule may have multiple features. Each feature is described using a separate feature line. Each feature is described using a feature id (integer value following the feature key word) followed by a label (string value with no spaces). The feature is not associated with any state information. For example, the line

feature 234 Tyr234

simply indicates that there is some feature (with id 234 and label Tyr234) that can exist in one of many multiple states (see feature-state below). For protein molecules, amino acids numbers could be used as feature identifiers for their corresponding amino acids; however, this is not required. Any integer may be used for a feature identifier so long as that integer is used only once for any given molecule.

N.B. features and feature-states (below) are not used by magrathea right now, but may be used in future to present information to the user. They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).


feature-state
key feature-state
format feature-state [integer] [integer] [string]
description Each feature described by a feature line may have one of multiple possible states. These possible states are described using the feature-state line.
required no
default value There are no default values
example feature-state 234 0 unphosphorylated
feature-state 234 1 phosphorylated

Notes: A molecule may have multiple features. Each feature is described using a separate feature line (above). Each feature can exist in one of many multiple states. Each of these possible states is described by a separate feature-state line. The first integer indicates the feature identifier that this state applies to. The second integer is a state-identifier indicating one possible state for this feature. An integer identifier should be unique to a feature on a molecule. The string value provides a label that describes this particular state.

Note: features and feature-values are not used by Magrathea, but may be used in future to present information to the user. They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).

Coordinators

coordinator
key coordinator
format coordinator [integer] [integer]
description A description of the coordinators that a molecule can “listen” to.
required no
default value there are no default coordinator assignments
example coordinator 1 3

Notes: Molecules of a given molecule type can be coordinated by a coordinator of a given coordinator type. Molecules may have multiple coordinators. A molecule joins a coordinator using one of its “channels”. A channel may be occupied by only one coordinator at a time. However, the same channel may be occupied by one of several different coordinator types. Channels could be thought of as binding sites and coordinators may be thought of as interactions (though the analogy is not applicable to all molecule coordinator pairings, hence the use of the “coordinator and channel” terminology). A binding site may be involved in one of several different interactions (i.e. with different binding partners). Therefore, multiple coordinator lines may be listed for a single molecule type. For instance, the lines:

coordinator 1 3
coordinator 1 4
coordinator 2 5

would be used to specify a molecule type that could pair (mutually exclusively) with either coordinator 3 or 4 using channel 1 and (at the same time) could pair with coordinator 5 using channel 2.


resident-compartment-type
key resident-compartment-type
format resident-compartment-type [integer]
description Specifies that a molecule is a resident of some coordinator that represents a compartment
required no
default value there are no default assignments
example resident-compartment-type 4

Notes: Spherical point coordinators may be used to represent compartments. At the beginning of a simulation, any molecules found inside a coordinator compartment will be kicked out unless this flag has been set indicating that the molecule may reside in that compartment type (the coordinator type id is used to specify the compartment type). If a molecule is a resident of a compartment, it will move randomly within the space of that compartment until it encounters the inside face of the compartment. Collisions with the inside face of a compartment will result in the molecule being repelled (contained) back towards the center of the compartment.

It is very important that the isSizeDynamic flag be set to 1 for coordinators that are used to represent compartments. If not, the size and shape of the coordinator rendered in the simulation is meaningless (it is drawn only to mark the point-location of the coordinator). When isSizeDynamic is TRUE, the coordinator is drawn as a sphere and its size reflects the radius of the imaginary sphere around the coordinator centre that maintains the offset distance of member molecules from the coordinator. This offset distance is also used to determine whether molecules are inside or outside the compartment.

Molecular Rules

Note: For the most part, rules should be encoded using Coordinator Rules. However, there are special cases where rules need to be specified for single molecules that are not associated with a coordinator. In these cases, Molecular Rules can be used.


[rule] …[/rule]
key See below. Multiple keys are associated with this subsection including id, if, competitve-with, then, and parameters
format
[rule]
id [integer]
if [string]
.
.
competitive-with [integer]
.
.
then [string|integer] [string] [string|integer]
.
.
parameters [string] [float]
.
.
[/rule]
description Used to define events that occur to a molecule.
required no
default value there are no default rules
example
[rule]
id 1
if 1.1.1
competitive-with 2
then 1 is-destroyed
parameters p 0.001
[/rule]

Notes: The [rule] … [/rule] subsection of molecules is used to define events that occur to a single molecule. Multiple rule subsections may be associated with one molecule. Each rule is defined using multiple lines with keywords id, if, competitive-with, then and parameters. These keywords and their line formats are described below.

In general, each rule has:

1) an identifier that is unique to the molecule

2) a set of prerequisite conditions (specified by if lines) that must be met in order for

3) some set of events (specified by then lines) that will occur with some probability according to

4) a set of parameters specified on one or more parameter lines.


See this example for an example model file that uses molecule rules.


[rule] id [/rule]
key id
format id [integer]
description Used to identify a rule for a molecule
required yes
default value there are no default rules
example id 1

Notes: The id line is an integer identifier for a rule. It must be the first line of the rule subsection and it must be unique to the rules defined for the molecule to which it belongs.


[rule] if [/rule]
key if
format if [string]
description Used to define a prerequisite condition for some event. The precondition is expressed as the molecule id with or without some feature-state specification
required no
default value there are no default values
example if 2.1.1

Notes: The if line is used to define a prerequisite condition for some event. The precondition is expressed as the molecule id with or without some feature-state specification. The line contains a single value that is a dot delimited list of integers. For example,

if 2.1.1.2.4

This dot-delimited condition is of the form specified in the next table.


if line format
position Meaning and possible values Example
1 Required molecule type (an integer corresponding to a molecule type id). See “id” key under [moleculeType] 2
2 + 2n Feature identifier specified by some integer. 1
3 + 2n Required state of feature (previous position) specified by some integer. 1

Note: n is an integer from 0, 1, 2… specifying a feature-state condition (see explanation below).

So the first three numbers in the example above

if 2.1.1

mean that the rule applies for each copy of molecule type 2, with feature 1 in state 1. And the following 2.4 (positions 4 - 5) would indicate that the molecule must have feature 2 in state 4.

[rule] competitive-with [/rule]
key competitive-with
format competitive-with [integer]
description Used to point out that the present rule and the rule having the specified id cannot occur simultaneously.
required no
default value there are no default values
example competitive-with 1

Notes: The competitive-with line specifies the identifier for a rule that is competitive to the current rule. That means that the rule including this line and the rule having the specified id can not occur simultaneously, even if the specified conditions in the if line were met, so the algorithm will choose one of them or neither of them, but never both. This is useful when having molecules that can follow different reactions.

[rule] then [/rule]
key then
format then [string, integer] [string] [string, integer]
description Used to define events that occur to a given molecule
required no
default value there are no default events
example then 1 is-destroyed

Notes:The then line is used to define events that may occur to a given molecule if the condition defined by the if line is met. There are several different possibilities for this line that are differentiated by the second string value. They are:

then 6.1 is-created-at-location-of 6

In this case, 1 instance of molecule type 6 is created at the same location of the molecule.

then 1 is-destroyed

In this case, the current molecule (1) is destroyed.

then 1 changes-state-to 1.2

In this case, the current molecule (tag 1) will change state according to the state description 1.2 (feature 1 changes state to state 2). Multiple feature–state changes may be specified on one line; i.e., 1.2.4.5.6.33 means that feature 1 assumes state 2, feature 4 assumes state 5 and feature 6 assumes state 33.

then 1 changes-colour-to .1:.32:.11

In this case, the molecule will change to the colour specified by .1:.32:.11 (the colons separate three float values in the RGB colour description; i.e. .1 .32 .11).

Currently, translocations are not supported as events for molecule rules (as they are for coordinator rules).

The reader should note carefully that there are minor but important differences between this format and that format used for then lines in coordinators (which have tags).


[rule] parameters [/rule]
key parameters
format parameters [string] [float]
description Used to define parameters for the event under consideration
required no
default value parameters p 1.0
example parameters kf 0.07

Notes: The parameters line is used to specify the value of the parameters for the event that will occur. The string value will represent the identifier for that parameter while the float value will represent the probability for the event to take place given that all conditions were met. The default parameters value is 1.0, meaning that events will occur if all conditions are met.


Instantiation

instantiate
key instantiate
format see below
description Creates instances of molecules and assigns locations in the
simulation.
required no
default value there are no default instantiations of molecule types
example instantiate 4 random spherical volume 10 15 10 10

Notes: The instantiate line is the last line listed for a molecule type description. This line creates instances of molecules and assigns them positions within the simulation. The instantiation line is composed of up to 14 white-space delimited fields. These fields and their formats are described in the table below, Specific examples of their use are described next.

The simplest case is to create one or more molecules at some determined point in space using the line:

instantiate 1 determined point - 10 15 10

This will create 1 molecule at a determined point (i.e. non-random) in the simulation with coordinates 10 15 10.

However, a set of molecules could also be created and given random locations within the volume of a sphere using

instantiate 4 random spherical volume 10 15 9 5

Here, 10 15 9 specifies the x,y,z coordinates for the centre of the sphere and 5 specifies the radius of the sphere.

The molecules could also be distributed on the surface of the sphere (instead of within its volume) using the line:

instantiate 4 random spherical surface 10 15 9 5

Or the distribution could be applied to a plane using:

instantiate 100 random planar - 10 15 22 5 0 1 0

Here 10 15 22 specifies the position of the plane in space, 5 represents the maximum distance from this point that the molecules will be distributed to (radius) and 0 1 0 describes a normal to the plane. In a breve simulation, a normal of 1 0 0 points up along the x axis, a normal of 0 1 0 points along the y axis and a normal of 0 0 1 points along the z axis in the positive direction. The – in field 5 is used as a placeholder since the centres of the molecules will be aligned with the plane and neither “volume” nor “surface” apply.


Lastly, a distribution may be applied to the surface or volume of a cylinder using

instantiate 100 random cylindrical volume 10 15 22 5 0 1 0 35

Here, 10 15 22 specifies the centre of the base of the cylinder. 0 1 0 specifies a normal vector to the base of the cylinder. 5 is the radius of the cylinder and 35 is the height of the cylinder.

Feature-state information may also be specified at the time of instantiation using a feature.state vector in the fourteenth field of the instantiate line. For example:

instantiate 10 random spherical volume 10 15 10 1 - - - - 1.1.2.0

will set feature 1 to state 1 and feature 2 to state 0 for this set of molecules. See feature and feature-state above.


Format of the instantiation line
position possible values description
1 instantiate This is the key that indicates an instantiation description is to follow.
2 integer Number of instances to be created.
3 random determined New instances may be distributed randomly or at a determined location in space.
4 point

planar

spherical

cylindrical

New instances are assigned some determined “point” location or a random location in a plane, sphere or cylinder.
5 volume

surface

-

Where the random distribution is specified for a solid, new instances may be distributed within the volume or on the surface of that solid. A – is used if the value is not applicable.
6 float x coordinate

x, y and z specify the position of either:

a determined point in space or

the centre of a plane or

the centre of a sphere or

the centre of a cylinder’s base

(depending on the value given in field 4)

7 float y coordinate
8 float z coordinate
9 float radius if field 4 is planar, spherical or cylindrical
10 float x coordinate

x, y and z specify vector corresponding to a normal to a plane or to the base of a cylinder (depending on the value given in field 4).

11 float y coordinate
12 float z coordinate
13 float length if field 4 specifies a cylinder
14 string

State information for the molecule. A series of two numbers (separated by dots) is used to specify the features and their states for the molecules being instantiated (see feature and feature-state above). For example, 1.0.2.3 indicates that feature 1 is in state 0 and feature 2 is in state 3.


Using multiple instantiate lines

Multiple instantiate lines may be used for creating multiple distributions of the same molecule (or coordinator) type at different locations within the simulation. Features of the molecule type may be altered between instantiate lines (see below for an example); the last description of a feature listed will be applied to the next instantiation. For example:

[moleculeType]
id 1
label molecule_a
color .81 .60 .21
shape Sphere 1
draw-as-point 0
opacity 1
show-neighbor-lines 0
neighborhood-size 5
dynamic-neighborhood-sizing 0
coordinator 1 3
instantiate 10 random spherical volume 10 30 10 5
color .99 .99 .99
instantiate 4 random spherical volume 10 20 10 5
[/moleculeType]

The above moleculeType description will create 14 molecules of type 1; however, 4 of the molecules will have a generally different starting location and a different color.


Describing coordinator types

An example coordinator type description is given below in the Figure. Each of the key-value entry lines are described in a separate table below.

An example coordinator type description

[coordinatorType]
id 4
label lipid_raft_assembly
color .81 .60 .21
draw-as-point 0
opacity 0.1
geometricType point
shape Cube .2 .2 .2
isCompartment 0
orientation vertex 0 1 0 pointing-at 0 1 0
isCreationDynamic 1
isMobile 1
isSizeDynamic 1
molecule 2 1000
instantiate 0 random spherical volume 10 18 10 1
[rule]
id 1
if 1.1.1 
if 2.2.1
then 6.1 is-created-at-location-of 1
then 1 is-destroyed
then 1 changes-state-to 1.2
then 1 changes-colour-to .1:.32:.11
then 1 translocates-to-compartment-of-molecule 2 
parameters p 1
[/rule]
[/coordinatorType]

Coordinator parameters

Appearances

id
key id
format id [integer]
description A unique identifier for this coordinator type
required yes
default value not applicable
example id 1

Notes: Id is usually the first key-value pair specified for a coordinatorType. This id is used to uniquely refer to this coordinator type in other parts of the model file.


label
key label
format label [string]
description A label for the coordinator type.
required no
default value coordinator
example label complex_ab

Notes: The label line allows the user to give a name to all coordinators of this coordinator type. The name will not appear during the simulation unless the user clicks on the coordinator during the simulation. Including spaces in a coordinator type name will truncate the name at the space.


color
key color
format color [0…1] [0…1] [0…1]
description A description of the color used to draw this coordinator type.
required no
default value some randomly chosen color
example color .81 .60 .21

Notes: A color may be specified by the user for drawing coordinators of this coordinator type.


draw-as-point
key draw-as-point
format draw-as-point [1 or 0]
description A Boolean flag indicating that the coordinator is to be drawn as a point.
required no
default value draw-as-point 0
example draw-as-point 1

Notes: If draw–as-point is set to 1 (TRUE) then the coordinator will appear in the simulation as a point. The radius will still be as specified in the shape line. This flag is used to speed up the simulation by reducing the amount of required rendering. It may also be used to hide coordinator types that are not of interest to the user. Values other than 1 are interpreted as 0 (FALSE).



opacity
key opacity
format opacity [0…1]
description A description of how opaque the coordinator should appear (where 0 is transparent and 1 is totally opaque).
required no
default value opacity 1
example opacity 0.1

Notes: Opacity can be set to some value below 1 in order to make it somewhat transparent. This allows the user to see through coordinators of a certain type that might otherwise block views to other parts of the simulation. This is particularly useful when the coordinator is used to describe a compartment in which molecules of interest are residing.


geometricType
key geometricType
format geometricType [point or plane or line]
description Specifies if the coordinator is a point, plane or line.
required no
default value geometricType point
example geometricType plane

Notes: Coordinators come in three geometric types; point, plane and line. This geometricType dictates how a member molecule will move if it joins the coordinator.

If a molecule joins a point coordinator, it will move towards the centre of the shape that is used to mark the coordinators position (see shape below). As molecules join the coordinator, the coordinator will grow into an imaginary sphere. The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules. All member molecules will maintain some distance from the centre of the coordinator such that they will be on the surface of this sphere. Non-member molecules that collide with the outside surface of a point coordinator will be deflected away from the coordinator. Non-member molecules that are resident to a compartment defined by a point coordinator (see resident-compartment-type under moleculeType) will be deflected towards the interior of the coordinator.

If a molecule joins a plane coordinator, it will move to the closest point on the surface of the plane described under shape. For example:

shape Cube 99 .2 100

Once the molecules reaches this “plane”, it will move randomly in the plane. The molecule’s distance from the centre of the plane will be constrained by the z dimension of the plane (in the above case, it will remain within 100/2 = 50 units of the centre of the plane. A plane coordinator could be used to represent a section of membrane. In this case, the settings

orientation vertex 0 1 0 pointing-at 0 1 0
isCreationDynamic 0
isMobile 0
isSizeDynamic 0

will also be used (see below) to (a) specify the orientation of the membrane, (b) to ensure that the membrane is never destroyed during the simulation, (c) to keep the membrane immobile during the simulation and (d) to maintain the size of the membrane section respectively.

Non-member molecules that collide with the outside surface of a plane coordinator will be deflected away from the plane.

Lines coordinators must be described using the “Cube” shape (see below), where the first coordinate will represent the length of the line and the other two coordinates will be a width and height that allow us to see the line. For example:

shape Cube 60 .4 .4

If a molecule joins a Line coordinator, it will move to the closest point on that line and move randomly along that line. Its motion along the line will be constrained to the length of the line. A Line coordinator could be used to represent cytoskeleton filaments (actin filaments, intermediate filaments, microtubules).


shape
key shape
format shape Sphere [float] [float]

shape Cube [float] [float] [float]

description A description of the shape used to draw this coordinator type.
required no
default value Cube 1.0 1.0 1.0
example shape Sphere 0.1
example shape Sphere 0.5
example shape Cube 100 0.2 101

Notes: Two shapes may be used to draw a coordinator: a sphere or a cube. Point coordinators can be represented as either a sphere or a cube. Plane and Line coordinators must always be represented as Cubes.

Point coordinators are usually drawn as a sphere. Only one additional float value must be given to specify the radius of the sphere. Point coordinators may optionally be drawn as a Cube so they are more easily distinguished from molecules. The point coordinator will appear as this shape and size regardless of how many molecules join it. However, the molecules will be offset from the centre of the coordinator by some distance such that they will appear to be assembled on the surface of an imaginary sphere surrounding the point coordinator. The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules. If the line

isSizeDynamic 1

is included, the size of the coordinator will grow (starting from its initial radius) to match this imaginary sphere. It is very important to set this flag in those cases where a point coordinator represents a compartment. If isSizeDynamic is set to 1, the user should choose to represent the point coordinator as a Sphere and not a Cube.

Plane coordinators are drawn as Cubes where the x, y and z coordinates are interpreted as length, thickness and width. Thickness (y) is present only for the purposes of visualizing the plane and member molecules will move in the xz plane regardless of the value of y. Note that the z coordinate is interpreted as a radius from the centre of the coordinator; member molecules cannot move past this radial boundary. Planes may be oriented to some normal using the orientation line.

Line coordinators use a Cube shape as well. The x dimension will be interpreted as length while the y and z dimension will be used to make the line visible. This does not mean that lines along the x axis are the only possibility. Lines may be oriented to any direction using the orientation line.

If the line

isSizeDynamic 1

is included, the size of the coordinator will grow by adding the diameter of each new molecule member to the length of the line.


isCompartment
key isCompartment
format isCompartment [0,1]
description Indicates whether this coordinator represents a compartment or barrier within a compartment.
required no
default value isCompartment 0
example isCompartment 1

Notes: A spherical coordinator may be used to represent a compartment that molecules can reside in and that molecules can translocate into and out of. A planar coordinator also acts as a barrier that molecules can translocate across. In either of these cases, the line

isCompartment 1

should be included.

Molecules that are part of these compartment coordinators will have a feature (feature id 99999) set to the coordinator type id when they become assembled with the coordinator. This allows rules to be written that specify that a molecule must be part of some compartment coordinator in order to participate in some rule. See rule below for examples.

A molecule should only belong to one coordinator that is a compartment.


orientation
key orientation
format orientation vertex [vector] pointing-at [vector]
description Specifies the orientation of a plane or line coordinator.
required no
default value orientation vertex 0 1 0 pointing-at 0 1 0
example orientation vertex 0 1 0 pointing-at 1 0 0

Notes: Orientation is used in combination with plane and line coordinators. By default, a plane coordinators shape will be positioned in the xz plane and a lines shape will be positioned in the x axis. This can be altered by pointing the plane or line along some other normal using the line:

orientation vertex 0 1 0 pointing-at 1 0 0

where 0 1 0 is some vertex on (relative to) the shape used to draw the coordinator. The vertex is used in combination with the coordinators position to create a vector. This vector is then “pointed at” some point in the simulation space (specified here as 1 0 0). The example above will orient the plane so its surface “points” or is orthogonal to the x axis. Multiple instances of a plane coordinator can be created with altered orientations to make a box like structure representing the simulation boundaries like this:

[coordinatorType]
id 10
label simulation-container
color .383 .466 .561
opacity 0.1
geometricType plane
shape Cube 100 .2 100
neighborhood-size 10
isCreationDynamic 0 
isMobile 0
#west wall
orientation vertex 0 1 0 pointing-at 1 0 0
instantiate 1 determined point  - 0 50 50
#east wall
orientation vertex 0 1 0 pointing-at -1 0 0
instantiate 1 determined point  - 100 50 50
#north wall
orientation vertex 0 1 0 pointing-at 0 0 1
instantiate 1 determined point  - 50 50 0
#south wall
orientation vertex 0 1 0 pointing-at 0 0 -1
instantiate 1 determined point  - 50 50 100
[/coordinatorType]


isCreationDynamic
key isCreationDynamic
format isCreationDynamic [0,1]
description A Boolean flag specifying whether the creation (and destruction) of the coordinator is dynamic.
required no
default value isCreationDynamic 1
example isCreationDynamic 0

Notes: Point coordinators that are used to represent complexes of molecules or single interactions are normally dynamically created; i.e., they are not instantiated by an instantiate line at the beginning of the simulation. Instead, they are created as member molecules of the coordinator as those molecules detect one another within one-another’s neighborhoods. Such a coordinator will only form if at least two member molecules are present to nucleate its formation. If a coordinator forms and subsequently loses members such that it has only one or no members, it destroys itself. This is the default behaviour of all point, plane and line coordinators. If the line,

isCreationDynamic 0

is included, then only those coordinators that are instantiated at the beginning of the simulation will be created and they will persist throughout the simulation (i.e. they cannot be destroyed). This setting is commonly used for plane coordinators used to represent membranes. Note that all values other than 1 will be treated as zero (FALSE).


isMobile
key isMobile
format isMobile [0,1]
description A Boolean flag specifying whether the coordinator is allowed to move during the simulation.
required no
default value isMobile 1
example isMobile 0

Notes: Point coordinators that are used to represent complexes of molecules or single interactions are normally mobile; i.e., at each iteration they move to some position that is central (average) to the positions of all member molecules.

Plane coordinators (used to represent membranes) and Line coordinators (used to represent cytoskeleton) are usually created once at the beginning of the simulation at some point in space. Using the line

isMobile 0

will ensure that the plane coordinator remains in this position for the duration of the simulation. Note that all values other than 1 will be treated as zero (FALSE).


isSizeDynamic
key isSizeDynamic
format isSizeDynamic [0,1]
description A Boolean flag specifying whether the size of the coordinator can change.
required no
default value isSizeDynamic 0
example isSizeDynamic 1

Notes: Point coordinators that are used to represent complexes of molecules or single interactions are normally statically sized; i.e., the initial size specified at the beginning of the simulation (under shape) is maintained throughout the simulation. In these cases, the shape of the coordinator is used only to mark the position of the coordinator. However, in cases where a point coordinator is used to represent a compartment, the size of the coordinator can be used to represent the boundaries of that compartment. Member molecules of the compartment coordinator will be offset from the centre of the coordinator by some distance such that they will appear to be assembled in the surface of an imaginary sphere surrounding the point coordinator. The surface area of this imaginary sphere will be equivalent to the sum of the cross-sectional areas of all of the member molecules. If the line

isSizeDynamic 1

is included, the size of the coordinator will grow (starting from its initial radius) to match this imaginary sphere. This flag is essential for compartment coordinators if they are to include or exclude molecules because the coordinator shape handles collisions with all molecules and determines whether they should be kept outside or inside the compartment.

Plane and line coordinators can also make use of this flag. As molecules are added to a plane coordinator, the surface area of the plane will increase to account for the added cross-sectional area of the molecule. In a line coordinator, the length of the line will increase an amount equal to the diameter of each recently added molecule.

Molecules

molecule
key molecule
format molecule [integer] [integer] [integer]
description A description of the potential member molecules for the coordinator along with their stoichiometries and whether their assembly into this coordinator is unconditional.
required no
default value there are no default molecule assignments but the third value (whether assembly into this coordinator is unconditional) has a default value of 1 if it is not specified
example molecule 1 2

Notes: A set of potential member molecules is specified using one or more molecule lines. Each line lists a moleculeType identifier (see id under moleculeType) and then a maximum allowed stochiometry for that molecule type. So for example, the line

molecule 1 2

allows for up to two instances of moleculeType 1 to join the coordinator.

The above line is equivalent to

molecule 1 2 1

Because the third value has a default value of one if not specified. This value (either 1 or 0) indicates whether the molecule type can assemble unconditionally into the coordinator (default is 1; meaning yes). However, if the line is

molecule 1 2 0

then the assembly of the molecule is dependent on the presence of other molecules (that must co-assemble with the molecule or that must already be present as members of the coordinator in order for the molecule to assemble . This dependency is described by a rule (see below).

Coordinator Rules

Note: For the most part, rules should be encoded using Coordinator Rules. However, there are special cases where rules need to be specified for single molecules that are not associated with a coordinator. In these cases, Molecular Rules can be used (see above).


[rule] …[/rule]
key See below. Multiple keys are associated with this subsection including id, time, if, competitve-with, then, and parameters
format
[rule]
id [integer]
time [float] optional
if [string]
.
.
competitive-with [integer]
.
.
then [string or integer] [string] [string or integer]
.
.
parameters [string] [float]
.
.
[/rule]
description Used to define events that occur between members of a coordinator.
required no
default value there are no default rules
example
[rule]
id 1
if 1.1.1
competitive-with 2
then 1 is-destroyed
parameters p 0.001
[/rule]

The [rule] … [/rule] subsection of coordinators is used to define events that occur between member molecules of a coordinator. Multiple rule subsections may be associated with one coordinator. Each rule is defined using multiple lines with keywords id, if, competitive-with, then and parameters. These keywords and their line formats are described below. In general, each rule has

1) an identifier that is unique to the coordinator

2) a set of prerequisite conditions (specified by if lines) that must be met in order for

3) some set of events (specified by then lines) that will occur with some probability defined by

4) a set of parameters specified on one or more parameter lines.



[rule] id [/rule]
key id
format id [integer]
description Used to identify a rule for a coordinator
required yes
default value not applicable
example id 1

Notes: The id line defines a single integer identifier for a rule. It must be the first line of the rule subsection and it must be unique to the rules defined for the coordinator of which it is a part.


[rule] time [/rule]
key time
format time [float]
description Used to identify a time when the rule should be considered.
required no
default value none - the event will be executed once the conditions are met (see if lines below)
example time 1.000000

Notes: The event will be executed at a specific time if the conditions are met at that time (see if line below). If no conditions are specified, then the rule will be executed at that time.


[rule] if [/rule]
key if
format if [string]
description Used to define a prerequisite condition for some event. The precondition is expressed as a set of molecules(s) of some type in some state that must be members of the coordinator (either already assembled or unassembled).
required no
default value there are no default values
example if 1.1.1.0

Notes: The if line is used to define a prerequisite condition for some event. The precondition is expressed as a set of molecules(s) of some type in some state that must be assembled members of the coordinator. The line contains a single value that is a dot delimited list of integers. For example,

if 34.2.1.1.3.4.0.8.6

This dot-delimited condition is of the form:


if line format
position Meaning and possible values Example
1 An integer that serves as a tag to identify this set of condition meeting molecules. This tag may be used in “then” lines for the rule (see below). 34
2 Required molecule type (an integer corresponding to a molecule type id). See “id” key under [moleculeType] 2
3 Required stoichiometry of molecules meeting this condition (some integer). 1
4 Either 1 or 0.

The molecule must already be an assembled member of the coordinator (1) or it may be only be an unassembled member (0). An explanation of “assembled” and “unassembled is given below.

1
5 + 3n The following two numbers indicate a feature-state match that must be met (1) or that must not be met (0). 1
6 + 3n Feature identifier specified by some integer. 3
7 + 3n Required state of feature (previous position) specified by some integer. 4

Notes: n is an integer from 0, 1, 2… specifying a feature state condition (see explanation below).

So the first four numbers in the example above

if 34.2.1.1

mean that 1 copy of molecule type 2 must be assembled (1) as part of the coordinator in order for this rule to be considered. This molecule is assigned the “tag” identifier of 34 for use in the then line (see below). In addition, a repeating series of three numbers may be appended to specify the required state of the molecule. For example, in

if 34.2.1.1.1.3.4.0.8.6

the appended 1.3.4 (at positions 5 to 7) would indicate that the molecule must have (1) feature 3 in state 4. And the following 0.8.6 (positions 8 -10) would indicate that the molecule must NOT have (0) feature 8 in state 6.

Molecules can be in one of three states with respect to the coordinator (not to be confused with states of molecule features). The three sates are:

1) UNASSEMBLED – meaning that the molecule is a potential member of the coordinator but it is not yet assembled as part of the coordinator nor is it ASSEMBLING.

2) ASSEMBLING – meaning that the molecule is a member of the coordinator but it is not yet assembled as part of the coordinator but is in the process of ASSEMBLING (i.e. moving under the influence of the coordinator towards the coordinator).

3) ASSEMBLED – meaning that the molecule has been moved into position by the coordinator and has reached the offset distance of the coordinator as defined by the coordinator and its member molecules.

For example, freely-diffusing potential members of a protein complex may become members of a new or existing coordinator but will be UNASSEMBLED with the point coordinator representing the complex until they meet some set of conditions required for assembly into the complex. Once these conditions are met, they will begin assembly (ASSEMBLING) as they move into position around a coordinator (the position of a coordinator is defined as the midpoint between all ASSEMBLED or ASSEMBLING member molecules).

In practice, a look-ahead function considers potential molecules for a coordinator and only adds them if they have the ability to begin assembly. If they do not meet conditions required for assembly, they are not added to the coordinator (or used to generate a new coordinator). If molecules are assigned as members of a coordinator and are then found to be unable to begin assembly (i.e. they are found to be UNASSEMBLED at the end of the iteration), they are removed from the coordinator and made available to the simulation so that they can help form new coordinators or join existing coordinators.

The ASSEMBLING member molecules will cease movement towards the coordinator once they reach some offset distance from the coordinator (that is, for example, defined as a sphere around the coordinator whose surface area is equivalent to the sum of the cross-sectional areas of the member molecules).

There is one special feature id (99999) that is reserved for holding compartment information. Molecules that are part of a planar or spherical coordinator that represent a compartment or compartment boundary (see isCompartment above) have their feature 99999 set to the identifier of the coordinator type once they become assembled with that coordinator. In addition, molecules that reside within a spherical coordinator have their feature 99999 set to the identifier of the coordinator type once they translocate into that coordinator or if they start in that compartment at the beginning of the simulation (see resident-compartment-type under moleculeType)

This feature-value pair is used when describing rules that use translocations (see below).


[rule] competitive-with [/rule]
key competitive-with
format competitive-with [integer]
description Used to point out that the present rule and the rule having the specified id can not occur simultaneously.
required no
default value there are no default values
example competitive-with 1

Notes: The competitive-with line specifies the identifier for a rule that is competitive to the current rule. That means that the rule including this line and the rule having the specified id can not occur simultaneously, even if the specified conditions in the if line were met, so the algorithm will choose one of them or neither of them, but never both. This is useful when having coordinators that can follow different reactions.


[rule] then [/rule]
key then
format then [string or integer] [string] [string or integer]
description Used to define events that occur as a result of interactions between members molecules
required no
default value there are no default events
example then 1 is-destroyed

Notes:

The then line is used to define events that occur (if some set of molecules in some state are assembled members of a coordinator as defined by the if lines). There are several different possibilities for this line that are differentiated by the second string value. They are:

then 3 begins-assembly

In this case, the molecule(s) with tag 3 (molecules meeting some condition defined by a preceding “if” line) are allowed to begin assembly with the coordinator.

then 6.1 is-created-at-location-of 1

In this case, 1 instance of molecule type 6 is created at the location of the molecule with tag 1 (see tags under “if” lines). State information can be specified for the molecule that is to be newly created; for example, 6.1.2.3 would create 1 instance of molecule 6 with feature 2 in state 3.

then 1 is-destroyed

In this case, the molecule(s) with tag 1 (see tags under “if” lines) is destroyed.

then 1 changes-state-to 1.2

In this case, the molecule(s) with tag 1 (see tags under “if” lines) will change state according to the state description 1.2 (feature 1 changes state to state 2). Multiple feature–state changes may be specified on one line; i.e., 1.2.4.5.6.33 means that feature 1 assumes state 2, feature 4 assumes state 5 and feature 6 assumes state 33.

then 1 changes-colour-to .1:.32:.11

In this case, the molecule(s) with tag 1 (see tags under “if” lines) will change to the colour specified by .1:.32:.11 (the colons separate three float values in the RGB colour description; i.e. .1 .32 .11).

then 1 translocates-into-compartment-of-molecule 2

In this case, the molecule(s) with tag 1 (see tags under “if” lines) will be translocated into the compartment that the molecule with tag 2 is a member of. This compartment is a point coordinator where

isCompartment 1
isSizeDynamic 1

has been specified.

The molecule with tag 2 is a mediator of the translocation and resides in the surface (membrane) of the compartment. Use of this translocation event is usually accompanied by an if line that first checks that the translocating molecule is outside the compartment and the mediating molecule is assembled with the surface of the compartment. See the file Example_model_files_for_Magrathea#Example 6.3 for an example model.

Do not use to translocate-into-compartment across a planar coordinator representing a membrane boundary. Instead use translocate-past-molecule (below).

then 1 translocates-outof-compartment-of-molecule 2

Similar to translocates-into-compartment-of-molecule except the translocated molecule is moved out of the compartment instead of into.

Use of this translocation event is usually accompanied by an if line that first checks that the translocating molecule is inside the compartment and the mediating molecule is assembled with the surface of the compartment. The translocating molecule has its resident compartment information altered accordingly.

See the file Example_model_files_for_Magrathea#Example 6.3 for an example model.

Do not use to translocate-outof-compartment across a planar coordinator representing a membrane boundary. Instead use translocate-past-molecule (below).

then 1 translocates-past-molecule 2

In this case, the molecule(s) with tag 1 (see tags under “if” lines) will be translocated across some membrane boundary (represented by a planar coordinator) that molecule 2 is a part of. This planar coordinator has been defined using the line

isCompartment 1

The molecule with tag 2 is a mediator of the translocation and resides in the surface (membrane) of the coordinator. Use of this translocation event is usually accompanied by an if line that first checks that the mediating molecule is assembled with the surface of the compartment. The translocated molecule moves to the other side of the boundary. There is no change made to the translocating molecule’s resident compartment information. See the file Example_model_files_for_Magrathea#Example 6.3 for an example model.

Do not use to translocate-past-molecule across a point coordinator representing a compartment. Instead use translocate-(into/outof)-compartment-of-molecule (above).

then 3 leaves-coordinator

In this case, the molecule(s) with tag 3 (molecules meeting some condition defined by a preceding if line) will leave the coordinator.


then 1.5 is-instantiated spherical surface - - - 1.0 - - - - 1.1

This format is used to create new molecules with respect to the position of coordinator and does not require any other molecules to position the newly formed molecules (c.f. "is-created-at-location-of"). It is intended to be used in combination with a timed event (see time above).

"1.5" means that five instances of molecule type 1 are to be created.

"spherical surface - - - 1.0 - - - - 1.3 -" means that the instantiation will occur on (random) locations on the surface of a sphere with radius 1.0 (with respect to the coordinator's centre) and that the new molecules will have their feature 1 set to state 3. This section of the line corresponds to the "instantiation line" format (see above). Dashes (-) correspond to options of the instantiaton line that do not apply in this case and are not supported. New molecules will be assigned to the compartment in which they are created. "point" may also be used in place of "spherical"; planar and cylindrical are currently not supported. "surface" may be replaced by "volume". See the "instantiation line" format above.


[rule] parameters [/rule]
key parameters
format parameters [string] [float]
description Used to define parameters for the event under consideration
required no
default value parameters p 1.0
example parameters kf 0.07

Notes: The parameters line is used to specify the value of the parameters for the event that will occur. The string value will represent the id for that parameter while the float value will represent the probability for the event to take place given that all conditions were met. The default parameters value is 1.0, meaning that events will occur if all conditions are met.


Instantiation

instantiate
key instantiate
format see “instantiate” line description above under the section for describing molecules
description Creates instances of coordinators and assigns locations in the simulation.
required no
default value there are no default instantiations of coordinator types
example instantiate 1 determined point - 10 15 100

Notes: Instantiation of coordinators is handled with an instantiate line that has the same format as the instantiate line for molecules (see above under moleculeType) except that coordinators have neither features nor states.

The instantiate line is optional and so may be omitted. This is quite often the case especially for point coordinators representing interactions or complexes that are dynamically created by their member molecules.


simulation

The simulation section is entirely optional (none of the parameters in this section are mandatory because they all have default values that are set by magrathea). However, specifying parameters in this section, allows the user to override default options that alter the running of the simulation itself.

An example of a simulation description is given in the Figure below. Each of the key-value entry lines are described in a separate section below.

An example simulation description

[simulation]
produce-visual-output 1
camera-at-from 10 10 0 0 1 30
light-source 0 20 20
background-color 0 0 0
movie-length 10
simulation-length 100
time-step .01
move-realistically 1
[/simulation]
produce-visual-output
key produce-visual-output
format produce-visual-output [0,1]
description Should visual output be generated
required no
default value produce-visual-output 1
example produce-visual-output 0

Notes: This should only be set to zero to prevent magrathea from trying to call visual libraries that may not be present in some environments (say on a Linux cluster node). This will prevent proper camera positioning, light positioning and movie making although an image may still appear in the breve simulation window.


camera-at-from
key camera-at-from
format camera-at-from [x y z x y z]
description Set up the camera.
required no
default value camera-at-from 20 20 0 1 5 50
example camera-at-from 10 10 0 0 1 30

Notes: The first x,y,z vector describes the camera target. The second vector describes the camera position. Vector values must be separated by spaces. Vector values can be floats. produce-visual-output must be set to 1.


light-source
key light-source
format light-source [x y z]
description Set up the light-source
required no
default value light-source 20 20 20
example light-source 0 20 20

Notes: The vector of x, y z floats describes the position of the light source in the simulation. produce-visual-output must be set to 1.


background-color
key background-color
format background-color [0...1] [0...1] [0...1]
description Background color for the simulation.
required no
default value background will be sky-blue
example background-color 0.1 0.1 0.1

Notes: This can be set to change the color of the "sky" in the simulation.


movie-length
key movie-length
format movie-length [float]
description Length of the movie.
required no
default value movie-length 5.0
example movie-length 100

Notes: Set the length of the simulation to be captured to simulation.mpeg. produce-visual-output must be set to 1.


simulation-length
key simulation-length
format simulation-length [float]
description Is there a time-limit on the simulation.
required no
default value simulation-length 0
example simulation-length 20

Notes: If this is set to zero, the simulation will not end. Otherwise, the simulation will end after the specified number of seconds of simulation time. As of breve 2.7.2 and magrathea 1.67, the simulation may not end gracefully and may require restarting breve. Default setting is recommended.


time-step
key time-step
format time-step [float]
description Time-step.
required no
default value time-step 0.1
example time-step 0.01

Notes: This value is used to call the controller methods setIntegrationStep and setIterationStep. See http://spiderland.org/documentation/steveclasses/Control.html. The default setting is recommended.


move-realistically
key move-realistically
format move-realistically [0,1]
description Animation or simulation.
required no
default value move-realistically 0
example move-realistically 1

Notes: This setting determines how molecules will move. A default value of zero will render animations. A value of one (1) will cause molecules to move according to brownian dynamics. The default setting is recommended. Not all features of magrathea are supported for move-realistically 1.

The counter

The counter section allows the user to specify the simulation entities that should be counted during the simulation. The result is a plain text file, whose columns represent the variables (time and each specified molecular species) and whose rows store each value of the time series. The file is called “output.txt” by default and is placed in the same directory as the breve executable.

An example of counter description is given in the Figure below. Each of the key-value entry lines are described in a separate section below.

An example counter description

[count]
counter-type specified
molecule-to-count 1.1.1.0.2.63
molecule-to-count 2.1.1.1.2.63
molecule-to-count 3.2.1.1.1.1
molecule-to-count 4.1.1.1.3.5
molecule-to-count 5.1.1.0.2.63.1.3.5
molecule-to-count 6.1.1.0.2.63.1.3.5.1.1.1
[/count]


counter-type
key counter-type
format counter-type [nothing, type, specified]
description Specify the type of counter.
required no
default value nothing
example counter-type specified

counter-type type

counter-type nothing

Notes: The line:

counter-type nothing

indicates that no counting will be done during the simulation. If counter-type is set to nothing, all information in the molecule-to-count line will be ignored.

The line:

counter-type type

indicates that instances of each molecule type will be counted during the simulation, regardless of their feature-state description.

The line:

counter-type specified

indicates that molecule instances will be counted during the simulation according to some specified molecule type and feature-state description. If counter-type is set to specified, the information in the molecule-to-count line will be used as such specification.

The counter types are mutually exclusive, so having more than one counter-type line is not allowed. In cases where the user needs to count certain molecules including their features and states together with other molecules without features or states, that could be done using the specified option.


molecule-to-count
key molecule-to-count
format molecule-to-count [string]
description Specify the molecule type to count (and features and states, when possible).
required no
default value none
example molecule-to-count 4

molecule-to-count 1.1.1.0.2.63

molecule-to-count 2.1.1.1.2.63

molecule-to-count 5.1.1.0.2.63.1.3.5

Notes: When working with counter-type type, the molecule-to-count line uses the format:

molecule-to-count [moleculeTypeId]

For example:

molecule-to-count 4

When working with counter-type specified, the molecule-to-count line uses a dot-delimited format, as explained below.

dot-delimited format for describing molecules
position Meaning and possible values Example
1 An integer that serves as a tag to identify this type of molecule. 1
2 Required molecule type (an integer corresponding to a molecule type id). See “id” key under [moleculeType] 1
3 Either 1 or 0.

The molecule must already be an assembled member of the coordinator (1) or it may only be an unassembled member (0). So far this position is ignored, but it must be specified in order to avoid errors.

1
4 + 3n The following two numbers indicate a feature-state match that must be met (1) or that must not be met (0). 0
5 + 3n Feature identifier specified by some integer. 2
6 + 3n Required state of feature (previous position) specified by some integer. 63

Notes: n is an integer from {0, 1, 2,…} specifying a feature-state pair.

As an example, the line

molecule-to-count 4.1.1.0.2.63.1.3.5

indicates a molecule type to count that is tagged '4' and has a molecule type with id 1 and assembled to the coordinator (1), which does not have (0) feature 2 in state 63 and does (1) have feature 3 in state 5. Molecules that met all these conditions will be counted as the same specified species (with tag 4 in the output file).

In principle, any number of molecule-to-count lines can be added. Each specified species will occupy a column of the output file.