The Magrathea Manual: Building Coordinated Agent Models

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

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.

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 neighborhood-size).
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	A description 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-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).

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. The abstract ideas of channels and coordinator are more thoroughly explained in previous sections of this manual.

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 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, 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 to be carried out (specified by then lines) 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 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 molecule to which belongs to.

[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:

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 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 molecules that can follow different reactions.

[rule] then [/rule]
key	then
format	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.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).

[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 (so far) 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.

In the future, the float value could include values of kinetic mass-action, Michaelis-Menten or Hill constants. Not implemented yet.

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. An instantiate line is also used to create new instances of coordinators and position them in space; the same format given below applies. 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

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 a point on the plane, 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 0 1 0 points up along the y axis, a normal of 1 0 0 points along the x 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 0 1 0 5 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.

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.

Format of the instantiation line
field	format	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 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.
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.

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 joins 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 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. Generally, a plane coordinator is 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. Generally, a Line coordinator is 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 2
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 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. '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 one 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 [1,0]
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 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 [1,0]
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 [1,0]
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 [1,0]
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, if, then, and parameters
format	[rule] id [integer] 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 to be carried out (specified by then lines) according to

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	there are no default rules
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] 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 sate 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 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 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 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.

[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 (so far) 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.

In the future, the float value could include values of kinetic mass-action, Michaelis-Menten or Hill constants. Not implemented yet.

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.

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 (called “output.txt” by default), whose columns represent the variables (time and each specified molecular species) and whose rows store each value of the time series.

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

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 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 + 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 case 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: Note: n is an integer from {0, 1, 2,…} specifying a feature-state condition.

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.