*****************************************
*					*
* @Author : Peter Kim			*
*					*
* Version 1.2				*
*					*
* XML template guide line		*
*					*
*****************************************



This document was created to provide guidance in writing XML specifications for the DESSA simulator.

The simulator is made of hierarchies of classes.


				     World
                        /              |           \
                    /                  |               \
		/	               |		   \
	     Assembly		    Assembly		Assembly
         /      |      \          /    |     \       /     |    \
	/	|	\	/      |      \	    /	   |     \
   Subunit   Subunit  Subunit Subunit Subunit Subunit ...
            /   |    \
         /      |      \
      Domain   Domain  Domain ...
             /   |    \
           /     |      \
Conformation Conformation Conformation ...
            /    |       \
	   /	 |        \
   bindingSite bindingSite  ...

The diagram above shows the hierarchy.  Each component has certain properties characteristic
to its class.  In addition, each has a physical position and rotation that is specified
relative to its parent class. For instance, a Subunit has a position that is specified relative
to the position (center) of the Assembly that contains it.

Users should note that current simulator requires very high precision numbers for position and
orientations. Up to 10 decimal points should be provided to make simulator to run correctly.

In specifying a simulation, there are four main sections that we need to deal with:
<Assembly>, < BindingSiteTypes> , <BindingInteract>, <SubunitType>.  Some other attributes are
available in the XML document but are not currently being used and are reserved for future
simulator releases.  For example, a  <Solution> element is intended to specify global properties
of the the solution where simulations of self-assembly are taking place, but its values are
currently ignored.

The XML tags used to specify the major classes are as follows:

1. <Assembly>

   An <Assembly> element is being used to specify a group of subunits attached by a
   connected bond network. An Assembly may consist only one subunit to multiple subunits. All
   the <Subunit> elements that are under an <Assembly> tag will be in the same Assembly class.
   
   I. Attributes
      name -	name of assembly.  You can specify any name that you want.
      k -	reserved for future use.  You can leave it blank.
      amount -	Amount of assembly.  When the amount is greater than 1, simulator will make
		copies of this assembly.
      type -    The type of the assembly. You can use any arbitrary name.

   II. <Subunit> 
       A <Subunit> element is used to specify a particular assembly subunit, typically
       representing one protein in a biological assembly.  A Subunit has a type, a position within
       its assembly, a rotation, a velocity, and a rotational velocity. It may also have some
       binding partners.

       i. Attributes
	  name -	name of the subunit. You can specify any them, but that name 
			should be used when you are binding two subunits.
	  domain -	This attribute is not currently used.
	  type -	Type of subunit. This types are specified in <SubunitType> as 
			name. 
	  <Position> -	This element specifies the position of the subunit relative to
                        the center of its assembly
	  <Rotation> -	This element specifies the rotation of the subunit relative to 
			its assembly.  The rotation is specified as an axis of rotation
			followed by an angle in radians by which the subunit is rotated
			clockwise about that axis.  This attribute is normally overridden
			when subunits are created in order to position them consistently
			with their bond networks and can usually be given a zero vector
			as input.
	  <Velocity> -  This feature is not currently being used. 
	  <Rotational_velocity> - This feature is not currently being used
	  <bindTo> -	This element is used to specify binding partners of this subunit
       			in its assembly.  There can be more than one <bindTo> if this
			subunit has multiple binding partners.  <bindTo> has the following
			parameters:
			subunit - subunit name of the binding partner
			bindingSite - bindingsite of the current subunit involved in the
			binding interaction. bindingsites are named in <SubunitType>
			bindTo - bindingsite of the binding partner involved in the
			binding interaction.
   
