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 Figure 1.

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]

An example model.txt file for Magrathea

###########
#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

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.

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 Figure 2. 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 Insert screen shot here

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]

id

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

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