Index: doc/userguide/userguide.xml
===================================================================
--- doc/userguide/userguide.xml	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/userguide.xml	(revision f73e0644af36b981af22685b57300f77cb7b0937)
@@ -488,54 +488,33 @@
 
         <section>
-          <title>Setting parser specific parameters</title>
-
-          <para>You can also tweak the parameters stored in this file easily.
-          For example, <productname>MPQC</productname> stores various
-          parameters modifying the specific ab-initio calculation performed.
-          For <productname>MPQC</productname> and 
-          <productname>Psi4</productname> this can be modified as 
-          follows.</para>
-
-          <programlisting>
-		... --set-parser-parameters mpqc \
-		    --parser-parameters "theory=CLHF;basis=6-31*G;"
+          <title>Output the current molecular system</title>
+
+          <para>This will store the current World, i.e. all its atoms, to a 
+          given file, where the output format is determined from the file
+          suffix.</para>
+
+          <programlisting>... --output-as world.xyz</programlisting>
+        </section>
+
+        <section>
+          <title>Output the current molecular system</title>
+
+          <para>This will store all atoms contained in the currently selected
+          molecules to file. This is different to "store-saturated-fragment"
+          as it will not saturate dangling bonds because only whole molecules,
+          i.e. whose bond graph is connected, will be stored.</para>
+
+          <programlisting>... --save-selected-molecules waters.pdb
           </programlisting>
-
-          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
-          and the basis set to 6-31*G. Please check the
-          <productname>MPQC</productname> manual on specific
-          parameters.</para>
-        </section>
-
-        <section>
-          <title>Tremolo specific options and potential files</title>
-
-          <para><productname>TREMOLO</productname>'s configuration files start
-          with a specific line telling the amount of information stored in the
-          file. This file can be modified, e.g. to enforce storing of
-          velocities and forces as well as the atoms positions and
-          element.</para>
-
-          <programlisting>
-		... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
-		    --reset 1
-	  </programlisting>
-
-          <para>This will not append but reset the old line and fill it with
-          the given string.</para>
-
-          <para>One specific action is required when loading certain
-          <productname>TREMOLO</productname> configuration files. These
-          contain element notations that refer to parameterized names used in
-          empirical potentials and molecular dynamics simulations and not the
-          usual chemical symbols, such as H or O. We may load an auxiliary
-          file that gives the required conversion from OH1 to H, which is the
-          so-called potential file.</para>
-
-          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
-
-          <para>This parses the lookup table from the file
-          <filename>water.potentials</filename> and it can be used in
-          following load actions.</para>
+        </section>
+
+        <section>
+          <title>Load extra bond information</title>
+
+          <para>For some parsers bond information is stored not with the atoms
+          coordinates but in an extra file. This action parses such a file.</para>
+
+          <programlisting>... --bond-file water.dbond
+          </programlisting>
         </section>
       </section>
@@ -571,19 +550,67 @@
             <itemizedlist>
               <listitem>
+                <para>All</para>
+                <programlisting>
+                ... --select-all-atoms
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>None</para>
+                <programlisting>
+                ... --unselect-all-atoms
+                </programlisting>
+                <programlisting>
+                ... --clear-atom-selection
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>Invert selection</para>
+                <programlisting>
+                ... --invert-atoms
+                </programlisting>
+              </listitem>
+
+              <listitem>
                 <para>By Element (all hydrogen atoms, all sulphur atoms,
                 ...)</para>
+                <programlisting>
+                ... --select-atom-by-element 1
+                </programlisting>
+                <programlisting>
+                ... --unselect-atom-by-element 1
+                </programlisting>
               </listitem>
 
               <listitem>
                 <para>By Id (atom with id 76)</para>
+                <programlisting>
+                ... --select-atom-by-id 76
+                </programlisting>
+                <programlisting>
+                ... --unselect-atom-by-id 76
+                </programlisting>
               </listitem>
 
               <listitem>
-                <para>By Order (the first (1), the second, ... the last, the
-                last but one)</para>
+                <para>By Order (the first (1), the second, ... the last 
+                created(-1), the last but one)</para>
+                <programlisting>
+                ... --select-atom-by-order 1
+                </programlisting>
+                <programlisting>
+                ... --unselect-atom-by-order -2
+                </programlisting>
               </listitem>
 
               <listitem>
                 <para>By Shape (specific region of the domain)</para>
+                <programlisting>
+                ... --select-atom-inside-volume
+                </programlisting>
+                <programlisting>
+                ... --unselect-atoms-inside-volume
+                </programlisting>
               </listitem>
 
@@ -591,4 +618,10 @@
                 <para>By Molecule (all atoms belonging to currently selected
                 molecules)</para>
+                <programlisting>
+                ... --select-molecules-atoms
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecules-atoms
+                </programlisting>
               </listitem>
             </itemizedlist>
@@ -600,13 +633,66 @@
             <itemizedlist>
               <listitem>
+                <para>All</para>
+                <programlisting>
+                ... --select-all-molecules
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>None</para>
+                <programlisting>
+                ... --unselect-all-molecules
+                </programlisting>
+                <programlisting>
+                ... --clear-molecule-selection
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>Invert selection</para>
+                <programlisting>
+                ... --invert-molecules
+                </programlisting>
+              </listitem>
+
+              <listitem>
                 <para>By Id (molecule with id 4)</para>
+                <programlisting>
+                ... --select-molecule-by-id 2
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecule-by-id 2
+                </programlisting>
               </listitem>
 
               <listitem>
-                <para>By Order (first molecule, second molecule, ...)</para>
+                <para>By Order (first created molecule, second created 
+                molecule, ...)</para>
+                <programlisting>
+                ... --select-molecule-by-order 2
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecule-by-order -2
+                </programlisting>
               </listitem>
 
               <listitem>
