Abstracted Protein Simulator: tutorial

Abstracted Protein Simulator

This page aims to help the user become familiar with the process of creating protein simulations. It will describe the creation of a simulation of protofilament formation. Protofilaments are the long rods of end-to-end tubulin molecules which associate laterally to form microtubules. The number of protofilaments making up a microtubule can vary, though 13 is typical, as is the case in the microtubule simulation. This page will only discuss the details of the XML input files which are relative to the protofilament example, for full details of the input file formats, see here.The files at each stage can be found in the tutorial directories located in the root directories pointed to by the simulator's file selectors. They can also be obtained by following the links in the relative section below.

Skeleton Files


The first step in the creation of the simulation is to create the skeleton template and object files. These have a standard format, given in following files:

tutorial01.tmpl

The blank template file

tutorial01.obj

The blank object file.


If you load these files into the simulator, the simulation can be run but, as is expected, there are no particles displayed.

A Single Tubulin


In this stage, an alpha-beta tubulin unit will be created. Tubulin units, as we shall be modelling them, are formed from two particles, an alpha and a beta monomer.


The first step is to create a Landscape object which determines how the particles will interact with the background. The most basic is the flat landscape which gives the particles uniform diffusion (due to Brownian Motion) in three dimensions. The following XML fragment defines the flat landscape (to be placed in the template file):


<list class="xmlobjects.XMLLandscape" id="flat" type="flat"/>


The next step is to create particle templates for the alpha and beta monomers. In the case of the alpha monomer, this can be acheived with the following code (to be placed in the template file):


<list class="xmlobjects.XMLParticleTemplate" id="alpha" mass="1" shape="cylinder" colourR="1.0" colourG="0.2" colourB="0.2" alpha="0.0" landscapeId="flat" collide="true"> <dimensions> <dimension class="Float" value="2E-9"/> <dimension class="Float" value="4E-9"/> </dimensions> </list>

This creates a template of type XMLParticleTemplate, which is the type taken by all particles in the simulation. The id element gives the ID for the particle template (each must have a unique ID and these must not be the same of any other ID in the simulation). The masses are treated as relative by the simulation, rather than absolute. In this example both monomers will have mass 1, indicating they are the same weight. The shape of the particle is specified as a cylinder. This is for display purposes only - in the simulation update routines it will be treated as a sphere. The colourR/G/B fields specify the red, blue and green components of the particle's colour and take fall in the range 0.0 - 1.0. alpha, which has a similar range specifies how transparent the particle is, with 0.0 representing fully opaque. landscapeId names the landscape used by the particle, in this case "flat", as mentioned above. The collide parameter can be true or false and indicates whether collision detection should be performed on this particle.


The dimensions list define the objects size. For spheres and cylinders the first element in the list is the radius. For cylinders the second element in the list is the height.


The beta monomer can be defined similarly. Once the particle templates have been defined it is necessary to create an object template to contain them and define their relative positions. This can be done with the following code (again in the template file):

This creates an template of type SimObjectTemplate which is the type which defines all object templates. As always the id field is present and unique. The particleTemplateIds field is a semi-colon separated list (with no white-space) specifying the ids of the particles which make up the object. The particleTemplateCoordX list specifies the x-coordinate of each particle in turn, relative to the centre of the object. The other fields do the same for the y and z-coordinates. The ParticleTemplateOrient fields specify an axis through the centre of the particle and a rotation about that axis.


The template file is now ready. Next the object file must be created. This is a simpler process than creating the template file, as all that must be specified is the position at which the tubulin object should be created. This can be done with the following code:


<list class="xmlobjects.XMLSimObject" id="alphabeta-001" templateId="alphabeta" centreOfMassX="0E-9" centreOfMassY="0E-9" centreOfMassZ="0E-9" orientationX="0.0" orientationY="1.0" orientationZ="0.0" orientationAngle="0.0"> </list>


The files are now ready to be run with the simulation. When they are run a single tubulin object will be created at the centre of the simulation. The complete template and object files are available from within the tutorials/ directory found in the default file directories of the simulator. They are also available here:

tutorial02.tmpl

The tubulin template file

tutorial02.obj

The single tubulin object file.

Multiple Tubulin

Protofilaments are formed from multiple tubulin units. In order to increase the number of tubulin in the simulation, the object code for the original tubulin object (the code from the object file) can be copied as many times as necessary and its coordinates changed. The object file below contains the code to create 77 tubulin objects. The template file is unchanged from above, but has been copied to tutorial03.tmpl for clarity.

tutorial03.tmpl

The tubulin template file

tutorial03.obj

The multiple tubulin object file.

Bonding

Running the above files in the simulator will cause the tubulin to diffuse through Brownian Motion, but they will not react with one another. This section will show you how to create bonding behaviour between the tubulin. In protofilaments the tubulin are joined end-to-end. In order to acheive this in the simulator each tubulin must be given two bond sites, one on the end of the alpha monomer and one on the end of the beta monomer. The first step which will be taken in the creation of bonds is the specification of some rules which will govern the bonding behaviour of the particles. The following three rules will be required:


