source: doc/userguide/userguide.xml@ 91c409

<?xml version='1.0' encoding='UTF-8'?>
<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY molecuilder_logo SYSTEM "pictures/molecuilder_logo.png" NDATA PNG>
<!ENTITY dialog_box SYSTEM "pictures/dialog_box.png" NDATA PNG>
<!ENTITY dialog_add-atom_tooltip SYSTEM "pictures/dialog_add-atom_tooltip.png" NDATA PNG>
<!ENTITY dialog_complex SYSTEM "pictures/dialog_complex.png" NDATA PNG>
<!ENTITY dialog_exit SYSTEM "pictures/dialog_exit.png" NDATA PNG>
<!ENTITY example_basic_view SYSTEM "pictures/example_basic_view.png" NDATA PNG>
]>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0">
  <info>
    <title>MoleCuilder - a Molecule Builder</title>
    <author>
      <personname>
        <firstname>Frederik</firstname>
        <surname>Heber</surname>
      </personname>
      <affiliation>
        <orgname>frederik.heber@gmail.com</orgname>
      </affiliation>
    </author>
    <pubdate>07/03/14</pubdate>
  </info>
  <chapter>
    <title>Introduction</title>
    <figure>
      <title>MoleCuilder logo depicting a tesselated buckyball and a benzene molecule</title>
      <mediaobject>
        <imageobject>
          <imagedata width="100%" scalefit="1" entityref="molecuilder_logo"/>
        </imageobject>
      </mediaobject>
    </figure>
    <section xml:id="whatis">
      <title xml:id="whatis.title">What is MoleCuilder?</title>
      <para>In Short,<command> MoleCuilder</command> is a concatenation of
      molecule and builder.</para>
      <para>In more words, molecular dynamics simulations are frequently
      employed to simulate material behavior under stress, chemical reactions
      such as of cementitious materials, or folding pathways and docking
      procedures of bio proteins. Even if the computational load, due to the
      large number of atoms, is very demanding, nonetheless they may serve as
      a starting point, e.g. extracting parameters for a coarser model.
      However, what is on the other hand the starting point of molecular
      dynamics simulations? It is the coordinate and element of each atom
      combined with potential functions that model the interactions.</para>
      <para>MoleCuilder allows to fully construct such a starting point:
      letting the user construct atomic and molecular geometries by a simple
      point&amp;click approach, a CAD-pendant on the nanoscale. Creating
      suitable empirical potentials by fitting parameters to ab-initio
      calculations within hours. Specific emphasis is placed on a
      simple-to-use interface, allowing for the quick-and-dirty building of
      molecular systems, and on scriptability. The last being important a eventually not a single, but
      many, related molecular systems have to be created.</para>
      <para>We hope you will enjoy using MoleCuilder as much as we had creating 
      it and still continue extending it. It obtains its flexibility from the use of
       agile programming techniques and state-of-the-art libraries such as Boost. 
       If you feel dissatiesfied with certain parts, please do not hesitate to give
        feedback (see below).</para>
      <section xml:id="installation">
        <title xml:id="installation.title">Installation requirements</title>
        <para>For installations requirements and instructions we refer to the
        internal documentation of MoleCuilder, created via <productname>doxygen</productname>. from the
        source code.</para>
      </section>
      <section xml:id="license">
        <title xml:id="license.title">License</title>
        <para>As long as no other license statement is given, MoleCuilder is
        free for user under the GNU Public License (GPL) Version 2 (see
        <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
      </section>
      <section xml:id="disclaimer">
        <title xml:id="disclaimer.title">Disclaimer</title>
        <para>We quote section 11 from the GPLv2 license:</para>
        <remark>Because the program is licensed free of charge, there is not warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing in the copyright holders and/or other parties provide the program &quot;as is&quot; without warranty of any kind, either expressed or implied. Including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair, or correction.</remark>
      </section>
      <section xml:id="feedback">
        <title xml:id="feedback.title">Feedback</title>
        <para>If you encounter any bugs, errors, or would like to submit
        feature request, please use the email address provided at the very
        beginning of this user guide. The author is especially thankful for
        any description of all related events prior to occurrence of the
        error, saved &quot;session scripts&quot; (see below) and auxiliary files. Please
        mind sensible space restrictions of email attachments.</para>
      </section>
      <section xml:id="notation">
        <title xml:id="notation.title">Notation</title>
        <para>We briefly explain a few specific wordings associated with the
        program:</para>
        <itemizedlist>
          <listitem>
            <para><emphasis>Action</emphasis> is a command that allows for
            undoing and redoing, i.e. a single atomic procedure for
            manipulating the molecular system. Here, atomic refers to indivisible and not to atoms. It is also referred to as a command.</para>
          </listitem>
          <listitem>
            <para>Selection refers to a subsets from the set of instances of a
            particular type, e.g. atoms, molecules, shapes, ...</para>
          </listitem>
          <listitem>
            <para>Shape means a specific region of the domain that can be
            described in the way of constructive geometry, i.e. as the
            intersection, negation, and combination of primitives such as
            spheres, cubes, or cylinders.</para>
          </listitem>
          <listitem>World refers to the whole of the molecular system, i.e. all 
          atoms with coordinates and element type (over all time steps), all 
          bonds between pairs of atoms, the size of the simulation domain. 
          This is also referred to as the state.</listitem>
          <listitem>Time step is the current discrete position in time. Molecular 
          dynamics simulations are executed in discrete (but very small) time 
          steps.  Each atom has a distinct position per time step. The discrete 
          positions over the discrete time steps samples its trajectory during a 
          simulation.</listitem>
        </itemizedlist>
      </section>
      <section xml:id="completeness">
        <title xml:id="completeness.title">Completeness</title>
        <para>This documentation takes quite some effort to write. Hence, the
        described features and especially the actions herein are settled with
        respect to their functionality, while newer features or actions are
        probably missing. This should be a clear sign to you that these are
        probably not safe to use yet. If you nonetheless require them, you 
        should acquire some familiarity with the code itself. This suggests
        changing to the developer documentation which is maintained along 
        with the source code with <productname>doxygen</productname>.
        </para>
      </section>
    </section>
  </chapter>
  <chapter>
    <title>Features</title>
    <para>Basically, <command>MoleCuilder</command> parses geometries from
    files, manipulates them, and stores them again in files. The manipulation
    can be done either via a command-line interface or via the graphical user
    interface.</para>
    <section xml:id="concepts">
      <title xml:id="concepts.title">Concepts</title>
      <para>In general, we divide the molecular systems into three different
      components or scales.</para>
      <orderedlist>
        <listitem>
          <para>Atoms</para>
          <para>Atoms are the undividable objects of the molecular systems.
          They have at least an element <quote>Z</quote> and three coordinates
          <quote>(x,y,z)</quote>.</para>
        </listitem>
        <listitem>
          <para>Molecules</para>
          <para>Molecules are bound conglomeration of atoms. They contain a
          number of atoms, i.e. by beginning at an arbitrary atom of the molecule and traversing its bond graph eventually all of the molecule&apos;s atoms are visited. Currently, a bond refers to a covalent bonding between atoms. Also, molecules may have a
          bounding box, i.e. a subdomain that contains all of the atoms in the
          molecule.</para>
          <para>Note that the molecular structure of the system, i.e. the
          bonding graph, is determined by MoleCuilder and used to dissect the
          system into distinct molecules on request.</para>
        </listitem>
        <listitem>
          <para>Clusters</para>
          <para>Clusters are unbound conglomeration of atoms. Clusters serves
          as groups of atoms for specific operations that would be to
          restricted if they worked on just molecules.</para>
        </listitem>
        <listitem>
          <para>Domain</para>
          <para>The domain refers to the simulation domain. It is the
          parallelepiped in 
          <inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:msup>
                    <mml:mi>R</mml:mi>
                    <mml:mn>3</mml:mn>
                  </mml:msup>
                </mml:mrow>
              </mml:math>
            </inlineequation> 
            where either periodic, wrapped, or open boundary
          conditions apply. The domain contains all atoms, i.e. the box
          containing all atoms.</para>
        </listitem>
      </orderedlist>
    </section>
    <section xml:id="interfaces">
      <title xml:id="interfaces.title">Interfaces</title>
      <para>MoleCuilder has four different interfaces: Command-line, text
      menu, graphical user interface, and python interface.</para>
      <orderedlist>
        <listitem>
          <para>Command-Line</para>
          <para>The command-line interface allows to use MoleCuilder
          non-interactively via a terminal session. The program is executed by
appending to the shell command a number of commands including all
          required options that are then executed one after the other. After
          execution of the last command, the program quits. The command-line
          interface usually works on a specific file that is given as input,
          manipulated, analysed, ... via the sequence of commands and
          eventually all changes are stored in the this file. Hence, the input
          file acts as the state of the starting configuration that is
          modified via MoleCuilder.</para>
        </listitem>
        <listitem>
          <para>Text menu</para>
          <para>The text-menu is similar to the command-line interface with
          the exception that it allows for interactive sessions. Commands are
          chosen from a text menu and executed directly after selection by the
          user.</para>
        </listitem>
        <listitem>
          <para>Graphical interface</para>
          <para>The graphical interface is based on Qt. It features a full graphical, three-dimensional
representation of the simulation domain with atoms and
          their bonds. It allows manipulation in point&amp;click fashion.
          Commands are selected from pull-down menus and dialogs are used to
          query the user for all required parameters to such a command.</para>
        </listitem>
        <listitem>
          <para>Python interface</para>
          <para>The last interface is accessible only within the python
          programming language. MoleCuilder can be loaded as a module and its
          commands can be executed with either the python interpreter
          interactively or via python scripts non-interactively. Note that
          this allows auxiliary calculations to be performed in pythons whose
          results may be used as parameters in subsequent commands.</para>
        </listitem>
      </orderedlist>
    </section>
    <section xml:id="fileformats">
      <title xml:id="fileformats.title">Known File formats</title>
      <para>We briefly list the file formats MoleCuilder can parse and
      store. We refer to external websites for more detailed information where appropriate.</para>
      <itemizedlist>
        <listitem>
          <para>XYZ, <filename>.xyz</filename> (simplest of all formats,
          line-wise element and three coordinates with two line header, number
          of lines and a comment line)</para>
        </listitem>
        <listitem>
          <para><link xlink:href="http://www.mpqc.org/">
              <productname>MPQC </productname>
            </link>, <filename>.in</filename></para>
        </listitem>
        <listitem>
          <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename> .pdb</filename></para>
        </listitem>
        <listitem>
          <para><productname>ESPACK</productname>, <filename>.conf</filename>
          (electronic structure package by Institute for Numerical Simulation,
          University of Bonn, code not in circulation)</para>
        </listitem>
        <listitem>
          <para><link xlink:href="http://www.psicode.org/">
              <productname>PSI4 </productname>
            </link>, <filename>.psi</filename></para>
        </listitem>
        <listitem>
          <para><link xlink:href="http://www.tremolo-x.org/">
              <productname> TREMOLO</productname>
            </link>, <filename>.data</filename></para>
        </listitem>
        <listitem>
          <para>XML, <filename>.xml</filename> (XML as read by 
          <link xlink:href="http://www.scafacos.org/">ScaFaCoS</link>
          project)</para>
        </listitem>
      </itemizedlist>
      <para>These are identified via their suffixes and can be converted from
      one into another (with possible loss of data outside of the intersection of
      stored properties of the two involved file formats).</para>
      <para>Note that the various formats differ in how much information they
      can store. This restriction may come from two sources: either the file format
      specification does not support more or the implementation is still lacking
      specific features.</para>
      <para>What all formats can store at least is the element per atom and a
      position in three spatial coordinates for a single time step.</para>
      <para>In the following we list some restrictions:</para>
      <itemizedlist>
        <listitem>
          <para>Multiple time steps supported by</para>
          <itemizedlist>
            <listitem>
              <para>Pdb</para>
            </listitem>
            <listitem>
              <para>Tremolo (note entries allows to change over steps are: x, u, F)</para>
            </listitem>
            <listitem>
              <para>Xyz</para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>Bond information supported by</para>
          <itemizedlist>
            <listitem>
              <para>Pdb</para>
            </listitem>
            <listitem>
              <para>Tremolo</para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>Full atom state storable (i.e. position, velocity, and force)</para>
          <itemizedlist>
            <listitem>
              <para>Tremolo</para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>Domain information (however, this is not parsed only stored)</para>
          <itemizedlist>
            <listitem>
              <para>Tremolo</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <para>You easily notice that the <productname>Tremolo</productname> format is currently
      the most versatile. However, by advised that you need to give a specific
    <emphasis>ATOMINFO</emphasis> line that specifies what needs to be stored,
    see <link linkend="various-specific.set-tremolo-atomdata">set-tremolo-atomdata</link>.</para>
    </section>
  </chapter>
  <chapter>
    <title>Interfaces</title>
    <para>In this chapter, we explain the intention and use of the four
    interfaces.</para>
    <para>We will give the most extensive explanation of the command-line
    interface, all subsequent interfaces are explained in highlighting their
    differences with respect to the command-line interface. This is because
    the command-line lends itself very well to representation in this textual
    user guide. Although some images of the graphical interface are given
    below, they would blow the size of the guide out of proportion.</para>
    <para>In any case, you should make yourself familiar with at least one of
    the interactive (text menu, GUI) and one of the non-interactive
    (command-line, python) interfaces to use MoleCuilder to its full potential:
    The interactive interface gives you the immediate feedback in constructing
    &quot;synthesis&quot; (build) chains (of commands) for constructing your specific
    molecular system in the computer. The non-interactive interface lends
    itself to quick creation of related systems that differ only by specific
    parameters you have modified in the script (command-line can be used in
    shell scripts, python itself is a scripted language). Also, the
    non-interactive interfaces are used for storing sessions which helps you
    in documentation your experiments and later on understanding of what has
    been actually created by the prescribed commands, i.e. debugging.</para>
    <section xml:id="command-line-interface">
      <title xml:id="command-line-interface.title">Command-line interface</title>
      <para>The command-line interface reads options and commands from the
      command line and executes them sequentially. This may be for example:
      Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, recognize the bond graph, choose a
      simulation box, fill the box with this given &quot;filler&quot; molecule, save the
      file. This enables the use of MoleCuilder in simple script-files to
      create a whole range of geometries that only differ in a few parameters
      automatically.</para>
      <para>Traditionally, <command>MoleCuilder</command> operates on a single
      configuration file - the state - which may also store additional
      information depending on the chosen file format such as parameters for
      ab-initio computations. To some small extent <command>MoleCuilder</command> also allows manipulation of these paramters. An example for the above procedure is given
      below:</para>
      <programlisting>
 ./molecuilder \
  -i sample.xyz \
  --add-atom H \
    --domain-position &quot;0.,0.,0.&quot; \
  ...
 </programlisting>
      <para>The first argument is the executable itself. Second, there is a
      slew of arguments -- one per line split with a backslash telling the comman 
      shell that the line still continues -- consisting of the input action and 
      an arbitrarily named file <filename>sample.xyz</filename>, which may be 
      empty and whose file format is chosen by the given extension. The third 
      is the add-atom action following by an option that gives the position in 
      the domain where to add the &quot;H&quot;ydrogen atom. An action is always 
      introduced via a double hyphen and its full name (containing just 
      non-capital letters and hyphens) or a single hyphen and a single letter 
      for its shortform, such as <emphasis role="bold"> -a</emphasis> for adding an atom to the system. It is 
      followed by a fixed number of options. Most of these have default values 
      and in this do not have to be specified.</para>
      <formalpara><title>Invalid values</title><para>Certain options accept only very specific input. For example, the option value associated with <emphasis role="bold">add-atom</emphasis></para>, i.e. the chemical element, can only be one of the chemical symbols that exist and not any arbitrary string. Each option value is checked on parsing the command-line. If any value is not valid, an error message is given and none of the actions is executed.</formalpara>
      <formalpara>
        <title>Shortforms of Actions</title>
        <para>Note that not all action have shortforms and it is best practice
        to have the full action name instead of its shortform to make the
        command-line comprehendable to you in years to come.</para>
      </formalpara>
      <note>
        <para>Note further that when placing a slew of commands in a script file
         it is generally recommended to use the above formatting: One command 
         or option per line and each receives an extra tab for indentation.</para>
      </note>
      <section xml:id="preliminaries">
        <title xml:id="preliminaries.title">Preliminaries</title>
        <para>Some preliminary remarks are in order which we have gathered
        here on how these actions work in general.</para>
        <para>We first delve into some details about secondary structure
        such as selections, shapes, and randomization required to specify
        subsets of atoms and molecules you wish to manipulate. Then, we have
give the details on the manipulation ordered by the
        scale they act upon - single atoms, multiple atoms organized as
        molecules, and all atoms organized by their containing domain.</para>
        <para>In the following we will always give a command to illustrate the
        procedure but just its necessary parts, i.e. &quot;...&quot; implies to prepend
        it with the executable and input command for a specific configuration
        file, for storing the manipulated state of the molecular system. </para>
        <para>So if we write</para>
        <programlisting>... --help</programlisting>
        <para>Then we actually mean you to write</para>
        <programlisting>./molecuilder --help</programlisting>
        <para>Note that this specific exemplary command is very useful  as it will always give you a list of all available actions and also a
        brief explanation on how to properly enter values of a specific type,
        e.g. an element, a vector, or a list of numbers. Details to a specific
        action can be requested when its full name is known, e.g. for
        &quot;add-atom&quot;,</para>
        <programlisting>./molecuilder --help add-atom</programlisting>
        <para>which fills you in on each option to the action: its full name,
        its expected type, and a possibly present default value, and a brief
        description of the option.</para>
        <para>An Action can be undone and redone, e.g. undo adding an atom as
        follows,</para>
        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo</programlisting>
        <para>and redo as follows</para>
        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo --redo</programlisting>
        <para>With the non-interactive interfaces this may seem rather
        superfluous but it comes in very handy in the interactive ones. Also
        this should tell you that actions are placed internally in a queue, i.e. a history,
        that undo and redo manipulate.</para>
        <para>Furthermore, a specific event in the history of actions can be 
        marked using
        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --set-undo-mark 1 --select-all-atoms --remove-atom</programlisting>
        Using this mark (that is unset by <programlisting>--set-undo-mark 0</programlisting>) 
        one can then step directly back to that event by undoing all actions in between
        the current and the marked event.
        <programlisting>--undo-till-mark</programlisting>
        Here, this will jump back to when the hydrogen atom was just added.
        This function is required as not all actions produce an event in the Action 
        history. Certain events will just calculate something and output, i.e. they
        do not change the state. However, thereby one cannot simply count actions
        to return back to a specific state. Hence, this function allows to mark a
        specific state beforehand.
        </para>
        <para>Due to a current limitation of the implementation each command can be used on the command-line only once. Note that this <emphasis role="italic">only</emphasis> applies to the command-line interface. All other interfaces, especially all interactive ones, do not have such a restriction. For the command-line interface there are several ways to work around it. Either by splitting the whole chain of commands into several chunks, each using only unique commands and using the input file (the state) to contain  and transport the intermediate stages as input for the next stage. Or to switch to other commands: often there are several possible ways of achieving a goal, especially when using selections.</para>
        <para>Being done now with the preliminaries we now go through all available actions present in MoleCuilder.</para>
      </section>
      <section xml:id="fileparsers">
        <title xml:id="fileparsers.title">File parsers</title>
        <para>We have already given a list of all known file formats, see
        <link linkend="fileformats">File formats</link>. Next, we explain how these
        file formats are picked and manipulated.</para>
        <section xml:id="fileparsers.parsing">
          <title xml:id="fileparsers.parsing.title">Parsing files</title>
          <para>We already discussed that the command-line interface works
          state-based and hence you should supply it with a file to work
          on.</para>
          <programlisting>... --input water.data</programlisting>
          <para>This will load all information, especially atoms with their
          element and position, from the file <filename>water.data</filename>
          into the state. Most importantly, all changes will eventually be stored to this file,
          or to files with the prefix <filename>water</filename> and suffixes
          of desired file formats, e.g. <filename>water.in</filename> if you
          specified <productname>MPQC</productname>.</para>
          <programlisting>... --load morewater.xyz</programlisting>
          <para>This will load another file <filename>water.xyz</filename>,
          however changes will still be written to files prefixed with
          <filename>water</filename> as designated by the 
          <emphasis role="bold">input</emphasis> command. Note that now already 
          two state files will stored, <filename>water.data</filename> and
          <filename>water.xyz</filename> as these two different file formats
          have been used. This is the default behavior: any additional file 
          format used in loading is registered internally and the output file
           will then be written in all registered formats on exit.</para>
          <note>If the loaded file is empty, then no parser is registered. This
           means if a new state file needs to be written,then the output format
           has to be stated explicitly, e.g.
          <programlisting>... --input hydrogen.xyz \
    --set-output xyz \
    --add-atom H --domain-position "0,0,0" </programlisting>
           </note>
          <note xml:id="various.fastparsing">
          <para>In the case that parsing all time steps from a given input 
          file will take too long, especially for larger systems, fast parsing 
          may be activated, only the first time step is loaded, all other are
           ignored.</para>
          <programlisting>... --fastparsing 1</programlisting>
        </note>
        </section>
        <section xml:id="fileparsers.set-output">
          <title xml:id="fileparsers.set-output.tile">Adding output file formats</title>
          <para>We already know that loading a file also picks a file format
          by its suffix. We may add further file formats to which the state of
          the molecular system is written to on program exit.</para>
          <programlisting>... --set-output mpqc tremolo</programlisting>
          <para>This will store the final state of the molecular systems as
          <productname>MPQC</productname> and as
          <productname>TREMOLO</productname> configuration file. See
        <link linkend="fileformats">File formats</link> for the list of all file formats available.</para>
        </section>
        <section xml:id="fileparsers.storing">
          <title xml:id="fileparsers.storing.title">Storing to files</title>
          <para>Storing the current World, i.e. all its atoms, to a 
          given file, happens automaticallyon program exists if an 
          <link linkend="fileparsers.parsing">input</link> file has been 
          specified. However, this can also be forced at any point in between
          by using one of two actions:</para>
          <programlisting>... --output</programlisting>
          <para>This action does not use an argument and will simply use the 
          currently registered input file and store the state of the World there
          This is handy if an intermediate state is required (making sense for 
          interactive and python interfaces).</para>
          <programlisting>... --output-as world.xyz</programlisting>
          <para>This action on the other hand will be write the current state
          to a new file "world.xyz".</para>
          <para>By default, this will not overwrite any present files. To
          overwrite present files, please append 
          <programlisting>--force-overwrite 1</programlisting>.</para>
        </section>
        <section xml:id="fileparsers.save-selected-molecules">
          <title xml:id="fileparsers.save-selected-molecules.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<emphasis role="bold">store-saturated-fragment</emphasis>
          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>
        </section>
      </section>
      <section xml:id="selections">
        <title xml:id="selections.title">Selections and unselections</title>
        <para>In order to tell MoleCuilder on what subset of atoms a specific
        Action is to be performed, there are <emphasis>selection actions</emphasis>. Note that a selection per se does not change
        anything in the state of the molecular system in any way. Essentially, it is just a filter.</para>
        <para>Selections either work on atoms, on molecules, or on shapes
        (this we explain later on). A given selection is maintained from the
        execution of the selection action to the end of program or until
        modified by another selection applied on the same type (atom,
        molecule, shape). Selections are not stored to file (i.e. do not belong to the state).</para>
        <para>We only give here a brief list on the available kind of selections for each of the three  types they work on.
Each action is executed either as follows, exemplified by selecting
        all atoms.</para>
        <programlisting>.... --select-all-atoms</programlisting>
        <para>or, exemplified by unselecting the last molecule,</para>
        <programlisting>... --unselect-molecule-by-order -1</programlisting>
        <para>i.e. they are prepended by either <emphasis role="bold">select</emphasis> or <emphasis role="bold">unselect</emphasis>.</para>
        <itemizedlist>
          <listitem>
            <para>Atoms</para>
            <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 Bond Neighbors (all bond neighbors of all currently 
                selected atoms are additionally selected)</para>
                <programlisting>
                ... --select-atom-bond-neighbors
                </programlisting>
              </listitem>
              <listitem>
                <para>By name (atom with molecule internal name "H1", e.g. 
                this will select all "H1" atoms in every present water molecule)</para>
                <programlisting>
                ... --select-atom-by-name "H1"
                </programlisting>
                <programlisting>
                ... --unselect-atom-by-name "H1"
                </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 
                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 Random Number of Atoms (e.g., 5 random atoms) </para>
                <programlisting>
                ... --select-atom-by-random 5
                </programlisting>
              </listitem>
              <listitem>
                <para id="selections.select-atom-inside-volume">By Shape (all 
                atoms inside the volume specified by the currently selected
                 shape)</para>
                <programlisting>
                ... --select-atom-inside-volume
                </programlisting>
                <programlisting>
                ... --unselect-atoms-inside-volume
                </programlisting>
              </listitem>
              <listitem>
                <para>By Molecule (all atoms belonging to currently selected
                molecules)</para>
                <programlisting>
                ... --select-molecules-atoms
                </programlisting>
                <programlisting>
                ... --unselect-molecules-atoms
                </programlisting>
              </listitem>
              <listitem>
                <para>Push/Pop the current selection to/from a stack to store 
                it momentarily and allow modifications in MakroActions (this is
                 very specific and used mostly internally).</para>
                <programlisting>
                ... --push-atom-selection
                </programlisting>
                <programlisting>
                ... --pop-atom-selection
                </programlisting>
              </listitem>
              <listitem>
                <para>Select bond neighbors of all currently selected atoms.
                 </para>
                <programlisting>
                ... --select-atoms-neighbors
                </programlisting>
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para>Molecules</para>
            <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 created molecule, second created 
                molecule, ...)</para>
                <programlisting>
                ... --select-molecule-by-order 2
                </programlisting>
                <programlisting>
                ... --unselect-molecule-by-order -2
                </programlisting>
              </listitem>
              <listitem>
                <para>By Formula (molecule with H2O as formula)</para>
                <programlisting>
                ... --select-molecules-by-formula &quot;H2O&quot;
                </programlisting>
                <programlisting>
                ... --unselect-molecules-by-formula &quot;H2O&quot;
                </programlisting>
              </listitem>
              <listitem>
                <para>By Name (all molecules named &quot;water4&quot;)</para>
                <programlisting>
                ... --select-molecules-by-name &quot;water4&quot;
                </programlisting>
                <programlisting>
                ... --unselect-molecules-by-name &quot;water4&quot;
                </programlisting>
              </listitem>
              <listitem>
                <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>
              <listitem>
                <para>Push/Pop the current selection to/from a stack to store 
  it momentarily and allow modifications in MakroActions.</para>
                <programlisting>
                ... --push-molecule-selection
                </programlisting>
                <programlisting>
                ... --pop-molecule-selection
                </programlisting>
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para>Shapes</para>
            <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 (all shapes named &quot;sphere1&quot;)</para>
                <programlisting>
                ... --select-shape-by-name &quot;sphere1&quot;
                </programlisting>
                <programlisting>
                ... --unselect-shape-by-name &quot;sphere1&quot;
                </programlisting>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <remark>Note that an unselected instance (e.g. an atom) remains unselected upon further unselection and vice versa with selection.</remark>
        <para>These above selections work then in conjunction with other
        actions and make them very powerful, e.g. you can remove all atoms
        inside a sphere by a selecting the spherical shape and subsequently
        selecting all atoms inside the shape and then removing them.</para>
      </section>
      <section xml:id="shapes">
        <title xml:id="shapes.title">Shapes</title>
        <para>Shapes are specific regions of the domain. There are just a few
        so-called <emphasis>primitive</emphasis> shapes such as cuboid,
        sphere, cylinder, the whole domain, or none of it. However, these can be
        combined via boolean operations such as and, or, and not. This
        approach is called <emphasis>constructive geometry</emphasis>. E.g. by
        combining a sphere with the negated (<emphasis role="italic">not</emphasis> operation) of a smaller sphere, we
        obtain a spherical surface of specific thickness.</para>
        <note>Shapes are especially useful in the QtGui where all selected
        shapes are visualized by their translucent boundary. This makes it
        especially easy to e.g. recognize all atoms that would be removed
        after <link linkend="selections.select-atom-inside-volume">selecting
        all atoms inside the volume</link> of a selected shape.</note>
        <section xml:id="shapes.create-shape">
          <title xml:id="shapes.create-shape.title">Creating shapes</title>
          <para>Primitive shapes can be created as follows,</para>
          <programlisting>
  ... --create-shape \
      --shape-type sphere \
      --shape-name &quot;sphere1&quot; \
      --stretch &quot;2,2,2&quot; \
      --translation &quot;5,5,5&quot;
   </programlisting>
          <para>This will create a sphere of radius 2 (initial radius is 1)
          with name &quot;sphere1&quot; that is centered at (5,5,5). Other primitives are
          cuboid and cylinder, where a rotation can be specified as
          follows.</para>
          <programlisting><programlisting>
  ... --create-shape \
      --shape-type cuboid \
      --shape-name &quot;box&quot; \
      --stretch &quot;1,2,2&quot; \
      --translation &quot;5,5,5&quot; \
      --angle-x &quot;90&quot;
   </programlisting>
  ... --create-shape \
      --shape-type cylinder \
      --shape-name &quot;cylinder&quot; \
      --stretch &quot;1,2,2&quot; \
      --translation &quot;5,5,5&quot; \
      --angle-y &quot;90&quot;
   </programlisting>
        </section>
        <section xml:id="shapes.combine-shapes">
          <title xml:id="shapes.combine-shapes.title">Combining shapes</title>
          <para>Any two shapes can be combined by boolean operations as follows</para>
          <programlisting>
  ... --combine-shapes \
      --shape-name &quot;combinedshape&quot; \
      --shape-op &quot;AND&quot;
   </programlisting>
          <para>This will combine two currently selected shapes vis the &quot;AND&quot; operation
          and create a new shape called &quot;combinedshape&quot;. 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 consists of only 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 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 xml:id="shapes.remove-shape">
          <title xml:id="shapes.remove-shape.title">Removing shapes</title>
          <para>Removing a shape is as simple as removing an atom.</para>
          <programlisting>... --remove-shape </programlisting>
          <para>This removes all currently selected shapes.</para>
        </section>
        <section xml:id="shapes.manipulation">
          <title xml:id="shapes.manipulation.title">Manipulating shapes</title>
          <para>Shapes can be stretched, scaled, rotated, and translated to
          modify primitives or combined primitive shapes. As you have seen
          this manipulation could have occurred already at creation but we may also