-                <para>By Name (molecule named "water4"</para>
+                <para>By Formula (molecule with H2O as formula)</para>
+                <programlisting>
+                ... --select-molecules-by-formula "H2O"
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecules-by-formula "H2O"
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>By Name (molecule named "water4")</para>
+                <programlisting>
+                ... --select-molecules-by-name "water4"
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecules-by-name "water4"
+                </programlisting>
               </listitem>
 
@@ -614,10 +700,14 @@
                 <para>By Atom (all molecules for which at least one atom is
                 currently selected)</para>
+                <programlisting>
+                ... --select-atoms-molecules
+                </programlisting>
+                <programlisting>
+                ... --unselect-atoms-molecules
+                </programlisting>
               </listitem>
             </itemizedlist>
           </listitem>
-        </itemizedlist>
-
-        <itemizedlist>
+
           <listitem>
             <para>Shapes</para>
@@ -625,29 +715,30 @@
             <itemizedlist>
               <listitem>
+                <para>All</para>
+                <programlisting>
+                ... --select-all-shapes
+                </programlisting>
+              </listitem>
+
+              <listitem>
+                <para>None</para>
+                <programlisting>
+                ... --unselect-all-shapes
+                </programlisting>
+              </listitem>
+
+              <listitem>
                 <para>By Name (shape name "sphere1")</para>
+                <programlisting>
+                ... --select-shape-by-name "sphere1"
+                </programlisting>
+                <programlisting>
+                ... --unselect-shape-by-name "sphere1"
+                </programlisting>
               </listitem>
             </itemizedlist>
           </listitem>
 
-          <listitem>
-            <para>All</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>All (selects or unselects all instances of the
-                type)</para>
-              </listitem>
-
-              <listitem>
-                <para>Clear (clears the current selection)</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
         </itemizedlist>
-
-        <para>Furthermore, a selection can be imverted, e.g. inverting the
-        current selection of atoms.</para>
-
-        <programlisting>... --invert-atoms</programlisting>
 
         <remark>Note that an unselected instance (e.g. an atom) remains
@@ -701,4 +792,37 @@
 
         <section>
+          <title>Combining shapes</title>
+
+          <para>Any two shapes can be combined by boolean operations as follows</para>
+
+          <programlisting>
+		... --combine-shapes \
+		    --shape-name "combinedshape" \
+		    --shape-op "AND" \
+	  </programlisting>
+
+          <para>This will combine two currently selected shapes vis the "AND" operation
+          and create a new shape called "combinedshape". Note that the two old shapes
+          are still present after this operation. We briefly explain each operation:
+          </para>
+          <itemizedlist>
+            <listitem>
+              <para><emphasis>AND</emphasis> combines two currently selected shapes
+              into a new shape that only consists of the volume where shapes overlap.</para>
+            </listitem>
+            <listitem>
+              <para><emphasis>OR</emphasis> combines two currently selected shapes
+              into a new shape that consists of all the volume where that either shape
+              occupies.</para>
+            </listitem>
+            <listitem>
+              <para><emphasis>NOT</emphasis> creates the inverse to a currently selected
+              single shape that contains the volume with respect to the simulation domain
+              that the present one does not.</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+
+        <section>
           <title>Removing shapes</title>
 
@@ -728,5 +852,5 @@
 
           <programlisting>
-		... --rotate-shape \
+		... --rotate-shapes \
 		    --center "10,2,2" \
 		    --angle-x 90 \
@@ -897,4 +1021,20 @@
 
         <section>
+          <title>Correcting bond degrees</title>
+
+          <para>Typically, after loading an input file bond information, e.g.
+          a PDB file, the bond graph is complete but we lack the weights. That
+          is we do not know whether a bond is single, double, triple, ...
+          This action corrects the bond degree by enforcing charge neutrality
+          among the connected atoms.
+          </para>
+          <para>This action is in fact quadratically scaling in the number of
+          atoms. Hence, for large systems this may take longer than expected.
+          </para>
+
+          <programlisting>... --correct-bonddegree</programlisting>
+        </section>
+
+        <section>
           <title>Analysing a bond graph</title>
 
@@ -924,4 +1064,15 @@
 
         <section>
+          <title>Updating molecule structure</title>
+
+          <para>When the bond information has changed, new molecules might 
+          have formed, this action updates all the molecules by scanning
+          the connectedness of the bond grapf of the molecular system.
+          </para>
+
+          <programlisting>... --update-molecules</programlisting>
+        </section>
+
+        <section>
           <title>Adding a bond manually</title>
 
@@ -940,4 +1091,22 @@
 
           <programlisting>... --remove-bond</programlisting>
+        </section>
+
+        <section>
+          <title>Saving bond information</title>
+
+          <para>Bond information can be saved to a file in <link 
+          xlink:href="http://www.molecuilder.com/"><programname>TREMOLO
+          </programname></link>'s dbond style.</para>
+
+          <programlisting>... --save-bonds system.dbonds</programlisting>
+          
+          <para>Similarly is the following Action which saves the bond
+          information as a simple list of one atomic id per line and in
+          the same line, separated by spaces, the ids of all atoms connected
+          to it.</para>
+          
+          <programlisting>... --save-adjacency system.adj</programlisting>
+          
         </section>
 
@@ -1015,9 +1184,279 @@
 
         <section>
-          <title>Fill a domain section with molecules</title>
-
+          <title>Change a molecules name</title>
+
+          <para>You can change the name of a molecule which is important for
+          selection.</para>
+
+          <programlisting>... -change-molname "test</programlisting>
+
+          <para>This will change the name of the (only) selected molecule to
+          "test".</para>
+
+          <para>Connected with this is the default name an unknown molecule
+          gets.</para>
+
+          <programlisting>... --default-molname test</programlisting>
+
+          <para>This will change the default name of a molecule to
+          "test".</para>
+
+          <note>
+            <para>Note that a molecule loaded from file gets the filename
+            (without suffix) as its name.</para>
+          </note>
+        </section>
+
+        <section>
+          <title>Rotate around self</title>
+
+          <para>You can rotate a molecule around its own axis.</para>
+
+          <programlisting>
+		... --rotate-around-self "90" \
+		    --axis "0,0,1"
+	  </programlisting>
+
+          <para>This rotates the molecule around the z axis by 90 degrees as
+          if the origin were at its center of origin.</para>
+        </section>
+
+        <section>
+          <title>Rotate around origin</title>
+
+          <para>In the same manner the molecule can be rotated around an
+          external origin.</para>
+
+          <programlisting>
+		... --rotate-around-origin 90 \
+		    --position "0,0,1"\
+	  </programlisting>
+
+          <para>This rotates the molecule around an axis from the origin to
+          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
+        </section>
+
+        <section>
+          <title>Rotate to principal axis system</title>
+
+          <para>The principal axis system is given by an ellipsoid that mostly
+          matches the molecules shape. The principal axis system can be just
+          simply determined by</para>
+
+          <programlisting>... --principal-axis-system</programlisting>
+
+          <para>To rotate the molecule around itself to align with this system
+          do as follows.</para>
+
+          <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>
+
+          <para>This rotates the molecule in such a manner that the ellipsoids
+          largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
+          would align anti-parallel.</remark></para>
+        </section>
+
+        <section>
+          <title>Perform verlet integration</title>
+
+          <para>Atoms not only have a position, but each instance also stores
+          velocity and a force vector. These can be used in a velocity verlet
+          integration step. Velocity verlet is a often employed time
+          integration algorithm in molecular dynamics simulations.</para>
+
+          <programlisting>
+		... --verlet-integration \
+		    --deltat 0.1 \
+		    --keep-fixed-CenterOfMass 0
+	  </programlisting>
+
+          <para>This will integrate with a timestep of <inlineequation>
+              <m:math display="inline">
+                <m:mi>\Delta_t = 0.1</m:mi>
+              </m:math>
+            </inlineequation>and correcting forces and velocities such that
+          the sum over all atoms is zero.</para>
+        </section>
+
+        <section>
+          <title>Anneal the atomic forces</title>
+
+          <para>This will shift the atoms in a such a way as to decrease (or
+          anneal) the forces acting upon them.</para>
+
+          <para>Forces may either be already present for the set of atoms by
+          some other way (e.g. from a prior fragmentation calculation) or,
+          as shown here, from an external file. We anneal the forces for
+          one step with a certain initial step width of 0.5 atomic time
+          units and do not create a new timestep for each optimization
+          step.</para>
+
+          <programlisting>
+          ... --force-annealing \
+          --forces-file test.forces \
+          --deltat 0.5 \
+          --steps 1 \
+          --output-every-step 0
+          </programlisting>
+        </section>
+
+        <section>
+          <title>Linear interpolation between configurations</title>
+
+          <para>This is similar to verlet-integration, only that it performs
+          a linear integration irrespective of the acting atomic forces.
+          </para>
+
+          <para>The following call will produce an interpolation between the
+          configurations in time step 0 and time step 1 with 98 intermediate
+          steps, i.e. current step 1 will end up in time step 99. In this
+          case an idential mapping is used to associated atoms in start and
+          end configuration.</para>
+
+          <programlisting>
+          ... --linear-interpolation-of-trajectories \
+          --start-step 0 \
+          --end-step 1 \
+          --interpolation-steps 100 \
+          --id-mapping 1
+          </programlisting>
+        </section>
+      </section>
+
+      <section>
+        <title>Manipulate domain</title>
+
+        <para>Here, we elaborate on how to duplicate all the atoms inside the
+        domain, how the scale the coordinate system, how to center the atoms
+        with respect to certain points, how to realign them by given
+        constraints, how to mirror and most importantly how to specify the
+        domain.</para>
+
+        <section>
+          <title>Changing the domain</title>
+
+          <para>The domain is specified by a symmetric 3x3 matrix. The
+          eigenvalues (diagonal entries in case of a diagonal matrix) give the
+          length of the edges, additional entries specify transformations of
+          the box such that it becomes a more general parallelepiped.</para>
+
+          <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
+
+          <para>As the domain matrix is symmetric, six values suffice to fully
+          specify it. We have to give the six components of the lower diagonal
+          matrix. Here, we change the box to a cuboid of equal edge length of
+          20.</para>
+        </section>
+
+        <section>
+          <title>Bound atoms inside box</title>
+
+          <para>The following applies the current boundary conditions to the
+          atoms. In case of periodic or wrapped boundary conditions the atoms
+          will be periodically translated to be inside the domain
+          again.</para>
+
+          <programlisting>... --bound-in-box</programlisting>
+        </section>
+
+        <section>
+          <title>Center atoms inside the domain</title>
+
+          <para>This is a combination of changing the box and bounding the
+          atoms inside it.</para>
+
+          <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
+        </section>
+
+        <section>
+          <title>Center the atoms at an edge</title>
+
+          <para>MoleCuilder can calculate the minimum box (parallel to the
+          cardinal axis) all atoms would fit in and translate all atoms in
+          such a way that the lower, left, front edge of this minimum is at
+          the origin (0,0,0).</para>
+
+          <programlisting>... --center-edge</programlisting>
+        </section>
+
+        <section>
+          <title>Extending the boundary by adding an empty boundary</title>
+
+          <para>In the same manner as above a minimum box is determined that
+          is subsequently expanded by a boundary of the given additional
+          thickness. This applies to either side.</para>
+
+          <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
+
+          <para>This will enlarge the box in such a way that every atom is at
+          least by a distance of 5 away from the boundary of the domain (in
+          the infinity norm).</para>
+        </section>
+
+        <section>
+          <title>Scaling the box</title>
+
+          <para>You can enlarge the domain by simple scaling factors.</para>
+
+          <programlisting>... --scale-box "1,1,2.5"</programlisting>
+
+          <para>Here, the domain is stretched in the z direction by a factor
+          of 2.5.</para>
+        </section>
+
+        <section>
+          <title>Repeating the box</title>
+
+          <para>Under periodic boundary conditions often only the minimal
+          periodic cell is stored. If need be, multiple images can be easily
+          added to the current state of the system by repeating the box, i.e.
+          the box along with all contained atoms is copied and placed
+          adjacently.</para>
+
+          <programlisting>... --repeat-box "1,2,2"</programlisting>
+
+          <para>This will create a 2x2 grid of the current domain, replicating
+          it along the y and z direction along with all atoms. If the domain
+          contained before a single water molecule, we will now have four of
+          them.</para>
+        </section>
+        
+        <section>
+          <title>Change the boundary conditions</title>
+
+          <para>Various boundary conditions can be applied that affect how
+          certain Actions work, e.g. translate-atoms. We briefly give a list
+          of all possible conditions:</para>
+          <itemizedlist>
+            <listitem>
+              <para>Wrap</para>
+              <para>Coordinates are wrapped to the other side of the domain, 
+              i.e. periodic boundary conditions.</para>
+            </listitem>
+            <listitem>
+              <para>Bounce</para>
+              <para>Coordinates are bounced back into the domain, i.e. they
+              are reflected from the domain walls.</para>
+            </listitem>
+            <listitem>
+              <para>Ignore</para>
+              <para>No boundary conditions apply.</para>
+            </listitem>
+          </itemizedlist>
+          
+          <para>The following will set the boundary conditions to periodic.
+          </para>
+
+          <programlisting>... --set-boundary-conditions "Wrap Wrap Wrap"
+          </programlisting>
+        </section>
+      </section>
+
+      <section>
+        <title>Filling</title>
+        
           <para>Filling a specific part of the domain with one type of
           molecule, e.g. a water molecule, is the more advanced type of
-          copying and we need several ingredients.</para>
+          copying of a molecule (see copy-molecule) and we need several 
+          ingredients.</para>
 
           <para>First, we need to specify the part of the domain. This is done
@@ -1026,8 +1465,9 @@
           region.</para>
 
-          <para>Then, they are two types of filling, volume and surface. The
-          volume is filled with a regular grid of fill-in points, and in the
-          same manner is the surface filled with a regular grid of points.
-          Molecules will be copied and translated points when they
+          <para>Then, they are three types of filling, domain, volume, and 
+          surface. The domain is filled with a regular grid of fill-in points.
+          A volume and a surface are filled by a set of equidistant points
+          distributed within the volume or on the surface of a selected
+          shape. Molecules will then be copied and translated points when they
           "fit".</para>
 
@@ -1043,4 +1483,7 @@
           additionally excluded from the filling region.</para>
 
+        <section>
+          <title>Fill the domain with molecules</title>
+
           <para>The call to fill the volume of the selected shape with the
           selected atoms is then as follows,</para>
@@ -1050,5 +1493,6 @@
 		    --mesh-size "5,5,5" \
 		    --mesh-offset ".5,.5,.5" \
-		    --DoRotate 1 --min-distance 1. \
+		    --DoRotate 1 \
+		    --min-distance 1. \
 		    --random-atom-displacement 0.05 \
 		    --random-molecule-displacement 0.4 \
@@ -1068,196 +1512,210 @@
 
         <section>
-          <title>Change a molecules name</title>
-
-          <para>You can change the name of a molecule which is important for
-          selection.</para>
-
-          <programlisting>... -change-molname "test</programlisting>
-
-          <para>This will change the name of the (only) selected molecule to
-          "test".</para>
-
-          <para>Connected with this is the default name an unknown molecule
-          gets.</para>
-
-          <programlisting>... --default-molname test</programlisting>
-
-          <para>This will change the default name of a molecule to
-          "test".</para>
-
-          <note>
-            <para>Note that a molecule loaded from file gets the filename
-            (without suffix) as its name.</para>
-          </note>
-        </section>
-
-        <section>
-          <title>Rotate around self</title>
-
-          <para>You can rotate a molecule around its own axis.</para>
-
-          <programlisting>
-		... --rotate-around-self "90" \
-		    --axis "0,0,1"
+          <title>Fill a shape's volume with molecules</title>
+          
+          <para>More specifically than filling the whole domain with molecules,
+          maybe except areas where other molecules already are, we also can
+          fill only specific parts by selecting a shape and calling upon
+          the following action:</para>
+
+          <programlisting>
+		... --fill-volume \
+		    --counts 12 \
+		    --min-distance 1. \
+		    --DoRotate 1 \
+		    --random-atom-displacement 0.05 \
+		    --random-molecule-displacement 0.4 \
+		    --tesselation-radius 2.5
 	  </programlisting>
-
-          <para>This rotates the molecule around the z axis by 90 degrees as
-          if the origin were at its center of origin.</para>
-        </section>
-
-        <section>
-          <title>Rotate around origin</title>
-
-          <para>In the same manner the molecule can be rotated around an
-          external origin.</para>
-
-          <programlisting>
-		... --rotate-around-origin 90 \
-		    --position "0,0,1"\
+        </section>
+          
+        <section>
+          <title>Fill a shape's surface with molecules</title>
+
+		  <para>Filling a surface is very similar to filling its volume.
+		  Again the number of equidistant points has to be specified.
+		  However, randomness is constrained as the molecule is be aligned
+		  with the surface in a specific manner. The alignment axis refers
+		  to the largest principal axis of the filler molecule and will
+		  be aligned parallel to the surface normal at the fill-in point.
+		  </para>
+
+		  <para>The call below fill in 12 points with a minimum distance
+		  between the instances of 1 angstroem. We allow for certain random
+		  displacements and use the z-axis for aligning the molecules on
+		  the surface.</para>
+
+          <programlisting>
+		... --fill-surface \
+		    --counts 12 \
+		    --min-distance 1. \
+		    --DoRotate 1 \
+		    --random-atom-displacement 0.05 \
+		    --random-molecule-displacement 0.4 \
+		    --Alignment-Axis "0,0,1"
 	  </programlisting>
-
-          <para>This rotates the molecule around an axis from the origin to
-          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
-        </section>
-
-        <section>
-          <title>Rotate to principal axis system</title>
-
-          <para>The principal axis system is given by an ellipsoid that mostly
-          matches the molecules shape. The principal axis system can be just
-          simply determined by</para>
-
-          <programlisting>... --principal-axis-system</programlisting>
-
-          <para>To rotate the molecule around itself to align with this system
-          do as follows.</para>
-
-          <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>
-
-          <para>This rotates the molecule in such a manner that the ellipsoids
-          largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
-          would align anti-parallel.</remark></para>
-        </section>
-
-        <section>
-          <title>Perform verlet integration</title>
-
-          <para>Atoms not only have a position, but each instance also stores
-          velocity and a force vector. These can be used in a velocity verlet
-          integration step. Velocity verlet is a often employed time
-          integration algorithm in molecular dynamics simulations.</para>
-
-          <programlisting>
-		... --verlet-integration \
-		    --deltat 0.1 \
-		    --keep-fixed-CenterOfMass 0
-	  </programlisting>
-
-          <para>This will integrate with a timestep of <inlineequation>
-              <m:math display="inline">
-                <m:mi>\Delta_t = 0.1</m:mi>
-              </m:math>
-            </inlineequation>and correcting forces and velocities such that
-          the sum over all atoms is zero.</para>
+        </section>
+
+        <section>
+          <title>Suspend in molecule</title>
+
+          <para>Add a given molecule in the simulation domain in such a way
+          that the total density is as desired.</para>
+
+          <programlisting>
+		... --suspend-in-molecule 1.
+	      </programlisting>
+        </section>
+
+        <section>
+          <title>Fill in molecule</title>
+
+          <para>This action will be soon be removed.</para>
+
+          <programlisting>
+		... --fill-molecule
+	      </programlisting>
+        </section>
+
+        <section>
+          <title>Fill void with molecule</title>
+
+          <para>This action will be soon be removed.</para>
+
+          <programlisting>
+		... --fill-void
+	      </programlisting>
         </section>
       </section>
 
       <section>
-        <title>Manipulate domain</title>
-
-        <para>Here, we elaborate on how to duplicate all the atoms inside the
-        domain, how the scale the coordinate system, how to center the atoms
-        with respect to certain points, how to realign them by given
-        constraints, how to mirror and most importantly how to specify the
-        domain.</para>
-
-        <section>
-          <title>Changing the domain</title>
-
-          <para>The domain is specified by a symmetric 3x3 matrix. The
-          eigenvalues (diagonal entries in case of a diagonal matrix) give the
-          length of the edges, additional entries specify transformations of
-          the box such that it becomes a more general parallelepiped.</para>
-
-          <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
-
-          <para>As the domain matrix is symmetric, six values suffice to fully
-          specify it. We have to give the six components of the lower diagonal
-          matrix. Here, we change the box to a cuboid of equal edge length of
-          20.</para>
-        </section>
-
-        <section>
-          <title>Bound atoms inside box</title>
-
-          <para>The following applies the current boundary conditions to the
-          atoms. In case of periodic or wrapped boundary conditions the atoms
-          will be periodically translated to be inside the domain
-          again.</para>
-
-          <programlisting>... --bound-in-box</programlisting>
-        </section>
-
-        <section>
-          <title>Center atoms inside the domain</title>
-
-          <para>This is a combination of changing the box and bounding the
-          atoms inside it.</para>
-
-          <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
-        </section>
-
-        <section>
-          <title>Center the atoms at an edge</title>
-
-          <para>MoleCuilder can calculate the minimum box (parallel to the
-          cardinal axis) all atoms would fit in and translate all atoms in
-          such a way that the lower, left, front edge of this minimum is at
-          the origin (0,0,0).</para>
-
-          <programlisting>... --center-edge</programlisting>
-        </section>
-
-        <section>
-          <title>Extending the boundary by adding an empty boundary</title>
-
-          <para>In the same manner as above a minimum box is determined that
-          is subsequently expanded by a boundary of the given additional
-          thickness. This applies to either side.</para>
-
-          <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
-
-          <para>This will enlarge the box in such a way that every atom is at
-          least by a distance of 5 away from the boundary of the domain (in
-          the infinity norm).</para>
-        </section>
-
-        <section>
-          <title>Scaling the box</title>
-
-          <para>You can enlarge the domain by simple scaling factors.</para>
-
-          <programlisting>... --scale-box "1,1,2.5"</programlisting>
-
-          <para>Here, the domain is stretched in the z direction by a factor
-          of 2.5.</para>
-        </section>
-
-        <section>
-          <title>Repeating the box</title>
-
-          <para>Under periodic boundary conditions often only the minimal
-          periodic cell is stored. If need be, multiple images can be easily
-          added to the current state of the system by repeating the box, i.e.
-          the box along with all contained atoms is copied and placed
-          adjacently.</para>
-
-          <programlisting>... --repeat-box "1,2,2"</programlisting>
-
-          <para>This will create a 2x2 grid of the current domain, replicating
-          it along the y and z direction along with all atoms. If the domain
-          contained before a single water molecule, we will now have four of
-          them.</para>
-        </section>
+        <title>Analysis</title>
+
+		<para></para>
+
+        <section>
+          <title>Pair Correlation</title>
+          
+          <para>Pair correlation checks for two given elements on the typical 
+          distance they can be found with respect to one another. E.g. for 
+          water one might be interested what is the typical distance for
+          hydrogen and oxygen atoms.</para>
+
+          <programlisting>
+          ... --pair-correlation \
+              --elements 1 8 \
+              --bin-start 0 \
+              --bin-width 0.7 \
+              --bin-end 10 \
+              --output-file histogram.dat \
+              --bin-output-file bins.dat \
+              --periodic 0
+          </programlisting>
+          
+          <para>This will compile a histogram for the interval [0,10] in steps
+          of 0.7 and increment a specific bin if the distance of one such pair
+          of a hydrogen and an oxygen atom can be found within its distance
+          interval.</para>
+        </section>
+
+        <section>
+          <title>Dipole Correlation</title>
+          
+          <para>The dipole correlation is similar to the pair correlation, only
+          that it correlates the orientation of dipoles in the molecular
+          system with one another.</para>
+          <para>Note that the dipole correlation works on the currently 
+          selected molecules, e.g. all water molecules if so selected.</para>
+
+          <programlisting>
+          ... --dipole-correlation \
+              --bin-start 0 \
+              --bin-width 0.7 \
+              --bin-end 10 \
+              --output-file histogram.dat \
+              --bin-output-file bins.dat \
+              --periodic 0
+          </programlisting>
+        </section>
+
+        <section>
+          <title>Dipole Angular Correlation</title>
+          
+          <para>The dipole angular correlation looks at the angles of a
+          dipole over time. It takes the orientation of a certain time step
+          as the zero angle and bins all other orientations found in later
+          time steps relative to it.
+          </para>
+          <para>Note that in contrast to the dipole correlation the dipole
+          angular correlation works on the molecules determined by a formula.
+          This is because selections do not work over time steps as molecules
+          might change.
+          </para>
+
+          <programlisting>
+          ... --dipole-angular-correlation H2O \
+              --bin-start 0 \
+              --bin-width 5 \
+              --bin-end 360 \
+              --output-file histogram.dat \
+              --bin-output-file bins.dat \
+              --periodic 0 \
+              --time-step-zero 0
+          </programlisting>
+        </section>
+
+        <section>
+          <title>Point Correlation</title>
+          
+          <para>Point correlation is very similar to pair correlation, only
+          that it correlates not positions of atoms among one another but
+          against a fixed, given point.</para>
+
+          <programlisting>
+          ... --point-correlation \
+              --elements 1 8 \
+              --position "0,0,0" \
+              --bin-start 0 \
+              --bin-width 0.7 \
+              --bin-end 10 \
+              --output-file histogram.dat \
+              --bin-output-file bins.dat \
+              --periodic 0
+          </programlisting>
+          
+          <para>This would calculate the correlation of all hydrogen and
+          oxygen atoms with respect to the origin.</para>
+        </section>
+
+        <section>
+          <title>Surface Correlation</title>
+          
+          <para>The surface correlation calculates the distance of a set
+          of atoms with respect to a tesselated surface.</para>
+
+          <programlisting>
+          ... --surface-correlation \
+              --elements 1 8 \
+              --bin-start 0 \
+              --bin-width 0.7 \
+              --bin-end 10 \
+              --output-file histogram.dat \
+              --bin-output-file bins.dat \
+              --periodic 0
+          </programlisting>
+        </section>
+
+        <section>
+          <title>Molecular Volume</title>
+          
+          <para>This simply calculates the volume that a selected molecule
+          occupies. For this the molecular surface is determined via a
+          tesselation. Note that this surface is minimal is that aspect
+          that each node of the tesselation consists of an atom of the
+          molecule.</para>
+
+          <programlisting>... --molecular-volume</programlisting>
+        </section>
+
       </section>
 
@@ -1304,6 +1762,6 @@
         equation. Such a calculation is implemented via the solver
         <productname>vmg</productname> by Julian Iseringhausen that is
-        contained in the <productname>ScaFaCoS</productname> package (<link
-        xlink:href="???">http://www.scafacos.org/</link>).</para>
+        contained in the <link xlink:href="http://www.scafacos.org/">
+        <productname>ScaFaCoS</productname></link>.</para>
 
         <para>Note that we treat hydrogen special (but can be switched off) as
@@ -1485,4 +1943,25 @@
           integration</link> is possible afterwards.</para>
         </section>
+        
+        <section>
+          <title>Store a saturated fragment</title>
+
+          <para>After the energies and force vectors of each fragment have
+          been calculated, they need to be summed up to an approximation for
+          the energy and force vectors of the whole molecular system. This is
+          done by calling this action.</para>
+
+          <para>This will store the currently selected atoms as a fragment
+          where all dangling bonds (by atoms that are connected in the bond
+          graph but have not been selected as well) are saturated with
+          additional hydrogen atoms. The output formats are set to just xyz.
+          </para>
+
+          <programlisting>
+		... --store-saturated-fragment \
+		    --DoSaturate 1 \
+		    --output-types xyz
+	      </programlisting>
+        </section>
       </section>
 
@@ -1529,5 +2008,5 @@
         container.</para>
 
-        <programlisting>... --store-homologies homologies.dat</programlisting>
+        <programlisting>... --save-homologies homologies.dat</programlisting>
 
         <para>Complementary, this stores the current contents of the homology
@@ -1619,10 +2098,10 @@
 
         <section>
-          <title>Fitting partial charges</title>
+          <title>Fitting particle charges</title>
 
           <para>The above empirical potential just model the short-range
           behavior in the molecular fragment, namely the bonded interaction.
           In order to model the long-range interaction as well without solving
-          for the electronic ground state in each time step, partial charges
+          for the electronic ground state in each time step, particle charges
           are used that capture to some degree the created dipoles due to
           charge transfer from one atom to another when bonded.</para>
@@ -1636,5 +2115,5 @@
 
           <programlisting>
-		... --fit-partial-charges \
+		... --fit-particle-charges \
 		    --fragment-charges 8 1 1 \
 		    --potential-file water.potentials \
@@ -1654,4 +2133,171 @@
 
       <section>
+        <title>Dynamics</title>
+
+        <para>For fitting potentials or charges we need many homologuous but
+        different fragments, i.e. atoms with slightly different positions.
+        How can we generate these?</para>
+
+        <para>One possibility is to use molecular dynamics. With the 
+        aforementioned fragmentation scheme we can quickly calculate not only 
+        energies but also forces if the chosen solver, such as 
+        <link xlink:href="http://www.mpqc.org/"><productname>MPQC
+        </productname></link>, supports it. Integrating these forces discretely over time 
+        gives insight into vibrational features of a molecular system and 
+        allows to generate those positions for fitting potentials that 
+        describe these vibrations.</para>
+
+        <section>
+          <title>Molecular dynamics</title>
+
+          <para>The molecular dynamics action is a so-called macro Action, 
+          i.e. it combines several other Actions into one, namely:</para>
+		  <itemizedlist>
+            <listitem>
+              <para>--verlet-integration</para>
+            </listitem>
+            <listitem>
+              <para>--output</para>
+            </listitem>
+            <listitem>
+              <para>--clear-fragment-results</para>
+            </listitem>
+            <listitem>
+              <para>--destroy-adjacency</para>
+            </listitem>
+            <listitem>
+              <para>--create-adjacency</para>
+            </listitem>
+            <listitem>
+              <para>--update-molecules</para>
+            </listitem>
+            <listitem>
+              <para>--fragment-molecule</para>
+            </listitem>
+            <listitem>
+              <para>--fragment-automation</para>
+            </listitem>
+            <listitem>
+              <para>--analyse-fragment-results</para>
+            </listitem>
+		  </itemizedlist>
+		  
+		  <para>The following will perform a molecular dynamics simulation
+		  for 100 time steps, each time step combining 0.5 atomic time units,
+		  i.e. 1.2 1e-17 s. The other options listed below will seem familiar
+		  to you if you have read about the other Actions listed above. Below
+		  we will not keep the bondgraph, i.e bonds and molecules may change
+		  over the simulation and hence also the created fragments per time
+		  step.
+		  </para>
+
+          <programlisting>
+          ... --molecular-dynamics \
+          --steps 100 \
+          --keep-bondgraph 0 \
+          --order 3 \
+          --distance 3. \
+          --deltat 0.5 \
+          --keep-fixed-CenterOfMass 1 \
+          --fragment-executable mpqc \
+          </programlisting>
+        </section>
+
+        <section>
+          <title>Structure optimization</title>
+
+		  <para>Structure optimization is also a macro Action, it basically
+		  combines the same Actions as molecular-dynamics does. However, it
+		  uses force-annealing instead of verlet-integration.</para>
+
+		  <para>The following performs a structure optimization of the 
+		  currently selected atoms (may also be a subset) for up to 100 time
+		  steps, where each time step ist 0.5 atomic time units. The time
+		  step here is the initial step with for annealing.
+		  </para>
+
+          <programlisting>
+          ... --optimize-structure \
+          --keep-bondgraph 1 \
+          --output-every-step 1 \
+          --steps 100 \
+          --order 3 \
+          --distance 3. \
+          --deltat 0.5 \
+          --keep-fixed-CenterOfMass 1 \
+          --fragment-executable mpqc \
+          </programlisting>
+
+  		  <para>Note that output-every-step will allow you to watch the 
+	  	  optimization as each step is placed into a distinct time step.
+		  Otherwise only two time steps would be created: the initial and
+		  the final one containing the optimized structure.</para>
+        </section>
+
+        <section>
+          <title>Set the world's time step</title>
+
+		  <para>In order to inspect or manipulate atoms and molecules at a
+		  certain time step, the World's time has to be set with the following
+		  Action.
+		  </para>
+		  
+		  <para>This will set the World's time to the fifth step (counting
+		  starts at zero).</para>
+
+          <programlisting>... --set-world-time 4</programlisting>
+        </section>
+
+        <section>
+          <title>Save the temperature information</title>
+
+		  <para>For each time step the temperature (i.e. the average velocity
+		  per atom times its mass) will be stored to a file.</para>
+
+          <programlisting>
+          ... --save-temperature temperature.dat \
+          </programlisting>
+        </section>
+      </section>
+    
+      <section>
+        <title>Tesselations</title>
+
+        <para>Tesselations obtain molecular surfaces (and volumes) by rolling
+        a virtual sphere of a certain radii on a molecule until a closed 
+        surface of connected triangles is created.</para>
+
+        <section>
+          <title>Non-convex envelope</title>
+          
+          <para>This will create a non-convex envelope for a molecule.</para>
+
+          <programlisting>
+          ... --nonconvex-envelope 6. \
+          --nonconvex-file nonconvex.dat
+          </programlisting>
+
+          <para>This tesselation file can be conveniently viewed with 
+          <programname>TecPlot</programname> or with one of the Tcl script 
+          in the util folder with <programname>VMD</programname>.</para>
+        </section>
+
+        <section>
+          <title>Convex envelope</title>
+          
+          <para>This will create a convex envelope for a molecule.</para>
+
+          <programlisting>
+          ... --convex-envelope 6. \
+          --convex-file convex.dat
+          </programlisting>
+
+          <para>This tesselation file can be conveniently viewed with 
+          <programname>TecPlot</programname> or with one of the Tcl script 
+          in the util folder with <programname>VMD</programname>.</para>
+        </section>
+      </section>
+
+      <section>
         <title>Various commands</title>
 
@@ -1677,4 +2323,27 @@
 
         <section>
+          <title>Loading an element database</title>
+
+          <para>Element databases contain information on valency, van der
+          Waals-radii and other information for each element.</para>
+
+          <para>This loads all element database from the current folder (in a
+          unix environment):</para>
+
+          <programlisting>... --element-db ./</programlisting>
+
+        </section>
+
+        <section>
+          <title>Fast parsing</title>
+
+          <para>Parsing all time steps from a given input file can take a 
+          while, especially for larger systems. If fast parsing is activated,
+          only the first time step is loaded, all other are ignored.</para>
+
+          <programlisting>... --fastparsing 1</programlisting>
+        </section>
+
+        <section>
           <title>Giving the version of the program</title>
 
@@ -1692,4 +2361,13 @@
 
           <programlisting>... --warranty</programlisting>
+        </section>
+
+        <section>
+          <title>Giving redistribution information</title>
+
+          <para>This gives information on the license and how to redistribute
+          the program and its source code</para>
+
+          <programlisting>... --help-redistribute</programlisting>
         </section>
       </section>
@@ -1705,36 +2383,110 @@
         session at the point where your attempts start to deviate from one
         another.</para>
+
+        <section>
+          <title>Storing a session</title>
+
+          <para>Storing sessions is simple,</para>
+
+          <programlisting>
+		  ... --store-session "session.py" \
+		      --session-type python
+	      </programlisting>
+
+          <para>Here, the session type is given as python (the other option is
+          cli for in the manner of the command-line interface) and the written
+          python script <filename>session.py</filename> can even be used with
+          the python interface described below, i.e. it is a full python script
+          (that however requires the so-called pyMoleCuilder module).</para>
+        </section>
+
+        <section>
+          <title>Loading a session</title>
+
+          <para>Loading a session only works for python scripts. This actually
+          blurs the line between the command-line interface and the python
+          interface a bit. But even more, MoleCuilder automatically executes a
+          script called <filename>molecuilder.py</filename> if such a file is
+          contained in the current directory.</para>
+
+          <programlisting>... --load-session "session.py"</programlisting>
+
+          <para>This will execute every action with its options contained in the
+          script <filename>session.py</filename>.</para>
+        </section>
       </section>
 
       <section>
-        <title>Storing a session</title>
-
-        <para>Storing sessions is simple,</para>
-
-        <programlisting>
-		... --store-session "session.py" \
-		    --session-type python
-	</programlisting>
-
-        <para>Here, the session type is given as python (the other option is
-        cli for in the manner of the command-line interface) and the written
-        python script <filename>session.py</filename> can even be used with
-        the python interface described below, i.e. it is a full python script
-        (that however requires the so-called pyMoleCuilder module).</para>
-      </section>
-
-      <section>
-        <title>Loading a session</title>
-
-        <para>Loading a session only works for python scripts. This actually
-        blurs the line between the command-line interface and the python
-        interface a bit. But even more, MoleCuilder automatically executes a
-        script called <filename>molecuilder.py</filename> if such a file is
-        contained in the current directory.</para>
-
-        <programlisting>... --load-session "session.py"</programlisting>
-
-        <para>This will execute every action with its options contained in the
-        script <filename>session.py</filename>.</para>
+        <title>Various specific commands</title>
+        
+        <para>In this (final) section of the action description we list a number
+        Actions that are very specific to some purposes (or other programs).
+        </para>
+        
+        <section>
+          <title>Saving exttypes of a set of atoms</title>
+          
+          <para>This saves the atomic ids of all currently selected atoms in a 
+           <link xlink:href="http://www.tremolo-x.com/"><programname>TREMOLO
+           </programname></link> exttypes file with the given name.</para>
+
+          <programlisting>
+          ... --save-selected-atoms-as-exttypes \
+          --filename test.exttypes </programlisting>
+        </section>
+        
+        <section>
+          <title>Setting parser specific parameters</title>
+
+          <para>You can also tweak the parameters stored in this file easily.
+          For example, <productname>MPQC</productname> stores various
+          parameters modifying the specific ab-initio calculation performed.
+          For <link xlink:href="http://www.mpqc.org/"><productname>MPQC
+          </productname></link> and 
+          <link xlink:href="http://www.psicode.org/"><productname>Psi4
+          </productname></link> this can be modified as follows.</para>
+
+          <programlisting>
+		... --set-parser-parameters mpqc \
+		    --parser-parameters "theory=CLHF;basis=6-31*G;"
+          </programlisting>
+
+          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
+          and the basis set to 6-31*G. Please check the
+          <productname>MPQC</productname> manual on specific
+          parameters.</para>
+        </section>
+
+        <section>
+          <title>Tremolo specific options and potential files</title>
+
+          <para><productname>TREMOLO</productname>'s configuration files start
+          with a specific line telling the amount of information stored in the
+          file. This file can be modified, e.g. to enforce storing of
+          velocities and forces as well as the atoms positions and
+          element.</para>
+
+          <programlisting>
+		... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
+		    --reset 1
+	  </programlisting>
+
+          <para>This will not append but reset the old line and fill it with
+          the given string.</para>
+
+          <para>One specific action is required when loading certain
+          <productname>TREMOLO</productname> configuration files. These
+          contain element notations that refer to parameterized names used in
+          empirical potentials and molecular dynamics simulations and not the
+          usual chemical symbols, such as H or O. We may load an auxiliary
+          file that gives the required conversion from OH1 to H, which is the
+          so-called potential file.</para>
+
+          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
+
+          <para>This parses the lookup table from the file
+          <filename>water.potentials</filename> and it can be used in
+          following load actions.</para>
+        </section>
       </section>
     </section>
@@ -2029,5 +2781,6 @@
 
     <para>Tutorials and more information is available online, see <link
-    xlink:href="???">http://www.molecuilder.com/</link>.</para>
+    xlink:href="http://www.molecuilder.com/">MoleCuilder's website</link>.
+    </para>
 
     <para>Be aware that in general knowing how the code works allows you to