2. <BindingSiteTypes>

   A <BindingsiteTypes> element defines different types of binding sites and specifies
   their partner allowed binding partners.  Any two distinct binding sites on a given subunit
   should have different binding site types.

   I. Attributes
      name		- the name of binding site type.  The user can pick any arbitrary name.
      <tolerance>	- specifies how perfectly two compatible binding sites need to align
			  before they are allowed to bind to one another.  Tolerance is specified
			  by a translational distance, a rotational torsion around the bond axis,
			  and a bending torsion perpendicular to the bond axis.
      <partner>		- This element specifies the other binding site types to which this
			  binding site type can bind. Multiple <partner> can be used if there are
			  multiple possible binding partners.  A <partner> also requires an
			  angle specifying how the partners are rotated relative to one another for
			  ideal binding.  The angle represents the angle different between two "up"
			  vectors (specified in SubunitType) that are projected onto the plane that
			  is perpendicular to the binding site. The following diagram illustrates how
			  the how up vectors are used:

					/
				       / <- primary up vector
				      /
				      |
				------|--------
	  projected plane----->/      |<-- bin/ding site  
			      /	      |      /
			     /--------|-----/
				      \
				       \ <- binding up vector
				        \

			  Here, the primary up vector is an up vector from the subunit possessing
			  the binding site whose type we are defining.  The binding up vector is the
			  up vector of its binding partner.  If we are looking from the primary
			  subunit along the bond vector to its partner, then a positive angle
			  corresponds to a clockwise rotation of the binding up vector relative to
			  the primary up vector.  A negative angle corresponds to a counterclockwise
			  rotation.  Angles are specified in radians on the range [-pi, pi].

3. <BindingInteract>
   
   A <BindingInteract> element is used to specify properties of a particular possible binding interaction.
   It is characterized by a mean binding time, a mean breaking time, a special fast bind time (used when
   two compatible binding sites are held in the proper relative positions by other binding interactions)
   and a conformational switching time. 

   <BindBreak>	   - the name of a <BindingSiteType> that is one of the partners to the BindingInteract.
		     Each <BindBreak> has one or more <Time> tags specifying the time parameters for a
		     particular binding partner, specified as follows:
   	<Time>	   	- a name attribute specifies partner binding site type. 
		     	  a bindTime attribute representing the mean binding time between the two
			  binding site types
		     	  a breakTime attribute representing the mean breaking time between the two binding 
		     	  site types
		     	  a fastbindTime attribute representing the mean binding time if the two binding
			  sites are held in the proper binding position by other binding interactions

   <ConformationTime> - This element is used to specify times for conformational switching events.
			Conformations are defined under SubunitType.  A <ConformationTime> has the
			following parameters:
				name attribute is used to specify conformation.
				<List> represents a conformation to which the present conformation 
				can be switched.  It has a name attribute to specify the neighboring
				conformation and a time attribute to specify the mean time for
				the conformational switching event.

4. <SubunitType>
   
   <SubunitType> element is used for specifying type of subunit. <SubunitType> consists 
   up vector for subunits, domains, conformations, and binding site position.

   I. Attributes
      name	  - name of subunit type. This name is used for specifying the subunit
		    type for a <Subunit> element
      id	  - a unique integer id for the subunit type
      <Up>	  - up vector for subunit. This up vector is used to specify the correct 
		    orientation of a subunit (see BindingSiteTypes).
      <Domain>	  - Domain of this subunit type. 
		    position attribute is currently unused.
		    id attribute is used to specify id of this domain
		    currentConf attribute is need to specify the starting conformation. 
		    User has to choose conformation name from <Conformation> element
      <Conformation> - Possible conformations of this subunit.
		       name attribute is used to distinguish one conformation from the 
		       other
		       Evalue attribute is not currently being used.  You can use the
		       default value of 6.6.
      <BindingSite> - Specifies sites by which this subunit will bind to other subunits. 
		      name attribute is used to distinguish each binding site. This name 
		      is used in <Subunit> to specify binding partners.
		      type attribute is needed to specify the type of this binding site. 
		      The list of types are shown in <BindingSiteTypes>
		      <Bpos> is a element for specifying the tip of the binding site. 
		      <Orientation> is a used in the graphical display of a binding site. 
		      The orientation is drawn as a cone, which has a default direction of
		      <0,1,0>.  The <Orientation> tag sets a quaternion that describes a
		      rotation applied to the cone.

To see how these features are used in practice, you can check the various sample XML
files provided with the code release.