do it           later on. As usual, we just list examples of the various manipulations
          below, each of them works on the currently selected shapes.</para>
          <programlisting>
  ... --stretch-shapes &quot;1,1,2&quot; \
      --stretch-center &quot;5,5,5&quot;
   </programlisting>
          <para>This stretches the shapes relative to the center at (5,5,5)
          (default is origin) by a factor of 2 in the z direction.</para>
          <programlisting>
  ... --rotate-shapes \
      --center &quot;10,2,2&quot; \
      --angle-x 90 \
      --angle-y 0 \
      --angle-z 0
   </programlisting>
          <para>This way all selected shapes are rotated by 90 degrees around
          the x axis with respect to the center at (10,2,2).</para>
          <programlisting>... --translate-shapes &quot;5,0,0&quot; </programlisting>
          <para>This translates all selected shapes by 5 along the x
          axis.</para>
        </section>
      </section>
      <section xml:id="geometry">
        <title xml:id="geometry.title">Geometry Objects</title>
        <para>Although we use the term geometry objects in the title, we 
        actually mean vectors, i.e. a position or direction in the 
        three-dimensional space. But maybe we have need for the more
        general term in the future.</para>
        <para>Vectors are required as input to many of the Actions further 
        below: translating atoms, rotating atoms around a specific axis,
        aligning a molecule with a vector, ...</para>
        <para>Therefore, vectors can be stored and referenced using a given
        name. This allows for a very powerful and handy manipulation of the
       molecular system afterwards. And to give a concrete example, let's have
       a look at translating a set of selected atoms, see subsection on
       <link linkend='atoms.translate-atom'>Translating atoms</link>. </para>
       <programlisting>
