source: doc/userguide/userguide.xml@ 3567e2

<?xml version="1.0" encoding="UTF-8"?>
<!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 version="5.0" 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:m="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>MoleCuilder - a Molecule Builder</title>

    <author>
      <personname><firstname>Frederik</firstname><surname>Heber</surname></personname>

      <affiliation>
        <orgname>heber@ins.uni-bonn.de</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 entityref="molecuilder_logo" scalefit="1" width="100%"/>
        </imageobject>
      </mediaobject>
    </figure>

    <section>
      <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. Eventually, not a single, but
      many, related molecular systems have to be created.</para>

      <section>
        <title>Installation requirements</title>

        <para>For installations requirements and instructions we refer to the
        internal documentation of MoleCuilder, created via doxgen from the
        source code.</para>
      </section>

      <section>
        <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>
        <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 "as is" 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>
        <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 "session scripts" (see below) and auxiliary files. Please
        mind sensible space restrictions of email attachments.</para>
      </section>

      <section>
        <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.</para>
          </listitem>

          <listitem>
            <para>Selection refers to a subsets from the set of instances of a
            particular type, e.g. atoms.</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 or cylinders.</para>
          </listitem>
        </itemizedlist>
      </section>

      <section>
        <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 and thus
        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>
      <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 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 and a specific center in the domain such that its
          atoms are placed relative to this center. Also, they 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 automatically.</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
          parallelepiped in <inlineequation>
              <m:math display="inline">
                <m:mi>\mathbb{R}^3</m:mi>
              </m: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>
      <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
          expanding the shell command with a number of commands including all
          required options that are 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 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>
      <title>Known File formats</title>

      <para>We briefly the file formats MoleCuilder can parse and
      store.</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><productname>MPQC</productname>, <filename>.in</filename>
          (<link xlink:href="???">http://www.mpqc.org/</link>)</para>
        </listitem>

        <listitem>
          <para>PDB, <filename>.pdb</filename> (<link
          xlink:href="???">http://www.pdb.org/</link>)</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><productname>PSI4</productname>, <filename>.psi</filename>
          (<link xlink:href="???">http://www.psicode.org/</link>)</para>
        </listitem>

        <listitem>
          <para><productname>TREMOLO</productname>, <filename>.data</filename>
          (<link xlink:href="???">http://www.tremolo-x.org/</link>)</para>
        </listitem>

        <listitem>
          <para>XML, <filename>.xml</filename> (XML as read by scafacos
          project, <link
          xlink:href="???">http://www.scafacos.org</link>/)</para>
        </listitem>
      </itemizedlist>

      <para>These are identified via their suffixes and can be converted from
      one into another (with loss of all data not in the intersection of
      stored properties of the two involved file formats).</para>
    </section>
  </chapter>

  <chapter>
    <title>Interfaces</title>

    <para>In this chapter, we explain the intention and use of the four
    interfaces.</para>

    <para>We 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 is full potential:
    The interactive interface gives you the immediate feedback in constructing
    "synthesis" (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 lateron understanding of what has
    been done.</para>

    <section>
      <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, choose a
      simulation box, fill the box with this given "filler" 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. An example for the above procedure is given
      below:</para>

      <programlisting>
        ./molecuilder \
                -i sample.xyz \
                --add-atom H \
                --domain-position "0.,0.,0." \
                ...
        </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 
      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 "H"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, e.g. -a 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. If not enough options are given 
      or invalid values have been entered, an error message is printed stating 
      the name of the first missing or invalid option value.</para>

      <note>
        <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 understable to you in years to come.</para>
      </note>

      <section>
        <title>Preliminaries</title>

        <para>Some preliminary remarks are in order which we have gathered
        here on how these actions work in general.</para>

        <para>Below 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
        ordered the subsequent details on the manipulation depending on the
        scale they act upon - single atoms, multiple atoms organised as
        molecules, and all atoms organised by their containing domain.</para>

        <para>In the following we will always give a command to illustrate the
        procedure but just the necessary parts, i.e. "..." implies to prepend
        it with the executable and input command for a specific configuration
        file, for storing the manipulated state of the molecular system. Note
        that</para>

        <programlisting>./molecuilder --help</programlisting>

        <para>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
        "add-atom",</para>

        <programlisting>./molecuilder --help --actionname 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 "0,0,0" --undo</programlisting>

        <para>and redo as follows</para>

        <programlisting>... --add-atom H --domain-position "0,0,0" --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 tells you that actions are placed in a queue, i.e. a history,
        that undo and redo manipulate.</para>
      </section>

      <section>
        <title>File parsers</title>

        <para>We have already given a list of all known file formats, see
        <link linkend="???">File formats</link>. Next, we explain how these
        file formats are picked and manipulated.</para>

        <section>
          <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. 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>. 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.</para>
        </section>

        <section>
          <title>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 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.</para>
        </section>

        <section>
          <title>Setting parser specific parameters</title>

          <para>You can also tweak the parameters stored in this file easily.
          For example, <productname>MPQC</productname> stores various
          parameters modifying the specific ab-initio calculation performed.
          For <productname>MPQC</productname> and 
          <productname>Psi4</productname> this can be modified as 
          follows.</para>

          <programlisting>
                ... --set-parser-parameters mpqc \
                    --parser-parameters "theory=CLHF;basis=6-31*G;"
          </programlisting>

          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
          and the basis set to 6-31*G. Please check the
          <productname>MPQC</productname> manual on specific
          parameters.</para>
        </section>

        <section>
          <title>Tremolo specific options and potential files</title>

          <para><productname>TREMOLO</productname>'s configuration files start
          with a specific line telling the amount of information stored in the
          file. This file can be modified, e.g. to enforce storing of
          velocities and forces as well as the atoms positions and
          element.</para>

          <programlisting>
                ... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
                    --reset 1
          </programlisting>

          <para>This will not append but reset the old line and fill it with
          the given string.</para>

          <para>One specific action is required when loading certain
          <productname>TREMOLO</productname> configuration files. These
          contain element notations that refer to parameterized names used in
          empirical potentials and molecular dynamics simulations and not the
          usual chemical symbols, such as H or O. We may load an auxiliary
          file that gives the required conversion from OH1 to H, which is the
          so-called potential file.</para>

          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>

          <para>This parses the lookup table from the file
          <filename>water.potentials</filename> and it can be used in
          following load actions.</para>
        </section>
      </section>

      <section>
        <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.</para>

        <para>Selections either work on atoms, on molecules, or on shapes
        (this we explain lateron). 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).</para>

        <para>We only give a brief list on the kind of selections per type,
        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>

        <itemizedlist>
          <listitem>
            <para>Atoms</para>

            <itemizedlist>
              <listitem>
                <para>By Element (all hydrogen atoms, all sulphur atoms,
                ...)</para>
              </listitem>

              <listitem>
                <para>By Id (atom with id 76)</para>
              </listitem>

              <listitem>
                <para>By Order (the first (1), the second, ... the last, the
                last but one)</para>
              </listitem>

              <listitem>
                <para>By Shape (specific region of the domain)</para>
              </listitem>

              <listitem>
                <para>By Molecule (all atoms belonging to currently selected
                molecules)</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Molecules</para>

            <itemizedlist>
              <listitem>
                <para>By Id (molecule with id 4)</para>
              </listitem>

              <listitem>
                <para>By Order (first molecule, second molecule, ...)</para>
              </listitem>

              <listitem>
                <para>By Name (molecule named "water4"</para>
              </listitem>

              <listitem>
                <para>By Atom (all molecules for which at least one atom is
                currently selected)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para>Shapes</para>

            <itemizedlist>
              <listitem>
                <para>By Name (shape name "sphere1")</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>All</para>

            <itemizedlist>
              <listitem>
                <para>All (selects or unselects all instances of the
                type)</para>
              </listitem>

              <listitem>
                <para>Clear (clears the current selection)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para>Furthermore, a selection can be imverted, e.g. inverting the
        current selection of atoms.</para>

        <programlisting>... --invert-atoms</programlisting>

        <remark>Note that an unselected instance (e.g. an atom) remains
        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>
        <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, 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 (not) of a smaller sphere, we
        obtain a spherical surface of specific thickness.</para>

        <section>
          <title>Creating shapes</title>

          <para>Primitive shapes can be created as follows,</para>

          <programlisting>
                ... --create-shape \
                    --shape-type sphere \
                    --shape-name "sphere1" \
                    --stretch "2,2,2" \
                    --translation "5,5,5"
          </programlisting>

          <para>This will create a sphere of radius 2 (initial radius is 1)
          with name "sphere1" that is centered at (5,5,5). Other primitives at
          cuboid and cylinder, where a rotation can be specified as
          follows.</para>

          <programlisting>
                ... --create-shape \
                    --shape-type cuboid \
                    --shape-name "box" \
                    --stretch "1,2,2" \
                    --translation "5,5,5" \
                    --angle-x "90"
          </programlisting>
        </section>

        <section>
          <title>Removing shapes</title>

          <para>Removing a shape is as simple as removing an atom.</para>

          <programlisting>... --remove-shape </programlisting>

          <para>This removes the currently selected shapes.</para>
        </section>

        <section>
          <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 also
          later on. We just the list examples of the various manipulations
          below, each works on the currently selected shapes.</para>

          <programlisting>
                ... --stretch-shapes "1,1,2" \
                    --stretch-center "5,5,5"
          </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-shape \
                    --center "10,2,2" \
                    --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 "5,0,0" </programlisting>

          <para>This translates all selected shapes by 5 along the x
          axis.</para>
        </section>
      </section>

      <section>
        <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 uniform 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 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 is always
        a multiple of 90 degrees).</para>

        <programlisting>
                ... --set-random-number-distribution "uniform_int" \
                    --random-number-distribution-parameters "p=1"
        </programlisting>

        <para>This changes the distribution to "uniform_int", i.e. integer
        numbers distributed uniformly.</para>

        <programlisting>
                ... --set-random-number-engine "mt19937" \
                    --random-numner-engine-parameters "seed=10"
        </programlisting>

        <para>Specifying the seed allows you to obtain the same sequence of
        random numbers for testing purposes.</para>
      </section>

      <section>
        <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>
          <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 "2.,3.,2.35"
          </programlisting>

          <para>where the element is given via its chemical symbol and the
          vector gives the position within the domain</para>
        </section>

        <section>
          <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>
          <title>Translating atoms</title>

          <para>In order to translate the current selected subset of atoms you
          specify a translation vector.</para>

          <programlisting>
                ... --translate-atoms "-1,0,0" \
                    --periodic 0
          </programlisting>

          <para>This translate all atoms by "-1" along the x axis and does not
          mind the boundary conditions, i.e. might shift atoms outside of the
          domain.</para>
        </section>

        <section>
          <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>
        <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>
          <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 a heuristic distance criterion.</para>

          <programlisting>... --create-adjacency</programlisting>

          <para>This uses by default a criterion based on van-der-Waals radii,
          i.e. if we look at two atoms indexed by "a" and "b"</para>

          <equation>
            <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) +
            \tau</title>

            <m:math display="block">
              <m:mi>where V(.) is the lookup table for the radii for a given
              element and \tau is a threshold value, set to 0.4.</m:mi>
            </m:math>
          </equation>

          <para>As a second 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>
              <m:math display="inline">
                <m:mi>V(a,b)</m:mi>
              </m:math>
            </inlineequation> in place of <inlineequation>
              <m:math display="inline">
                <m:mi>V(a)+V(b)</m:mi>
              </m:math>
            </inlineequation>.</para>
        </section>

        <section>
          <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>
          <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>
        </section>

        <section>
          <title>Dissecting the molecular system into molecules</title>

          <para>The bond graph information can be used to recognize the
          molecule within the system. 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. Note that this is
          just structural information and does not change the state of the
          system.</para>

          <programlisting>... --subgraph-dissection</programlisting>

          <para>This analyses the bond graph and splits the single molecule up
          into individual (new) ones that each contain a single connected
          subgraph, hence the naming.</para>
        </section>

        <section>
          <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.
          First, you must have selected two atoms.</para>

          <programlisting>... --add-bond</programlisting>
        </section>

        <section>
          <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-bond</programlisting>
        </section>

        <section>
          <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>
        </section>

        <section>
          <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 degree by
          translating the two outer atoms of this triangle (the atom connected
          to both others is the axis of the rotation).</para>
        </section>
      </section>

      <section>
        <title>Manipulate molecules</title>

        <para>Molecules are agglomerations of atoms that are 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
        all bonds in between. Actions below mostly deal with copying
        molecules. Removing of molecules is done via selecting the molecule'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="???">Dissecting the molecular system
          into molecules</link></para>
        </note>

        <section>
          <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 "10,10,10"
          </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'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>
        </section>

        <section>
          <title>Fill a domain section with molecules</title>

          <para>Filling a specific part of the domain with one type of
          molecule, e.g. a water molecule, is the more advanced type of
          copying and we need several ingredients.</para>

          <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, they are two types of filling, volume and surface. The
          volume is filled with a regular grid of fill-in points, and in the
          same manner is the surface filled with a regular grid of points.
          Molecules will be copied and translated points when they
          "fit".</para>

          <para>The filler procedure checks each fill-in point whether there
          is enough space for the molecule. To know this, we require a cluster
          instead of a molecule. This 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 this cluster. For this a number of
          atoms have to be specified, the minimum bounding box is generated
          automatically.</para>

          <para>On top of that molecules can be selected whose volume is
          additionally excluded from the filling region.</para>

          <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 "5,5,5" \
                    --mesh-offset ".5,.5,.5" \
                    --DoRotate 1 --min-distance 1. \
                    --random-atom-displacement 0.05 \
                    --random-molecule-displacement 0.4 \
                    --tesselation-radius 2.5
          </programlisting>

          <para>This generates a grid of 5x5x5 fill-in points within the
          sphere that are offset such as to lay centered within the sphere
          (offset per axis in [0,1]). Additionally, each molecule is rotated
          by random rotation matrix, each atom is translated randomly by at
          most 0.05, each molecule's center at most by 0.4. The selected
          molecules' 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="???">1.4
          Randomization </link>for details on changing the randomness.</para>
        </section>

        <section>
          <title>Change a molecules name</title>

          <para>You can change the name of a molecule which is important for
          selection.</para>

          <programlisting>... -change-molname "test</programlisting>

          <para>This will change the name of the (only) selected molecule to
          "test".</para>

          <para>Connected with this is the default name an unknown molecule
          gets.</para>

          <programlisting>... --default-molname test</programlisting>

          <para>This will change the default name of a molecule to
          "test".</para>

          <note>
            <para>Note that a molecule loaded from file gets the filename
            (without suffix) as its name.</para>
          </note>
        </section>

        <section>
          <title>Rotate around self</title>

          <para>You can rotate a molecule around its own axis.</para>

          <programlisting>
                ... --rotate-around-self "90" \
                    --axis "0,0,1"
          </programlisting>

          <para>This rotates the molecule around the z axis by 90 degrees as
          if the origin were at its center of origin.</para>
        </section>

        <section>
          <title>Rotate around origin</title>

          <para>In the same manner the molecule can be rotated around an
          external origin.</para>

          <programlisting>
                ... --rotate-around-origin 90 \
                    --position "0,0,1"\
          </programlisting>

          <para>This rotates the molecule around an axis from the origin to
          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
        </section>

        <section>
          <title>Rotate to principal axis system</title>

          <para>The principal axis system is given by an ellipsoid that mostly
          matches the molecules shape. The principal axis system can be just
          simply determined by</para>

          <programlisting>... --principal-axis-system</programlisting>

          <para>To rotate the molecule around itself to align with this system
          do as follows.</para>

          <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>

          <para>This rotates the molecule in such a manner that the ellipsoids
          largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
          would align anti-parallel.</remark></para>
        </section>

        <section>
          <title>Perform verlet integration</title>

          <para>Atoms not only have a position, but each instance also stores
          velocity and a force vector. These can be used in a velocity verlet
          integration step. Velocity verlet is a often employed time
          integration algorithm in molecular dynamics simulations.</para>

          <programlisting>
                ... --verlet-integration \
                    --deltat 0.1 \
                    --keep-fixed-CenterOfMass 0
          </programlisting>

          <para>This will integrate with a timestep of <inlineequation>
              <m:math display="inline">
                <m:mi>\Delta_t = 0.1</m:mi>
              </m:math>
            </inlineequation>and correcting forces and velocities such that
          the sum over all atoms is zero.</para>
        </section>
      </section>

      <section>
        <title>Manipulate domain</title>

        <para>Here, we elaborate on how to duplicate all the atoms inside the
        domain, how the scale the coordinate system, how to center the atoms
        with respect to certain points, how to realign them by given
        constraints, how to mirror and most importantly how to specify the
        domain.</para>

        <section>
          <title>Changing the domain</title>

          <para>The domain is specified by a symmetric 3x3 matrix. The
          eigenvalues (diagonal entries in case of a diagonal matrix) give the
          length of the edges, additional entries specify transformations of
          the box such that it becomes a more general parallelepiped.</para>

          <programlisting>... change-box "20,0,20,0,0,20"</programlisting>

          <para>As the domain matrix is symmetric, six values suffice to fully
          specify it. We have to give the six components of the lower diagonal
          matrix. Here, we change the box to a cuboid of equal edge length of
          20.</para>
        </section>

        <section>
          <title>Bound atoms inside box</title>

          <para>The following applies the current boundary conditions to the
          atoms. In case of periodic or wrapped boundary conditions the atoms
          will be periodically translated to be inside the domain
          again.</para>

          <programlisting>... --bound-in-box</programlisting>
        </section>

        <section>
          <title>Center atoms inside the domain</title>

          <para>This is a combination of changing the box and bounding the
          atoms inside it.</para>

          <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
        </section>

        <section>
          <title>Center the atoms at an edge</title>

          <para>MoleCuilder can calculate the minimum box (parallel to the
          cardinal axis) all atoms would fit in and translate all atoms in
          such a way that the lower, left, front edge of this minimum is at
          the origin (0,0,0).</para>

          <programlisting>... --center-edge</programlisting>
        </section>

        <section>
          <title>Extending the boundary by adding an empty boundary</title>

          <para>In the same manner as above a minimum box is determined that
          is subsequently expanded by a boundary of the given additional
          thickness. This applies to either side.</para>

          <programlisting>... --add-empty-boundary "5,5,5"</programlisting>

          <para>This will enlarge the box in such a way that every atom is at
          least by a distance of 5 away from the boundary of the domain (in
          the infinity norm).</para>
        </section>

        <section>
          <title>Scaling the box</title>

          <para>You can enlarge the domain by simple scaling factors.</para>

          <programlisting>... --scale-box "1,1,2.5"</programlisting>

          <para>Here, the domain is stretched in the z direction by a factor
          of 2.5.</para>
        </section>

        <section>
          <title>Repeating the box</title>

          <para>Under periodic boundary conditions often only the minimal
          periodic cell is stored. If need be, multiple images can be easily
          added to the current state of the system by repeating the box, i.e.
          the box along with all contained atoms is copied and placed
          adjacently.</para>

          <programlisting>... --repeat-box "1,2,2"</programlisting>

          <para>This will create a 2x2 grid of the current domain, replicating
          it along the y and z direction along with all atoms. If the domain
          contained before a single water molecule, we will now have four of
          them.</para>
        </section>
      </section>

      <section>
        <title>Fragmentation</title>

        <para>Fragmentation refers to a so-called linear-scaling method called
        "Bond-Order diSSection in an ANOVA-like fashion" (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 (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>
            <m:math display="inline">
              <m:mi>{\cal O}(M^3}</m:mi>
            </m:math>
          </inlineequation>with the number of atoms <inlineequation>
            <m:math display="inline">
              <m:mi>M</m:mi>
            </m:math>
          </inlineequation>. Hence, calculating the ground state energy of a
        number of fragment molecules scaling linearly with the number of atoms
        yields a linear-scaling methods. 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 are artificially truncated, however,
        with this fragment 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 <productname>ScaFaCoS</productname> package (<link
        xlink:href="???">http://www.scafacos.org/</link>).</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>

        <section>
          <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 "BondFragment" \
                    --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 all need
          a common prefix, here "BondFragment". 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>
              <m:math display="inline">
                <m:mi>&gt;10^{-4}</m:mi>
              </m:math>
            </inlineequation>) in systems with many interconnected aromatic
          rings, such as graphene. Next, we give a distance cutoff of 3 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. As input the solver
          requires the density which is sampled on a cartesian grid whose
          resolution these parameter defines (<inlineequation>
              <m:math display="inline">
                <m:mi>2^{\mathrm{level}}</m:mi>
              </m:math>
            </inlineequation>). And finally, we give the output file formats,
          i.e. which file formats are used for writing each fragment
          configuration (prefix is "BondFragment", 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="???">Parsers</link> above on how to
          change the parameters of the ab-initio calculation.</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>
        </section>

        <section>
          <title>Calculating fragment energies automatically</title>

          <para>Another way of doing this is enabled if you have
          <productname>JobMarket</productname> package. 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, samewise specified in the package.
          The results are gathered together by the server and can be requested
          from MoleCuilder once they are done. This essentially describe 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="???">Fragmenting a molecule</link>.</para>

          <programlisting>
                ... --parse-fragment-jobs \
                    --fragment-jobs "BondFragment00.in" "BondFragment01.in" \
                    --fragment-path "./" \
                    --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
          "./", 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 \
                    --fragment-resultfile BondFragment_results.dat \
                    --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'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's server. All calculated results are placed in
          the result file. If none is given, they are instead again placed in
          an internal storage for later access.</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 charge is reduces
          respectively. 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.</para>
        </section>

        <section>
          <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 "BondFragment" \
                    --fragment-resultfile BondFragment_results.dat \
                    --store-grids 1
          </programlisting>

          <para>The purpose of the prefix should already be known to you, same
          with the result file that is the file parsed by MoleCuilder. 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). 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="???">verlet
          integration</link> is possible afterwards.</para>
        </section>
      </section>

      <section>
        <title>Homologies</title>

        <para>After a fragmentation procedure has been performed fully, what
        to do with the results? The forces can be used already but what about
        the energies? The energy value is basically the function evaluation of
        the Born-Oppenheimer surface. For molecular dynamics simulations
        continuous ab-initio calculations to evaluate the Born-Oppenheimer
        surface is not feasible. Instead usually empirical potential functions
        are fitted as to resemble the Born-Oppenheimer surface to a sufficient
        degree.</para>

        <para>One frequent method is the many-body expansion of said surface
        which is basically nothing else than the fragment 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 parameter of the
        empirical potential function in such a way as to most closely obtain
        the same function evaluation as the ab-initio calculation did with the
        same nuclear coordinates. Usually, this is done in a least-square
        sense, minimising the euclidean norm.</para>

        <para>Homologies 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).</para>

        <para>Now, we explain the actions that parse and store
        homologies.</para>

        <programlisting>... --parse-homologies homologies.dat</programlisting>

        <para>This parses the all homologies contained in the file
        <filename>homologies.dat</filename> and appends them to the homology
        container.</para>

        <programlisting>... --store-homologies homologies.dat</programlisting>

        <para>Complementary, this stores the current contents of the homology
        container, overwriting the file
        <filename>homologies.dat</filename>.</para>
      </section>

      <section>
        <title>Potentials</title>

        <para>In much the same manner, we would now ask what are homology
        files or containers good for but with the just had explanation it
        should be clear: We fit potential function to these function
        evaluation of terms of the many-body expansion of the Born-Oppenheimer
        surface of the full system.</para>

        <section>
          <title>Fitting empirical potentials</title>

          <para>Let'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 and two hydrogen atoms.
          Next, we specify the nuclei coordinates of the potential. We give
          the type of the potential as morse, which requires a single distance
          or two nuclear coordinates, here between an oxygen and a hydrogen
          atom. Finally, we state that the non-linear regression should be
          done with five random starting positions 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. Hence,
            the two atomic positions, here for oxygen and hydrogen, are
            converted to a single distance. If we had given an harmonic
            angular potential and three charges/element, 8 1 1, i.e. oxygen
            and two hydrogens, we would have obtained three distances.</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.</para>
          </note>

          <para>Another way is using a file containing a specific set of
          potential functions, possibly even with initial values.</para>

          <programlisting>
                ... --fit-potential \
                    --fragment-charges 8 1 1 \
                    --potential-file water.potentials \
                    --set-threshold 1e-3 \
                    --training-file test.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, if 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 we would
          fit a still simple function approximating the energy of a single
          water molecule. Here, the threshold takes the place of the
          take-best-of option. Here, random starting parameters are used as
          long as the final L2 error is not 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 or other
          type of analysis.</para>

          <para>Note that you can combine the two ways, i.e. start with the
          first but give an empty potential file. The resulting parameters are
          stored in this way. Fit other potentials and give different file
          names for each. Eventually, you have to combine the file in a text
          editor at the moment.</para>
        </section>

        <section>
          <title>Fitting partial charges</title>

          <para>The above empirical potential just model the short-range
          behavior in the molecular fragment, namely the bonded interaction.
          In order to model the long-range interaction as well without solving
          for the electronic ground state in each time step, partial charges
          are used that capture to some degree the created dipoles due to
          charge transfer from one atom to another when bonded.</para>

          <para>To allow least-squares regression of these partial charges we
          need the results of long-range calculations and the store-grids
          option (see above under <link linkend="???">Fragmentation</link>)
          must have been given. With these sampled charge density and Coulomb
          potential stored in the homology containers, we call this action as
          follows.</para>

          <programlisting>
                ... --fit-partial-charges \
                    --fragment-charges 8 1 1 \
                    --potential-file water.potentials \
                    --radius 0.2
          </programlisting>

          <para>This will again use water molecule as homologous fragment
          "key" to request configurations from the container. Results are
          stored in <filename>water.potentials</filename>. The radius is used
          to mark the 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>

      <section>
        <title>Various commands</title>

        <para>Here, we gather all commands that do not fit into one of above
        categories for completeness.</para>

        <section>
          <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 sets the verbosity from default of 2 to 4,</para>

          <programlisting>... --verbose 4</programlisting>

          <para>or shorter,</para>

          <programlisting>... -v 4</programlisting>
        </section>

        <section>
          <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>
          <title>Giving warranty information</title>

          <para>As follows warranty information is given,</para>

          <programlisting>... --warranty</programlisting>
        </section>
      </section>

      <section>
        <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 might be seen as a clever way of storing
        the state of a molecular system. 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>
      </section>

      <section>
        <title>Storing a session</title>

        <para>Storing sessions is simple,</para>

        <programlisting>
                ... --store-session "session.py" \
                    --session-type python
        </programlisting>

        <para>Here, the session type is given as python (the other option is
        cli for in the manner of the command-line interface) and the written
        python script <filename>session.py</filename> can even be used with
        the python interface described below, i.e. it is a full python script
        (that however requires the so-called pyMoleCuilder module).</para>
      </section>

      <section>
        <title>Loading a session</title>

        <para>Loading a session only works for python scripts. This actually
        blurs the line between the command-line interface and the python
        interface a bit. But even more, MoleCuilder automatically executes a
        script called <filename>molecuilder.py</filename> if such a file is
        contained in the current directory.</para>

        <programlisting>... --load-session "session.py"</programlisting>

        <para>This will execute every action with its options contained in the
        script <filename>session.py</filename>.</para>
      </section>
    </section>

    <section>
      <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. 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.</para>
    </section>

    <section>
      <title linkend="GUI">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. 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 is mostly helpful to design more advanced structures that are
      conceptually difficult to imagine without visual aid. At the end, a
      session may be stored and this script can then be used to construct
      various derived or slightly modified structures.</para>

      <section>
        <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 entityref="example_basic_view" scalefit="1" width="100%"/>
            </imageobject>
          </mediaobject>
        </figure>

        <section>
          <title>3D view</title>

          <para>In the above figure, you see the stick-and-ball representation
          of the water molecules, the dreibein giving the positive axis
          direction and the cuboidal domain on a black background.</para>
        </section>

        <section>
          <title>Information Tabs</title>

          <para>Beneath this 3D view that you can rotate at will 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's also an oxygen atom and should bne coloured 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>
          <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
          manipulate them via the buttons beneath this list.</para>
        </section>

        <section>
          <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>
          <title>Selection tables</title>

          <para>Underneath the time line there is another place for
          tabs.</para>

          <para>The first is on molecules, listing all present molecules of
          the molecular system in a list 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).</para>

          <para>The next tab enumerates all elements known to MoleCuilder
          where the ones are greyed 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>Subsequent follow tabs on enumerating the fragments and their
          fragment energies if calculated and the homologies along with
          graphical depiction (via QWT) if present.</para>
        </section>
      </section>

      <section>
        <title>Selections</title>

        <para>Selections work generally always by selecting the respective
        action from the pull-down menu.</para>

        <para>However, 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 with 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.</para>
      </section>

      <section>
        <title>Dialogs</title>

        <para>Most essential, however, to the GUI are the dialogs. Each action
        calls forth such a dialog even if no options are required (the
        execution of the action has at least to be confirmed). Each dialog
        consisting of queries for a particular option value. 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's Ok is greyed out until all entered option values
          are valid.</para>
        </note>

        <section>
          <title>Domain query</title>

          <figure>
            <title>Screenshot of a dialog showing a domain query</title>

            <mediaobject>
              <imageobject>
                <imagedata entityref="dialog_box" scalefit="1" width="100%"/>
              </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 ok button will be greyed
            out if the matrix is either singular or not symmetric.</para>
          </figure>
        </section>

        <section>
          <title>Element query</title>

          <figure>
            <title>Screenshot the add atom action containing an element
            query</title>

            <mediaobject>
              <imageobject>
                <imagedata entityref="dialog_add-atom_tooltip" scalefit="1" width="100%"/>
              </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>
          <title>Complex query</title>

          <figure>
            <title>Screenshot of a complex dialog consisting of multiple
            queries</title>

            <mediaobject>
              <imageobject>
                <imagedata entityref="dialog_complex" scalefit="1" width="100%"/>
              </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 "choose" buttons opens a file
            dialog).</para>
          </figure>
        </section>

        <section>
          <title>Exit query</title>

          <figure>
            <title>Screenshort showing the exit dialog</title>

            <mediaobject>
              <imageobject>
                <imagedata entityref="dialog_exit" scalefit="1" width="100%"/>
              </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>
      <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 general, MoleCuilder can execute arbitrary python
      scripts where prior to its execution a specific module is loaded by
      default enabling access to MoleCuilder's actions from inside the
      script.</para>

      <para>MoleCuilder's python module is called pyMoleCuilder. 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 destination 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's actions with their function
      signatures within python as contained in the module pyMoleCuilder named
      as mol 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.</para>

      <para>Let'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>
    </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/</link>.</para>

    <para>Be aware that in general knowing how the code works allows you to
    understand what's going wrong if something'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.</para>
    </section>
  </chapter>
</book>