Index |
Last Appendix |
Next Appendix |
This Appendix describes the simple object description language used in the "Protein Dynamic Description Files", or ".pddf files" to designate the important properties of the monomers used by the nanoscale simulation program. This is the central file used by the program to specify all the user-set details of the simulation (aside from a small number of command line options that mainly specify details of reporting and logging - see Appendix E).
These .pddf files must specify the:
The .pddf file is a series of definitions describing the structure and behaviour of the objects the nanosimulator will process and simulate.
The .pddf files use a number of basic data types for atomic information. The most common is the floating point number (e.g., ignoring quotes; '48', '0.4' or '9000.992'). Strings are frequently used to name objects, and simply appear as unadorned text (e.g., ignoring quotes; 'frog', 'pond_47'). In addition, two other special data types are used, points and colours.
Points represent a position in three dimensional Cartesian space. They are expressed as a triplet comprised of an x, y and a z co-ordinate value (each a floating point number) separated by angle brackets:
point:
<x co-ord, y co-ord, z co-ord>
e.g. <14,-2.6,0>
No spaces should appear between the start and end angle bracket in a point definition.
Colours are used for display purposes only. They are useful to show the different molecular species in a simulation, and the different states of the objects. Colours are specified by either a small number of keyword strings, or a hexadecimal RGB triplet expressing a 24 bit colour.
colour:
red, green, blue, gray, grey, black, white, lightRed, lightGreen, lightBlue, yellow, purple, cyan
or
OxRRGGBB
(Where RRGGBB are hexadecimal digits, the 'RR' digits specifying the red value, the 'GG' triplet specifying the green value, and the 'BB' triplet specifying the blue value)
e.g. 0xFF0000 is the same as red.
A .pddf file has two main parts; a model definition, followed by linkage definitions. The model definition must come first.
.pddf file:
model definitions
linkage definitions
The model definition must describe each molecular species in terms of its geometry, 'colour' (used for display purposes only), binding site geometry, states, and list the events that cause state changes. The order this is done in is important, as it is not possible to use entities before they have been defined (i.e. a component sphere cannot be mentioned in a state definition before it has been defined).
model definition:
{
geometrical structure
linkage sites
states
events
}
The geometrical structure of the object is defined solely as a set of component spheres. This usually involves approximating the structure of the object to some extent; for example a rod-like protein must be represented as a string of spheres.
structure definition:
<list of component spheres>
component sphere:
sphere name radius centre colour
sphere - a key word specifying the start of a component sphere declaration. In the future, other keywords may be added for other geometries.
name - a human readable unique name that is used within the .pddf file, and for logging info.
radius - a floating point number specifying the radius of the sphere in nanometers
centre - a point specifying the position of the sphere centre
colour - the initial colour of this sphere in the starting state
e.g.
sphere Molecule_Centre 0.9 <0,0,0> red
A linkage site is an approximation of molecular binding, that reduces the link between two molecules to a single point of contact. The linkage site definition must specify the position of the site, as well as the direction of the site and optionally a "twist" vector for the site, which must be at right angles to the direction. When another molecule links to this site with its own linkage, the positions of the two linkages overlap, the direction vectors are set to be exactly opposite to each other, and the 'twist' vectors if present, are made to overlap exactly. (The rational being that the two links should be at the same position, pointing in opposite directions, with the 'twist' vector acting to set a common third direction (i.e. 'up') to orient both molecules.)
linkage definition:
site name position [direction [twist] ]
site - a keyword specifying the start of a linkage site specification
name - a human readable unique name for the site, used by the .pddf file and for logging
position - a point giving the position of the linkage site
direction - a point optionally giving the direction of the linkage site. If not specified, the direction defaults to the position vector, normalised (i.e. straight out from the centre).
twist - a point optionally giving a twist vector to the direction vector (which must be specified if a twist is specified). If not specified the binding orientation of the molecules is not strongly defined by the program; it will be regular according to an internal rule of the program that is not necessarily obvious to the user.
e.g.
site antibody_linkage_site <1,0,0> <1,0,0> <0,1,0>
(This sets a site called 'antibody_linkage_site' at position <1,0,0>, also in direction <1,0,0>, and specifies that any molecule linking to the site must rotate to align twist vectors to <0,1,0>.)
Often polymerising proteins undergo a state change when certain links are made or broken. To reflect this, the program implements a simple state machine. In the linkage definitions below (not to be confused with the linkage site section above) it is possible to define different binding strengths for different states of the object. It is also possible to display different states in different colours for the edification of viewers. Often states are given names appropriate to the event that created them; e.g. 'bound' or 'unbound'.
state definition:
state name [colour]
state - a keyword specifying a state definition
name - a human readable name used in the .pddf file and for logging
colour - either a hex format rgb triplet in the format 0xRRGGBB, or one of the following predefined colours {red, green, blue, yellow, magenta, cyan, pink, lightgreen, lightblue, lightred, white, lightgray, gray, darkgray, black,}
e.g.
state bound 0xFF0000
or
state energized red
(Note that the colour is the same in both instances.)
An event is an program occurrence that causes an object to change state. The most usual occurrence is a binding or breaking of a particular link, but it is possible to define random state changes as well (e.g. an object in an unphosphorylated state might have a chance of randomly rephosphorylating in the presence of free ATP.
event definition;
event bind {[linkA, linkB]} state-name1 -> state-name2
or
event break {[link]} state-name1 -> state-name2
or
event random probability state-name1 -> state-name2
event - key word specifying an event definition
bind - key work specifying a binding event definition
break - key word specifying a breakage event definition
random - key work specifying a random event definition
[linkA,linkB] - optional parameters specifying particular links that must bind
[link] - an optional parameter specifying a particular link that must break
probability - the probability (per cycle) of the event occurring.
state - the state from which (first argument), or to which (second argument), the object changes to when this event occurs
-> - key symbol
e.g.
event bind { } unbound -> bound
event break { first_link } bound -> unbound
random 0.1 adp -> atp
Once the various object models and their linkage sites have been defined, it is necessary to specify the binding and breaking probabilities of each linkage site with each other linkage site that it can interact with (unspecified linkage combinations are set to zero).
linkage definition:
binding object site state to object site state = bindprob breakprob
binding - keyword for linkage definition
object - the object being linked
site - the particular site being linked (may include keyword 'all' - see note below)
state - the state that this link applies to (may include keyword 'all' - see note below)
to - keyword
= - key symbol
bindprob - a floating point number giving the probability of the two links binding (if they touch during a collision).
Optionally this may be enclosed by the keywords "bind( ... )" for clarity.
breakprob - a floating point number giving the probability (per cycle) of the link breaking once formed
Optionally this may be enclosed by the keywords "break( ... )" for clarity
e.g.
binding virus siteA unbound to antibody activesite unbound = 0.001 0.0045
binding actin top bound to actin bottom unbound = bind(0.02) break(0.0001)
Combining all the elements above into a single file is not quite as onerous as might be imagined. The following is a simple, if verbose, example of a .pddf file that defines the structure of an (imaginary) flat triangular structure. Notice how the structure and links effectively define (in this example) a two-dimensional structure.
# spheres in a graphite-like flat triangular lattice structure
Model Triangle
{
Sphere a 0.9 <0,0,0> red
# site name <position> <direction> twist
#
site Aside <1,0,0> <1,0,0>
site Bside <-0.5,0.8660254,0> <-0.5,0.8660254,0>
site Cside <-0.5,-0.8660254,0> <-0.5,-0.8660254,0>
State unbound
State bound # a new state, with no physical changes
colour a = blue
# The event list is all of the form:
# Event: link { A B } | break | random (chance / cycle)
# StateA -> StateB
Event bind { } unbound -> bound
Event break { all } # if the top link is broken,
# object becomes "unbound" with
bound -> unbound # no change in phosphorylation
}
# specify links and states, and give their binding and breaking chance
# links are transitive.
# unbound links
Binding Triangle Aside unbound to Triangle Aside unbound = 0.001 0
Binding Triangle Aside unbound to Triangle Bside unbound = 0.001 0
Binding Triangle Aside unbound to Triangle Cside unbound = 0.001 0
Binding Triangle Bside unbound to Triangle Aside unbound = 0.001 0
Binding Triangle Bside unbound to Triangle Bside unbound = 0.001 0
Binding Triangle Bside unbound to Triangle Cside unbound = 0.001 0
Binding Triangle Cside unbound to Triangle Aside unbound = 0.001 0
Binding Triangle Cside unbound to Triangle Bside unbound = 0.001 0
Binding Triangle Cside unbound to Triangle Cside unbound = 0.001 0
# half bound links
Binding Triangle Aside bound to Triangle Aside unbound = 0.9 0
Binding Triangle Aside bound to Triangle Bside unbound = 0.9 0
Binding Triangle Aside bound to Triangle Cside unbound = 0.9 0
Binding Triangle Bside bound to Triangle Aside unbound = 0.9 0
Binding Triangle Bside bound to Triangle Bside unbound = 0.9 0
Binding Triangle Bside bound to Triangle Cside unbound = 0.9 0
Binding Triangle Cside bound to Triangle Aside unbound = 0.9 0
Binding Triangle Cside bound to Triangle Bside unbound = 0.9 0
Binding Triangle Cside bound to Triangle Cside unbound = 0.9 0
# unbound links
Binding Triangle Aside unbound to Triangle Aside bound = 0.9 0
Binding Triangle Aside unbound to Triangle Bside bound = 0.9 0
Binding Triangle Aside unbound to Triangle Cside bound = 0.9 0
Binding Triangle Bside unbound to Triangle Aside bound = 0.9 0
Binding Triangle Bside unbound to Triangle Bside bound = 0.9 0
Binding Triangle Bside unbound to Triangle Cside bound = 0.9 0
Binding Triangle Cside unbound to Triangle Aside bound = 0.9 0
Binding Triangle Cside unbound to Triangle Bside bound = 0.9 0
Binding Triangle Cside unbound to Triangle Cside bound = 0.9 0
#bound links
Binding Triangle Aside bound to Triangle Aside bound = 0.9 0
Binding Triangle Aside bound to Triangle Bside bound = 0.9 0
Binding Triangle Aside bound to Triangle Cside bound = 0.9 0
Binding Triangle Bside bound to Triangle Aside bound = 0.9 0
Binding Triangle Bside bound to Triangle Bside bound = 0.9 0
Binding Triangle Bside bound to Triangle Cside bound = 0.9 0
Binding Triangle Cside bound to Triangle Aside bound = 0.9 0
Binding Triangle Cside bound to Triangle Bside bound = 0.9 0
Binding Triangle Cside bound to Triangle Cside bound = 0.9 0
# some environment constants
Temperature 310 # kelvin - physiological temperature
Viscosity .69 # approximate viscosity for water at 37 degrees Celsius
TimeScale 100 # 100 nanoseconds per program cycle
# Finally, specify the mix of molecules in solution.
Mix Triangle 100%
The above syntax is somewhat verbose, as every link in every state must be explicitly specified. The program is moving to support the keyword 'all' as a valid linkage state and linkage site. At the time of writing this is only partially implemented (for sites, but not for states). At the moment, the above file should be able to be rewritten as:
--------------------------------------------------------------------------------------------------------------------
Model Triangle
{
Sphere a 0.9 <0,0,0> red
site Aside <1,0,0> <1,0,0>
site Bside <-0.5,0.8660254,0> <-0.5,0.8660254,0>
site Cside <-0.5,-0.8660254,0> <-0.5,-0.8660254,0>
State unbound
State bound colour a = blue
Event bind { } unbound -> bound
Event break { } bound -> unbound
}
# unbound links
Binding Triangle all unbound to Triangle all unbound = 0.001 0
# half bound links
Binding Triangle all bound to Triangle all unbound = 0.9 0
# unbound links
Binding Triangle all unbound to Triangle all bound = 0.9 0
#bound links
Binding Triangle all bound to Triangle all bound = 0.9 0
# some environment constants
Temperature 310 # kelvin - physiological temperature
Viscosity .69 # approximate viscosity for water at 37 degrees Celsius
TimeScale 100 # 100 nanoseconds per program cycle
# Finally, specify the mix of molecules in solution.
Mix Triangle 100%
--------------------------------------------------------------------------------------------------------------------
... Which will obviously be somewhat more manageable. This can only be used however for molecules with a number of identical links that can thus be treated as a group, and is thus not suitable for all cases.
Index |
Last Appendix |
Next Appendix |