... --translate-atoms &quot;unitVectorX&quot;
       </programlisting>
       <para>This would use the automatically created reference 
       &quot;unitVectorX&quot;, i.e. the vector with components (1,0,0) as
       the translation vector for the given set of atoms. In other words, all
       selected atoms get shifted by 1 unit (e.g. Angstr&ouml;m) in +X
       direction.</para>
       <para>We have the following automatically created geometry objects 
       whose names are self-explanatory:</para>
       <itemizedlist>
        <listitem>zeroVector</listitem>
        <listitem>unitVectorX</listitem>
        <listitem>unitVectorY</listitem>
        <listitem>unitVectorZ</listitem>
       </itemizedlist>
       <para>However, more vectors can be simply constructed from atomic 
       positions, such as the position of an atom directly, the distance between 
       two atoms (in case they are bonded, then this would be the bond vector) 
       or from three atoms, defining a plane and giving its normal vector.
       </para>
       <remark>We have refrained from giving automated names to vectors and even
       keeping them up-to-date automatically, i.e. the distance between two atoms
       O1 and O2 could be named &quot;distance_O1_O2&quot; or similar. However, we want
       the user to have full control and maybe come up with more suitable names 
       such as &quot;rotation_axis&quot; in this case.</remark>
       <warning>Note that names have to be unique and the Action will fail if
       the name is already used.</warning>
        <section xml:id="geometry.distance-to.vector">
          <title xml:id="geometry.distance-to-vector.title">Atomic distance to stored vector</title>
          <para>The distance between two selected atoms is stored as a vector as follows,</para>
          <programlisting>
  ... --distance-to-vector &quot;distance_vec&quot; \
      --reverse 0
          </programlisting>
          <para>where the distance vector can be referenced by &quot;distance_vec&quot; 
          from then on in other Actions requiring a vector as input.</para>
          <note>Since selected atoms are used in the fixed order of their ids
           (and not in the order they were clicked at in 
           <link linkend="graphical-user-interface">QtGui</link>), the 
           direction can be inverted by giving the "reverse" option. It is
           off (or 0) by default.</note>
        </section>
        <section xml:id="geometry.input-to.vector">
          <title xml:id="geometry.input-to-vector.title">Coordinates to stored vector</title>
          <para>We may also create a geometry vector simply by supplying the 
          three coordinates of a vector.</para>
          <programlisting>
  ... --input-to-vector &quot;vector&quot; \
      --position &quot;1,2,3&quot;
          </programlisting>
          <para>where the vector with components (1,2,3) can be referenced 
          by &quot;vector&quot; .</para>
        </section>
        <section xml:id="geometry.plane-to.vector">
          <title xml:id="geometry.plane-to-vector.title">Normal of plane to stored vector</title>
          <para>Three positions in space (if they are not linear dependent)
          define a plane in three-dimensional space.</para>
          <para>Therefore, when exactly three atoms are selected, this Action
          will construct the resulting plane and store its normal vector as a
          geometry object for later reference.</para>
          <programlisting>
  ... --plane-to-vector &quot;planenormal&quot; \
      --reverse 1
          </programlisting>
          <para>where the plane's normal vector can be referenced by 
          &quot;planenormal&quot;. The additional "reverse" option will invert
          the plane's normal vector as this is ambiguous about the direction.</para>
        </section>
        <section xml:id="geometry.position-to.vector">
          <title xml:id="geometry.position-to-vector.title">Atomic position to stored vector</title>
          <para>Storing the position of a singly selected atom as a vector is simply done as follows,</para>
          <programlisting>
  ... --position-to-vector &quot;vector_O1&quot; \
          </programlisting>
          <para>where the vector can be referenced by &quot;vector_O1&quot; 
          from then on.</para>
        </section>
        <section xml:id="geometry.remove-geometry">
          <title xml:id="geometry.remove-geometry.title">Remove a stored vector</title>
          <para>Finally, a stored vector can also be removed.</para>
          <programlisting>
  ... --remove-geometry &quot;vector_O1&quot; \
          </programlisting>
          <para>this removes  the stored &quot;vector_O1&quot;.</para>
        </section>
      </section>
      <section xml:id="randomization">
        <title xml:id="randomization.title">Randomization</title>
        <para>Some operations require randomness as input, e.g. when filling a
        domain with molecules these may be randomly translated and rotated.
        Random values are obtained by a random number generator that consists
        of two parts: engine and distribution. The engine yields a <emphasis role="italic">uniform</emphasis> set
        of random numbers in a specific interval, the distribution modifies
        them, e.g. to become gaussian.</para>
        <para>There are several Actions to modify the specific engine and
        distribution and their parameters. One example usage is that with the
        aforementioned filling of the domain (see below) molecules are rotated randomly.
        If you specify a random number generator that randomly just spills out
        values 0,1,2,3, then the randomness is just the orientation of the
        molecule with respect to a specific axis: x,y,z. (rotation is at most
        360 degrees and 0,1,2,3 act as divisor, hence rotation angle will then be always
        a multiple of 90 degrees).</para>
        <programlisting>
  ... --set-random-number-distribution &quot;uniform_int&quot; \
      --random-number-distribution-parameters &quot;p=1&quot;
 </programlisting>
        <para>This changes the distribution to &quot;uniform_int&quot;, i.e. integer
        numbers that are distributed uniformly.</para>
        <programlisting>
  ... --set-random-number-engine &quot;mt19937&quot; \
      --random-numner-engine-parameters &quot;seed=10&quot;
 </programlisting>
        <para>Specifying the seed allows you to obtain the same sequence of
        random numbers for testing purposes.</para>
        <para>Moreover, actions such as 
        <link linkend="atoms.random-perturbation">random perturbation</link>
        of atoms and <link linkend="filling">filling</link> of molecules into the
        domain use the random number generator.</para>
      </section>
      <section xml:id="atoms">
        <title xml:id="atoms.title">Manipulate atoms</title>
        <para>Here, we explain in detail how to add, remove atoms, change its
        element type, scale the bond in between or measure the bond length or
        angle.</para>
        <section xml:id="atoms.add-atom">
          <title xml:id="atoms.add-atom.title">Adding atoms</title>
          <para>Adding an atom to the domain requires the element of the atom
          and its coordinates as follows,</para>
          <programlisting>
  ... --add-atom O \
      --domain-position &quot;2.,3.,2.35&quot;
   </programlisting>
          <para>where the element is given via its chemical symbol and the
          vector gives the position within the domain</para>
         <para>Note that instead of giving an explicit vector you may also use
        a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
         <para>Finally, if you select a molecule before adding the atom, then
         the atom is added to that particular molecule. Otherwise a new molecule
         is created internally to contain that atom. Atoms always need to be
         associated with a molecule.</para>
        </section>
        <section xml:id="atoms.random-perturbation">
          <title xml:id="atoms.random-perturbation.title">Randomly perturb atoms</title>
          <para>The positions of a set of selected atom(s) can be randomly 
          perturbed by giving a maximum noise level..</para>
          <programlisting>... --random-number-distribution "uniform_01" \
    --random-perturbation 0.1</programlisting>
          <para>This will perturb all atomic positions by adding a vector
          with components chosen randomly from the interval [-level, level].</para>
          <para>Note that the manner these random numbers are picked depends
          on the current random number distribution (and also on the engine),
          see <link linkend='randomization'>Randomization</link>. The default
          one will not give good results, therefore the example uses the 
          uniform_01 distribution</para>
        </section>
        <section xml:id="atoms.remove-atom">
          <title xml:id="atoms.remove-atom.title">Removing atoms</title>
          <para>Removing atom(s) does not need any option and operates on the
          currently selected ones.</para>
          <programlisting>... --remove-atom</programlisting>
        </section>
        <section xml:id="atoms.saturate-atom">
          <title xml:id="atoms.saturate-atom.title">Saturating atoms</title>
          <para>Newly instantiated atoms have no bonds to any other atom. If
          you want to fill up their valence by a slew of hydrogen atoms 
          residing on a sphere around this atom, use this action.</para>
          <programlisting>
  ... --saturate-atoms
   </programlisting>
          <para>A number of hydrogen atoms is added around each selected atom 
          corresponding to the valence of the chemical element. The hydrogen 
          atoms are placed at the same distance to the selected atom which is
          taken from an internal database for the typical hydrogen bond length 
          and approximately with same distance to their nearest neighbor 
          hydrogens. Already present bonds (i.e. the position of neighboring 
          atoms) are taken into account and left intact.</para>
          <programlisting>^M
  ... --saturate-atoms --use-outer-shell 1^M
   </programlisting>
          <para>This will not simply consider the number of unoccupied orbitals
          of the respective element. Instead it will take the outermost shell
          into consideration and use the number of orbitals in total as the
          ideal polyhedra but only taking the number of unoccupied orbitals as
          free nodes, i.e. where to saturate with hydrogens. For example, 
          nitrogen will then fill an tetrahedron (4 orbitals in outer shell)
          where one orbital is already fully occupied and 3 nodes in the 
          tetrahedron remain to fill up with hydrogens.
          Without the outer shell, saturate atoms would simply consider a 
          triangle as the ideal polyhedron and fill its 3 corners.</para>
        </section>
        <section xml:id="atoms.bondify-atom">
          <title xml:id="atoms.bondify-atom.title">Bonding atoms</title>
          <para>This action is to an extent the opposite of 
        <link linkend='atoms.saturate-atom'>saturate-atom</link>. Instead of
          adding hydrogens to saturate an atom with unoccupied valence orbitals
          MoleCuilder looks for other non-hydrogen atoms in the vicinity that
          have bonds with hydrogen atoms. If these non-hydrogen atoms are 
          within suitable bonding distance, the hydrogen bond with the hydrogen
          atom is removed and a bond between the two non-hydrogen atoms is
          added. Hence, while saturate-atom adds more hydrogens, bondify-atom
          will try to remove hydrogens and saturate atom valencies by 
          additional bonds.</para>
          <note>The typical bond distances between the two non-hydrogen atoms
          is taken from bond table, loaded through
        <link linkend='bond.create-adjacency'>bond-table</link>.</note>
          <para>The action is called as follows:
          <programlisting>
  ... --bondify-atoms
   </programlisting>
          and will work on a single, currrently selected atom.
          </para>
        </section>
        <section xml:id="atoms.translate-atom">
          <title xml:id="atoms.translate-atom.title">Translating atoms</title>
          <para>In order to translate the current selected subset of atoms you
have to          specify a translation vector.</para>
          <programlisting>
  ... --translate-atoms &quot;-1,0,0&quot; \
      --periodic 0
   </programlisting>
          <para>This translates all atoms by &quot;-1&quot; along the x axis and does not
          mind the boundary conditions, i.e. it might shift atoms outside of the
          domain.</para>
         <para>Again, note that instead of giving an explicit vector you may
         also use a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="atoms.mirror-atoms">
          <title xml:id="atoms.mirror-atoms.title">Mirroring atoms</title>
          <para>Present (and selected) atoms can be mirrored with respect to
          a certain plane. You have to specify the normal vector of the plane
          and the offset with respect to the origin as follows</para>
          <programlisting>
  ... --mirror-atoms &quot;1,0,0&quot; \
      --plane-offset 10.1 \
      --periodic 0
   </programlisting>
         <para>And of course instead of giving an explicit vector you may also 
         use a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="atoms.translate-to-origin">
          <title xml:id="atoms.translate-to-origin.title">Translating atoms to origin</title>
          <para>The following Action is convenient to place a subset of atoms
          at a known position, the origin, and then translate them to some other
          absolute coordinate. It calculates the average position of the set
          of selected atoms and then translates all atoms by the negative of
          this center, i.e. the center over all selected atoms is afterwards at the origin.</para>
          <programlisting>... --translate-to-origin</programlisting>
          <para>Note that this naturally does not heed the boundary conditions of the simulation domain.</para>
        </section>
        <section xml:id="atoms.change-element">
          <title xml:id="atoms.change-element.title">Changing an atoms element </title>
          <para>You can easily turn lead or silver into gold, by selecting the
          silver atom and calling the change element action.</para>
          <programlisting>... --change-element Au</programlisting>
        </section>
      </section>
      <section xml:id="bond">
        <title xml:id="bond.title">Bond-related manipulation</title>
        <para>Atoms can also be manipulated with respect to the bonds.
        <remark>Note that with bonds we always mean covalent bonds.</remark>      First, we explain how to modify the bond structure itself, then we go
        in the details of using the bond information to change bond distance
        and angles.</para>
        <section xml:id="bond.create-adjacency">
          <title xml:id="bond.create-adjacency.title">Creating a bond graph </title>
          <para>In case you have loaded a configuration file with no bond
          information, e.g. XYZ, it is necessary to create the bond graph.
          This is done by either of two options, based on a heuristic criterion.</para>
          <para>By default it is based on van-der-Waals radii,
          i.e. if we look at two atoms indexed by &quot;a&quot; and &quot;b&quot;</para>
          <equation>
            <title></title>
            <mml:math display="block">
              <mml:mrow>
                <mml:mi>V(a) + V(b) - &tau; &lt;</mml:mi>
                <mml:msub>
                  <mml:mi>R</mml:mi>
                  <mml:mn>ab</mml:mn>
                </mml:msub>
                <mml:mi>&lt; V(a) + V(b) + &tau;</mml:mi>
              </mml:mrow>
            </mml:math>
          </equation>
          where 
          <inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:mi>V(.)</mml:mi>
                </mml:mrow>
              </mml:math>
            </inlineequation> 
          is the lookup table for the radii for a given element and \tau is a threshold value, set to 0.4.
          <para>As a alternative option, you may load a file containing bond table
          information.</para>
          <programlisting>... --bond-table table.dat</programlisting>
          <para>which would parse a file <filename>table.dat</filename> for a
          table giving typical bond distances between elements a and b. These
          are used in the above criterion as 
          <inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:mi>V(a,b)</mml:mi>
                </mml:mrow>
              </mml:math>
            </inlineequation> 
            in place of 
            <inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:mi>V(a) + V(b)</mml:mi>
                </mml:mrow>
              </mml:math>
            </inlineequation>
            .</para>
            <para>In either case,</para>
          <programlisting>... --create-adjacency</programlisting>
          <para> will then create the bond graph based on above criterion.</para>
        </section>
        <section xml:id="bond.destroy-adjacency">
          <title xml:id="bond.destroy-adjacency.title">Destroying the bond graph</title>
          <para>The bond graph can be removed completely (and all bonds along
          with it).</para>
          <programlisting>... --destroy-adjacency</programlisting>
        </section>
        <section xml:id="bond.correct-bonddegree">
          <title xml:id="bond.correct-bonddegree.title">Correcting bond degrees</title>
          <para>Typically, after loading an input file with 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>
          <para>However, in normal use scenarios the action is fast and linear scaling.</para>
        </section>
        <section xml:id="bond.depth-first-search">
          <title xml:id="bond.depth-first-search.title">Analysing a bond graph</title>
          <para>You can perform a depth-first search analysis that reveals
          cycles and other graph-related information.</para>
          <programlisting>... --depth-first-search</programlisting>
          <para>Note that this will only print some information and has no other impact on the state.</para>
        </section>
        <section xml:id="bond.subgraph-dissection">
          <title xml:id="bond.subgraph-dissection.title">Dissecting the molecular system into molecules</title>
          <para>The bond graph information can be used to recognize the
          molecules within the system. It removes the current bond graph (if 
          any bonds are presents) and recreates it. Afterwards it walks it along
          and finds any disconnected subgraphs, associating a molecule with 
          each. Note that this is just structural information and does not 
          change the state of the system.</para>
          <programlisting>... --subgraph-dissection</programlisting>
        </section>
        <section xml:id="bond.update-molecules">
          <title xml:id="bond.update-molecules.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 graph of the molecular system. </para>
          <para>Moreover, Imagine you have just loaded a PDB file
          containing bond information. However, initially all atoms are dumped
          into the same molecule. Before you can start manipulating, you need
          to dissect the system into individual molecules. 
          </para>
          <programlisting>... --update-molecules</programlisting>
        </section>
        <section xml:id="bond.adds-bond">
          <title xml:id="bond.adds-bond.title">Adding a bond manually</title>
          <para>When the automatically created adjacency or bond graph
          contains faulty bonds or lacks some, you can add them manually.
          </para>
          <programlisting>... --add-bonds</programlisting>
          <para>If two atoms are selected, the single bond in between is added, if not