<list class="xmlobjects.XMLRuleTemplate" id="blockAll" action="block" ifClause="this.connected == *"/> <list class="xmlobjects.XMLRuleTemplate" id="end-end-alpharule" action="add" ifClause="that == end-end-beta"/> <list class="xmlobjects.XMLRuleTemplate" id="end-end-betarule" action="add" ifClause="that == end-end-alpha"/>

All rules in the simulation are of the XMLRuleTemplate class, but there are three types: block, add and drop. The type is specified by the action parameter. Each rule also has an ifClause which defines the conditions of the rule, given as a semi-colon separated list (with no white-space around the semi-colon). The conditions must all be satisfied for the rule to be true and a rule being true causes the specified action to occur. With in the conditions, this refers to the bond containing the rule and that refers to the bond being considered for a possible pairing with this bond. In the first rule the if clause states that the rule is true if 'the ID of the bond paired with this bond is not null', or more simply 'if this bond is already part of a pair, it won't bond with anything else'. In the second rule the rule is true if 'the bond being considered for a pairing with this one has the ID end-end-beta', or 'this bond can pair with the bond on the beta end of a tubulin'. The third has a similar meaning.


The next step is to create the actual bonds which will be assigned to each particle. The two bond definitions (one for alpha and one for the beta monomer) are given below:


<list class="xmlobjects.XMLBondTemplate" id="end-end-alpha" blockRuleTemplateIds="blockAll" dropRuleTemplateIds="" addRuleTemplateIds="end-end-alpharule"/> <list class="xmlobjects.XMLBondTemplate" id="end-end-beta" blockRuleTemplateIds="blockAll" dropRuleTemplateIds="" addRuleTemplateIds="end-end-betarule"/>


The first one creates the bond for the alpha monomer. It takes two rules, the first and second from the ones above. These rules combine to give the bond the following behaviour: if the alpha monomer is not bonded to anything, it is available to bond to a similarly available beta monomer. The second bond creates the reciprocal behaviour for the beta monomer.


The final step in creating bonding behaviour in the simulator is to associate the bonds with their respective particles. In the case of the alpha particle this can be acheived by altering its particle definition from that given in the single tubulin section to the following:

The most obvous change is the addition of the bondPointX / Y / Z lists. These give the coordinates of three points which define the position and orientation of the bond. The bond site is perhaps best thought of as a 2D area which is placed (typically on the surface) of the object. The first point (defined by the first element in each coordinate list) specifies the centre of this 2D area - when a bond-pair is formed, their two centres are set to the same location. The second point is a point on the vector, normal to the area, which passes through the first point - when a bond-pair is formed the two normals will be rotated to lie along the same line, but point in opposite directions. The third point is another point on the surface of the area (and at right angles to the normal) - when the bond pair is formed the vectors from point 1 to point 3 on each bond will be rotated into alignment.

Another change is the inclusion of the bondTemplateIds parameter which declares the bonds associated with this particle. It takes the form of the comma separated list, with the first bond located by the first three bond point coordinates, the second by the second three, etc. The final change which has been made is the addition of the bondedColourR / G / B / Alpha parameters which override the particle's normal colour settings whenever the particle has at least one paired bond.


The complete files are given below and are in the default directories of the simulator. Running them will result in the creation of self-forming microtubules. The object file has not changed, but is once again copied to have the same number as the corresponding template.

tutorial04.tmpl

The bonding tubulin template file

tutorial04.obj

The multiple tubulin object file.

Probabilities

When the simulation files above are run, the bonds will form pretty much instantly. This is because the rules specified are easily satisfied, as long as there are free tubulin units nearby. Sometimes however, it is unrealistic to have bonds always forming instantly. Sometimes it would be better if the bond formation had only a certain probability of forming when the rule is satisfied. This can be acheived by modifying the rule templates. The modification for the alpha rule is shown here:


<list class="xmlobjects.XMLRuleTemplate" id="end-end-alpharule" action="add" ifClause="that == end-end-beta"> <probabilities> <probabilities class="Float" value="0.0"/> <probabilities class="Float" value="0.5"/> </probabilities> <times> <times class="Float" value="0"/> <times class="Float" value="100E-6"/> </times> </list>


The probabilities list specifies the probabilities of the rule being true and the corresponding entries in the times list specify the time at which a given probability is in force. These probabilities are scaled between to find the probabilities for intermediate times. The beta rule can be modified in the same way as the alpha rule. The files for this change can be found here:

tutorial05.tmpl

The probability bonding template file

tutorial05.obj

The multiple tubulin object file.


This tutorial has now introduced the basic principles behind the creation of simulations. The user should now know enough about the XML file format to begin altering the sample simulation and creating new ones. For a more detailed specification of the file formats, see here.