already    present. If more than two atoms are selected, than the
   bond between any pair of these is added.</para>
          <note>
            <para>This is especially useful in conjunction with the
   fragmentation scheme (explained later on). If you want to know the contribution from
   certain fragments whose subgraph is not connected, you can simply
   make the associated subset of atoms connected by selecting all
   bonds and adding the bonds.</para>
          </note>
        </section>
        <section xml:id="bond.remove-bonds">
          <title xml:id="bond.remove-bonds.title">Removing a bond manually </title>
          <para>In much the same way as adding a bond, you can also remove a
          bond.</para>
          <programlisting>... --remove-bonds</programlisting>
          <para>Similarly, if more than two atoms are selected, then all bonds
   found between any pair of these is removed.</para>
        </section>
        <section xml:id="bond.set-bond-degree">
          <title xml:id="bond.set-bond-degree.title">Setting the bond degree manually </title>
          <para>The bond degrees are usually automatically set to fulfill the 
          valency constraints of each bond partner. However, degrees can also be 
          set manually for a set of selected atoms. Note that the degree is set
          to the given value for all bonds in between any pair of atoms within
          the set.</para>
          <programlisting>... --set-bond-degree 2</programlisting>
          <para>Similarly, if more than two atoms are selected, then all bonds
   found between any pair of these are modified.</para>
        </section>
        <section xml:id="bond.save-bonds">
          <title xml:id="bond.save-bonds.title">Saving bond information </title>
          <para>Bond information can be saved to a file in
              <productname>TREMOLO </productname>&apos;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>
          <para>This corresponds to the <emphasis role="bold">bond-file</emphasis> Action.</para>
        </section>
        <section xml:id="fileparsers.bond-file">
          <title xml:id="fileparsers.bond-file.title">Load extra bond information</title>
          <para>The reverse Action of <emphasis role="bold">save-bonds</emphasis> is the following which loads bond information from the file <emphasis role="bold">water.dbond</emphasis>.</para>
          <programlisting>... --bond-file water.dbond</programlisting>
          <para>Note that because of the use of ids the bond file is intimately connected to the associated input file containing the atomic coordinates and thus both should parsed right after another and to the very beginning of any sequence of Actions.</para>
        </section>
        <section xml:id="bond.stretch-bond">
          <title xml:id="bond.stretch-bond.title">Stretching a bond</title>
          <para>Stretching a bond actually refers to translation of the
          associated pair of atoms. However, this action will keep the rest of
          the molecule to which both atoms belong to invariant as well.</para>
          <programlisting>... --stretch-bond 1.2</programlisting>
          <para>This scales the original bond distance to the new bond
          distance 1.2, shifting the right hand side and the left hand side of
          the molecule accordingly.</para>
          <warning>
            <para>this fails with aromatic rings (but you can always
            undo).</para>
          </warning>
          <note>The action will uses typical bond distances, taken from
          <link linkend='bond.create-adjacency'>bond-table</link> to scale
          the bond length if the desired bond length is non-positive.</note>
        </section>
        <section xml:id="bond.change-bond-angle">
          <title xml:id="bond.change-bond-angle.title">Changing a bond angle </title>
          <para>In the same way as stretching a bond, you can change the angle
          in between two bonds. This works if exactly three atoms are selected
          and two pairs are bonded.</para>
          <programlisting>... --change-bond-angle 90</programlisting>
          <para>This will change the angle from its value to 90 degrees by
          translating the two outer atoms of this triangle (the atom connected
          to both other atoms serves as rotation joint).</para>
        </section>
        <section xml:id="bond.evaluate-chemical-space">
          <title xml:id="bond.evaluate-chemical-space.title">Evaluate the Chemical Space</title>
          <para>Imagine that we are given a graph consisting of nodes and edges.
          As we have been speaking extensively of the adjacency graph before, then
          any graph where nodes are assigned a chemical element and edges are given
          a degree, effectively represent a molecule of covalently bonded atoms.</para>
          <para>This is the notion behind constructing parts of the chemical space that
          encompasses all molecules that either already exist or could be devised,
          i.e. that are stable.</para>
          <para>One method of creating points in this chemical space, i.e. stable
          molecules, is presented in the article by Hamaekers et al. 2017, where
          they follow the well-known <emphasis>octet rule</emphasis>.</para>
          <para>In this action essentially the same method is implemented. Given
          an arbitrary graph, encoded as Graph6 string, such as produced by
          the <link xlink:href="http://users.cecs.anu.edu.au/~bdm/nauty/">nauty</link> 
          toolset (Brendan McKay and Adolfo Piperno), and a set of chemical
          elements, the action creates every possible molecule using the graph
          and the given elements for each of its nodes, changing bond degrees
          as long as to fulfil the octet rule.</para>
          <programlisting>--evaluate-chemical-space \
  --graph6 "B`" --elements C C</programlisting>
        <para>The graph6 string "B`" represents the simplest graph consisting
        of just two nodes, connected by a single edge. Designating each node
        to be a carbon atom, this action will then produce the carbonhydrates
        C2H6, C2H4, and C2H2.</para>
        <para>At the moment, the molecules are not created but their signatures
        are used in looking up the fragments in the internal homology container,
        see <link linkend="fragmentation">Fragmentation </link> and 
        <link linkend="homology">Homologies</link>. Instead of creating atomic
        coordinates, approximate energies are given that allow to estimate
        whether the molecule candidate is stable or not. Note that this requires
        that a suitable homology container file has been loaded first that contains
        all necessary fragments. If multiple entries and thus multiple energies
        are present for a given fragment, then the lowest energy is taken for the
        summation.</para>
        <note>The graph is automatically saturated with hydrogens in obeying
        the octet rule, i.e. hydrogen should not be given in the list of elements.</note>
        <para>Using nauty that produces all possible graphs with a fixed number
        of nodes, these can be simply fed into <productname>MoleCuilder </productname>
        to produce all associated molecules.</para>
        </section>
        <section xml:id="bond.print-selected-atoms-as-graphstring">
          <title xml:id="bond.print-selected-atoms-as-graphstring.title">Print selected atoms as graph6 string</title>
          <para>In the light of  the last section it would also be useful to obtain
          the graph6 representation of a present set of atoms, e.g., those belonging
          to a molecule. The following command will print the graph6 string to the
          console for all currently present atoms.
          <programlisting>--select-all-atoms \
  --print-selected-atoms-as-graphstring</programlisting>
          </para>
        </section>
      </section>
      <section xml:id="molecule">
        <title xml:id="molecule.title">Manipulate molecules</title>
        <para>Molecules are agglomerations of atoms that are (covalently) bonded. Hence,
        the Actions working on molecules differ from those working on atoms.
        Joining two molecules can only be accomplished by adding a bond in
        between, and in the reverse fashion splitting a molecule by removing
some or even        all bonds in between. The Actions below mostly deal with copying
        molecules. Removing of molecules is done via selecting the molecule&apos;s
        atoms and removing them, which removes the atoms as well.</para>
        <note>
          <para>Initially when you load a file via the input action all atoms
          are placed in a single molecule despite any present bond
          information, see <link linkend="fragmentation">Dissecting the molecular system into molecules</link></para>
        </note>
        <section xml:id="molecule.copy">
          <title xml:id="molecule.copy.title">Copy molecules</title>
          <para>A basic operation is to duplicate a molecule. This works on a
          single, currently selected molecule. Afterwards, we elaborate on a
          more complex manner of copying, filling a specific shape with
          molecules.</para>
          <programlisting>
  ... --copy-molecule \
      --position &quot;10,10,10&quot;
   </programlisting>
          <para>This action copies the selected molecule and inserts it at the
          position (10,10,10) in the domain with respect to the molecule&apos;s
          center. In effect, it copies all the atoms of the original molecule
          and adds new bonds in between these copied atoms such that their
          bond subgraphs are identical.</para>
         <para>Here, instead of giving an explicit vector you may also use
        a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="molecule.change-molname">
          <title xml:id="molecule.change-molname.title">Change a molecules name</title>
          <para>You can change the name of a molecule which is important for
          selection.</para>
          <programlisting>... -change-molname &quot;test</programlisting>
          <para>This will change the name of the (only) selected molecule to
          &quot;test&quot;.</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 new molecules to
          &quot;test&quot;.</para>
          <note>
            <para>Note that a molecule loaded from file gets the filename
            (without suffix) as its name.</para>
          </note>
        </section>
        <section xml:id="molecule.remove-molecule">
          <title xml:id="molecule.remove-molecule.title">Remove molecules </title>
          <para>This removes one or multiple selected molecules.</para>
          <programlisting>... -remove-molecule</programlisting>
          <para>This essentially just removes all of the molecules&apos; atoms
          which in turn also causes the removal of the molecule.</para>
        </section>
        <section xml:id="molecule.translate-molecules">
          <title xml:id="molecule.translate-molecules.title">Translate molecules </title>
          <para>This translates one or multiple selected molecules by a
   specific offset..</para>
          <programlisting>... -translate-molecules</programlisting>
          <para>As before, this is actually just an operation on all of the 
          molecule&apos;s atoms, namely translating them.</para>
         <para>Same as with <link linkend='atoms.translate-atom'>translate-atoms</link>
         instead of giving an explicit vector you may also use a vector stored 
         as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="molecule.rotate-around-bond">
          <title xml:id="molecule.rotate-around-bond.title">Rotate around bond </title>
          <para>This rotates parts of a molecule around a given bond, i.e. the
          bond vector becomes the rotation axis but only atoms on the side of
          second atom get rotated. This naturally does not work for bonds in a
          cycle.</para>
          <programlisting>
  ... --rotate-around-bond &quot;90&quot; \
      --bond-side 0
   </programlisting>
        </section>
        <section xml:id="molecule.rotate-around-self">
          <title xml:id="molecule.rotate-around-self.title">Rotate around self </title>
          <para>You can rotate a molecule around its own axis.</para>
          <programlisting>
  ... --rotate-around-self &quot;90&quot; \
      --axis &quot;0,0,1&quot;
   </programlisting>
          <para>This rotates the molecule around the z axis by 90 degrees as
          if the origin were at its wn center of origin.</para>
        </section>
        <section xml:id="molecule.rotate-around-origin">
          <title xml:id="molecule.rotate-around-origin.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 &quot;0,0,1&quot;\
   </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, where
          for the position you may also use a stored vector, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="molecule.rotate-to-principal-axis-system">
          <title xml:id="molecule.rotate-to-principal-axis-system.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
          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 &quot;0,0,1&quot;
          </programlisting>
          <para>This rotates the molecule in such a manner that the ellipsoids
          largest axis is aligned with the z axis. <remark>Note that 
          &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
         <para>Again instead of giving the coordinates explicitly you may also 
         use a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="molecule.verlet-integration">
          <title xml:id="molecule.verlet-integration.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 an 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>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:mi>
                    <mml:msub>
                      <mml:mi>&Delta;</mml:mi>
                      <mml:mn>t</mml:mn>
                    </mml:msub>
                    <mml:mi>= V(a) + V(b)</mml:mi>
                  </mml:mi>
                </mml:mrow>
              </mml:math>
            </inlineequation>
            and correcting forces and velocities such that
          the sum over all atoms is zero.</para>
          <note>Although it may be useful in rare cases to use this Action 
          directly, most of the time it is far more convenient to use the
          MakroAction <link linkend="dynamics.molecular-dynamics">molecular-dynamics</link>
          which incorporates also the force calculation and allows for time
          integration over more than just a single time step.</note>
        </section>
        <section xml:id="molecule.force-annealing">
          <title xml:id="molecule.force-annealing.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, loaded 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>
          <note>Same as before, although in rare useful, we refer to the
          MakroAction <link linkend="dynamics.optimize-structure">optimize-structure</link>
          which incorporates also the force calculation and allows for 
          structure optimization over more than just a single step.</note>
        </section>
        <section xml:id="molecule.linear-interpolation-of-trajectories">
          <title xml:id="molecule.linear-interpolation-of-trajectories.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 identity 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 xml:id="domain">
        <title xml:id="domain.title">Manipulate domain</title>
        <para>Here, we elaborate on how to duplicate all the atoms inside the
        domain, how to 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 xml:id="domain.change-box">
          <title xml:id="domain.change-box.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 &quot;20,0,20,0,0,20&quot;</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 triangle
          matrix. Here, we change the box to a cuboid of equal edge length of
          20.
          <warning>
            <para>In case of the python interface an upper triangle matrix is given. Hence, the above would read &quot;20,0,0,20,0,20&quot;.</para>
          </warning></para>
        </section>
        <section xml:id="domain.bound-in-box">
          <title xml:id="domain.bound-in-box.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 xml:id="domain.center-in-box">
          <title xml:id="domain.center-in-box.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 &quot;20,0,20,0,0,20&quot;</programlisting>
        </section>
        <section xml:id="domain.center-edge">
          <title xml:id="domain.center-edge.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 xml:id="domain.add-empty-boundary">
          <title xml:id="domain.add-empty-boundary.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, i.e. left and right, top and bottom, front and back.</para>
          <programlisting>... --add-empty-boundary &quot;5,5,5&quot;</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 xml:id="domain.scale-box">
          <title xml:id="domain.scale-box.title">Scaling the box</title>
          <para>You can enlarge the domain by simple scaling factors.</para>
          <programlisting>... --scale-box &quot;1,1,2.5&quot;</programlisting>
          <para>Here, the domain is stretched in the z direction by a factor
          of 2.5. Also, all positions are scaled by the same factor.</para>
        </section>
        <section xml:id="domain.repeat-box">
          <title xml:id="domain.repeat-box.title">Repeating the box</title>
          <para>Under periodic boundary conditions often only the minimal
          periodic cell is stored. E.g. for a crystallic system this minimal cell is all that&apos;s needed to completely specify a larger body. 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 &quot;1,2,2&quot;</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 xml:id="domain.set-boundary-conditions">
          <title xml:id="domain.set-boundary-conditions.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 &quot;Wrap Wrap Wrap&quot;</programlisting>
          <para>Note that boundary conditions are not enforced unless explicitly requested, e.g. by the <emphasis role="bold">bound-in-box</emphasis> action</para>
        </section>
      </section>
      <section xml:id="filling">
        <title xml:id="filling.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 of a molecule (see <emphasis role="bold">copy-molecule</emphasis>) and for this we need several 
          ingredients.</para>
        <para>First, we need to specify the part of the domain. This is done
          via a shape. We have already learned how to create and select
          shapes. The currently selected shape will serve as the fill-in
          region.</para>
        <para>Then, there 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. The latter is closed connected to the respective shape selected. Molecules will then be copied and translated points when they
          &quot;fit&quot;. Note that not only primitive shape can be used for filling in molecules inside their volume or on their surface but also any kind of combined shape. </para>
        <remark>Note however that not all combinations may already be fully working.</remark>
        <para>The filler procedure checks each fill-in point whether there
          is enough space for the set of atoms. To this end, we require a cluster
          instead of a molecule. A cluster is more general than a molecule as it is not restricted to a connected subgraph with respect to the bond graph. A cluster is just a general agglomeration of atoms
          combined with a bounding box that contains all of them and serves as
          its minimal volume. I.e. we need such a cluster. For this a number of
          atoms have to be specified, the minimum bounding box is generated
          automatically by which it is checked whether sufficient space is available at the fill-in point.</para>
        <para>On top of that, molecules can be selected whose volume is
          additionally excluded from the filling region.</para>
        <section xml:id="filling.fill-regular-grid">
          <title xml:id="filling.fill-regular-grid.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>
          <programlisting>
  ... --fill-regular-grid \
      --mesh-size &quot;5,5,5&quot; \
      --mesh-offset &quot;.5,.5,.5&quot; \
      --DoRotate 1 \
      --min-distance 1. \
      --random-atom-displacement 0.05 \
      --random-molecule-displacement 0.4 \
      --tesselation-radius 2.5
   </programlisting>
          <para>This generates a cardinal grid of 5x5x5 fill-in points within the
          sphere that are offset such as to lie centered within the sphere, defined by a relative offset per axis in [0,1]. Hence, with an offset of &quot;0&quot; we have the points left-aligned, with &quot;0.5&quot; centered, and with &quot;1&quot; right-aligned. Additionally, each molecule is rotated
          by a random rotation matrix, each atom is translated randomly by at
          most 0.05, each molecule&apos;s center similarly but at most by 0.4. The selected
          molecules&apos; volume is obtained by tesselating their surface and
          excluding every fill-in point whose distance to this surface does
          not exceed 1. We refer to our comments in 
          <link linkend="randomization">Randomization</link>for details on 
          changing the randomness and obtaining some extra flexibility thereby.</para>
        </section>
        <section xml:id="filling.fill-volume">
          <title xml:id="filling.fill-volume.title">Fill a shape&apos;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>The specified option all have the same function as before. Here, we specified to generate 12 points inside the volume of the selected shape.</para>
        </section>
        <section xml:id="filling.fill-surface">
          <title xml:id="filling.fill-surface.title">Fill a shape&apos;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 has to be aligned
    with the surface in a specific manner. The idea is to have the molecules point away from the surface in a similar way. This is done by aligning an axis with the surface normal. 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.
This is the same syntax as with <emphasis role="bold">rotate-around-self</emphasis>.   </para>
          <para>The call below will 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 &quot;0,0,1&quot;
   </programlisting>
         <para>Note that instead of giving an explicit axis you may also use
        a vector stored as a geometry object, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="filling.suspend-in-molecule">
          <title xml:id="filling.suspend-in-molecule.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 xml:id="filling.fill-molecule">
          <title xml:id="filling.fill-molecule.title">Fill in molecule</title>
          <para>This action will be soon be removed.</para>
          <programlisting>
  ... --fill-molecule
       </programlisting>
        </section>
        <section xml:id="filling.fill-void">
          <title xml:id="filling.fill-void.title">Fill void with molecule </title>
          <para>This action will be soon be removed.</para>
          <programlisting>
  ... --fill-void
       </programlisting>
        </section>
      </section>
      <section xml:id="analysis">
        <title xml:id="analysis.title">Analysis</title>
        <para>If atoms are manipulated and molecules are filled in, it is also a good idea to check on the manner of the filling. This can be done by for example looking at the pair correlation or angular correlation function. This may be useful in checking what is the mean distance between water molecules and how they are aligned with respect to each other.</para>
        <section xml:id="analysis.pair-correlation">
          <title xml:id="analysis.pair-correlation.title">Pair Correlation </title>
          <para>For two given elements Pair correlation checks on the typical 
          distance in which 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. These data files can be used for plotting the distribution right away in order to check on the correlation between the elements.</para>
          <para>The action may also be called with just a single element in the
          option <emphasis>elements</emphasis>. This will then trigger a pair
          correlation between all atoms of this element and the set of 
          currently selected atoms.</para>
        </section>
        <section xml:id="analysis.dipole-correlation">
          <title xml:id="analysis.dipole-correlation.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>
          <para>Hence, instead of calculating a function of the distance in [0,infinity), it calculates the angular histogram in [0,2pi).</para>
        </section>
        <section xml:id="analysis.dipole-angular-correlation">
          <title xml:id="analysis.dipole-angular-correlation.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 xml:id="analysis.point-correlation">
          <title xml:id="analysis.point-correlation.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 &quot;0,0,0&quot; \
    --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>
         <para>Naturally, instead of giving explicit coordinates you may also 
         use a vector stored as a geometry object for position, see section
        <link linkend='geometry'>Geometry</link>.</para>
        </section>
        <section xml:id="analysis.surface-correlation">
          <title xml:id="analysis.surface-correlation.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 xml:id="analysis.molecular-volume">
          <title xml:id="analysis.molecular-volume.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 of its surface. Note that this surface is minimal in 
          that respect that each node of the tesselation consists of an atom 
          of the molecule.</para>
          <programlisting>... --molecular-volume</programlisting>
          <note>The rolling sphere used in the tesselation algorithm has a 
          default diameter of 10 angström.</note>
        </section>
        <section xml:id="analysis.average-molecule-force">
          <title xml:id="analysis.average-molecule-forcetitle">Average force acting on a molecule</title>
          <para>This sums up all the forces of each atom of a currently 
          selected molecule and returns the average force vector. This should
          give you the general direction of acceleration of the molecule.
          </para>
          <programlisting>... --molecular-volume</programlisting>
        </section>
      </section>
      <section xml:id="fragmentation">
        <title xml:id="fragmentation.title">Fragmentation</title>
        <para>Fragmentation refers to a so-called linear-scaling method called
        &quot;Bond-Order diSSection in an ANOVA-like fashion&quot; (BOSSANOVA),
        developed by <personname>Frederik Heber</personname>. In this section
        we briefly explain what the method does and how the associated actions
        work.</para>
        <para>The central idea behind the BOSSANOVA scheme is to fragment the
        graph of the molecular system into connected subgraphs of a certain
        number of vertices, namely a fixed number of atoms. To give an example, loading a ethane atom
        with the chemical formula C2H6, fragmenting the molecule up to order 1
        means creating two fragments, both methane-like from either carbon
        atom including surrounding hydrogen atoms. Fragmenting up to order 2
        would return both the methane fragments and additionally the full
        ethane molecule as it resembles a fragment of order 2, namely
        containing two (non-hydrogen) atoms.</para>
        <para>The reason for doing this is that usual ab-initio calculations
        of molecular systems via methods such as Density Functional Theory or
        Hartree-Fock scale at least as 
        <inlineequation>
            <mml:math display="inline">
              <mml:mrow>
                <mml:mi>O(</mml:mi>
                <mml:msup>
                  <mml:mi>M</mml:mi>
                  <mml:mn>3</mml:mn>
                </mml:msup>
                <mml:mi>)</mml:mi>
              </mml:mrow>
            </mml:math>
          </inlineequation>
          with the number of atoms 
          <inlineequation>
            <mml:math display="inline">
              <mml:mrow>
                <mml:mi>M</mml:mi>
              </mml:mrow>
            </mml:math>
          </inlineequation>
          . In general, this cost is prohibitive for calculating ground state energies and forces (required for molecular dynamics simulations) for larger molecules such as bio proteins. By fragmenting the molecular system and looking at fragments of fixed size, calculating the ground state energy of a
        number of fragment molecules becomes a linear scaling operation with the number of atoms. In the doctoral thesis of Frederik
        Heber, it is explained why this is a sensible ansatz mathematically
        and shown that it delivers a very good accuracy if electrons (and
        hence interactions) are in general localized.</para>
        <para>Long-range interactions (e.g. Coulomb or van-der-Waals interactions) are artificially truncated, however,
        with this fragmentation ansatz. It can be obtained in a perturbation manner
        by sampling the resulting electronic and nuclei charge density on a
        grid, summing over all fragments, and solving the associated Poisson
        equation. Such a calculation is implemented via the solver
        <productname>vmg</productname> by Julian Iseringhausen that is
        contained in the <link xlink:href="http://www.scafacos.org/">
            <productname>ScaFaCoS</productname>
          </link>. This enhancement is currently implemented via another program package named <productname>JobMarket</productname> that is at the moment not available publicly (contact the author Frederik Heber if interested).</para>
        <para>Note that we treat hydrogen special (but can be switched off) as
        fragments are calculated as closed shell (total spin equals zero).
        Also, we use hydrogen to saturate any dangling bonds that occur as
        bonds are cut when fragmenting a molecule (this, too, can be switched
        off).</para>
        <para>Eventually, the goal of fragmentation is to yield an energy and gradients with respect to nuclear positions per atom for each fragment. These forces can be used for molecular dynamics simulations, for structure optimization or for fitting empirical potential functions. The underlying operation consists of three parts. The first part is always the act of splitting up the selected atoms in the molecular system into fragments. The energies of the fragments are calculated in the second part via an external ab-initio solver, where the actual solver used is arbitrary and to some extent up to the user (<productname>MPQC </productname> is used by default). The second part of the fragmentation is to combine fragment results to energy and gradients for the total molecular system.</para>
        <para>Note that the molecular system itself is not touched in any way by this fragmentation. </para>
        <section xml:id="fragmentation.fragment-molecule">
          <title xml:id="fragmentation.fragment-molecule.title">Fragmenting a molecular system</title>
          <para>For the current selection of atoms, all fragments consisting
          of these (sub)set of atoms are created in the following
          manner.</para>
          <programlisting>
  ... --fragment-molecule &quot;BondFragment&quot; \
      --DoCyclesFull 1 \
      --distance 3. \
      --order 3 \
      --grid-level 5 \
      --output-types xyz mpqc
   </programlisting>
          <para>We go through each of the options one after the other. During
          fragmentation some files are created storing state information, i.e.
          the vertex/atom indices per fragment and so on. These files are used when re-performing the fragmentation on a slightly modified state (e.g. after a time integration step with essentially the same bond graph) for faster operation. These files all need
          a common prefix, here &quot;BondFragment&quot;. Then, we specify that cycles
          should be treated fully. This compensates for electrons in aromatic
          rings being delocalized over the ring. If cycles in the graph,
          originating from aromatic rings, are always calculated fully, i.e.
          the whole ring becomes a fragment, we partially overcome these
          issues. This does however not work indefinitely and accuracy of the
          approximation is limited (
          <inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:mi>&gt;</mml:mi>
                  <mml:msup>
                    <mml:mi>10</mml:mi>
                    <mml:mn>-4</mml:mn>
                  </mml:msup>
                </mml:mrow>
              </mml:math>
            </inlineequation>) in systems with many interconnected aromatic
          rings, such as graphene. Next, we give a distance cutoff of 3 angstroem used
          in bond graph creation. Then, we specify the maximum order, i.e. the
          maximum number of (non-hydrogen) atoms per fragment, here 3. The
          higher this number the more expensive the calculation becomes
          (because substantially more fragments are created) but also the more
          accurate. The grid level refers to the part where long-range Coulomb
          interactions are calculated. This is done via solving the associated
          Poisson equation with a multigrid solver -- however, this requires the <productname>JobMarket</productname> package. As input the solver
          requires the density which is sampled on a cartesian grid whose
          resolution these parameter defines (<inlineequation>
              <mml:math display="inline">
                <mml:mrow>
                  <mml:msup>
                    <mml:mi>2</mml:mi>
                    <mml:mn>level</mml:mn>
                  </mml:msup>
                </mml:mrow>
              </mml:math>
            </inlineequation>). And finally, we give the output file formats,
          i.e. which file formats are used for writing each fragment
          configuration (prefix is &quot;BondFragment&quot;, remember?). Here, we use
          XYZ (mainly for checking the configurations visually) and MPQC,
          which is a very robust Hartree-Fock solver. We refer to the
          discussion of the <link linkend="fileparsers">Parsers</link>  
          on how to change the parameters of the ab-initio calculation. That is to the extent implemented in Molecuilder the created configuration files for the specific solver are manipulated with the options also manipulating the state file written on program exit.</para>
          <para>After having written all fragment configuration files, you
          need to calculate each fragment, grab the resulting energy (and
          force vectors) and place them into a result file manually. This at
          least is necessary if you have specified output-types above. If not,
          the fragments are not written to file but stored internally. Read
          on.</para>
          <para>All created fragments, i.e. their id sets, are stored in an
          internal structure that associates each atom with all fragments it
          is contained in. This AtomFragments container structure can be parsed
          and stored, see <link linkend="atomfragments">AtomFragments</link>.
          They are used e.g. for fitting partial charges. There, a selection of
          atoms is used to fit partial charges to all fragments (and the charge
          grids obtained from long-range calculations, see <link linkend="fragmentation.fragment-automation">FragmentAutomation</link>,
          and the container is needed to know all fragments.
          <note>This structure is cleared by this action and created fragment
          information is inserted afterwards, i.e. it contains only the
          associations from the current fragmentation.</note>
          </para>
        </section>
        <section xml:id="fragmentation.fragment-automation">
          <title xml:id="fragmentation.fragment-automation.title">Calculating fragment energies automatically</title>
          <para>Another way of doing this is enabled if you have
the           <productname>JobMarket</productname> package. Initially, the package was required but now it is only recommended as then calculations can be performed in parallel or arbitrarily many cores (and also the long-range calculation are only available then). JobMarket implements a
          client/server ansatz, i.e. two (or more) independent programs are
          running (even on another computer but connected via an IP network),
          namely a server and at least one client. The server receives
          fragment configurations from MoleCuilder and assigns these to a
          client who is not busy. The client launches an executable that is
          specified in the work package he is assigned and gathers after
          calculation a number of values, likewise specified in the package.
          The results are gathered together by the server and can be requested
          from MoleCuilder once they are done. This essentially describes what
          is happening during the execution of this action.</para>
          <para>Stored fragment jobs can also be parsed again, i.e. reversing
          the effect of having output-types specified in <link linkend="fragmentation.fragment-molecule">Fragmenting a molecule </link>.</para>
          <programlisting>
  ... --parse-fragment-jobs \
      --fragment-jobs &quot;BondFragment00.in&quot; &quot;BondFragment01.in&quot; \
      --fragment-path &quot;./&quot; \
      --grid-level 5
   </programlisting>
          <para>Here, we have specified two files, namely
          <filename>BondFragment00.in</filename> and
          <filename>BondFragment01.in</filename>, to be parsed from the path
          &quot;./&quot;, i.e. the current directory. Also, we have specified to sample
          the electronic charge density obtained from the calculated ground
          state energy solution with a resolution of 5 (see fragment molecule
          and also below).</para>
          <para>This allows for automated and parallel calculation of all
          fragment energies and forces directly within MoleCuilder. The
          FragmentationAutomation action takes the fragment configurations
          from an internal storage wherein they are placed if in
          FragmentMolecule no output-types have been specified.</para>
          <programlisting>
  ... --fragment-automation \
      --fragment-executable mpqc \
      --DoLongrange 1 \
      --DoValenceOnly 1 \
      --grid-level 5 \
      --interpolation-degree 3 \
      --near-field-cells 4 \
      --server-address 127.0.0.1 \
      --server-port 1025
   </programlisting>
          <para>Again, we go through each of the action&apos;s options step by
          step.</para>
          <para>The executable is required if you do not have a patched
          version of <productname>MPQC</productname> that may directly act as
          a client to JobMarket&apos;s server.</para>
          <note>
            <para>Long-calculations are only possible with a client that knows
            how to handle VMG jobs. If you encounter failures, then it is most
            likely that you do not have a suitable client.</para>
          </note>
          <para>In the next line, we have all options related to calculation
          of long-range interactions. We only sample valence charges on the
          grid, i.e. not core electrons and the nuclei charges are reduced
          suitably. This avoids problems with sampling highly localized
          charges on the grid and is in general recommended. Next, there
          follow parameters for the multi grid solver, namely the resolution
          of the grid, see under fragmenting the molecule, the interpolation
          degree and the number of near field cells. A grid level of 6 is
          recommended but costly in terms of memory, the other values are at
          their recommend values.</para>
          <para>In the last line, parameters are given on how to access the
          JobMarket server, namely it address and its port. If the JobMarket 
          package is not available, then these option values cannot be given. 
          Instead the solver is called internally on the same machine and one 
          fragment energy is calculated after the other.</para>
          <note>The structure storing the fragment results internally is 
          cleared prior to this action and calculated fragment results
          is inserted afterwards, i.e. it contains only the
          calculations from the current run.</note>
          <note>All calculated results may be placed in a result file for
          later parsing, see
          <link linkend="fragmentation.save-fragment-results">save fragment results</link>
          .</note>
        </section>
        <section xml:id="fragmentation.clear-fragment-state">
          <title xml:id="fragmentation.clear-fragment-state.title"> Clear fragmentation state</title>
          <para>MoleCuilder keeps an internal state about the fragmentation 
          process in order to make calculations more efficient.</para>
          <para>This state contains for example the current bond order used
          at a "site", namely an atom. When the same molecule is fragmented
          again, then certain results can be reused or simply improved upon.</para>
          <para>However, if the molecule has changed, e.g., because the element
          of an atom was modified which changes saturation and invalidates this
          caching of results, then this state needs to be reset manually.</para>
          <para>This is done by calling the action by</para>
          <programlisting>
  ... --clear-fragment-state \
   </programlisting>
          <note>This action is at the moment irreversible, i.e. it cannot be
          undone.</note>
        </section>
        <section xml:id="fragmentation.analyse-fragment-results">
          <title xml:id="fragmentation.analyse-fragment-results.title"> Analyse fragment results</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>
          <programlisting>
  ... --analyse-fragment-results \
      --fragment-prefix &quot;BondFragment&quot; \
      --store-grids 1
   </programlisting>
          <para>The purpose of the prefix should already be known to you. The
          last option states that the sampled charge densities and the
          calculated potential from the long-range calculations should be
          stored with the summed up energies and forces. Note that this makes
          the resulting files substantially larger (Hundreds of megabyte or
          even gigabytes as currently the densities are stored on the full cartesian grid). Fragment energies and forces are stored in
          so-called internal homology containers. These are explained in the
          next section.</para>
          <para>Note that this action sets the force vector if these have been
          calculated for the fragment. Hence, a 
          <link linkend="molecule.verlet-integration">verlet integration</link>
          is possible afterwards.</para>
          <note>If not obtained by 
          <link linkend="fragmentation.fragment-automation">fragment automation</link>
          then fragment results need to be parsed from file, see
          <link linkend="fragmentation.parse-fragment-results">parse fragment results</link>
          .</note>
        </section>
        <section xml:id="fragmentation.store-saturated-fragment">
          <title xml:id="fragmentation.store-saturated-fragment.title">Store a saturated fragment</title>
          <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.</para>
          <para>This can work two ways: Either the saturated fragment is 
          written to file. If not "output-types" is given, then the fragment
          will instead be written to the FragmentQueue. In other words, its
          energy is calculated when <link linkend="fragmentation.fragment-automation">fragment automation</link> is used.</para>
          <programlisting>
  ... --store-saturated-fragment \
      --DoSaturate 1 \
      --output-types xyz
          </programlisting>
          <para>Alternatively, use the following to store in fragment job 
          queue.</para>
          <programlisting>
  ... --store-saturated-fragment \
      --DoSaturate 1 \
      --grid-level 6
      --max_meshwidth 0.3
       </programlisting>
        </section>
        <section xml:id="fragmentation.parse-fragment-jobs">
          <title xml:id="fragmentation.parse-fragment-jobs.title">Parse fragment jobs from files</title>
          <para>The fragment jobs that are created by
          <link linkend="fragmentation.fragment-molecule">fragment molecule</link>
          may also be placed in a file for later retrieval. See the details of 
          this action on how to create one file per job.</para>
          <para>Later, for parsing these job files, we need to use the parse 
          fragment jobs action as follows:</para>
          <programlisting>
  ... --parse-fragment-jobs \
      --fragment-jobs &quot;BondFragment00.in&quot; &quot;BondFragment01.in&quot; \
      --fragment-path &quot;./&quot;
   </programlisting>
        <para>Here, we give a list of files by the first option and the second
        option gives an optional path where all these files are stored.</para>
        </section>
        <section xml:id="fragmentation.parse-fragment-results">
          <title xml:id="fragmentation.parse-fragment-results.title">Parse calculated fragment results from file</title>
          <para>Fragment results can either be obtained directly from 
          solving the associated electronic structure problem for each
          of the fragment jobs. Or if that has been done at some earlier
          stage and results have been written to a file, see
          <link linkend="fragmentation.save-fragment-results">save fragment results</link>
          , then we may also parse these results.</para>
          <programlisting>
  ... --parse-fragment-results &quot;results.dat&quot;
   </programlisting>
        </section>
        <section xml:id="fragmentation.save-fragment-results">
          <title xml:id="fragmentation.save-fragment-results.title">Save calculated fragment results to file</title>
          <para>Calculated fragment results may be stored to a single file
          for later analysis as follows:</para>
          <programlisting>
  ... --save-fragment-results &quot;results.dat&quot;
   </programlisting>
        <note>Beware though that files from long-range calculations may be
        very large and are stored quite inefficiently at the moment.</note>
        </section>
      </section>
      <section xml:id="homology">
        <title xml:id="homology.title">Homologies</title>
        <para>After a fragmentation procedure has been performed fully, what
        to do with the results? The forces can be used for time integration and structure optimization but what about
        the energies? The energy value is basically the function evaluation of
        the Born-Oppenheimer surface of the molecular system. For molecular dynamics simulations
        continuous ab-initio calculations to evaluate the Born-Oppenheimer
        surface, especially the gradient at the current position of the molecular system&apos;s configuration, is not feasible. Instead usually empirical potential functions
        are fitted as to resemble the Born-Oppenheimer surface to a sufficient
        degree.</para>
        <para>One frequently employed method is the many-body expansion of said surface
        which is basically nothing else than the fragmentation ansatz described
        above. Potential functions resemble a specific term in this many-body
        expansion. These are discussed in the next section.</para>
        <para>For each of these terms all homologous fragments (i.e. having
        the same atoms with respect to the present elements and bonded in the
        same way), differing only in the coordinate of each atom, are just a
        sampling or a function evaluation of this term of the many-body
        expansion with respect to varying nuclei coordinates. Hence, it is
        appropriate to use these function evaluations in a non-linear
        regression procedure. That is, we want to tune the parameters of the
        empirical potential function in such a way as to most closely obtain
        the same function evaluation as the ab-initio calculation did using the
        same nuclear coordinates. Usually, this is done in a least-square
        sense, minimising the euclidean norm.</para>
        <para>Homologies -- in the sense used here -- are then nothing else but containers for a specific
        type of fragment of all the different, calculated configurations (i.e.
        varying nuclear coordinates of the same fragment, i.e. same atoms with identical bonding).</para>
        <para>Homologies are created inside MoleCuilder from fragment calculations
        by using the action 
        <programlisting>... --analyse-fragment-results</programlisting>.
        This computes the energy of the molecule from the fragments and also the
        fragment energies. These are put into the internal homology container.</para>
        <para>Now, we explain the actions that parse and store those
        homologies.</para>
        <programlisting>... --parse-homologies homologies.dat</programlisting>
        <para>This parses the all homologies contained in the file
        <filename>homologies.dat</filename> and <emphasis role="italic">appends</emphasis> them to the homology
        container. It will also print all found homology graphs and the range
        of energies calculated for them if the <link linkend="various.verbose">verbosity</link>
        is suitably set.</para>
        <programlisting>... --save-homologies homologies.dat</programlisting>
        <para>Complementary, this stores the current contents of the homology
        container, <emphasis role="italic">overwriting</emphasis> the file
        <filename>homologies.dat</filename>.</para>
        <programlisting>... --clear-homologies</programlisting>
        <para>Finally, this clears the current contents of the homology
        container.</para>
      </section>
      <section xml:id="homology.evaluate-stability">
         <title xml:id="homology.evaluate-stability.title">Evaluate Stability</title>
         <para>The homologies can be used to quickly get an approximation on
         the ground state energy of a molecule.
         <warning>This does not accurately take the current geometry into account.</warning>
         In other words, it will produce the equilibrium energy for the given
         molecule.
         Using this, there is an action that evaluates the stability of a molecule
         by removing each bond, saturating the ends and comparing the ground
         state energy of the two products to the educt plus the ground state
         energy of as many hydrogen molecules to match the cut bond's degree.
         <programlisting>... --evaluate-stability output.csv</programlisting>
         This writes a table of educt and product names along with their summed
         energies. The comparison between educt and product energy in each row
         yields whether this molecule is overall stable.
         <note>Be aware that this calculation is based on saturation, i.e. hydrogens
         are added to saturate dangling bonds. These additional atoms need to
         be compensated and for this reason there is an additional educt, a
         number of hydrogen molecules.</note>
         </para>
      </section>
      <section xml:id="atomfragments">
        <title xml:id="atomfragments.title">AtomFragments</title>
        <para>Similarly, to <link linkend="homology">Homologies</link> also
        the associations between atoms and the respective fragments they take
        part in can be stored to a file and parse again at a later time.</para>
       <programlisting>... --parse-atom-fragments atomfragments.dat</programlisting>
        <para>This parses the all atom fragment associattions contained in the file
        <filename>atomfragments.dat</filename> and <emphasis role="italic">appends</emphasis> 
        them to the atom fragments associations container.</para>
        <programlisting>... --save-atom-fragments atomfragments.dat</programlisting>
        <para>Complementary, this stores the current contents of the atom fragments 
        associations container, <emphasis role="italic">overwriting</emphasis> the file
        <filename>atomfragments.dat</filename>.</para>
      </section>
      <section xml:id="potentials">
        <title xml:id="potentials.title">Potentials</title>
        <para>In much the same manner as we asked before: what are homology
        files or containers good for? However, taking into account what we have just explained, it
        should be clear: We fit potential function to these function
        evaluations of terms of the many-body expansion of the Born-Oppenheimer
        surface of the full system.</para>
        <section xml:id="potentials.add-potential">
          <title xml:id="potentials.add-potential.title">Adding potentials</title>
          <para>First of all, potentials can be added using</para>
          <programlisting>
  ... --add-potential Morse \
      --potential-charges 8 1
          </programlisting>
          <para>This will add a "Morse" potential between the elements carbon(8) and
          hydrogen(1) (the order <emph>not</emph> always irrelevant. Here, for this
          pair potential it is).</para>
        </section>
        <section xml:id="potentials.remove-potential">
          <title xml:id="potentials.remove-potential.title">Removing potentials</title>
          <para>And similarly, potentials can be removed using</para>
          <programlisting>
  ... --remove-potential Morse \
      --potential-charges 8 1
          </programlisting>
          <para>This will remove a "Morse" potential between the elements carbon(8) and
          hydrogen(1).</para>
          <note>Typically, however, you do not want to add potentials this way. They
          lack the parametrization that make them any useful. In the following, we
          present more actions for fitting the potential to calculcated energies and
          forces and thus obtaining such a useful parametrization.</note>
        </section>
        <section xml:id="potentials.fit-potential">
          <title xml:id="potentials.fit-potential.title">Fitting empirical potentials</title>
          <para>Empirical potentials are function that represent a certain aspect
          of binding forces in molecular dynamics, e.g. a bond potential represents
          the force between two atoms arising because of a binding orbital in
          between that may be (in some approximartion) represented by a Hooke's
          spring law. 
          In a more abstract view, an empirical potential consists of the 
          following: a binding model representable as a graph consisting of nodes
          and edges, a function that takes the distance between nodes and the
          set of edges (representing bonds in the binding model) and last but
          not least a set of parameters that represent the respective strength
          of the bonds. For example, a torsion potential has a binding model
          containing four nodes and three edges connecting node 1 and 2, 2 and
          3, and 3 and 4. The function requires the six interatomic distances. And
          the parameters are coefficients in the functions that need to be
          evaluated to obtain the resulting force vector.
          </para>
          <para>In this manner, empirical potentials are implemented in 
          MoleCuilder. They are not just a function but always an additional
          binding model that allows to associate atoms with a specific node
          in the model and thereby to assicate it with a particular interatomic
          distance. And said model determines in what order the elements have 
          to be given.
          </para>
          <para>Let&apos;s take a look at an exemplary call to the fit potential
          action.</para>
          <programlisting>
  ... --fit-potential \
      --fragment-charges 8 1 1 \
      --potential-charges 8 1 \
      --potential-type morse \
      --take-best-of 5
   </programlisting>
          <para>Again, we look at each option in turn. The first is the
          charges or elements specifying the set of homologous fragments that
          we want to look at. Here, obviously we are interested in water
          molecules, consisting of a single oxygen (8) and two hydrogen atoms (1).
          Next, we specify the chemical element type of the potential, here a
          potential between oxygen (8) and hydrogen (1). We give the type of 
          the potential as morse, which requires a single distance or two 
          nuclear coordinates and the distance taken between the two. Finally, 
          we state that the non-linear regression should be done with five 
          random starting positions, i.e. five individual minimizations, and 
          the set of parameters with the smallest L2 norm wins.</para>
          <note>
            <para>Due to translational and rotational degrees of freedom for
            fragments smaller than 7 atoms, it is appropriate to look at the
            pair-wise distances and not at the absolute coordinates. In the
            case of the water molecule as a the fragment whose energy we
            want to represent by a empirical potential, there are 3 atoms
            and therefore 3 unique distances between any pair of atoms.
            From this set of distances MoleCuilder needs to pick any subset
            that matches with the ones required by the binding model.
            In our case of the Morse potential, we need two atoms, oxygen 
            and hydrogen, i.e. a single distance. If we had given a harmonic
            angular potential and the then required three charges/elements, 
            &quot;1 8 1&quot;, i.e. oxygen and two hydrogens, we would have 
            obtained three distances. The order of the elements, i.e. 
            &quot;8 1 1&quot; would match a different angular interaction
            in the same fragment, depends on the binding model of the
            potential. In the case of the harmonic angle, the second element
            in the list is the central atom in the angle, while the first and
            third atom define either arm of the angle.Naturally, for the Morse
            potential the order does not matter as each distance is symmetric.
            </para>
            <para>MoleCuilder always adds a so-called constant potential to
            the fit containing only a single parameter, the energy offset.
            This offset compensates for the interaction energy associated with
            a fragment of order 1, e.g. a single hydrogen atom. Essentially, 
            this captures the atomic energy that is not associated to any 
            binding interactions.</para>
            <para>Note that by choosing "set-max-iterations" and "take-best-of"
            one can force the optimization to try either a single set of random
            initial parameters very thoroughly or many different sets just for
            a few iterations. Or any in between.</para>
          </note>
        </section>
        <section xml:id="potentials.fit-compound-potential">
          <title xml:id="potentials.fit-compound-potential.title">Fitting many empirical potentials simultaneously</title>
          <para>Another way is using a file containing a specific set of
          potential functions, possibly even with initial values.</para>
          <para>The .potentials file needs to be loaded beforehand by using
          the <link linkend="potentials.parse-potential">parse potentials</link>
          action. After the fit it needs to be saved using
          <link linkend="potentials.save-potential">save potentials</link>
          to have it contain the updated values.</para>
          <programlisting>
  ... --fit-compound-potential \
      --fragment-charges 8 1 1 \
      --set-threshold 1e-3 \
      --training-file test.dat
      --error-file error.dat
   </programlisting>
          <para>Now, all empirical potential functions are summed up into a
          so-called compound potential over the combined set of parameters.
          These are now fitted simultaneously. For example, let&apos;s say the potential
          file <filename>water.potentials</filename> contains a harmonic bond
          potential between oxygen and hydrogen and another angular potential
          for the angle between hydrogen, oxygen, and hydrogen atom. Then, we would
          fit a function consisting of the sum of the two potentials functions in 
          order to approximate the energy of a single water molecule (actually, 
          it&apos;s the sum of three potentials. As mentioned before, a constant 
          potential is always added to compensate non-bonding energies, i.e. not 
          depending on interatomic distances). Here, the threshold criterion takes 
          the place of the<emphasis role="bold"> take-best-of</emphasis> option. 
          Here, the minimization is reiterated so often on random (but to some 
          extent chosen from a sensible range) starting parameters until the final 
          L2 error is below 1e-3. Also, all data used for training, i.e. the tuples 
          consisting of the fragments nuclei coordinates and the associated energy 
          value are written to the file <filename>test.dat</filename>. This allows 
          for graphical representation or other way of analysis, e.g. for a Morse 
          potential between oxygen and hydrogen the bonding energy can be plotted 
          as a one-dimensional function and compared to the &quot;point cloud&quot; 
          of sample points from the fragment term of Born-Oppenheimer surface. 
          It is this point cloud, i.e. the training data, that is written to the file
          <filename>test.dat</filename>. Moreover, the error per fragment is written
          to the file <filename>error.dat</filename></para>
          <para>Note that you can combine the two ways, i.e. start with a
          fit-potential call but give an empty potential file. The resulting
          parameters are stored in it. Fit other potentials and give different
          file names for each in turn. Eventually, you have to combine the file
          in a text editor at the moment. And perform a fit-compound-potential
          with this file.</para>
          <para>Here, also "set-max-iterations" and "take-best-of" can be used
          to mix thorough or shallow search from random initial parameter sets.
          </para>
        </section>
        <section xml:id="potentials.parse-potential">
          <title xml:id="potentials.parse-potential.title">Parsing an empirical potentials file</title>
          <para>Taking part in the compound potential is every potential
          function whose signature matches with the designated fragment-charges
          and who is currently known to MoleCuilder.</para>
          <para>More potentials can be registered (<emphasis role="bold">fit-potential</emphasis> will also
          register the potential it fits) by parsing them from a file.</para>
          <programlisting>
  ... --parse-potentials water.potentials
   </programlisting>
          <note>Currently, only <productname>TREMOLO</productname>potential files are understood and can be parsed.</note>
        </section>
        <section xml:id="potentials.generate-potentials">
          <title xml:id="potentials.generate-potentials.title">Generate empirical potentials</title>
          <para>The actions to fit potentials take either a single potential name or a 
          potentials file. In order to create all potentials that would match with its
          particle types the following action can be called:
          <programlisting>
                  ... --generate-potentials \
                  --fragment-charges 8 1 1
          </programlisting>
          Here, it would create all potentials for a fragment specifying a water 
          molecule: harmonic_bond for O and H, morse for O and H, harmonic_angle
          for H, O, and H (and not for O, H, H, or other combinations as these
          subgraphs do not exists for the molecule H-O-H), and tersoff for the
          types O and H.
          <programlisting>
                  ... --generate-potentials \
                  --fragment-charges 8 1 1 \
                  --potential-list constant harmonic_bond harmonic_angle
          </programlisting>
          This would generate the potentials taken from the restricted set of 
          listed potential names. If the give list is empty (i.e. the parameter
          is unset), then by default all available potentials are used.</para>
        </section>
        <section xml:id="potentials.save-potential">
          <title xml:id="potentials.save-potential.title">Saving an empirical potentials file</title>
          <para>The opposite to <emphasis role="bold">parse-potentials</emphasis> is to save all currently registered potential functions to the given
          file along with the currently fitted parameters</para>
          <programlisting>
  ... --save-potentials water.potentials
   </programlisting>
          <note>Again, only the <productname>TREMOLO</productname>potential format is understood currently and is written.</note>
        </section>
        <section xml:id="potentials.fit-partial-charges">
          <title xml:id="potentials.fit-partial-charges.title">Fitting partial particle charges</title>
          <para>The above empirical potential just model the short-range
          behavior in the molecular fragment, namely the (covalently) bonded interaction.
          In order to model the Coulomb long-range interaction as well without solving
          for the electronic ground state in each time step, partial charges
          are used that capture to some degree the created dipoles due to
          charge transfer from one atom to another when bonded. These are called
          partial charges because they combine both nuclei and electronic
          charges to yield an in general fractional charge.</para>
          <para>Note that so far the placement of partial charges is restricted 
          to the position of nuclei in the molecular system. There are more
          complex ways of placing partial charges, e.g. as employed in higher
          TIP water molecules, that also use anti-bonding potentials. This is
          so far not implemented.</para>
          <para>To allow least-squares regression of these partial charges, we
          need the results of long-range calculations and the <emphasis role="bold">store-grids</emphasis>
          option (see above under <link linkend="fragmentation">Fragmentation </link>) 
          must have been given.</para>
          <para>Furthermore, we require associations between selected atoms and
          the fragments, residing in the <link linkend="homology">Homology container</link>.
          These are contained in the <link linkend="atomfragments">AtomFragments association</link>
          container, that can also be parsed and stored.</para>
          <para>With these sampled charge density and Coulomb potential stored 
          in the homology containers, we call this action as follows.</para>
          <programlisting>
  ... --fit-partial-charges \
      --potential-file water.particles \
      --radius 1.5
   </programlisting>
          <para>Assume that a water molecule has been selected previously. Then
          all homologous fragments that contain any of the water molecules are
          used as &quot;key&quot; to request all configurations of this type
          from the homologies container. For each of the atoms then an average
          partial charge is computed by fitting their respective Coulomb 
          potential to the obtained from the fragment calculations. Resulting
          values are stored in <filename>water.particles</filename>. The
          radius is used to mask a certain region directly around the nuclei
          from the fit procedure. As here the charges of the core electrons and
          the nuclei itself dominate, we however are only interested in a good
          approximation to the long-range potential, this mask radius allows
          to give the range of the excluded zone.</para>
        </section>
        <section xml:id="potentials.parse-particle-parameters">
          <title xml:id="potentials.parse-particle-parameters.title">Parsing a particles file</title>
          <para>Empirical Potential contain parameters for function that model
          interactions between two or more specific particles. However,
          interactions can also be more general, such as a Coulomb 
          potential, that interacts with any other particle with non-zero
          charge, or Lennard-Jones potential that interacts with any other
          particle close enough.
          Parameters for these particles are encoded in the internal Particle
          class and are parsed from and stored to a special particles file.
          This parse particle parameters function loads the parameters from
          a file, instantiates them in a new particle, and registers them
          such that they are known within molecuilder.</para>
          <para>More particles can be registered (<emphasis role="bold">fit-partial-charges</emphasis> will also
          register the particles it fits) by parsing them from a file.</para>
          <programlisting>
  ... --parse-particle-parameters water.particles
   </programlisting>
          <note>Currently, only <productname>TREMOLO</productname>particles files are understood and can be parsed.</note>
        </section>
        <section xml:id="potentials.save-particle-parameters">
          <title xml:id="potentials.save-particle-parameters.title">Saving a particles file</title>
          <para>The opposite to <emphasis role="bold">parse-particle-parameters</emphasis> 
          is to save all currently registered particle and their parameters to
          the given file.</para>
          <programlisting>
  ... --save-particle-parameters water.particles
   </programlisting>
          <note>Again, only the <productname>TREMOLO</productname>particles format is understood currently and is written.</note>
        </section>
      </section>
      <section xml:id="dynamics">
        <title xml:id="dynamics.title">Dynamics</title>
        <para>For fitting potentials or charges we need many homologous 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 close to the equilibrium and allows to generate those positions for fitting 
        potentials that describe these vibrations.</para>
        <section xml:id="dynamics.molecular-dynamics">
          <title xml:id="dynamics.molecular-dynamics.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>--<emphasis role="bold">verlet-integration</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">output</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">clear-fragment-results</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">destroy-adjacency</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">create-adjacency</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">update-molecules</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">fragment-molecule</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">fragment-automation</emphasis></para>
            </listitem>
            <listitem>
              <para>--<emphasis role="bold">analyse-fragment-results</emphasis></para>
            </listitem>
          </itemizedlist>
          <para>The following command will perform a molecular dynamics simulation
    for 100 time steps, each time step continuing over <emphasis role="bold">deltat</emphasis> equal to 0.5 atomic time units,
    i.e. 1.2e-17 s. Some of the other options listed below, such as <emphasis role="bold">order</emphasis>, <emphasis role="bold">distance</emphasis>, or <emphasis role="bold">fragment-executable</emphasis>, will seem familiar
    to you if you have read in this guide about the fragmentation actions. Look at the list above to see that they are a part of the makro action that performs molecular dynamics simulations. Below
    we will not keep the bond graph, i.e bonds and molecules may change
    over the simulation and hence also the created fragments per time
    step.
Furthermore, the forces are corrected such that the force add up to zero.    </para>
          <programlisting>... --molecular-dynamics \
    --steps 100 \
    --keep-bondgraph 0 \
    --order 3 \
    --distance 3. \
    --deltat 0.5 \
    --keep-fixed-CenterOfMass 1 \
    --fragment-executable mpqc \
          </programlisting>
          <para>Keeping the bond graph is useful when simulating close to the equilibrium and no bond breaking or forming should occur. Note that in general the BOSSANOVA fragmentation scheme is discontinuous with respect to the formation of bonds in the energy. This discontinuity arrises because of the threshold criterion used for detecting the bond graph. After each simulation step the bond graph is recreated (if <emphasis role="bold">keep-bondgraph</emphasis> is switched off) to accomodate for any structural changes. If bonds are added because two atoms are suddenly within the required distance which before was not the case, additional fragments are generated, calculated, and added to the approximation of the whole system. As the addition of these contributions is sudden -- in general, they will already be non-zero when the bonds are detected -- a slight jump in the total energy of the system can be expected.</para>
          <para>To sum it up, the use of the BOSSANOVA scheme in bond breaking/forming scenarios is in general not recommended. That&apos;s why keeping the bond graph is always sensible. However, if potential energies are too far away from equilibrium the simulation may still produce unphysical results.</para>
        </section>
        <section xml:id="dynamics.optimize-structure">
          <title xml:id="dynamics.optimize-structure.title">Structure optimization</title>
          <para>Structure optimization is also a macro Action, it basically
    combines the same Actions as <emphasis role="bold">molecular-dynamics</emphasis> does. However, it
    uses the <emphasis role="bold">force-annealing</emphasis> action instead of <emphasis role="bold">verlet-integration</emphasis>.</para>
          <remark>Because it is a MacroAction we cannot use any more elaborate 
          line search method during the optimization. In essence, we minimize the
          energy function that depends on the nuclei coordinates. The function is
          non-linear and non-convex. The best choice, given that we have gradient
          information, would be the Conjugate Gradient method (such as Fletcher-
          Reeves which work well also for non-linear functions). However, these
          methods perform a line search along the gradient direction which we 
          cannot as our Actions do not contain any internal information (apart
          from the state for Undo/Redo). Therefore, we are restricted to the
          method of Barzilai-Borwein where no line-search is needed but that also
          works well for high-dimensional minimization problems.</remark>
          <para>The command below performs a structure optimization of the 
    currently selected atoms (may also be a subset) for up to 100 time
    steps, where each time step is again 0.5 atomic time units. The time
    step here serves as the initial step width 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 <emphasis role="bold">output-every-step</emphasis> 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>
        <para>Because of the use of Barzilai-Borwein for computing the 
        stepwidth  we do not need any 'deltat' parameters. If the computed
        step width is zero, we use a default step width of 1.</para>
        
        <section xml:id="dynamics.optimize-structure.bondgraph">
          <title xml:id="dynamics.optimize-structure.bondgraph.title">... using the bond graph</title>
          <para>A more efficient optimization, especially for larger molecules
          is obtained, if the bond graph is taken into account. To this end,
          the structure optimization can be called as follows:</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 \
      --use-bondgraph 1 \
      --damping-factor 0.5 \
      --max-distance 8
            </programlisting>
            <para>Note that two additional arguments <emphasis role="bold">use-bondgraph</emphasis>,
            <emphasis role="bold">damping-factor</emphasis>and 
            <emphasis role="bold">max-distance</emphasis>. The first will 
            switch on using the bond graph while the latter two are parameters
            controlling its behavior.</para>
            <para>Let us briefly sketch the central idea of using the bond graph:
            If a specific atom has a non-zero gradient, then this gradient will
            cause the atom to be shifted into its negative direction. The
            gradient however is a sum of forces acting on this atom from all
            other atoms. The gradient therefore states the net effect on the 
            toal energy if the atom (and only the atom) would be moved according 
            to its negative direction. In other words, the force on one side of 
            the atom are stronger than those on the other side, where the
            sides are defined by the plane with the gradient as its normal 
            vector.</para>
            <para>The idea now is to not only move the atom itself but also
            all atoms in the direction of the negative gradient by a fraction
            as well. The underlying notion is that if there is a misplacement
            of the said atom under consideration, then this misplacement
            will faster spread out to the edges of the molecule and dissipate
            there. If we move only the atom, this will cause a lot of 
            oscillations that will take a while to settle. One might think of
            it like the smoothing step of a multigrid solver.
            Essentially, we consider the gradient as a local error that is
            smoothed out by powers of <emphasis role="bold">damping-factor</emphasis>
            the further out we go in the bond graph from the respective
            atom till <emphasis role="bold">max-distance</emphasis>. Note that
            the distance is here to be understood in the sense of a graph, i.e.
            stepping from one atom to a bond neighbor in the bond graph
            is a distance of 1.</para>
            <note>The truncated power series of the <emphasis role="bold">max-distance</emphasis>
            should sum to 1, i.e. values between 0.5 and 1 work well.</note>
            <note>Hydrogens due to their typically much ligher mass compared
            to other nuclei are excluded from this procedure. They feel the
            dampened gradients of others but their gradient acts only on
            themselves</note>
            <note>Barzilai-Borwein step width sometimes tends to overshoot
            as it is a approximation to the secant and assumes linearity. To 
            counter this, we cap the step width at 0.2 angstroem.</note>
          </section>
        </section>
        <section xml:id="dynamics.step-world-time">
          <title xml:id="dynamics.step-world-time.title">Step forward and backward through world time</title>
          <para>Some MacroActions are applied for a number of steps and need to
          increment the current world time, e.g. molecule dynamics or structure
          optimization. To this end, we may call upon
          </para>
          <programlisting>... --step-world-time 1</programlisting>
          <para>Note that the argument gives the number of steps to step forward
          and may be any integer. Hence, we may also step backwards.</para>
        </section>
        <section xml:id="dynamics.set-world-time">
          <title xml:id="dynamics.set-world-time.title">Set the world&apos;s time step</title>
          <para>In order to inspect or manipulate atoms and molecules at a
    certain time step, the World&apos;s time has to be set with the following
    Action.
    </para>
          <para>This will set the World&apos;s time to the fifth step (counting
    starts at zero).</para>
          <programlisting>... --set-world-time 4</programlisting>
          <para>Note that each atom has its own tracjectory storage and manages it in a clever way. That&apos;s why subsets of atoms may be time-integrated, while the other atoms will not get taken over on the time axis. They simply remain frozen during the integration.</para>
        </section>
        <section xml:id="dynamics.save-energies">
          <title xml:id="dynamics.save-energies.title">Save the temperature information</title>
          <para>For each present time step the temperature (i.e. the average velocity
    per atom multiplied with its mass), momentum and force will be stored to a file.</para>
          <programlisting> ... --save-energies temperature.dat</programlisting>
          <para>That is <emphasis role="italic">temperature.dat</emphasis> contains two columns: the first contains the time step and the second column contains the temperature of the system in atomic units.</para>
        </section>
      </section>
      <section xml:id="dynamics.tesselation">
        <title xml:id="dynamics.tesselation.title">Tesselations</title>
        <para>A tesselation is a set of triangles that form a closed surface. They are used to obtain molecular surfaces (and volumes) by rolling
        a virtual sphere of a certain radii on a molecule such that it always rests on at least three atoms. From such a resting position the sphere is rolled over all of its three sides until it rests again. This is continued until the closed 
        surface of connected triangles is created.</para>
        <note>Tesselations are used internally by the graphical interface in 
        order to show molecules by their surface. This is in general faster 
        than displaying them as a ball-stick model consisting of spheres and 
        cylinders.</note>
        <section xml:id="dynamics.tesselation.nonconvex-envelope">
          <title xml:id="dynamics.tesselation.nonconvex-envelope.title"> Non-convex envelope</title>
          <para>This will create a non-convex envelope for a molecule and store
          it to a file for viewing with external programs.</para>
          <programlisting>... --nonconvex-envelope 6. \
    --nonconvex-file nonconvex.dat
          </programlisting>
          <para>This tesselation file can be conveniently viewed with 
          <productname>TecPlot</productname> or with one of the Tcl script 
          in the <emphasis role="italic">util</emphasis> folder with <productname>VMD</productname>. Also,
          still pictures can be produced with <productname>Raster3D </productname>.
          <note>The required file header.r3d can be found in a subfolder of the util folder.</note>
          </para>
        </section>
        <section xml:id="dynamics.tesselation.convex-envelope">
          <title xml:id="dynamics.tesselation.convex-envelope.title">Convex envelope</title>
          <para>This will create a convex envelope for a molecule and give the
          volumes of both the non-convex and the convex envelope. This is good
          for measuring the space a molecule takes up, e.g. when filling a 
          domain and taking care of correct densities.</para>
          <programlisting>... --convex-envelope 6. \
    --convex-file convex.dat
          </programlisting>
          <para>This tesselation file can be likewise viewed with 
          <productname>TecPlot</productname> or with one of the Tcl script 
          in the util folder with <productname>VMD</productname>.</para>
        </section>
      </section>
      <section xml:id="various">
        <title xml:id="various.title">Various commands</title>
        <para>Here, we gather all commands that do not fit into one of above
        categories for completeness.</para>
        <section xml:id="various.verbose">
          <title xml:id="various.verbose.title">Changing verbosity</title>
          <para>The verbosity level is the amount of stuff printed to screen.
          This information will in general help you to understand when
          something does not work. Mind the <emphasis>ERROR</emphasis> and
          <emphasis>WARNING</emphasis> messages in any case.</para>
          <para>This command below sets the verbosity from default of 2 to 4,</para>
          <programlisting>... --verbose 4</programlisting>
          <para>or shorter,</para>
          <programlisting>... -v 4</programlisting>
        </section>
        <section xml:id="various.dry-run">
          <title xml:id="various.dry-run.title">Dry runs</title>
          <para>A &quot;dry run&quot; refers to a test run where commands are not 
   actually executed. You may bracket a certain set of actions by
   putting --<emphasis role="bold">dry-run</emphasis> before and --<emphasis role="bold">no-dry-run</emphasis> afterwards. Then, all
   actions in between will be looked at but not executed, i.e. they
   make it to the history but nothing is changed in the World.</para>
          <para>As an example, the following listing contains the adding of a
   hydrogen atom at position (5,5,5) inside the aforementioned dry run
   statements. Hence, no hydrogen atom is added but the <emphasis role="bold">add-atom</emphasis> action is
   stored in the history and will make it to a stored session.</para>
          <programlisting>... --dry-run \
    --add-atom 1 --domain-position &quot;5,5,5&quot;
    --no-dry-run</programlisting>
          <para>This is useful for converting shell commands into python scripts. Commands are not executed but all are eventually found in the written pyrthon file.</para>
        </section>
        <section xml:id="various.element-db">
          <title xml:id="various.element-db.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 xml:id="various.version">
          <title xml:id="various.version.title">Giving the version of the program</title>
          <para>This prints the version information of the code, especially
          important when you request the fixing of bugs or implementation of
          features.</para>
          <programlisting>... --version</programlisting>
        </section>
        <section xml:id="various.warranty">
          <title xml:id="various.warranty.title">Giving warranty information</title>
          <para>As follows warranty information is given,</para>
          <programlisting>... --warranty</programlisting>
        </section>
        <section xml:id="various.help-redistribute">
          <title xml:id="various.help-redistribute.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>
      <section xml:id="sessions">
        <title xml:id="sessions.title">Sessions</title>
        <para>A session refers to the queue of actions you have executed.
        Together with the initial configuration (and all files required for
        actions in the queue) this may be seen as a clever way of storing
        the state and history of a molecular system manipulation session. When proceeding in a try&amp;error
        fashion to construct a certain system, it is a good idea, to store the
        session at the point where your attempts start to deviate from one
        another.</para>
        <para>Note only that but stored session used in the graphical interface may safe a lot of repetitive pointing and clicking. On top of that if the python session file is called <emphasis role="italic">molecuilder.py</emphasis> and resides in the folder you start MoleCuilder from, then it will be executed automatically and even before creating the graphical interface (i.e. it is also faster).</para>
        <section xml:id="sessions.store-session">
          <title xml:id="sessions.store-session.title">Storing a session </title>
          <para>Storing sessions is simple,</para>
          <programlisting>... --store-session &quot;session.py&quot; \
    --session-type python
       </programlisting>
          <para>Here, the session type is given as python (the other option is
&quot;     cli&quot; for storing in the manner of the command-line interface, i.e. just as our example code snippets throughout this guide). 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 <emphasis role="italic">pyMoleCuilder</emphasis> module).</para>
          <note>The python session will store a file with python commands using named arguments. As some actions have quite
          a number of arguments, all of them end up in a single function call. This makes it very hazard-prone to mix them up.
          Therefore, it is <emphasis>strongly</emphasis> recommended to always use named arguments in python scripts
          when employing MoleCuilder commands.</note>
          <para>When using named arguments for MoleCuilder commands in Python scripts, remember that dashes ("-") in
          argument names have been converted to underscores ("_") as the former characters are illegal. Apart from that
          the argument names resemble exactly the token names as encountered on the command line, e.g.
          <programlisting>
          pyMoleCuilder.CommandVerbose(verbose="1")
          ...
          </programlisting>
          where the keyword argument "verbose" is for the Action that changes MoleCuilder's output verbosity. Also,
          you see that arguments are always given as string.
          </para>
        </section>
        <section xml:id="sessions.load-session">
          <title xml:id="sessions.load-session.title">Loading a session</title>
          <para>Loading a session only works for python scripts, i.e. only for session type python and not for type cli. This actually
          blurs the line between the command-line interface and the python
          interface a bit. Again, MoleCuilder automatically executes a
          script called <filename>molecuilder.py</filename> if such a file is
          contained in the current directory.</para>
          <programlisting>... --load-session &quot;session.py&quot;</programlisting>
          <para>This will execute every action with its options contained in the
          script <filename>session.py</filename>.</para>
        </section>
      </section>
      <section xml:id="various-specific">
        <title xml:id="various-specific.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 xml:id="various-specific.save-selected-atoms-as-exttypes">
          <title xml:id="various-specific.save-selected-atoms-as-exttypes.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/">
              <productname>TREMOLO </productname>
            </link> exttypes file with the given name.</para>
          <programlisting>... --save-selected-atoms-as-exttypes \
    --filename test.exttypes </programlisting>
        </section>
        <section xml:id="various-specific.set-parser-parameters">
          <title xml:id="various-specific.set-parser-parameters.title">Setting parser specific parameters</title>
          <para>You can tweak the parameters stored in files associated to specific ab initio programs to some extent.
          For example, <productname>MPQC</productname> stores various
          parameters modifying the specific ab-initio calculation performed, e.g. the basis set used, the level of theory, whether gradients are calculated.
          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 &quot;theory=CLHF;basis=6-31*G;&quot;
          </programlisting>
          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
          and the basis set to 6-31*G. Note the specific &quot;key=value;&quot; system. That is a key such as &quot;theory&quot; is followed by an equivalent sign and by a value, here &quot;CLHF&quot; for closed-shell Hartree-Fock, and finally a semicolon to separate the key-value pairs. Please avoid any unnecessary white spaces. Note that the implementation is probably not complete, hence do check the
          <productname>MPQC</productname> manual on further supported values that must be added by hand. We list below the currently implementd list of keys and their values.</para>
          <itemizedlist>
            <listitem>Hessian - yes/no
            </listitem>
            <listitem>savestate - yes/no
            </listitem>
            <listitem>do_gradient - yes/no
            </listitem>
            <listitem>maxiter - positive integer value
            </listitem>
            <listitem>memory - positive integer value
            </listitem>
            <listitem>stdapprox
              <itemizedlist>
                <listitem>A'</listitem>
              </itemizedlist>
            </listitem>
            <listitem>nfzc - positive integer value
            </listitem>
            <listitem>basis - any basis listed in data folder, e.g.
              <itemizedlist>
                <listitem>3-21G</listitem>
                <listitem>6-31+G*</listitem>
                <listitem>...</listitem>
              </itemizedlist>
            </listitem>
            <listitem>aux_basis - same as under basis
            </listitem>
            <listitem>integration
              <itemizedlist>
                <listitem>IntegralCints</listitem>
              </itemizedlist>
            </listitem>
            <listitem>theory
              <itemizedlist>
                <listitem>CLHF</listitem>
                <listitem>CLKS</listitem>
                <listitem>MBPT2</listitem>
                <listitem>MBPT2_R12</listitem>
              </itemizedlist>
              </listitem>
            <listitem>jobtype
              <itemizedlist>
                <listitem>Default</listitem>
                <listitem>Optimization</listitem>
              </itemizedlist>
              </listitem>
          </itemizedlist>
        </section>
        <section xml:id="various-specific.set-tremolo-atomdata">
          <title xml:id="various-specific.set-tremolo-atomdata.title">Tremolo specific options and potential files</title>
          <para><productname>TREMOLO</productname>&apos;s configuration files start
          with a specific line telling the amount of information that is contained in the
          file. This line 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 &quot;id element u=3 v=3 F=3&quot; \
    --reset 1
   </programlisting>
          <para>This will not append but reset the old line and fill it with
          the given string. </para>
          <para>Find a list of all keys that are also used internally in MoleCuilder below:</para>
          <itemizedlist>
            <listitem><para>id number - Id</para></listitem>
            <listitem><para>chemical element - type</para></listitem>
            <listitem><para>position - x=3</para></listitem>
            <listitem><para>velocity - u=3</para></listitem>
            <listitem><para>force - F=3</para></listitem>
            <listitem><para>enumerating bonded atom ids - neighbors=4</para></listitem>
            <listitem><para>name of atom - name</para></listitem>
            <listitem><para>charge - Charge</para></listitem>
          </itemizedlist>  
          <para>Furthermore, find the rest of all available keys:</para>
          <itemizedlist>
            <listitem><para>stress tensor - stress</para></listitem>
            <listitem><para>enumerating bonded atom ids for improper potential - imprData</para></listitem>
            <listitem><para>unknown - GroupMeasureTypeNo</para></listitem>
            <listitem><para>group association for external forces - exttype</para></listitem>
            <listitem><para>residual name of atom (see PDB) - resName</para></listitem>
            <listitem><para>chain Id (see PDB) - chainId</para></listitem>
            <listitem><para>residual sequence (see PDB) - resSeq</para></listitem>
            <listitem><para>occupancy of electron orbitals - occupancy</para></listitem>
            <listitem><para>temperature factor - tempFactor</para></listitem>
            <listitem><para>segment id (see PDB) - segID</para></listitem>
            <listitem><para>different charge - charge</para></listitem>
            <listitem><para>unknown - GrpTypeNo</para></listitem>
            <listitem><para>enumerating bonded atom ids for torsion potential - torsion</para></listitem>
          </itemizedlist>  
          <para>One further 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 potentials 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>
          <para>Note that this is the same format as written by the fitting actions. However, apart from this the Actions are not related, i.e. <emphasis role="bold">parse-potentials</emphasis> will not also load these element descriptions. If this is desired, the above Action has to be used.</para>
        </section>
      </section>
    </section>
    <section xml:id="textmenu-interface">
      <title xml:id="textmenu-interface.title">Text menu</title>
      <para>We now discuss how to use the text menu interface.</para>
      <para>The text menu is very much the interface counterpart to the
      command-line interface. However, both work in a terminal session.</para>
      <para>In the text menu, actions can be selected from hierarchical lists.
      Note that the menus for the graphical interface are organized in the
      exactly same way. After an action has been chosen, the option values
      have to be entered one after the other. After the last option value has
      been given, the action is executed and the result printed to the
      screen.</para>
      <para>With regards to the other functionality, it is very much the same
      as the command-line interface above. It differs by being interactive, i.e. when using an external viewer on the state file and saving it after an Action has been performed, output can be checked. However, you may work in this way also directly by using the graphical interface.</para>
    </section>
    <section xml:id="graphical-user-interface">
      <title xml:id="graphical-user-interface.title">Graphical user interface </title>
      <para>The main point of the GUI is that it renders the atoms and
      molecules visually. These are represented by the common
      stick-and-ball-model by default. For faster rendering, molecules can also be visualized by the a non-convex envelope, see Tesselations. Single or multiple atoms and molecules can easily
      be accessed, activated, and manipulated via tables. Changes made in the
      tables cause immediate update of the visual representation. Under the
      hood each of these manipulations is nothing but the call to an action,
      hence is fully undo- and redoable.</para>
      <para>This interface is most helpful in designing more advanced structures that are
      conceptually difficult to imagine without visual aid. Results can be inspected directly and, if unsuitable, can be undone and reperformed with tweaked parameters. At the end, a
file containing the      session may be stored and this script can then be used to construct
      various derived or slightly modified structures.</para>
      <section xml:id="graphical-user-interface.basic-view">
        <title xml:id="graphical-user-interface.basic-view.title">Basic view </title>
        <para>Let us first give an impression of the basic view of the GUI         after a molecule has been loaded.</para>
        <figure>
          <title>Screenshot of the basic view of the GUI after loading a file with eight water molecules.</title>
          <mediaobject>
            <imageobject>
              <imagedata width="100%" scalefit="1" entityref="example_basic_view"/>
            </imageobject>
          </mediaobject>
        </figure>
        <section xml:id="graphical-user-interface.3d-view">
          <title xml:id="graphical-user-interface.3d-view.title">3D view </title>
          <para>In the above figure, you see the stick-and-ball representation
          of the water molecules, the &quot;dreibein&quot; giving the positive axis
          directions and the slightly translucent cuboid of the domain on a black background.</para>
        </section>
        <section xml:id="graphical-user-interface.information-tabs">
          <title xml:id="graphical-user-interface.information-tabs.title"> Information Tabs</title>
          <para>Beneath this 3D view that you can rotate at will with your mouse
          and zoom in and out with your scroll wheel, you find to the right a
          part containing two tabs named Atom and Molecule. Look at where the
          mouse pointer is. It has colored the atom underneath in cyan
          (although it&apos;s also an oxygen atom and should be colored in rose
          as the rest). You can inspect its properties in the tab Atom: Name,
          element, mass, charge, position and number of bonds. If you switch
          to the Molecule tab, you would see the properties of the water
          molecule this specific atom belongs to.</para>
        </section>
        <section xml:id="graphical-user-interface.shape">
          <title xml:id="graphical-user-interface.shape.title">Shape section </title>
          <para>Beneath these information tabs you find the shape sections.
          There you find a list of all currently created shapes and you can
select them by clicking on them, which lets their surface appear in the 3D view, and          manipulate them via the buttons beneath this list. Note that the calculation of the shape&apos;s surface may take up to a few seconds, so don&apos;t get itchy right away when nothing seems to happen for a moment.</para>
        </section>
        <section xml:id="graphical-user-interface.timeline">
          <title xml:id="graphical-user-interface.timeline.title">Timeline </title>
          <para>Directly below the 3D view there is a long slider. If a loaded
          file has multiple time step entries, this slider allows you to
          smoothly select one time frame after another. Sliding it with the
          mouse from left to right will reveal the animation that is hidden
          behind the distinct snapshots stored in the configuration
          file.</para>
        </section>
        <section xml:id="graphical-user-interface.tables">
          <title xml:id="graphical-user-interface.tables.title">Selection tables</title>
          <para>Underneath the time line there is another place for
          tabs.</para>
          <itemizedlist>
            <listitem>Molecules</listitem>
            <listitem>All Elements</listitem>
            <listitem>All Fragments</listitem>
            <listitem>All Homologies</listitem>
            <listitem>All Geometries</listitem>
            <listitem>Logs</listitem>
            <listitem>Errors</listitem>
          </itemizedlist>
          <para>The first is on molecules, listing all present molecules of
          the molecular system in a tree view. If you click on a specific
          molecule, the one will get selected or unselected depending on its
          current selection state (see below for details on this with respect
          to the GUI). Also, if you tick the box the visibility of the specific molecules is changed: it switches between being displayed as either ball-and-stick, for manipulating its individual atoms, or as a molecular surface for (un)selecting it as a whole.</para>
          <para>The next tab enumerates all elements known to MoleCuilder
          where the ones are grayed out that are not present in the molecular
          system. Clicking on a present element will select all atoms of this
          specific element. A subsequent click unselects again.</para>
          <para>Subsequently follow two tabs on enumerating the fragments and their
          fragment energies if calculated and the homologies along with
          graphical depiction (via QWT), again if present.</para>
          <para>After that, we have a tab listing all geometry objects. These
          are vectors you may store via one of the Actions. If you hover over
          a vector, its length is shown. If you have selected one vector and
          hover over another one, then the angle between the two is shown.
          </para>
          <para>Finally, there are two tabs showing log messages of actions
          in the first tab and general information on what is currently done. Errors and
          warnings are listed in the second tab.</para>
        </section>
      </section>
      <section xml:id="graphical-user-interface.selections">
        <title xml:id="graphical-user-interface.selections.title">Selections </title>
        <para>Selections work generally always by calling a selection action from the pull-down menu and filling it with required parameters.</para>
        <para>With the GUI it may also be accessed directly: The row of icons
        above the 3D view has two icons depicting the selection of individual
        atoms or molecules. If either of them is selected, clicking with the
        left mouse button on an atom will either (un)select the atom or its
        associated molecule. Multiple atoms can be selected in this
        manner.</para>
        <para>Also, the selection tabs may be used by clicking on the name of a
        molecule as stated above or at an element.</para>
        <para>Similarly, if shapes are present in the shape section, clicking
        them will select them and also cause a translucent visualization to
        appear in the 3D view. Note that this visualization is quite costly
        right now and not suited to complex shapes. (This is in contrast to the molecular surfaces which are actually cheaper than the ball-and-stick presentation).</para>
      </section>
      <section xml:id="graphical-user-interface.dialogs">
        <title xml:id="graphical-user-interface.dialogs.title">Dialogs</title>
        <para>Most essential to the GUI are dialogs. Many action
        calls forth such a dialog. A dialog         consists of a list of queries for a particular option value, one below the other. As each option
        value has a specific type, we briefly go into the details of how these
        queries look like.</para>
        <note>
          <para>Each dialog&apos;s okay button is grayed out until all entered option values
          are valid.</para>
        </note>
        <section xml:id="graphical-user-interface.dialogs.domain">
          <title xml:id="graphical-user-interface.dialogs.domain.title">Domain query</title>
          <figure>
            <title>Screenshot of a dialog showing a domain query</title>
            <mediaobject>
              <imageobject>
                <imagedata width="100%" scalefit="1" entityref="dialog_box"/>
              </imageobject>
            </mediaobject>
            <para>In the domain query a 3x3 symmetric matrix has to be
            entered. In the above screenshots you notice that the only
            non-zero entries are on the main diagonal. Here, we have simply
            specified a cube of edge length 8. The okay button will be grayed
            out if the matrix is either singular or not symmetric.</para>
          </figure>
        </section>
        <section xml:id="graphical-user-interface.dialogs.element">
          <title xml:id="graphical-user-interface.dialogs.element.title"> Element query</title>
          <figure>
            <title>Screenshot the add atom action containing an element query</title>
            <mediaobject>
              <imageobject>
                <imagedata width="100%" scalefit="1" entityref="dialog_add-atom_tooltip"/>
              </imageobject>
            </mediaobject>
            <para>Elements are picked from a pull-down box where all known
            elements are listed.</para>
            <para>In this dialog you also notice that a tooltip is given,
            briefly explaining what the action does.</para>
          </figure>
        </section>
        <section xml:id="graphical-user-interface.dialogs.action">
          <title xml:id="graphical-user-interface.dialogs.action.title"> Complex query</title>
          <figure>
            <title>Screenshot of a complex dialog consisting of multiple queries</title>
            <mediaobject>
              <imageobject>
                <imagedata width="100%" scalefit="1" entityref="dialog_complex"/>
              </imageobject>
            </mediaobject>
            <para>Here we show a more complex dialog. It queries for strings,
            for integer values (see the increase/decrease arrows), for
            booleans and for files (the &quot;choose&quot; buttons opens a file
            dialog).</para>
          </figure>
        </section>
        <section xml:id="graphical-user-interface.dialogs.exit">
          <title xml:id="graphical-user-interface.dialogs.exit.title">Exit query</title>
          <figure>
            <title>Screenshort showing the exit dialog</title>
            <mediaobject>
              <imageobject>
                <imagedata width="100%" scalefit="1" entityref="dialog_exit"/>
              </imageobject>
            </mediaobject>
            <para>Finally, we show the dialog that will pop up when exiting
            the graphical interface. It will ask whether it should store the
            current state of the system in the input file or not. You may
            cancel the exit, close without saving or save the current
            state.</para>
          </figure>
        </section>
      </section>
    </section>
    <section xml:id="python-interface">
      <title xml:id="python-interface.title">Python interface</title>
      <para>Last but not least we elaborate on the python interface. We have
      already discusses this interface to some extent. The current session,
      i.e. the queue of actions you have executed, can be stored as a python
      script and subsequently executed independently of the user interface it
      was created with. More generally, MoleCuilder&apos;s Actions can be executed within arbitrary python
      scripts where prior to its execution a specific module has to be loaded, enabling access to MoleCuilder&apos;s actions from inside the
      script.</para>
      <para>MoleCuilder&apos;s python module is called <emphasis role="italic">pyMoleCuilder</emphasis>. It is
      essentially a library that can be imported into python just as any other
      module. Let us assume you have started the python interpreter and you
      have added the containing folder of the <filename>pyMoleCuilder</filename>
      library to the <varname>PYTHONPATH</varname> variable.</para>
      <programlisting>import pyMoleCuilder as mol</programlisting>
      <para>Subsequently, you can access the help via</para>
      <programlisting>help(mol)</programlisting>
      <para>This will list all of MoleCuilder&apos;s actions with their function
      signatures within python as contained in the module <emphasis role="italic">pyMoleCuilder</emphasis> named
      as <emphasis role="bold">mol</emphasis> in the scope of the currently running interpreter. Note that the
      function names are not the names you know from the command-line
      interface, they might be called
      <computeroutput>WorldChangeBox(...)</computeroutput> or alike. However, they are related by a certain naming system. The first word is identical to the menu name it resides in the text or graphical interface. Then its followed by the actual name of the action that is similar to the command-line token.</para>
      <para>Let&apos;s try it out.</para>
      <programlisting>print mol.CommandVersion()</programlisting>
      <para>This will state the current version of the library.</para>
      <para>Go ahead and try out other commands. Refer to the documentation
      under the command-line interface and look up the function name via
      help.</para>
      <para>You can freely mix calls to the pymolecuilder module and other python commands.</para>
      <note>However, be aware that all Actions are executed in another thread,
      i.e. run in parallel. That means that a pymolecuilder command is not 
      necessarily finished when python steps on to the next line!</note>
      <para>In order to make python wait for the Actions to finish before
      stepping, there is the special wait() command.</para>
      <programlisting>
         mol.MoleculeLoad("...")
         status = mol.wait()
      </programlisting>
      <para>This will continue first only after the molecule has been fully 
      loaded. Moreover, wait returns whether the actions contained executed
      succesfully.</para>
      <warning>These wait()s will have no effect if the python script is loaded
      via the "load-session" command inside a User Interface (command-line,
      GUI, ...) as this would cause the queue to wait indefinitely, namely till
      the load-session itself would have finished.</warning>
      <para>Therefore, more complex python scripts need to be called with
      python and a set PYTHONPATH as described above.</para>
          <note>It is <emphasis>strongly</emphasis> recommended to always use named arguments in python scripts
          when employing MoleCuilder commands. As commands tend to have many arguments, it is very easy to mix
          them up as python is not a strongly typed language.</note>
    </section>
  </chapter>
  <chapter>
    <title>Conclusions</title>
    <para>This ends this user guide.</para>
    <para>We have given you a brief introduction to the aim of the program and
    how each of the four interfaces are to be used. The rest is up to
    you.</para>
    <para>Tutorials and more information is available online, see <link xlink:href="http://www.molecuilder.com/">MoleCuilder&apos;s website</link>.
    </para>
    <para>Be aware that in general knowing how the code works allows you to
    understand what&apos;s going wrong if something&apos;s going wrong.</para>
    <section>
      <title>Thanks</title>
      <para>Huge thanks go out to Saskia Metzler who was patient enough to let
      me sit next to her while riding ten hours in a bus to Berlin as I was writing the very first version of this guide.</para>
    </section>
  </chapter>
</book>