Changeset d12d818


Ignore:
Timestamp:
Jul 23, 2015, 10:34:39 PM (9 years ago)
Author:
Frederik Heber <heber@…>
Branches:
Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable
Children:
9b3262b
Parents:
599b32
git-author:
Frederik Heber <heber@…> (06/01/15 07:42:19)
git-committer:
Frederik Heber <heber@…> (07/23/15 22:34:39)
Message:

DOCU: Corrected userguide.

  • this still needs some more work, e.g. w.r.t to code snippets indentation.
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/userguide/userguide.xml

    r599b32 rd12d818  
    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    3                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
     1<?xml version='1.0' encoding='UTF-8'?>
     2<!-- 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" [
    43<!ENTITY molecuilder_logo SYSTEM "pictures/molecuilder_logo.png" NDATA PNG>
    54<!ENTITY dialog_box SYSTEM "pictures/dialog_box.png" NDATA PNG>
    … …  
    98<!ENTITY example_basic_view SYSTEM "pictures/example_basic_view.png" NDATA PNG>
    109]>
    11 <book version="5.0" xmlns="http://docbook.org/ns/docbook"
    12       xmlns:xlink="http://www.w3.org/1999/xlink"
    13       xmlns:xi="http://www.w3.org/2001/XInclude"
    14       xmlns:svg="http://www.w3.org/2000/svg"
    15       xmlns:m="http://www.w3.org/1998/Math/MathML"
    16       xmlns:html="http://www.w3.org/1999/xhtml"
    17       xmlns:db="http://docbook.org/ns/docbook">
     10<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:m="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">
    1811  <info>
    1912    <title>MoleCuilder - a Molecule Builder</title>
    20 
    2113    <author>
    22       <personname><firstname>Frederik</firstname><surname>Heber</surname></personname>
    23 
     14      <personname>
     15        <firstname>Frederik</firstname>
     16        <surname>Heber</surname>
     17      </personname>
    2418      <affiliation>
    2519        <orgname>heber@ins.uni-bonn.de</orgname>
    2620      </affiliation>
    2721    </author>
    28 
    2922    <pubdate>07/03/14</pubdate>
    3023  </info>
    31 
    3224  <chapter>
    3325    <title>Introduction</title>
    34 
    3526    <figure>
    36       <title>MoleCuilder logo depicting a tesselated buckyball and a benzene
    37       molecule</title>
    38 
     27      <title>MoleCuilder logo depicting a tesselated buckyball and a benzene molecule</title>
    3928      <mediaobject>
    4029        <imageobject>
    41           <imagedata entityref="molecuilder_logo" scalefit="1" width="100%"/>
     30          <imagedata width="100%" scalefit="1" entityref="molecuilder_logo"/>
    4231        </imageobject>
    4332      </mediaobject>
    4433    </figure>
    45 
    46     <section xml:id='whatis'>
    47       <title  xml:id='whatis.title'>What is MoleCuilder?</title>
    48 
     34    <section xml:id="whatis">
     35      <title xml:id="whatis.title">What is MoleCuilder?</title>
    4936      <para>In Short,<command> MoleCuilder</command> is a concatenation of
    5037      molecule and builder.</para>
    51 
    5238      <para>In more words, molecular dynamics simulations are frequently
    5339      employed to simulate material behavior under stress, chemical reactions
    … …  
    5945      dynamics simulations? It is the coordinate and element of each atom
    6046      combined with potential functions that model the interactions.</para>
    61 
    6247      <para>MoleCuilder allows to fully construct such a starting point:
    6348      letting the user construct atomic and molecular geometries by a simple
    … …  
    6651      calculations within hours. Specific emphasis is placed on a
    6752      simple-to-use interface, allowing for the quick-and-dirty building of
    68       molecular systems, and on scriptability. Eventually, not a single, but
     53      molecular systems, and on scriptability. The last being important a eventually not a single, but
    6954      many, related molecular systems have to be created.</para>
    70 
    71       <section xml:id='installation'>
    72         <title xml:id='installation.title'>Installation requirements</title>
    73 
     55      <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>
     56      <section xml:id="installation">
     57        <title xml:id="installation.title">Installation requirements</title>
    7458        <para>For installations requirements and instructions we refer to the
    75         internal documentation of MoleCuilder, created via doxgen from the
     59        internal documentation of MoleCuilder, created via <productname>doxygen</productname>. from the
    7660        source code.</para>
    7761      </section>
    78 
    79       <section xml:id='license'>
    80         <title xml:id='license.title'>License</title>
    81 
     62      <section xml:id="license">
     63        <title xml:id="license.title">License</title>
    8264        <para>As long as no other license statement is given, MoleCuilder is
    8365        free for user under the GNU Public License (GPL) Version 2 (see
    8466        <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
    8567      </section>
    86 
    87       <section xml:id='disclaimer'>
    88         <title xml:id='disclaimer.title'>Disclaimer</title>
    89 
     68      <section xml:id="disclaimer">
     69        <title xml:id="disclaimer.title">Disclaimer</title>
    9070        <para>We quote section 11 from the GPLv2 license:</para>
    91 
    92         <remark>Because the program is licensed free of charge, there is not
    93         warranty for the program, to the extent permitted by applicable law.
    94         Except when otherwise stated in writing in the copyright holders
    95         and/or other parties provide the program "as is" without warranty of
    96         any kind, either expressed or implied. Including, but not limited to,
    97         the implied warranties of merchantability and fitness for a particular
    98         purpose. The entire risk as to the quality and performance of the
    99         program is with you. Should the program prove defective, you assume
    100         the cost of all necessary servicing, repair, or correction.</remark>
    101       </section>
    102 
    103       <section xml:id='feedback'>
    104         <title xml:id='feedback.title'>Feedback</title>
    105 
     71        <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>
     72      </section>
     73      <section xml:id="feedback">
     74        <title xml:id="feedback.title">Feedback</title>
    10675        <para>If you encounter any bugs, errors, or would like to submit
    10776        feature request, please use the email address provided at the very
    10877        beginning of this user guide. The author is especially thankful for
    10978        any description of all related events prior to occurrence of the
    110         error, saved "session scripts" (see below) and auxiliary files. Please
     79        error, saved &quot;session scripts&quot; (see below) and auxiliary files. Please
    11180        mind sensible space restrictions of email attachments.</para>
    11281      </section>
    113 
    114       <section xml:id='notation'>
    115         <title xml:id='notation.title'>Notation</title>
    116 
     82      <section xml:id="notation">
     83        <title xml:id="notation.title">Notation</title>
    11784        <para>We briefly explain a few specific wordings associated with the
    11885        program:</para>
    119 
    12086        <itemizedlist>
    12187          <listitem>
    12288            <para><emphasis>Action</emphasis> is a command that allows for
    12389            undoing and redoing, i.e. a single atomic procedure for
    124             manipulating the molecular system.</para>
     90            manipulating the molecular system. Here, atomic refers to indivisible and not to atoms. It is also referred to as a command.</para>
    12591          </listitem>
    126 
    12792          <listitem>
    12893            <para>Selection refers to a subsets from the set of instances of a
    129             particular type, e.g. atoms.</para>
     94            particular type, e.g. atoms, molecules, shapes, ...</para>
    13095          </listitem>
    131 
    13296          <listitem>
    13397            <para>Shape means a specific region of the domain that can be
    13498            described in the way of constructive geometry, i.e. as the
    13599            intersection, negation, and combination of primitives such as
    136             spheres or cylinders.</para>
     100            spheres, cubes, or cylinders.</para>
    137101          </listitem>
     102          <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 state is also referred to as the state.</listitem>
     103          <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>
    138104        </itemizedlist>
    139105      </section>
    140 
    141       <section xml:id='completeness'>
    142         <title xml:id='completeness.title'>Completeness</title>
    143 
     106      <section xml:id="completeness">
     107        <title xml:id="completeness.title">Completeness</title>
    144108        <para>This documentation takes quite some effort to write. Hence, the
    145109        described features and especially the actions herein are settled with
    146110        respect to their functionality, while newer features or actions are
    147111        probably missing. This should be a clear sign to you that these are
    148         probably not safe to use yet. If you nonetheless require them and thus
    149         should acquire some familiarity with the code itself. This suggests
     112        probably not safe to use yet. If you nonetheless require them, you         should acquire some familiarity with the code itself. This suggests
    150113        changing to the developer documentation which is maintained along with
    151114        the source code with <productname>doxygen</productname>.</para>
    … …  
    153116    </section>
    154117  </chapter>
    155 
    156118  <chapter>
    157119    <title>Features</title>
    158 
    159120    <para>Basically, <command>MoleCuilder</command> parses geometries from
    160     files, manipulates them and stores them again in files. The manipulation
     121    files, manipulates them, and stores them again in files. The manipulation
    161122    can be done either via a command-line interface or via the graphical user
    162123    interface.</para>
    163 
    164     <section xml:id='concepts'>
    165       <title xml:id='concepts.title'>Concepts</title>
    166 
     124    <section xml:id="concepts">
     125      <title xml:id="concepts.title">Concepts</title>
    167126      <para>In general, we divide the molecular systems into three different
    168127      components or scales.</para>
    169 
    170128      <orderedlist>
    171129        <listitem>
    172130          <para>Atoms</para>
    173 
    174131          <para>Atoms are the undividable objects of the molecular systems.
    175           They have an element <quote>Z</quote> and three coordinates
     132          They have at least an element <quote>Z</quote> and three coordinates
    176133          <quote>(x,y,z)</quote>.</para>
    177134        </listitem>
    178 
    179135        <listitem>
    180136          <para>Molecules</para>
    181 
    182137          <para>Molecules are bound conglomeration of atoms. They contain a
    183           number of atoms and a specific center in the domain such that its
    184           atoms are placed relative to this center. Also, they may have a
     138          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
    185139          bounding box, i.e. a subdomain that contains all of the atoms in the
    186140          molecule.</para>
    187 
    188141          <para>Note that the molecular structure of the system, i.e. the
    189142          bonding graph, is determined by MoleCuilder and used to dissect the
    190           system into distinct molecules automatically.</para>
     143          system into distinct molecules on request.</para>
    191144        </listitem>
    192 
    193145        <listitem>
    194146          <para>Clusters</para>
    195 
    196147          <para>Clusters are unbound conglomeration of atoms. Clusters serves
    197148          as groups of atoms for specific operations that would be to
    198149          restricted if they worked on just molecules.</para>
    199150        </listitem>
    200 
    201151        <listitem>
    202152          <para>Domain</para>
    203 
    204           <para>The domain refers to the simulation domain. It is
     153          <para>The domain refers to the simulation domain. It is the
    205154          parallelepiped in <inlineequation>
    206155              <m:math display="inline">
    … …  
    213162      </orderedlist>
    214163    </section>
    215 
    216     <section xml:id='interfaces'>
    217       <title xml:id='interfaces.title'>Interfaces</title>
    218 
     164    <section xml:id="interfaces">
     165      <title xml:id="interfaces.title">Interfaces</title>
    219166      <para>MoleCuilder has four different interfaces: Command-line, text
    220167      menu, graphical user interface, and python interface.</para>
    221 
    222168      <orderedlist>
    223169        <listitem>
    224170          <para>Command-Line</para>
    225 
    226171          <para>The command-line interface allows to use MoleCuilder
    227172          non-interactively via a terminal session. The program is executed by
    228           expanding the shell command with a number of commands including all
    229           required options that are executed one after the other. After
     173appending to the shell command a number of commands including all
     174          required options that are then executed one after the other. After
    230175          execution of the last command, the program quits. The command-line
    231176          interface usually works on a specific file that is given as input,
    … …  
    235180          modified via MoleCuilder.</para>
    236181        </listitem>
    237 
    238182        <listitem>
    239183          <para>Text menu</para>
    240 
    241184          <para>The text-menu is similar to the command-line interface with
    242185          the exception that it allows for interactive sessions. Commands are
    … …  
    244187          user.</para>
    245188        </listitem>
    246 
    247189        <listitem>
    248190          <para>Graphical interface</para>
    249 
    250           <para>The graphical interface is based on Qt. It features a full
    251           graphical representation of the simulation domain with atoms and
     191          <para>The graphical interface is based on Qt. It features a full graphical, three-dimensional
     192representation of the simulation domain with atoms and
    252193          their bonds. It allows manipulation in point&amp;click fashion.
    253194          Commands are selected from pull-down menus and dialogs are used to
    254195          query the user for all required parameters to such a command.</para>
    255196        </listitem>
    256 
    257197        <listitem>
    258198          <para>Python interface</para>
    259 
    260199          <para>The last interface is accessible only within the python
    261200          programming language. MoleCuilder can be loaded as a module and its
    … …  
    267206      </orderedlist>
    268207    </section>
    269 
    270     <section xml:id='fileformats'>
    271       <title xml:id='fileformats.title'>Known File formats</title>
    272 
    273       <para>We briefly the file formats MoleCuilder can parse and
    274       store.</para>
    275 
     208    <section xml:id="fileformats">
     209      <title xml:id="fileformats.title">Known File formats</title>
     210      <para>We briefly list the file formats MoleCuilder can parse and
     211      store. We refer to external websites for more detailed information where appropriate.</para>
    276212      <itemizedlist>
    277213        <listitem>
    … …  
    280216          of lines and a comment line)</para>
    281217        </listitem>
    282 
    283218        <listitem>
    284           <para><link xlink:href="http://www.mpqc.org/"><productname>MPQC
    285           </productname></link>, <filename>.in</filename></para>
     219          <para><link xlink:href="http://www.mpqc.org/">
     220              <productname>MPQC </productname>
     221            </link>, <filename>.in</filename></para>
    286222        </listitem>
    287 
    288223        <listitem>
    289           <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename>
    290           .pdb</filename></para>
     224          <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename> .pdb</filename></para>
    291225        </listitem>
    292 
    293226        <listitem>
    294227          <para><productname>ESPACK</productname>, <filename>.conf</filename>
    … …  
    296229          University of Bonn, code not in circulation)</para>
    297230        </listitem>
    298 
    299231        <listitem>
    300           <para><link xlink:href="http://www.psicode.org/"><productname>PSI4
    301           </productname></link>, <filename>.psi</filename></para>
     232          <para><link xlink:href="http://www.psicode.org/">
     233              <productname>PSI4 </productname>
     234            </link>, <filename>.psi</filename></para>
    302235        </listitem>
    303 
    304236        <listitem>
    305           <para><link xlink:href="http://www.tremolo-x.org/"><productname>
    306           TREMOLO</productname></link>, <filename>.data</filename></para>
     237          <para><link xlink:href="http://www.tremolo-x.org/">
     238              <productname> TREMOLO</productname>
     239            </link>, <filename>.data</filename></para>
    307240        </listitem>
    308 
    309241        <listitem>
    310242          <para>XML, <filename>.xml</filename> (XML as read by
    … …  
    313245        </listitem>
    314246      </itemizedlist>
    315 
    316247      <para>These are identified via their suffixes and can be converted from
    317       one into another (with loss of all data not in the intersection of
     248      one into another (with possible loss of data outside of the intersection of
    318249      stored properties of the two involved file formats).</para>
    319250    </section>
    320251  </chapter>
    321 
    322252  <chapter>
    323253    <title>Interfaces</title>
    324 
    325254    <para>In this chapter, we explain the intention and use of the four
    326255    interfaces.</para>
    327 
    328     <para>We give the most extensive explanation of the command-line
     256    <para>We will give the most extensive explanation of the command-line
    329257    interface, all subsequent interfaces are explained in highlighting their
    330258    differences with respect to the command-line interface. This is because
    … …  
    332260    user guide. Although some images of the graphical interface are given
    333261    below, they would blow the size of the guide out of proportion.</para>
    334 
    335262    <para>In any case, you should make yourself familiar with at least one of
    336263    the interactive (text menu, GUI) and one of the non-interactive
    337     (command-line, python) interfaces to use MoleCuilder to is full potential:
     264    (command-line, python) interfaces to use MoleCuilder to its full potential:
    338265    The interactive interface gives you the immediate feedback in constructing
    339     "synthesis" (build) chains (of commands) for constructing your specific
     266    &quot;synthesis&quot; (build) chains (of commands) for constructing your specific
    340267    molecular system in the computer. The non-interactive interface lends
    341268    itself to quick creation of related systems that differ only by specific
    … …  
    343270    shell scripts, python itself is a scripted language). Also, the
    344271    non-interactive interfaces are used for storing sessions which helps you
    345     in documentation your experiments and lateron understanding of what has
    346     been done.</para>
    347 
    348     <section xml:id='command-line-interface'>
    349       <title xml:id='command-line-interface.title'>Command-line interface</title>
    350 
     272    in documentation your experiments and later on understanding of what has
     273    been actually created by the prescribed commands, i.e. debugging.</para>
     274    <section xml:id="command-line-interface">
     275      <title xml:id="command-line-interface.title">Command-line interface</title>
    351276      <para>The command-line interface reads options and commands from the
    352277      command line and executes them sequentially. This may be for example:
    353       Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, choose a
    354       simulation box, fill the box with this given "filler" molecule, save the
     278      Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, recognize the bond graph, choose a
     279      simulation box, fill the box with this given &quot;filler&quot; molecule, save the
    355280      file. This enables the use of MoleCuilder in simple script-files to
    356281      create a whole range of geometries that only differ in a few parameters
    357282      automatically.</para>
    358 
    359283      <para>Traditionally, <command>MoleCuilder</command> operates on a single
    360284      configuration file - the state - which may also store additional
    361285      information depending on the chosen file format such as parameters for
    362       ab-initio computations. An example for the above procedure is given
     286      ab-initio computations. To some small extent <command>MoleCuilder</command> also allows manipulation of these paramters. An example for the above procedure is given
    363287      below:</para>
    364 
    365288      <programlisting>
    366         ./molecuilder \
    367                 -i sample.xyz \
    368                 --add-atom H \
    369                 --domain-position "0.,0.,0." \
    370                 ...
    371         </programlisting>
    372 
     289 ./molecuilder \
     290  -i sample.xyz \
     291  --add-atom H \
     292    --domain-position &quot;0.,0.,0.&quot; \
     293  ...
     294 </programlisting>
    373295      <para>The first argument is the executable itself. Second, there is a
    374       slew of arguments -- one per line split with a backslash telling the
     296      slew of arguments -- one per line split with a backslash telling the comman
    375297      shell that the line still continues -- consisting of the input action and
    376298      an arbitrarily named file <filename>sample.xyz</filename>, which may be
    377299      empty and whose file format is chosen by the given extension. The third
    378300      is the add-atom action following by an option that gives the position in
    379       the domain where to add the "H"ydrogen atom. An action is always
     301      the domain where to add the &quot;H&quot;ydrogen atom. An action is always
    380302      introduced via a double hyphen and its full name (containing just
    381303      non-capital letters and hyphens) or a single hyphen and a single letter
    382       for its shortform, e.g. -a for adding an atom to the system. It is
     304      for its shortform, such as <emphasis role="bold"> -a</emphasis> for adding an atom to the system. It is
    383305      followed by a fixed number of options. Most of these have default values
    384       and in this do not have to be specified. If not enough options are given
    385       or invalid values have been entered, an error message is printed stating
    386       the name of the first missing or invalid option value.</para>
    387 
    388       <note>
     306      and in this do not have to be specified.</para>
     307      <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>
     308      <formalpara>
     309        <title>Shortforms of Actions</title>
    389310        <para>Note that not all action have shortforms and it is best practice
    390311        to have the full action name instead of its shortform to make the
    391         command-line understable to you in years to come.</para>
     312        command-line comprehendable to you in years to come.</para>
     313      </formalpara>
     314      <note>
     315        <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</para>
     316        <para>option receives an extra tab for indentation.</para>
    392317      </note>
    393 
    394       <section xml:id='preliminaries'>
    395         <title xml:id='preliminaries.title'>Preliminaries</title>
    396 
     318      <section xml:id="preliminaries">
     319        <title xml:id="preliminaries.title">Preliminaries</title>
    397320        <para>Some preliminary remarks are in order which we have gathered
    398321        here on how these actions work in general.</para>
    399 
    400         <para>Below we first delve into some details about secondary structure
     322        <para>We first delve into some details about secondary structure
    401323        such as selections, shapes, and randomization required to specify
    402324        subsets of atoms and molecules you wish to manipulate. Then, we have
    403         ordered the subsequent details on the manipulation depending on the
    404         scale they act upon - single atoms, multiple atoms organised as
    405         molecules, and all atoms organised by their containing domain.</para>
    406 
     325give the details on the manipulation ordered by the
     326        scale they act upon - single atoms, multiple atoms organized as
     327        molecules, and all atoms organized by their containing domain.</para>
    407328        <para>In the following we will always give a command to illustrate the
    408         procedure but just the necessary parts, i.e. "..." implies to prepend
     329        procedure but just its necessary parts, i.e. &quot;...&quot; implies to prepend
    409330        it with the executable and input command for a specific configuration
    410         file, for storing the manipulated state of the molecular system. Note
    411         that</para>
    412 
     331        file, for storing the manipulated state of the molecular system. </para>
     332        <para>So if we write</para>
     333        <programlisting>... --help</programlisting>
     334        <para>Then we actually mean you to write</para>
    413335        <programlisting>./molecuilder --help</programlisting>
    414 
    415         <para>will always give you a list of all available actions and also a
     336        <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
    416337        brief explanation on how to properly enter values of a specific type,
    417338        e.g. an element, a vector, or a list of numbers. Details to a specific
    418339        action can be requested when its full name is known, e.g. for
    419         "add-atom",</para>
    420 
    421         <programlisting>./molecuilder --help --actionname add-atom</programlisting>
    422 
     340        &quot;add-atom&quot;,</para>
     341        <programlisting>./molecuilder --help add-atom</programlisting>
    423342        <para>which fills you in on each option to the action: its full name,
    424343        its expected type, and a possibly present default value, and a brief
    425344        description of the option.</para>
    426 
    427345        <para>An Action can be undone and redone, e.g. undo adding an atom as
    428346        follows,</para>
    429 
    430         <programlisting>... --add-atom H --domain-position "0,0,0" --undo</programlisting>
    431 
     347        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo</programlisting>
    432348        <para>and redo as follows</para>
    433 
    434         <programlisting>... --add-atom H --domain-position "0,0,0" --undo --redo</programlisting>
    435 
     349        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo --redo</programlisting>
    436350        <para>With the non-interactive interfaces this may seem rather
    437351        superfluous but it comes in very handy in the interactive ones. Also
    438         this tells you that actions are placed in a queue, i.e. a history,
     352        this should tell you that actions are placed internally in a queue, i.e. a history,
    439353        that undo and redo manipulate.</para>
    440       </section>
    441 
    442       <section xml:id='fileparsers'>
    443         <title xml:id='fileparsers.title'>File parsers</title>
    444 
     354        <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>
     355        <para>Being done now with the preliminaries we now go through all available actions present in MoleCuilder.</para>
     356      </section>
     357      <section xml:id="fileparsers">
     358        <title xml:id="fileparsers.title">File parsers</title>
    445359        <para>We have already given a list of all known file formats, see
    446360        <link linkend="fileformats">File formats</link>. Next, we explain how these
    447361        file formats are picked and manipulated.</para>
    448 
    449         <section xml:id='fileparsers.parsing'>
    450           <title xml:id='fileparsers.parsing.title'>Parsing files</title>
    451 
     362        <section xml:id="fileparsers.parsing">
     363          <title xml:id="fileparsers.parsing.title">Parsing files</title>
    452364          <para>We already discussed that the command-line interface works
    453365          state-based and hence you should supply it with a file to work
    454366          on.</para>
    455 
    456367          <programlisting>... --input water.data</programlisting>
    457 
    458368          <para>This will load all information, especially atoms with their
    459369          element and position, from the file <filename>water.data</filename>
    460           into the state. All changes will eventually be stored to this file,
     370          into the state. Most importantly, all changes will eventually be stored to this file,
    461371          or to files with the prefix <filename>water</filename> and suffixes
    462372          of desired file formats, e.g. <filename>water.in</filename> if you
    463373          specified <productname>MPQC</productname>.</para>
    464 
    465374          <programlisting>... --load morewater.xyz</programlisting>
    466 
    467375          <para>This will load another file <filename>water.xyz</filename>,
    468376          however changes will still be written to files prefixed with
    469           <filename>water</filename>. Note that now already two state files
     377          <filename>water</filename> as designated by the <emphasis role="bold">input</emphasis> command. Note that now already two state files
    470378          will stored, <filename>water.data</filename> and
    471379          <filename>water.xyz</filename> as these two different file formats
    472           have been used.</para>
    473         </section>
    474 
    475         <section xml:id='fileparsers.set-output'>
    476           <title xml:id='fileparsers.set-output.tile'>Adding output file
    477           formats</title>
    478 
     380          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>
     381        </section>
     382        <section xml:id="fileparsers.set-output">
     383          <title xml:id="fileparsers.set-output.tile">Adding output file formats</title>
    479384          <para>We already know that loading a file also picks a file format
    480385          by its suffix. We may add further file formats to which the state of
    481           the molecular system on program exit.</para>
    482 
     386          the molecular system is written to on program exit.</para>
    483387          <programlisting>... --set-output mpqc tremolo</programlisting>
    484 
    485388          <para>This will store the final state of the molecular systems as
    486389          <productname>MPQC</productname> and as
    487           <productname>TREMOLO</productname> configuration file.</para>
    488         </section>
    489 
    490         <section xml:id='fileparsers.output-as'>
    491           <title xml:id='fileparsers.output-as.title'>Output the current
    492           molecular system</title>
    493 
     390          <productname>TREMOLO</productname> configuration file. See
     391        <link linkend="fileformats">File formats</link> for the list of all file formats available.</para>
     392        </section>
     393        <section xml:id="fileparsers.output-as">
     394          <title xml:id="fileparsers.output-as.title">Output the World</title>
    494395          <para>This will store the current World, i.e. all its atoms, to a
    495396          given file, where the output format is determined from the file
    496397          suffix.</para>
    497 
    498398          <programlisting>... --output-as world.xyz</programlisting>
    499         </section>
    500 
    501         <section xml:id='fileparsers.save-selected-molecules'>
    502           <title xml:id='fileparsers.save-selected-molecules.title'>Output
    503           the current molecular system</title>
    504 
     399          <para>This will be automatically done on program exit, but in case an intermediate state is required (making sense for interactive and python interfaces), this command can be used.</para>
     400        </section>
     401        <section xml:id="fileparsers.save-selected-molecules">
     402          <title xml:id="fileparsers.save-selected-molecules.title">Output the current molecular system</title>
    505403          <para>This will store all atoms contained in the currently selected
    506           molecules to file. This is different to "store-saturated-fragment"
     404          molecules to file. This is different to<emphasis role="bold">store-saturated-fragment</emphasis>
    507405          as it will not saturate dangling bonds because only whole molecules,
    508406          i.e. whose bond graph is connected, will be stored.</para>
    509 
    510407          <programlisting>... --save-selected-molecules waters.pdb
    511408          </programlisting>
    512409        </section>
    513 
    514         <section xml:id='fileparsers.bond-file'>
    515           <title xml:id='fileparsers.bond-file.title'>Load extra bond
    516           information</title>
    517 
    518           <para>For some parsers bond information is stored not with the atoms
    519           coordinates but in an extra file. This action parses such a file.</para>
    520 
    521           <programlisting>... --bond-file water.dbond
    522           </programlisting>
    523         </section>
    524       </section>
    525 
    526       <section xml:id='selections'>
    527         <title xml:id='selections.title'>Selections and unselections</title>
    528 
     410      </section>
     411      <section xml:id="selections">
     412        <title xml:id="selections.title">Selections and unselections</title>
    529413        <para>In order to tell MoleCuilder on what subset of atoms a specific
    530         Action is to be performed, there are <emphasis>selection
    531         actions</emphasis>. Note that a selection per se does not change
    532         anything in the state of the molecular system in any way.</para>
    533 
     414        Action is to be performed, there are <emphasis>selection actions</emphasis>. Note that a selection per se does not change
     415        anything in the state of the molecular system in any way. Essentially, it is just a filter.</para>
    534416        <para>Selections either work on atoms, on molecules, or on shapes
    535         (this we explain lateron). A given selection is maintained from the
     417        (this we explain later on). A given selection is maintained from the
    536418        execution of the selection action to the end of program or until
    537419        modified by another selection applied on the same type (atom,
    538         molecule, shape).</para>
    539 
    540         <para>We only give a brief list on the kind of selections per type,
    541         each action is executed either as follows, exemplified by selecting
     420        molecule, shape). Selections are not stored to file (i.e. do not belong to the state).</para>
     421        <para>We only give here a brief list on the available kind of selections for each of the three  types they work on.
     422Each action is executed either as follows, exemplified by selecting
    542423        all atoms.</para>
    543 
    544424        <programlisting>.... --select-all-atoms</programlisting>
    545 
    546425        <para>or, exemplified by unselecting the last molecule,</para>
    547 
    548426        <programlisting>... --unselect-molecule-by-order -1</programlisting>
    549 
     427        <para>i.e. they are prepended by either <emphasis role="bold">select</emphasis> or <emphasis role="bold">unselect</emphasis>.</para>
    550428        <itemizedlist>
    551429          <listitem>
    552430            <para>Atoms</para>
    553 
    554431            <itemizedlist>
    555432              <listitem>
    … …  
    559436                </programlisting>
    560437              </listitem>
    561 
    562438              <listitem>
    563439                <para>None</para>
    … …  
    569445                </programlisting>
    570446              </listitem>
    571 
    572447              <listitem>
    573448                <para>Invert selection</para>
    … …  
    576451                </programlisting>
    577452              </listitem>
    578 
    579453              <listitem>
    580454                <para>By Element (all hydrogen atoms, all sulphur atoms,
    … …  
    587461                </programlisting>
    588462              </listitem>
    589 
    590463              <listitem>
    591464                <para>By Id (atom with id 76)</para>
    … …  
    597470                </programlisting>
    598471              </listitem>
    599 
    600472              <listitem>
    601473                <para>By Order (the first (1), the second, ... the last
    … …  
    608480                </programlisting>
    609481              </listitem>
    610 
    611482              <listitem>
    612                 <para>By Shape (specific region of the domain)</para>
     483                <para>By Shape (all atoms inside the volume specified by the currently selected shape)</para>
    613484                <programlisting>
    614485                ... --select-atom-inside-volume
    … …  
    618489                </programlisting>
    619490              </listitem>
    620 
    621491              <listitem>
    622492                <para>By Molecule (all atoms belonging to currently selected
    … …  
    629499                </programlisting>
    630500              </listitem>
    631 
    632501              <listitem>
    633502                <para>Push/Pop the current selection to/from a stack to store
    634                 it momentarily and allow modifications in MakroActions.</para>
     503  it momentarily and allow modifications in MakroActions (this is very specific and used mostly internally).</para>
    635504                <programlisting>
    636505                ... --push-atom-selection
    … …  
    642511            </itemizedlist>
    643512          </listitem>
    644 
    645513          <listitem>
    646514            <para>Molecules</para>
    647 
    648515            <itemizedlist>
    649516              <listitem>
    … …  
    653520                </programlisting>
    654521              </listitem>
    655 
    656522              <listitem>
    657523                <para>None</para>
    … …  
    663529                </programlisting>
    664530              </listitem>
    665 
    666531              <listitem>
    667532                <para>Invert selection</para>
    … …  
    670535                </programlisting>
    671536              </listitem>
    672 
    673537              <listitem>
    674538                <para>By Id (molecule with id 4)</para>
    … …  
    680544                </programlisting>
    681545              </listitem>
    682 
    683546              <listitem>
    684547                <para>By Order (first created molecule, second created
    … …  
    691554                </programlisting>
    692555              </listitem>
    693 
    694556              <listitem>
    695557                <para>By Formula (molecule with H2O as formula)</para>
    696558                <programlisting>
    697                 ... --select-molecules-by-formula "H2O"
    698                 </programlisting>
    699                 <programlisting>
    700                 ... --unselect-molecules-by-formula "H2O"
     559                ... --select-molecules-by-formula &quot;H2O&quot;
     560                </programlisting>
     561                <programlisting>
     562                ... --unselect-molecules-by-formula &quot;H2O&quot;
    701563                </programlisting>
    702564              </listitem>
    703 
    704565              <listitem>
    705                 <para>By Name (molecule named "water4")</para>
    706                 <programlisting>
    707                 ... --select-molecules-by-name "water4"
    708                 </programlisting>
    709                 <programlisting>
    710                 ... --unselect-molecules-by-name "water4"
     566                <para>By Name (all molecules named &quot;water4&quot;)</para>
     567                <programlisting>
     568                ... --select-molecules-by-name &quot;water4&quot;
     569                </programlisting>
     570                <programlisting>
     571                ... --unselect-molecules-by-name &quot;water4&quot;
    711572                </programlisting>
    712573              </listitem>
    713 
    714574              <listitem>
    715575                <para>By Atom (all molecules for which at least one atom is
    … …  
    722582                </programlisting>
    723583              </listitem>
    724 
    725584              <listitem>
    726585                <para>Push/Pop the current selection to/from a stack to store
    727                 it momentarily and allow modifications in MakroActions.</para>
     586  it momentarily and allow modifications in MakroActions.</para>
    728587                <programlisting>
    729588                ... --push-molecule-selection
    … …  
    735594            </itemizedlist>
    736595          </listitem>
    737 
    738596          <listitem>
    739597            <para>Shapes</para>
    740 
    741598            <itemizedlist>
    742599              <listitem>
    … …  
    746603                </programlisting>
    747604              </listitem>
    748 
    749605              <listitem>
    750606                <para>None</para>
    … …  
    753609                </programlisting>
    754610              </listitem>
    755 
    756611              <listitem>
    757                 <para>By Name (shape name "sphere1")</para>
    758                 <programlisting>
    759                 ... --select-shape-by-name "sphere1"
    760                 </programlisting>
    761                 <programlisting>
    762                 ... --unselect-shape-by-name "sphere1"
     612                <para>By Name (all shapes named &quot;sphere1&quot;)</para>
     613                <programlisting>
     614                ... --select-shape-by-name &quot;sphere1&quot;
     615                </programlisting>
     616                <programlisting>
     617                ... --unselect-shape-by-name &quot;sphere1&quot;
    763618                </programlisting>
    764619              </listitem>
    765620            </itemizedlist>
    766621          </listitem>
    767 
    768622        </itemizedlist>
    769 
    770         <remark>Note that an unselected instance (e.g. an atom) remains
    771         unselected upon further unselection and vice versa with
    772         selection.</remark>
    773 
     623        <remark>Note that an unselected instance (e.g. an atom) remains unselected upon further unselection and vice versa with selection.</remark>
    774624        <para>These above selections work then in conjunction with other
    775625        actions and make them very powerful, e.g. you can remove all atoms
    … …  
    777627        selecting all atoms inside the shape and then removing them.</para>
    778628      </section>
    779 
    780       <section xml:id='shapes'>
    781         <title xml:id='shapes.title'>Shapes</title>
    782 
     629      <section xml:id="shapes">
     630        <title xml:id="shapes.title">Shapes</title>
    783631        <para>Shapes are specific regions of the domain. There are just a few
    784632        so-called <emphasis>primitive</emphasis> shapes such as cuboid,
    785         sphere, cylinder, the whole domain, none of it. However, these can be
     633        sphere, cylinder, the whole domain, or none of it. However, these can be
    786634        combined via boolean operations such as and, or, and not. This
    787635        approach is called <emphasis>constructive geometry</emphasis>. E.g. by
    788         combining a sphere with the negated (not) of a smaller sphere, we
     636        combining a sphere with the negated (<emphasis role="italic">not</emphasis> operation) of a smaller sphere, we
    789637        obtain a spherical surface of specific thickness.</para>
    790 
    791         <section xml:id='shapes.create-shape'>
    792           <title xml:id='shapes.create-shape.title'>Creating shapes</title>
    793 
     638        <section xml:id="shapes.create-shape">
     639          <title xml:id="shapes.create-shape.title">Creating shapes</title>
    794640          <para>Primitive shapes can be created as follows,</para>
    795 
    796           <programlisting>
    797                 ... --create-shape \
    798                     --shape-type sphere \
    799                     --shape-name "sphere1" \
    800                     --stretch "2,2,2" \
    801                     --translation "5,5,5"
    802           </programlisting>
    803 
     641          <programlisting>
     642  ... --create-shape \
     643      --shape-type sphere \
     644      --shape-name &quot;sphere1&quot; \
     645      --stretch &quot;2,2,2&quot; \
     646      --translation &quot;5,5,5&quot;
     647   </programlisting>
    804648          <para>This will create a sphere of radius 2 (initial radius is 1)
    805           with name "sphere1" that is centered at (5,5,5). Other primitives at
     649          with name &quot;sphere1&quot; that is centered at (5,5,5). Other primitives are
    806650          cuboid and cylinder, where a rotation can be specified as
    807651          follows.</para>
    808 
    809           <programlisting>
    810                 ... --create-shape \
    811                     --shape-type cuboid \
    812                     --shape-name "box" \
    813                     --stretch "1,2,2" \
    814                     --translation "5,5,5" \
    815                     --angle-x "90"
    816           </programlisting>
    817         </section>
    818 
    819         <section xml:id='shapes.combine-shapes'>
    820           <title xml:id='shapes.combine-shapes.title'>Combining shapes</title>
    821 
     652          <programlisting><programlisting>
     653  ... --create-shape \
     654      --shape-type cuboid \
     655      --shape-name &quot;box&quot; \
     656      --stretch &quot;1,2,2&quot; \
     657      --translation &quot;5,5,5&quot; \
     658      --angle-x &quot;90&quot;
     659   </programlisting>
     660  ... --create-shape \
     661      --shape-type cylinder \
     662      --shape-name &quot;cylinder&quot; \
     663      --stretch &quot;1,2,2&quot; \
     664      --translation &quot;5,5,5&quot; \
     665      --angle-y &quot;90&quot;
     666   </programlisting>
     667        </section>
     668        <section xml:id="shapes.combine-shapes">
     669          <title xml:id="shapes.combine-shapes.title">Combining shapes</title>
    822670          <para>Any two shapes can be combined by boolean operations as follows</para>
    823 
    824           <programlisting>
    825                 ... --combine-shapes \
    826                     --shape-name "combinedshape" \
    827                     --shape-op "AND" \
    828           </programlisting>
    829 
    830           <para>This will combine two currently selected shapes vis the "AND" operation
    831           and create a new shape called "combinedshape". Note that the two old shapes
     671          <programlisting>
     672  ... --combine-shapes \
     673      --shape-name &quot;combinedshape&quot; \
     674      --shape-op &quot;AND&quot;
     675   </programlisting>
     676          <para>This will combine two currently selected shapes vis the &quot;AND&quot; operation
     677          and create a new shape called &quot;combinedshape&quot;. Note that the two old shapes
    832678          are still present after this operation. We briefly explain each operation:
    833679          </para>
    … …  
    835681            <listitem>
    836682              <para><emphasis>AND</emphasis> combines two currently selected shapes
    837               into a new shape that only consists of the volume where shapes overlap.</para>
     683              into a new shape that consists of only the volume where shapes overlap.</para>
    838684            </listitem>
    839685            <listitem>
    840686              <para><emphasis>OR</emphasis> combines two currently selected shapes
    841               into a new shape that consists of all the volume where that either shape
     687              into a new shape that consists of all the volume that either shape
    842688              occupies.</para>
    843689            </listitem>
    … …  
    849695          </itemizedlist>
    850696        </section>
    851 
    852         <section xml:id='shapes.remove-shape'>
    853           <title xml:id='shapes.remove-shape.title'>Removing shapes</title>
    854 
     697        <section xml:id="shapes.remove-shape">
     698          <title xml:id="shapes.remove-shape.title">Removing shapes</title>
    855699          <para>Removing a shape is as simple as removing an atom.</para>
    856 
    857700          <programlisting>... --remove-shape </programlisting>
    858 
    859           <para>This removes the currently selected shapes.</para>
    860         </section>
    861 
    862         <section xml:id='shapes.manipulation'>
    863           <title xml:id='shapes.manipulation.title'>Manipulating shapes</title>
    864 
     701          <para>This removes all currently selected shapes.</para>
     702        </section>
     703        <section xml:id="shapes.manipulation">
     704          <title xml:id="shapes.manipulation.title">Manipulating shapes</title>
    865705          <para>Shapes can be stretched, scaled, rotated, and translated to
    866706          modify primitives or combined primitive shapes. As you have seen
    867           this manipulation could have occurred already at creation but also
    868           later on. We just the list examples of the various manipulations
    869           below, each works on the currently selected shapes.</para>
    870 
    871           <programlisting>
    872                 ... --stretch-shapes "1,1,2" \
    873                     --stretch-center "5,5,5"
    874           </programlisting>
    875 
     707          this manipulation could have occurred already at creation but we may also
     708do it           later on. As usual, we just list examples of the various manipulations
     709          below, each of them works on the currently selected shapes.</para>
     710          <programlisting>
     711  ... --stretch-shapes &quot;1,1,2&quot; \
     712      --stretch-center &quot;5,5,5&quot;
     713   </programlisting>
    876714          <para>This stretches the shapes relative to the center at (5,5,5)
    877715          (default is origin) by a factor of 2 in the z direction.</para>
    878 
    879           <programlisting>
    880                 ... --rotate-shapes \
    881                     --center "10,2,2" \
    882                     --angle-x 90 \
    883                     --angle-y 0 \
    884                     --angle-z 0
    885           </programlisting>
    886 
     716          <programlisting>
     717  ... --rotate-shapes \
     718      --center &quot;10,2,2&quot; \
     719      --angle-x 90 \
     720      --angle-y 0 \
     721      --angle-z 0
     722   </programlisting>
    887723          <para>This way all selected shapes are rotated by 90 degrees around
    888724          the x axis with respect to the center at (10,2,2).</para>
    889 
    890           <programlisting>... --translate-shapes "5,0,0" </programlisting>
    891 
     725          <programlisting>... --translate-shapes &quot;5,0,0&quot; </programlisting>
    892726          <para>This translates all selected shapes by 5 along the x
    893727          axis.</para>
    894728        </section>
    895729      </section>
    896 
    897       <section xml:id='randomization'>
    898         <title xml:id='randomization.title'>Randomization</title>
    899 
     730      <section xml:id="randomization">
     731        <title xml:id="randomization.title">Randomization</title>
    900732        <para>Some operations require randomness as input, e.g. when filling a
    901733        domain with molecules these may be randomly translated and rotated.
    902734        Random values are obtained by a random number generator that consists
    903         of two parts: engine and distribution. The engine yields a uniform set
     735        of two parts: engine and distribution. The engine yields a <emphasis role="italic">uniform</emphasis> set
    904736        of random numbers in a specific interval, the distribution modifies
    905737        them, e.g. to become gaussian.</para>
    906 
    907738        <para>There are several Actions to modify the specific engine and
    908739        distribution and their parameters. One example usage is that with the
    909         aforementioned filling of the domain molecules are rotated randomly.
     740        aforementioned filling of the domain (see below) molecules are rotated randomly.
    910741        If you specify a random number generator that randomly just spills out
    911742        values 0,1,2,3, then the randomness is just the orientation of the
    912743        molecule with respect to a specific axis: x,y,z. (rotation is at most
    913         360 degrees and 0,1,2,3 act as divisor, hence rotation angle is always
     744        360 degrees and 0,1,2,3 act as divisor, hence rotation angle will then be always
    914745        a multiple of 90 degrees).</para>
    915 
    916746        <programlisting>
    917                 ... --set-random-number-distribution "uniform_int" \
    918                     --random-number-distribution-parameters "p=1"
    919         </programlisting>
    920 
    921         <para>This changes the distribution to "uniform_int", i.e. integer
    922         numbers distributed uniformly.</para>
    923 
     747  ... --set-random-number-distribution &quot;uniform_int&quot; \
     748      --random-number-distribution-parameters &quot;p=1&quot;
     749 </programlisting>
     750        <para>This changes the distribution to &quot;uniform_int&quot;, i.e. integer
     751        numbers that are distributed uniformly.</para>
    924752        <programlisting>
    925                 ... --set-random-number-engine "mt19937" \
    926                     --random-numner-engine-parameters "seed=10"
    927         </programlisting>
    928 
     753  ... --set-random-number-engine &quot;mt19937&quot; \
     754      --random-numner-engine-parameters &quot;seed=10&quot;
     755 </programlisting>
    929756        <para>Specifying the seed allows you to obtain the same sequence of
    930757        random numbers for testing purposes.</para>
    931758      </section>
    932 
    933       <section xml:id='atoms'>
    934         <title xml:id='atoms.title'>Manipulate atoms</title>
    935 
     759      <section xml:id="atoms">
     760        <title xml:id="atoms.title">Manipulate atoms</title>
    936761        <para>Here, we explain in detail how to add, remove atoms, change its
    937762        element type, scale the bond in between or measure the bond length or
    938763        angle.</para>
    939 
    940         <section xml:id='atoms.add-atom'>
    941           <title xml:id='atoms.add-atom.title'>Adding atoms</title>
    942 
     764        <section xml:id="atoms.add-atom">
     765          <title xml:id="atoms.add-atom.title">Adding atoms</title>
    943766          <para>Adding an atom to the domain requires the element of the atom
    944767          and its coordinates as follows,</para>
    945 
    946           <programlisting>
    947                 ... --add-atom O \
    948                     --domain-position "2.,3.,2.35"
    949           </programlisting>
    950 
     768          <programlisting>
     769  ... --add-atom O \
     770      --domain-position &quot;2.,3.,2.35&quot;
     771   </programlisting>
    951772          <para>where the element is given via its chemical symbol and the
    952773          vector gives the position within the domain</para>
    953774        </section>
    954 
    955         <section xml:id='atoms.remove-atom'>
    956           <title xml:id='atoms.remove-atom.title'>Removing atoms</title>
    957 
     775        <section xml:id="atoms.remove-atom">
     776          <title xml:id="atoms.remove-atom.title">Removing atoms</title>
    958777          <para>Removing atom(s) does not need any option and operates on the
    959778          currently selected ones.</para>
    960 
    961779          <programlisting>... --remove-atom</programlisting>
    962780        </section>
    963 
    964         <section xml:id='atoms.saturate-atom'>
    965           <title xml:id='atoms.saturate-atom.title'>Saturating atoms</title>
    966 
     781        <section xml:id="atoms.saturate-atom">
     782          <title xml:id="atoms.saturate-atom.title">Saturating atoms</title>
    967783          <para>Newly instantiated atoms have no bonds to any other atom. If
    968784          you want to fill up their valence by a slew of hydrogen atoms
    969785          residing on a sphere around this atom, use this action.</para>
    970 
    971           <programlisting>
    972                 ... --saturate-atoms
    973           </programlisting>
    974 
    975           <para>A number of hydrogen atoms is added. The number corrresponding
    976           to the valence of each selected atom. They are placed in the same
     786          <programlisting>
     787  ... --saturate-atoms
     788   </programlisting>
     789          <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 in the same
    977790          distance to this atom and approximately with same distance to their
    978           nearest neighbors.</para>
    979         </section>
    980 
    981         <section xml:id='atoms.translate-atom'>
    982           <title xml:id='atoms.translate-atom.title'>Translating atoms</title>
    983 
     791   nearest neighbors. Already present bonds (i.e. the position of neighboring atoms) is taken into account.</para>
     792        </section>
     793        <section xml:id="atoms.translate-atom">
     794          <title xml:id="atoms.translate-atom.title">Translating atoms</title>
    984795          <para>In order to translate the current selected subset of atoms you
    985           specify a translation vector.</para>
    986 
    987           <programlisting>
    988                 ... --translate-atoms "-1,0,0" \
    989                     --periodic 0
    990           </programlisting>
    991 
    992           <para>This translate all atoms by "-1" along the x axis and does not
    993           mind the boundary conditions, i.e. might shift atoms outside of the
     796have to          specify a translation vector.</para>
     797          <programlisting>
     798  ... --translate-atoms &quot;-1,0,0&quot; \
     799      --periodic 0
     800   </programlisting>
     801          <para>This translates all atoms by &quot;-1&quot; along the x axis and does not
     802          mind the boundary conditions, i.e. it might shift atoms outside of the
    994803          domain.</para>
    995804        </section>
    996 
    997         <section xml:id='atoms.mirror-atoms'>
    998           <title xml:id='atoms.mirror-atoms.title'>Mirroring atoms</title>
    999 
     805        <section xml:id="atoms.mirror-atoms">
     806          <title xml:id="atoms.mirror-atoms.title">Mirroring atoms</title>
    1000807          <para>Present (and selected) atoms can be mirrored with respect to
    1001808          a certain plane. You have to specify the normal vector of the plane
    1002809          and the offset with respect to the origin as follows</para>
    1003 
    1004           <programlisting>
    1005                 ... --mirror-atoms "1,0,0" \
     810          <programlisting>
     811  ... --mirror-atoms &quot;1,0,0&quot; \
    1006812                    --plane-offset 10.1 \
    1007813                    --periodic 0
    1008           </programlisting>
    1009         </section>
    1010 
    1011         <section xml:id='atoms.translate-to-origin'>
    1012           <title xml:id='atoms.translate-to-origin.title'>Translating atoms</title>
    1013 
     814   </programlisting>
     815        </section>
     816        <section xml:id="atoms.translate-to-origin">
     817          <title xml:id="atoms.translate-to-origin.title">Translating atoms to origin</title>
    1014818          <para>The following Action is convenient to place a subset of atoms
    1015           at a known position, the origin, and then translate to some other
     819          at a known position, the origin, and then translate them to some other
    1016820          absolute coordinate. It calculates the average position of the set
    1017821          of selected atoms and then translates all atoms by the negative of
    1018           this center, i.e. the center is afterwards at the origin.</para>
    1019 
     822          this center, i.e. the center over all selected atoms is afterwards at the origin.</para>
    1020823          <programlisting>... --translate-to-origin</programlisting>
    1021         </section>
    1022 
    1023         <section xml:id='atoms.change-element'>
    1024           <title xml:id='atoms.change-element.title'>Changing an atoms element
    1025           </title>
    1026 
     824          <para>Note that this naturally does not heed the boundary conditions of the simulation domain.</para>
     825        </section>
     826        <section xml:id="atoms.change-element">
     827          <title xml:id="atoms.change-element.title">Changing an atoms element </title>
    1027828          <para>You can easily turn lead or silver into gold, by selecting the
    1028829          silver atom and calling the change element action.</para>
    1029 
    1030830          <programlisting>... --change-element Au</programlisting>
    1031831        </section>
    1032832      </section>
    1033 
    1034       <section xml:id='bond'>
    1035         <title xml:id='bond.title'>Bond-related manipulation</title>
    1036 
     833      <section xml:id="bond">
     834        <title xml:id="bond.title">Bond-related manipulation</title>
    1037835        <para>Atoms can also be manipulated with respect to the bonds.
    1038         <remark>Note that with bonds we always mean covalent bonds.</remark>
    1039         First, we explain how to modify the bond structure itself, then we go
     836        <remark>Note that with bonds we always mean covalent bonds.</remark>      First, we explain how to modify the bond structure itself, then we go
    1040837        in the details of using the bond information to change bond distance
    1041838        and angles.</para>
    1042 
    1043         <section xml:id='bond.create-adjacency'>
    1044           <title xml:id='bond.create-adjacency.title'>Creating a bond graph
    1045           </title>
    1046 
     839        <section xml:id="bond.create-adjacency">
     840          <title xml:id="bond.create-adjacency.title">Creating a bond graph </title>
    1047841          <para>In case you have loaded a configuration file with no bond
    1048842          information, e.g. XYZ, it is necessary to create the bond graph.
    1049843          This is done by a heuristic distance criterion.</para>
    1050 
    1051844          <programlisting>... --create-adjacency</programlisting>
    1052 
    1053845          <para>This uses by default a criterion based on van-der-Waals radii,
    1054           i.e. if we look at two atoms indexed by "a" and "b"</para>
    1055 
     846          i.e. if we look at two atoms indexed by &quot;a&quot; and &quot;b&quot;</para>
    1056847          <equation>
    1057             <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) +
    1058             \tau</title>
    1059 
     848            <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) + \tau</title>
    1060849            <m:math display="block">
    1061               <m:mi>where V(.) is the lookup table for the radii for a given
    1062               element and \tau is a threshold value, set to 0.4.</m:mi>
     850              <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>
    1063851            </m:math>
    1064852          </equation>
    1065 
    1066853          <para>As a second option, you may load a file containing bond table
    1067854          information.</para>
    1068 
    1069855          <programlisting>... --bond-table table.dat</programlisting>
    1070 
    1071856          <para>which would parse a file <filename>table.dat</filename> for a
    1072857          table giving typical bond distances between elements a and b. These
    … …  
    1081866            </inlineequation>.</para>
    1082867        </section>
    1083 
    1084         <section xml:id='bond.destroy-adjacency'>
    1085           <title xml:id='bond.destroy-adjacency.title'>Destroying the bond
    1086           graph</title>
    1087 
     868        <section xml:id="bond.destroy-adjacency">
     869          <title xml:id="bond.destroy-adjacency.title">Destroying the bond graph</title>
    1088870          <para>The bond graph can be removed completely (and all bonds along
    1089871          with it).</para>
    1090 
    1091872          <programlisting>... --destroy-adjacency</programlisting>
    1092873        </section>
    1093 
    1094         <section xml:id='bond.correct-bonddegree'>
    1095           <title xml:id='bond.correct-bonddegree.title'>Correcting bond
    1096           degrees</title>
    1097 
    1098           <para>Typically, after loading an input file bond information, e.g.
     874        <section xml:id="bond.correct-bonddegree">
     875          <title xml:id="bond.correct-bonddegree.title">Correcting bond degrees</title>
     876          <para>Typically, after loading an input file with bond information, e.g.
    1099877          a PDB file, the bond graph is complete but we lack the weights. That
    1100878          is we do not know whether a bond is single, double, triple, ...
    … …  
    1105883          atoms. Hence, for large systems this may take longer than expected.
    1106884          </para>
    1107 
    1108885          <programlisting>... --correct-bonddegree</programlisting>
    1109         </section>
    1110 
    1111         <section xml:id='bond.depth-first-search'>
    1112           <title xml:id='bond.depth-first-search.title'>Analysing a bond
    1113           graph</title>
    1114 
     886          <para>However, in normal use scenarios the action is fast and linear scaling.</para>
     887        </section>
     888        <section xml:id="bond.depth-first-search">
     889          <title xml:id="bond.depth-first-search.title">Analysing a bond graph</title>
    1115890          <para>You can perform a depth-first search analysis that reveals
    1116891          cycles and other graph-related information.</para>
    1117 
    1118892          <programlisting>... --depth-first-search</programlisting>
    1119         </section>
    1120 
    1121         <section xml:id='bond.subgraph-dissection'>
    1122           <title xml:id='bond.subgraph-dissection.title'>Dissecting the
    1123           molecular system into molecules</title>
    1124 
     893          <para>Note that this will only print some information and has no other impact on the state.</para>
     894        </section>
     895        <section xml:id="bond.subgraph-dissection">
     896          <title xml:id="bond.subgraph-dissection.title">Dissecting the molecular system into molecules</title>
    1125897          <para>The bond graph information can be used to recognize the
    1126           molecule within the system. Imagine you have just loaded a PDB file
     898          molecules within the system. Imagine you have just loaded a PDB file
    1127899          containing bond information. However, initially all atoms are dumped
    1128900          into the same molecule. Before you can start manipulating, you need
    … …  
    1130902          just structural information and does not change the state of the
    1131903          system.</para>
    1132 
    1133904          <programlisting>... --subgraph-dissection</programlisting>
    1134 
    1135           <para>This analyses the bond graph and splits the single molecule up
    1136           into individual (new) ones that each contain a single connected
    1137           subgraph, hence the naming.</para>
    1138         </section>
    1139 
    1140         <section xml:id='bond.update-molecules'>
    1141           <title xml:id='bond.update-molecules.title'>Updating molecule
    1142           structure</title>
    1143 
     905          <para>This analyses the bond graph, removes all currently present molecules and creates new molecules that each contain a single connected
     906          subgraph, hence the naming of the Action.</para>
     907        </section>
     908        <section xml:id="bond.update-molecules">
     909          <title xml:id="bond.update-molecules.title">Updating molecule structure</title>
    1144910          <para>When the bond information has changed, new molecules might
    1145911          have formed, this action updates all the molecules by scanning
    1146           the connectedness of the bond grapf of the molecular system.
     912          the connectedness of the bond graph of the molecular system.
    1147913          </para>
    1148 
    1149914          <programlisting>... --update-molecules</programlisting>
    1150915        </section>
    1151 
    1152         <section xml:id='bond.adds-bond'>
    1153           <title xml:id='bond.adds-bond.title'>Adding a bond manually</title>
    1154 
     916        <section xml:id="bond.adds-bond">
     917          <title xml:id="bond.adds-bond.title">Adding a bond manually</title>
    1155918          <para>When the automatically created adjacency or bond graph
    1156919          contains faulty bonds or lacks some, you can add them manually.
    1157920          </para>
    1158 
    1159921          <programlisting>... --add-bonds</programlisting>
    1160 
    1161           <para>If two atoms are selected, the single bond in between, if not
    1162           present, is added. If more than two atoms are selected, than the
    1163           bond between any pair of these is added.</para>
    1164          <note><para>This is especially useful in conjunction with the
    1165           fragmentation scheme. If you want to know the contribution from
    1166           certain fragments whose subgraph is not connected you can simply
    1167           make the associated subset of atoms connected by selecting all
    1168           bonds and adding the bonds.</para>
    1169          </note>
    1170         </section>
    1171 
    1172         <section xml:id='bond.remove-bonds'>
    1173           <title xml:id='bond.remove-bonds.title'>Removing a bond manually
    1174           </title>
    1175 
     922          <para>If two atoms are selected, the single bond in between is added, if not
     923already    present. If more than two atoms are selected, than the
     924   bond between any pair of these is added.</para>
     925          <note>
     926            <para>This is especially useful in conjunction with the
     927   fragmentation scheme (explained later on). If you want to know the contribution from
     928   certain fragments whose subgraph is not connected, you can simply
     929   make the associated subset of atoms connected by selecting all
     930   bonds and adding the bonds.</para>
     931          </note>
     932        </section>
     933        <section xml:id="bond.remove-bonds">
     934          <title xml:id="bond.remove-bonds.title">Removing a bond manually </title>
    1176935          <para>In much the same way as adding a bond, you can also remove a
    1177936          bond.</para>
    1178 
    1179937          <programlisting>... --remove-bonds</programlisting>
    1180 
    1181           <para>Similarly, if more than two atoms are selected, then all bonds
    1182           found between any pair of these is removed.</para>
    1183         </section>
    1184 
    1185         <section xml:id='bond.save-bonds'>
    1186           <title xml:id='bond.save-bonds.title'>Saving bond information
    1187           </title>
    1188 
    1189           <para>Bond information can be saved to a file in <link
    1190           xlink:href="http://www.molecuilder.com/"><productname>TREMOLO
    1191           </productname></link>'s dbond style.</para>
    1192 
     938          <para>Similarly, if more than two atoms are selected, then all bonds
     939   found between any pair of these is removed.</para>
     940        </section>
     941        <section xml:id="bond.save-bonds">
     942          <title xml:id="bond.save-bonds.title">Saving bond information </title>
     943          <para>Bond information can be saved to a file in <link xlink:href="http://www.molecuilder.com/">
     944              <productname>TREMOLO </productname>
     945            </link>&apos;s dbond style.</para>
    1193946          <programlisting>... --save-bonds system.dbonds</programlisting>
    1194          
    1195947          <para>Similarly is the following Action which saves the bond
    1196948          information as a simple list of one atomic id per line and in
    1197949          the same line, separated by spaces, the ids of all atoms connected
    1198950          to it.</para>
    1199          
    1200951          <programlisting>... --save-adjacency system.adj</programlisting>
    1201          
    1202         </section>
    1203 
    1204         <section xml:id='bond.stretch-bond'>
    1205           <title xml:id='bond.stretch-bond.title'>Stretching a bond</title>
    1206 
     952          <para>This corresponds to the <emphasis role="bold">bond-file</emphasis> Action.</para>
     953        </section>
     954        <section xml:id="fileparsers.bond-file">
     955          <title xml:id="fileparsers.bond-file.title">Load extra bond information</title>
     956          <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>
     957          <programlisting>... --bond-file water.dbond</programlisting>
     958          <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>
     959        </section>
     960        <section xml:id="bond.stretch-bond">
     961          <title xml:id="bond.stretch-bond.title">Stretching a bond</title>
    1207962          <para>Stretching a bond actually refers to translation of the
    1208963          associated pair of atoms. However, this action will keep the rest of
    1209964          the molecule to which both atoms belong to invariant as well.</para>
    1210 
    1211965          <programlisting>... --stretch-bond 1.2</programlisting>
    1212 
    1213966          <para>This scales the original bond distance to the new bond
    1214967          distance 1.2, shifting the right hand side and the left hand side of
    1215968          the molecule accordingly.</para>
    1216 
    1217969          <warning>
    1218970            <para>this fails with aromatic rings (but you can always
    … …  
    1220972          </warning>
    1221973        </section>
    1222 
    1223         <section xml:id='bond.change-bond-angle'>
    1224           <title xml:id='bond.change-bond-angle.title'>Changing a bond angle
    1225           </title>
    1226 
     974        <section xml:id="bond.change-bond-angle">
     975          <title xml:id="bond.change-bond-angle.title">Changing a bond angle </title>
    1227976          <para>In the same way as stretching a bond, you can change the angle
    1228977          in between two bonds. This works if exactly three atoms are selected
    1229978          and two pairs are bonded.</para>
    1230 
    1231979          <programlisting>... --change-bond-angle 90</programlisting>
    1232 
    1233           <para>This will change the angle from its value to 90 degree by
     980          <para>This will change the angle from its value to 90 degrees by
    1234981          translating the two outer atoms of this triangle (the atom connected
    1235           to both others is the axis of the rotation).</para>
    1236         </section>
    1237       </section>
    1238 
    1239       <section xml:id='molecule'>
    1240         <title xml:id='molecule.title'>Manipulate molecules</title>
    1241 
    1242         <para>Molecules are agglomerations of atoms that are bonded. Hence,
    1243         the actions working on molecules differ from those working on atoms.
     982          to both other atoms serves as rotation joint).</para>
     983        </section>
     984      </section>
     985      <section xml:id="molecule">
     986        <title xml:id="molecule.title">Manipulate molecules</title>
     987        <para>Molecules are agglomerations of atoms that are (covalently) bonded. Hence,
     988        the Actions working on molecules differ from those working on atoms.
    1244989        Joining two molecules can only be accomplished by adding a bond in
    1245990        between, and in the reverse fashion splitting a molecule by removing
    1246         all bonds in between. Actions below mostly deal with copying
    1247         molecules. Removing of molecules is done via selecting the molecule's
     991some or even        all bonds in between. The Actions below mostly deal with copying
     992        molecules. Removing of molecules is done via selecting the molecule&apos;s
    1248993        atoms and removing them, which removes the atoms as well.</para>
    1249 
    1250994        <note>
    1251995          <para>Initially when you load a file via the input action all atoms
    1252996          are placed in a single molecule despite any present bond
    1253           information, see <link linkend="fragmentation">Dissecting the
    1254           molecular system into molecules</link></para>
     997          information, see <link linkend="fragmentation">Dissecting the molecular system into molecules</link></para>
    1255998        </note>
    1256 
    1257         <section xml:id='molecule.copy'>
    1258           <title xml:id='molecule.copy.title'>Copy molecules</title>
    1259 
     999        <section xml:id="molecule.copy">
     1000          <title xml:id="molecule.copy.title">Copy molecules</title>
    12601001          <para>A basic operation is to duplicate a molecule. This works on a
    12611002          single, currently selected molecule. Afterwards, we elaborate on a
    12621003          more complex manner of copying, filling a specific shape with
    12631004          molecules.</para>
    1264 
    1265           <programlisting>
    1266                 ... --copy-molecule \
    1267                     --position "10,10,10"
    1268           </programlisting>
    1269 
     1005          <programlisting>
     1006  ... --copy-molecule \
     1007      --position &quot;10,10,10&quot;
     1008   </programlisting>
    12701009          <para>This action copies the selected molecule and inserts it at the
    1271           position (10,10,10) in the domain with respect to the molecule's
     1010          position (10,10,10) in the domain with respect to the molecule&apos;s
    12721011          center. In effect, it copies all the atoms of the original molecule
    12731012          and adds new bonds in between these copied atoms such that their
    12741013          bond subgraphs are identical.</para>
    12751014        </section>
    1276 
    1277         <section xml:id='molecule.change-molname'>
    1278           <title xml:id='molecule.change-molname.title'>Change a molecules
    1279           name</title>
    1280 
     1015        <section xml:id="molecule.change-molname">
     1016          <title xml:id="molecule.change-molname.title">Change a molecules name</title>
    12811017          <para>You can change the name of a molecule which is important for
    12821018          selection.</para>
    1283 
    1284           <programlisting>... -change-molname "test</programlisting>
    1285 
     1019          <programlisting>... -change-molname &quot;test</programlisting>
    12861020          <para>This will change the name of the (only) selected molecule to
    1287           "test".</para>
    1288 
     1021          &quot;test&quot;.</para>
    12891022          <para>Connected with this is the default name an unknown molecule
    12901023          gets.</para>
    1291 
    12921024          <programlisting>... --default-molname test</programlisting>
    1293 
    1294           <para>This will change the default name of a molecule to
    1295           "test".</para>
    1296 
     1025          <para>This will change the default name of new molecules to
     1026          &quot;test&quot;.</para>
    12971027          <note>
    12981028            <para>Note that a molecule loaded from file gets the filename
    … …  
    13001030          </note>
    13011031        </section>
    1302 
    1303         <section xml:id='molecule.remove-molecule'>
    1304           <title xml:id='molecule.remove-molecule.title'>Remove molecules
    1305           </title>
    1306 
     1032        <section xml:id="molecule.remove-molecule">
     1033          <title xml:id="molecule.remove-molecule.title">Remove molecules </title>
    13071034          <para>This removes one or multiple selected molecules.</para>
    1308 
    13091035          <programlisting>... -remove-molecule</programlisting>
    1310 
    1311           <para>This essentially just removes all of the molecules' atoms
     1036          <para>This essentially just removes all of the molecules&apos; atoms
    13121037          which in turn also causes the removal of the molecule.</para>
    13131038        </section>
    1314 
    1315         <section xml:id='molecule.translate-molecules'>
    1316           <title xml:id='molecule.translate-molecules.title'>Translate molecules
    1317           </title>
    1318 
     1039        <section xml:id="molecule.translate-molecules">
     1040          <title xml:id="molecule.translate-molecules.title">Translate molecules </title>
    13191041          <para>This translates one or multiple selected molecules by a
    1320           specific offset..</para>
    1321 
     1042   specific offset..</para>
    13221043          <programlisting>... -translate-molecules</programlisting>
    1323 
    1324           <para>This essentially translates all of the molecules' atoms.</para>
    1325         </section>
    1326 
    1327         <section xml:id='molecule.rotate-around-self'>
    1328           <title xml:id='molecule.rotate-around-self.title'>Rotate around self
    1329           </title>
    1330 
     1044          <para>As before, this is actually just an operation on all of the molecule&apos;s atoms, namely translating them.</para>
     1045        </section>
     1046        <section xml:id="molecule.rotate-around-self">
     1047          <title xml:id="molecule.rotate-around-self.title">Rotate around self </title>
    13311048          <para>You can rotate a molecule around its own axis.</para>
    1332 
    1333           <programlisting>
    1334                 ... --rotate-around-self "90" \
    1335                     --axis "0,0,1"
    1336           </programlisting>
    1337 
     1049          <programlisting>
     1050  ... --rotate-around-self &quot;90&quot; \
     1051      --axis &quot;0,0,1&quot;
     1052   </programlisting>
    13381053          <para>This rotates the molecule around the z axis by 90 degrees as
    1339           if the origin were at its center of origin.</para>
    1340         </section>
    1341 
    1342         <section xml:id='molecule.rotate-around-origin'>
    1343           <title xml:id='molecule.rotate-around-origin.title'>Rotate around
    1344           origin</title>
    1345 
     1054          if the origin were at its wn center of origin.</para>
     1055        </section>
     1056        <section xml:id="molecule.rotate-around-origin">
     1057          <title xml:id="molecule.rotate-around-origin.title">Rotate around origin</title>
    13461058          <para>In the same manner the molecule can be rotated around an
    13471059          external origin.</para>
    1348 
    1349           <programlisting>
    1350                 ... --rotate-around-origin 90 \
    1351                     --position "0,0,1"\
    1352           </programlisting>
    1353 
     1060          <programlisting>
     1061  ... --rotate-around-origin 90 \
     1062      --position &quot;0,0,1&quot;\
     1063   </programlisting>
    13541064          <para>This rotates the molecule around an axis from the origin to
    13551065          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
    13561066        </section>
    1357 
    1358         <section xml:id='molecule.rotate-to-principal-axis-system'>
    1359           <title xml:id='molecule.rotate-to-principal-axis-system.title'>
    1360           Rotate to principal axis system</title>
    1361 
     1067        <section xml:id="molecule.rotate-to-principal-axis-system">
     1068          <title xml:id="molecule.rotate-to-principal-axis-system.title"> Rotate to principal axis system</title>
    13621069          <para>The principal axis system is given by an ellipsoid that mostly
    1363           matches the molecules shape. The principal axis system can be just
     1070          matches the molecules shape. The principal axis system can be
    13641071          simply determined by</para>
    1365 
    13661072          <programlisting>... --principal-axis-system</programlisting>
    1367 
    13681073          <para>To rotate the molecule around itself to align with this system
    1369           do as follows.</para>
    1370 
    1371           <programlisting>... --rotate-to-principal-axis-system "0,0,1"
     1074          do as follows</para>
     1075          <programlisting>... --rotate-to-principal-axis-system &quot;0,0,1&quot;
    13721076          </programlisting>
    1373 
    13741077          <para>This rotates the molecule in such a manner that the ellipsoids
    1375           largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
    1376           would align anti-parallel.</remark></para>
    1377         </section>
    1378 
    1379         <section xml:id='molecule.verlet-integration'>
    1380           <title xml:id='molecule.verlet-integration.title'>Perform verlet
    1381           integration</title>
    1382 
     1078          largest axis is aligned with the z axis. <remark>Note that &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
     1079        </section>
     1080        <section xml:id="molecule.verlet-integration">
     1081          <title xml:id="molecule.verlet-integration.title">Perform verlet integration</title>
    13831082          <para>Atoms not only have a position, but each instance also stores
    13841083          velocity and a force vector. These can be used in a velocity verlet
    1385           integration step. Velocity verlet is a often employed time
     1084          integration step. Velocity verlet is an often employed time
    13861085          integration algorithm in molecular dynamics simulations.</para>
    1387 
    1388           <programlisting>
    1389                 ... --verlet-integration \
    1390                     --deltat 0.1 \
    1391                     --keep-fixed-CenterOfMass 0
    1392           </programlisting>
    1393 
     1086          <programlisting>
     1087  ... --verlet-integration \
     1088      --deltat 0.1 \
     1089      --keep-fixed-CenterOfMass 0
     1090   </programlisting>
    13941091          <para>This will integrate with a timestep of <inlineequation>
    13951092              <m:math display="inline">
    … …  
    13991096          the sum over all atoms is zero.</para>
    14001097        </section>
    1401 
    1402         <section xml:id='molecule.force-annealing'>
    1403           <title xml:id='molecule.force-annealing.title'>Anneal the atomic
    1404           forces</title>
    1405 
     1098        <section xml:id="molecule.force-annealing">
     1099          <title xml:id="molecule.force-annealing.title">Anneal the atomic forces</title>
    14061100          <para>This will shift the atoms in a such a way as to decrease (or
    14071101          anneal) the forces acting upon them.</para>
    1408 
    14091102          <para>Forces may either be already present for the set of atoms by
    14101103          some other way (e.g. from a prior fragmentation calculation) or,
    1411           as shown here, from an external file. We anneal the forces for
     1104          as shown here, loaded from an external file. We anneal the forces for
    14121105          one step with a certain initial step width of 0.5 atomic time
    14131106          units and do not create a new timestep for each optimization
    14141107          step.</para>
    1415 
    14161108          <programlisting>
    14171109          ... --force-annealing \
    … …  
    14221114          </programlisting>
    14231115        </section>
    1424 
    1425         <section xml:id='molecule.linear-interpolation-of-trajectories'>
    1426           <title xml:id='molecule.linear-interpolation-of-trajectories.title'>
    1427           Linear interpolation between configurations</title>
    1428 
    1429           <para>This is similar to verlet-integration, only that it performs
     1116        <section xml:id="molecule.linear-interpolation-of-trajectories">
     1117          <title xml:id="molecule.linear-interpolation-of-trajectories.title"> Linear interpolation between configurations</title>
     1118          <para>This is similar to verlet integration, only that it performs
    14301119          a linear integration irrespective of the acting atomic forces.
    14311120          </para>
    1432 
    14331121          <para>The following call will produce an interpolation between the
    14341122          configurations in time step 0 and time step 1 with 98 intermediate
    14351123          steps, i.e. current step 1 will end up in time step 99. In this
    1436           case an idential mapping is used to associated atoms in start and
     1124          case an identity mapping is used to associated atoms in start and
    14371125          end configuration.</para>
    1438 
    14391126          <programlisting>
    14401127          ... --linear-interpolation-of-trajectories \
    … …  
    14461133        </section>
    14471134      </section>
    1448 
    1449       <section xml:id='domain'>
    1450         <title xml:id='domain.title'>Manipulate domain</title>
    1451 
     1135      <section xml:id="domain">
     1136        <title xml:id="domain.title">Manipulate domain</title>
    14521137        <para>Here, we elaborate on how to duplicate all the atoms inside the
    1453         domain, how the scale the coordinate system, how to center the atoms
     1138        domain, how to scale the coordinate system, how to center the atoms
    14541139        with respect to certain points, how to realign them by given
    14551140        constraints, how to mirror and most importantly how to specify the
    14561141        domain.</para>
    1457 
    1458         <section xml:id='domain.change-box'>
    1459           <title xml:id='domain.change-box.title'>Changing the domain</title>
    1460 
     1142        <section xml:id="domain.change-box">
     1143          <title xml:id="domain.change-box.title">Changing the domain</title>
    14611144          <para>The domain is specified by a symmetric 3x3 matrix. The
    14621145          eigenvalues (diagonal entries in case of a diagonal matrix) give the
    14631146          length of the edges, additional entries specify transformations of
    14641147          the box such that it becomes a more general parallelepiped.</para>
    1465 
    1466           <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
    1467 
     1148          <programlisting>... change-box &quot;20,0,20,0,0,20&quot;</programlisting>
    14681149          <para>As the domain matrix is symmetric, six values suffice to fully
    1469           specify it. We have to give the six components of the lower diagonal
    1470           matrix. Here, we change the box to a cuboid of equal edge length of
    1471           20.</para>
    1472         </section>
    1473 
    1474         <section xml:id='domain.bound-in-box'>
    1475           <title xml:id='domain.bound-in-box.title'>Bound atoms inside box
    1476           </title>
    1477 
     1150          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
     1151          20.<warning>
     1152              <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>
     1153            </warning></para>
     1154        </section>
     1155        <section xml:id="domain.bound-in-box">
     1156          <title xml:id="domain.bound-in-box.title">Bound atoms inside box </title>
    14781157          <para>The following applies the current boundary conditions to the
    14791158          atoms. In case of periodic or wrapped boundary conditions the atoms
    14801159          will be periodically translated to be inside the domain
    14811160          again.</para>
    1482 
    14831161          <programlisting>... --bound-in-box</programlisting>
    14841162        </section>
    1485 
    1486         <section xml:id='domain.center-in-box'>
    1487           <title xml:id='domain.center-in-box.title'>Center atoms inside the
    1488           domain</title>
    1489 
     1163        <section xml:id="domain.center-in-box">
     1164          <title xml:id="domain.center-in-box.title">Center atoms inside the domain</title>
    14901165          <para>This is a combination of changing the box and bounding the
    14911166          atoms inside it.</para>
    1492 
    1493           <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
    1494         </section>
    1495 
    1496         <section xml:id='domain.center-edge'>
    1497           <title xml:id='domain.center-edge.title'>Center the atoms at an
    1498           edge</title>
    1499 
     1167          <programlisting>... --center-in-box &quot;20,0,20,0,0,20&quot;</programlisting>
     1168        </section>
     1169        <section xml:id="domain.center-edge">
     1170          <title xml:id="domain.center-edge.title">Center the atoms at an edge</title>
    15001171          <para>MoleCuilder can calculate the minimum box (parallel to the
    15011172          cardinal axis) all atoms would fit in and translate all atoms in
    15021173          such a way that the lower, left, front edge of this minimum is at
    15031174          the origin (0,0,0).</para>
    1504 
    15051175          <programlisting>... --center-edge</programlisting>
    15061176        </section>
    1507 
    1508         <section xml:id='domain.add-empty-boundary'>
    1509           <title xml:id='domain.add-empty-boundary.title'>Extending the
    1510           boundary by adding an empty boundary</title>
    1511 
     1177        <section xml:id="domain.add-empty-boundary">
     1178          <title xml:id="domain.add-empty-boundary.title">Extending the boundary by adding an empty boundary</title>
    15121179          <para>In the same manner as above a minimum box is determined that
    15131180          is subsequently expanded by a boundary of the given additional
    1514           thickness. This applies to either side.</para>
    1515 
    1516           <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
    1517 
     1181          thickness. This applies to either side, i.e. left and right, top and bottom, front and back.</para>
     1182          <programlisting>... --add-empty-boundary &quot;5,5,5&quot;</programlisting>
    15181183          <para>This will enlarge the box in such a way that every atom is at
    15191184          least by a distance of 5 away from the boundary of the domain (in
    15201185          the infinity norm).</para>
    15211186        </section>
    1522 
    1523         <section xml:id='domain.scale-box'>
    1524           <title xml:id='domain.scale-box.title'>Scaling the box</title>
    1525 
     1187        <section xml:id="domain.scale-box">
     1188          <title xml:id="domain.scale-box.title">Scaling the box</title>
    15261189          <para>You can enlarge the domain by simple scaling factors.</para>
    1527 
    1528           <programlisting>... --scale-box "1,1,2.5"</programlisting>
    1529 
     1190          <programlisting>... --scale-box &quot;1,1,2.5&quot;</programlisting>
    15301191          <para>Here, the domain is stretched in the z direction by a factor
    15311192          of 2.5.</para>
    15321193        </section>
    1533 
    1534         <section xml:id='domain.repeat-box'>
    1535           <title xml:id='domain.repeat-box.title'>Repeating the box</title>
    1536 
     1194        <section xml:id="domain.repeat-box">
     1195          <title xml:id="domain.repeat-box.title">Repeating the box</title>
    15371196          <para>Under periodic boundary conditions often only the minimal
    1538           periodic cell is stored. If need be, multiple images can be easily
     1197          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
    15391198          added to the current state of the system by repeating the box, i.e.
    15401199          the box along with all contained atoms is copied and placed
    15411200          adjacently.</para>
    1542 
    1543           <programlisting>... --repeat-box "1,2,2"</programlisting>
    1544 
     1201          <programlisting>... --repeat-box &quot;1,2,2&quot;</programlisting>
    15451202          <para>This will create a 2x2 grid of the current domain, replicating
    15461203          it along the y and z direction along with all atoms. If the domain
    … …  
    15481205          them.</para>
    15491206        </section>
    1550        
    1551         <section xml:id='domain.set-boundary-conditions'>
    1552           <title xml:id='domain.set-boundary-conditions.title'>Change the
    1553           boundary conditions</title>
    1554 
     1207        <section xml:id="domain.set-boundary-conditions">
     1208          <title xml:id="domain.set-boundary-conditions.title">Change the boundary conditions</title>
    15551209          <para>Various boundary conditions can be applied that affect how
    15561210          certain Actions work, e.g. translate-atoms. We briefly give a list
    … …  
    15721226            </listitem>
    15731227          </itemizedlist>
    1574          
    15751228          <para>The following will set the boundary conditions to periodic.
    15761229          </para>
    1577 
    1578           <programlisting>... --set-boundary-conditions "Wrap Wrap Wrap"
    1579           </programlisting>
    1580         </section>
    1581       </section>
    1582 
    1583       <section xml:id='filling'>
    1584         <title xml:id='filling.title'>Filling</title>
    1585        
    1586           <para>Filling a specific part of the domain with one type of
     1230          <programlisting>... --set-boundary-conditions &quot;Wrap Wrap Wrap&quot;</programlisting>
     1231          <para>Note that boundary conditions are not enforced unless explicitly requested, e.g. by the <emphasis role="bold">bound-in-box</emphasis> action</para>
     1232        </section>
     1233      </section>
     1234      <section xml:id="filling">
     1235        <title xml:id="filling.title">Filling</title>
     1236        <para>Filling a specific part of the domain with one type of
    15871237          molecule, e.g. a water molecule, is the more advanced type of
    1588           copying of a molecule (see copy-molecule) and we need several
     1238          copying of a molecule (see <emphasis role="bold">copy-molecule</emphasis>) and for this we need several
    15891239          ingredients.</para>
    1590 
    1591           <para>First, we need to specify the part of the domain. This is done
     1240        <para>First, we need to specify the part of the domain. This is done
    15921241          via a shape. We have already learned how to create and select
    15931242          shapes. The currently selected shape will serve as the fill-in
    15941243          region.</para>
    1595 
    1596           <para>Then, they are three types of filling, domain, volume, and
     1244        <para>Then, there are three types of filling: domain, volume, and
    15971245          surface. The domain is filled with a regular grid of fill-in points.
    15981246          A volume and a surface are filled by a set of equidistant points
    15991247          distributed within the volume or on the surface of a selected
    1600           shape. Molecules will then be copied and translated points when they
    1601           "fit".</para>
    1602 
    1603           <para>The filler procedure checks each fill-in point whether there
    1604           is enough space for the molecule. To know this, we require a cluster
    1605           instead of a molecule. This is just a general agglomeration of atoms
     1248          shape. The latter is closed connected to the respective shape selected. Molecules will then be copied and translated points when they
     1249          &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>
     1250        <remark>Note however that not all combinations may already be fully working.</remark>
     1251        <para>The filler procedure checks each fill-in point whether there
     1252          is enough space for the set of atoms. To this end, we require a cluster
     1253          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
    16061254          combined with a bounding box that contains all of them and serves as
    1607           its minimal volume. I.e. we need this cluster. For this a number of
     1255          its minimal volume. I.e. we need such a cluster. For this a number of
    16081256          atoms have to be specified, the minimum bounding box is generated
    1609           automatically.</para>
    1610 
    1611           <para>On top of that molecules can be selected whose volume is
     1257          automatically by which it is checked whether sufficient space is available at the fill-in point.</para>
     1258        <para>On top of that, molecules can be selected whose volume is
    16121259          additionally excluded from the filling region.</para>
    1613 
    1614         <section xml:id='filling.fill-regular-grid'>
    1615           <title xml:id='filling.fill-regular-grid.title'>Fill the domain with
    1616           molecules</title>
    1617 
     1260        <section xml:id="filling.fill-regular-grid">
     1261          <title xml:id="filling.fill-regular-grid.title">Fill the domain with molecules</title>
    16181262          <para>The call to fill the volume of the selected shape with the
    16191263          selected atoms is then as follows,</para>
    1620 
    1621           <programlisting>
    1622                 ... --fill-regular-grid \
    1623                     --mesh-size "5,5,5" \
    1624                     --mesh-offset ".5,.5,.5" \
    1625                     --DoRotate 1 \
    1626                     --min-distance 1. \
    1627                     --random-atom-displacement 0.05 \
    1628                     --random-molecule-displacement 0.4 \
    1629                     --tesselation-radius 2.5
    1630           </programlisting>
    1631 
    1632           <para>This generates a grid of 5x5x5 fill-in points within the
    1633           sphere that are offset such as to lay centered within the sphere
    1634           (offset per axis in [0,1]). Additionally, each molecule is rotated
    1635           by random rotation matrix, each atom is translated randomly by at
    1636           most 0.05, each molecule's center at most by 0.4. The selected
    1637           molecules' volume is obtained by tesselating their surface and
     1264          <programlisting>
     1265  ... --fill-regular-grid \
     1266      --mesh-size &quot;5,5,5&quot; \
     1267      --mesh-offset &quot;.5,.5,.5&quot; \
     1268      --DoRotate 1 \
     1269      --min-distance 1. \
     1270      --random-atom-displacement 0.05 \
     1271      --random-molecule-displacement 0.4 \
     1272      --tesselation-radius 2.5
     1273   </programlisting>
     1274          <para>This generates a cardinal grid of 5x5x5 fill-in points within the
     1275          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
     1276          by a random rotation matrix, each atom is translated randomly by at
     1277          most 0.05, each molecule&apos;s center similarly but at most by 0.4. The selected
     1278          molecules&apos; volume is obtained by tesselating their surface and
    16381279          excluding every fill-in point whose distance to this surface does
    16391280          not exceed 1. We refer to our comments in
    16401281          <link linkend="randomization">Randomization</link>for details on
    1641           changing the randomness.</para>
    1642         </section>
    1643 
    1644         <section xml:id='filling.fill-volume'>
    1645           <title xml:id='filling.fill-volume.title'>Fill a shape's volume
    1646           with molecules</title>
    1647          
     1282          changing the randomness and obtaining some extra flexibility thereby.</para>
     1283        </section>
     1284        <section xml:id="filling.fill-volume">
     1285          <title xml:id="filling.fill-volume.title">Fill a shape&apos;s volume with molecules</title>
    16481286          <para>More specifically than filling the whole domain with molecules,
    16491287          maybe except areas where other molecules already are, we also can
    16501288          fill only specific parts by selecting a shape and calling upon
    16511289          the following action:</para>
    1652 
    1653           <programlisting>
    1654                 ... --fill-volume \
    1655                     --counts 12 \
    1656                     --min-distance 1. \
    1657                     --DoRotate 1 \
    1658                     --random-atom-displacement 0.05 \
    1659                     --random-molecule-displacement 0.4 \
    1660                     --tesselation-radius 2.5
    1661           </programlisting>
    1662         </section>
    1663          
    1664         <section xml:id='filling.fill-surface'>
    1665           <title xml:id='filling.fill-surface.title'>Fill a shape's surface
    1666           with molecules</title>
    1667 
    1668                   <para>Filling a surface is very similar to filling its volume.
    1669                   Again the number of equidistant points has to be specified.
    1670                   However, randomness is constrained as the molecule is be aligned
    1671                   with the surface in a specific manner. The alignment axis refers
    1672                   to the largest principal axis of the filler molecule and will
    1673                   be aligned parallel to the surface normal at the fill-in point.
    1674                   </para>
    1675 
    1676                   <para>The call below fill in 12 points with a minimum distance
    1677                   between the instances of 1 angstroem. We allow for certain random
    1678                   displacements and use the z-axis for aligning the molecules on
    1679                   the surface.</para>
    1680 
    1681           <programlisting>
    1682                 ... --fill-surface \
    1683                     --counts 12 \
    1684                     --min-distance 1. \
    1685                     --DoRotate 1 \
    1686                     --random-atom-displacement 0.05 \
    1687                     --random-molecule-displacement 0.4 \
    1688                     --Alignment-Axis "0,0,1"
    1689           </programlisting>
    1690         </section>
    1691 
    1692         <section xml:id='filling.suspend-in-molecule'>
    1693           <title xml:id='filling.suspend-in-molecule.title'>Suspend in molecule
    1694           </title>
    1695 
     1290          <programlisting>
     1291  ... --fill-volume \
     1292      --counts 12 \
     1293      --min-distance 1. \
     1294      --DoRotate 1 \
     1295      --random-atom-displacement 0.05 \
     1296      --random-molecule-displacement 0.4 \
     1297      --tesselation-radius 2.5
     1298   </programlisting>
     1299          <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>
     1300        </section>
     1301        <section xml:id="filling.fill-surface">
     1302          <title xml:id="filling.fill-surface.title">Fill a shape&apos;s surface with molecules</title>
     1303          <para>Filling a surface is very similar to filling its volume.
     1304    Again the number of equidistant points has to be specified.
     1305    However, randomness is constrained as the molecule has to be aligned
     1306    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
     1307    to the largest principal axis of the filler molecule and will
     1308    be aligned parallel to the surface normal at the fill-in point.
     1309This is the same syntax as with <emphasis role="bold">rotate-around-self</emphasis>.   </para>
     1310          <para>The call below will fill in 12 points with a minimum distance
     1311    between the instances of 1 angstroem. We allow for certain random
     1312    displacements and use the z-axis for aligning the molecules on
     1313    the surface.</para>
     1314          <programlisting>
     1315  ... --fill-surface \
     1316      --counts 12 \
     1317      --min-distance 1. \
     1318      --DoRotate 1 \
     1319      --random-atom-displacement 0.05 \
     1320      --random-molecule-displacement 0.4 \
     1321      --Alignment-Axis &quot;0,0,1&quot;
     1322   </programlisting>
     1323        </section>
     1324        <section xml:id="filling.suspend-in-molecule">
     1325          <title xml:id="filling.suspend-in-molecule.title">Suspend in molecule </title>
    16961326          <para>Add a given molecule in the simulation domain in such a way
    16971327          that the total density is as desired.</para>
    1698 
    1699           <programlisting>
    1700                 ... --suspend-in-molecule 1.
    1701               </programlisting>
    1702         </section>
    1703 
    1704         <section xml:id='filling.fill-molecule'>
    1705           <title xml:id='filling.fill-molecule.title'>Fill in molecule</title>
    1706 
     1328          <programlisting>
     1329  ... --suspend-in-molecule 1.
     1330       </programlisting>
     1331        </section>
     1332        <section xml:id="filling.fill-molecule">
     1333          <title xml:id="filling.fill-molecule.title">Fill in molecule</title>
    17071334          <para>This action will be soon be removed.</para>
    1708 
    1709           <programlisting>
    1710                 ... --fill-molecule
    1711               </programlisting>
    1712         </section>
    1713 
    1714         <section xml:id='filling.fill-void'>
    1715           <title xml:id='filling.fill-void.title'>Fill void with molecule
    1716           </title>
    1717 
     1335          <programlisting>
     1336  ... --fill-molecule
     1337       </programlisting>
     1338        </section>
     1339        <section xml:id="filling.fill-void">
     1340          <title xml:id="filling.fill-void.title">Fill void with molecule </title>
    17181341          <para>This action will be soon be removed.</para>
    1719 
    1720           <programlisting>
    1721                 ... --fill-void
    1722               </programlisting>
    1723         </section>
    1724       </section>
    1725 
    1726       <section xml:id='analysis'>
    1727         <title xml:id='analysis.title'>Analysis</title>
    1728 
    1729                 <para></para>
    1730 
    1731         <section xml:id='analysis.pair-correlation'>
    1732           <title xml:id='analysis.pair-correlation.title'>Pair Correlation
    1733           </title>
    1734          
    1735           <para>Pair correlation checks for two given elements on the typical
    1736           distance they can be found with respect to one another. E.g. for
     1342          <programlisting>
     1343  ... --fill-void
     1344       </programlisting>
     1345        </section>
     1346      </section>
     1347      <section xml:id="analysis">
     1348        <title xml:id="analysis.title">Analysis</title>
     1349        <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>
     1350        <section xml:id="analysis.pair-correlation">
     1351          <title xml:id="analysis.pair-correlation.title">Pair Correlation </title>
     1352          <para>For two given elements Pair correlation checks on the typical
     1353          distance in which they can be found with respect to one another. E.g. for
    17371354          water one might be interested what is the typical distance for
    17381355          hydrogen and oxygen atoms.</para>
    1739 
    17401356          <programlisting>
    17411357          ... --pair-correlation \
    … …  
    17481364              --periodic 0
    17491365          </programlisting>
    1750          
    17511366          <para>This will compile a histogram for the interval [0,10] in steps
    17521367          of 0.7 and increment a specific bin if the distance of one such pair
    17531368          of a hydrogen and an oxygen atom can be found within its distance
    1754           interval.</para>
    1755         </section>
    1756 
    1757         <section xml:id='analysis.dipole-correlation'>
    1758           <title xml:id='analysis.dipole-correlation.title'>Dipole Correlation
    1759           </title>
    1760          
     1369          interval. These data files can be used for plotting the distribution right away in order to check on the correlation between the elements.</para>
     1370        </section>
     1371        <section xml:id="analysis.dipole-correlation">
     1372          <title xml:id="analysis.dipole-correlation.title">Dipole Correlation </title>
    17611373          <para>The dipole correlation is similar to the pair correlation, only
    17621374          that it correlates the orientation of dipoles in the molecular
    … …  
    17641376          <para>Note that the dipole correlation works on the currently
    17651377          selected molecules, e.g. all water molecules if so selected.</para>
    1766 
    17671378          <programlisting>
    17681379          ... --dipole-correlation \
    … …  
    17741385              --periodic 0
    17751386          </programlisting>
    1776         </section>
    1777 
    1778         <section xml:id='analysis.dipole-angular-correlation'>
    1779           <title xml:id='analysis.dipole-angular-correlation.title'>Dipole
    1780           Angular Correlation</title>
    1781          
     1387          <para>Hence, instead of calculating a function of the distance in [0,infinity), it calculates the angular histogram in [0,2pi).</para>
     1388        </section>
     1389        <section xml:id="analysis.dipole-angular-correlation">
     1390          <title xml:id="analysis.dipole-angular-correlation.title">Dipole Angular Correlation</title>
    17821391          <para>The dipole angular correlation looks at the angles of a
    17831392          dipole over time. It takes the orientation of a certain time step
    … …  
    17901399          might change.
    17911400          </para>
    1792 
    17931401          <programlisting>
    17941402          ... --dipole-angular-correlation H2O \
    … …  
    18021410          </programlisting>
    18031411        </section>
    1804 
    1805         <section xml:id='analysis.point-correlation'>
    1806           <title xml:id='analysis.point-correlation.title'>Point Correlation
    1807           </title>
    1808          
     1412        <section xml:id="analysis.point-correlation">
     1413          <title xml:id="analysis.point-correlation.title">Point Correlation </title>
    18091414          <para>Point correlation is very similar to pair correlation, only
    18101415          that it correlates not positions of atoms among one another but
    18111416          against a fixed, given point.</para>
    1812 
    18131417          <programlisting>
    18141418          ... --point-correlation \
    18151419              --elements 1 8 \
    1816               --position "0,0,0" \
     1420              --position &quot;0,0,0&quot; \
    18171421              --bin-start 0 \
    18181422              --bin-width 0.7 \
    … …  
    18221426              --periodic 0
    18231427          </programlisting>
    1824          
    18251428          <para>This would calculate the correlation of all hydrogen and
    18261429          oxygen atoms with respect to the origin.</para>
    18271430        </section>
    1828 
    1829         <section xml:id='analysis.surface-correlation'>
    1830           <title xml:id='analysis.surface-correlation.title'>Surface
    1831           Correlation</title>
    1832          
     1431        <section xml:id="analysis.surface-correlation">
     1432          <title xml:id="analysis.surface-correlation.title">Surface Correlation</title>
    18331433          <para>The surface correlation calculates the distance of a set
    18341434          of atoms with respect to a tesselated surface.</para>
    1835 
    18361435          <programlisting>
    18371436          ... --surface-correlation \
    … …  
    18451444          </programlisting>
    18461445        </section>
    1847 
    1848         <section xml:id='analysis.molecular-volume'>
    1849           <title xml:id='analysis.molecular-volume.title'>Molecular Volume
    1850           </title>
    1851          
     1446        <section xml:id="analysis.molecular-volume">
     1447          <title xml:id="analysis.molecular-volume.title">Molecular Volume </title>
    18521448          <para>This simply calculates the volume that a selected molecule
    18531449          occupies. For this the molecular surface is determined via a
    1854           tesselation. Note that this surface is minimal is that aspect
     1450(convex)           tesselation of its surface. Note that this surface is minimal is that aspect
    18551451          that each node of the tesselation consists of an atom of the
    18561452          molecule.</para>
    1857 
    18581453          <programlisting>... --molecular-volume</programlisting>
    18591454        </section>
    1860 
    1861         <section xml:id='analysis.average-molecule-force'>
    1862           <title xml:id='analysis.average-molecule-forcetitle'>Average force
    1863           acting on a molecule</title>
    1864          
     1455        <section xml:id="analysis.average-molecule-force">
     1456          <title xml:id="analysis.average-molecule-forcetitle">Average force acting on a molecule</title>
    18651457          <para>This sums up all the forces of each atom of a currently
    18661458          selected molecule and returns the average force vector. This should
    18671459          give you the general direction of acceleration of the molecule.
    18681460          </para>
    1869 
    18701461          <programlisting>... --molecular-volume</programlisting>
    18711462        </section>
    1872 
    1873       </section>
    1874 
    1875       <section xml:id='fragmentation'>
    1876         <title xml:id='fragmentation.title'>Fragmentation</title>
    1877 
     1463      </section>
     1464      <section xml:id="fragmentation">
     1465        <title xml:id="fragmentation.title">Fragmentation</title>
    18781466        <para>Fragmentation refers to a so-called linear-scaling method called
    1879         "Bond-Order diSSection in an ANOVA-like fashion" (BOSSANOVA),
     1467        &quot;Bond-Order diSSection in an ANOVA-like fashion&quot; (BOSSANOVA),
    18801468        developed by <personname>Frederik Heber</personname>. In this section
    18811469        we briefly explain what the method does and how the associated actions
    18821470        work.</para>
    1883 
    18841471        <para>The central idea behind the BOSSANOVA scheme is to fragment the
    18851472        graph of the molecular system into connected subgraphs of a certain
    1886         number of vertices (atoms). To give an example, loading a ethane atom
     1473        number of vertices, namely a fixed number of atoms. To give an example, loading a ethane atom
    18871474        with the chemical formula C2H6, fragmenting the molecule up to order 1
    18881475        means creating two fragments, both methane-like from either carbon
    … …  
    18911478        ethane molecule as it resembles a fragment of order 2, namely
    18921479        containing two (non-hydrogen) atoms.</para>
    1893 
    18941480        <para>The reason for doing this is that usual ab-initio calculations
    18951481        of molecular systems via methods such as Density Functional Theory or
    … …  
    19021488              <m:mi>M</m:mi>
    19031489            </m:math>
    1904           </inlineequation>. Hence, calculating the ground state energy of a
    1905         number of fragment molecules scaling linearly with the number of atoms
    1906         yields a linear-scaling methods. In the doctoral thesis of Frederik
     1490          </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
     1491        number of fragment molecules becomes a linear scaling operation with the number of atoms. In the doctoral thesis of Frederik
    19071492        Heber, it is explained why this is a sensible ansatz mathematically
    19081493        and shown that it delivers a very good accuracy if electrons (and
    19091494        hence interactions) are in general localized.</para>
    1910 
    1911         <para>Long-range interactions are artificially truncated, however,
    1912         with this fragment ansatz. It can be obtained in a perturbation manner
     1495        <para>Long-range interactions (e.g. Coulomb or van-der-Waals interactions) are artificially truncated, however,
     1496        with this fragmentation ansatz. It can be obtained in a perturbation manner
    19131497        by sampling the resulting electronic and nuclei charge density on a
    19141498        grid, summing over all fragments, and solving the associated Poisson
    … …  
    19161500        <productname>vmg</productname> by Julian Iseringhausen that is
    19171501        contained in the <link xlink:href="http://www.scafacos.org/">
    1918         <productname>ScaFaCoS</productname></link>.</para>
    1919 
     1502            <productname>ScaFaCoS</productname>
     1503          </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>
    19201504        <para>Note that we treat hydrogen special (but can be switched off) as
    19211505        fragments are calculated as closed shell (total spin equals zero).
    … …  
    19231507        bonds are cut when fragmenting a molecule (this, too, can be switched
    19241508        off).</para>
    1925 
    1926         <section xml:id='fragmentation.fragment-molecule'>
    1927           <title xml:id='fragmentation.fragment-molecule.title'>Fragmenting a
    1928           molecular system</title>
    1929 
     1509        <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>
     1510        <para>Note that the molecular system itself is not touched in any way by this fragmentation. </para>
     1511        <section xml:id="fragmentation.fragment-molecule">
     1512          <title xml:id="fragmentation.fragment-molecule.title">Fragmenting a molecular system</title>
    19301513          <para>For the current selection of atoms, all fragments consisting
    19311514          of these (sub)set of atoms are created in the following
    19321515          manner.</para>
    1933 
    1934           <programlisting>
    1935                 ... --fragment-molecule "BondFragment" \
    1936                     --DoCyclesFull 1 \
    1937                     --distance 3. \
    1938                     --order 3 \
    1939                     --grid-level 5 \
    1940                     --output-types xyz mpqc
    1941           </programlisting>
    1942 
     1516          <programlisting>
     1517  ... --fragment-molecule &quot;BondFragment&quot; \
     1518      --DoCyclesFull 1 \
     1519      --distance 3. \
     1520      --order 3 \
     1521      --grid-level 5 \
     1522      --output-types xyz mpqc
     1523   </programlisting>
    19431524          <para>We go through each of the options one after the other. During
    19441525          fragmentation some files are created storing state information, i.e.
    1945           the vertex/atom indices per fragment and so on. These files all need
    1946           a common prefix, here "BondFragment". Then, we specify that cycles
     1526          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
     1527          a common prefix, here &quot;BondFragment&quot;. Then, we specify that cycles
    19471528          should be treated fully. This compensates for electrons in aromatic
    19481529          rings being delocalized over the ring. If cycles in the graph,
    … …  
    19551536              </m:math>
    19561537            </inlineequation>) in systems with many interconnected aromatic
    1957           rings, such as graphene. Next, we give a distance cutoff of 3 used
     1538          rings, such as graphene. Next, we give a distance cutoff of 3 angstroem used
    19581539          in bond graph creation. Then, we specify the maximum order, i.e. the
    19591540          maximum number of (non-hydrogen) atoms per fragment, here 3. The
    … …  
    19621543          accurate. The grid level refers to the part where long-range Coulomb
    19631544          interactions are calculated. This is done via solving the associated
    1964           Poisson equation with a multigrid solver. As input the solver
     1545          Poisson equation with a multigrid solver -- however, this requires the <productname>JobMarket</productname> package. As input the solver
    19651546          requires the density which is sampled on a cartesian grid whose
    19661547          resolution these parameter defines (<inlineequation>
    … …  
    19701551            </inlineequation>). And finally, we give the output file formats,
    19711552          i.e. which file formats are used for writing each fragment
    1972           configuration (prefix is "BondFragment", remember?). Here, we use
     1553          configuration (prefix is &quot;BondFragment&quot;, remember?). Here, we use
    19731554          XYZ (mainly for checking the configurations visually) and MPQC,
    19741555          which is a very robust Hartree-Fock solver. We refer to the
    1975           discussion of the <link linkend="fileparsers">Parsers</link> above
    1976           on how to change the parameters of the ab-initio calculation.</para>
    1977 
     1556          discussion of the <link linkend="fileparsers">Parsers</link> 
     1557          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>
    19781558          <para>After having written all fragment configuration files, you
    19791559          need to calculate each fragment, grab the resulting energy (and
    … …  
    19831563          on.</para>
    19841564        </section>
    1985 
    1986         <section xml:id='fragmentation.fragment-automation'>
    1987           <title xml:id='fragmentation.fragment-automation.title'>Calculating
    1988           fragment energies automatically</title>
    1989 
     1565        <section xml:id="fragmentation.fragment-automation">
     1566          <title xml:id="fragmentation.fragment-automation.title">Calculating fragment energies automatically</title>
    19901567          <para>Another way of doing this is enabled if you have
    1991           <productname>JobMarket</productname> package. JobMarket implements a
     1568the           <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
    19921569          client/server ansatz, i.e. two (or more) independent programs are
    19931570          running (even on another computer but connected via an IP network),
    … …  
    19961573          client who is not busy. The client launches an executable that is
    19971574          specified in the work package he is assigned and gathers after
    1998           calculation a number of values, samewise specified in the package.
     1575          calculation a number of values, likewise specified in the package.
    19991576          The results are gathered together by the server and can be requested
    2000           from MoleCuilder once they are done. This essentially describe what
     1577          from MoleCuilder once they are done. This essentially describes what
    20011578          is happening during the execution of this action.</para>
    2002 
    20031579          <para>Stored fragment jobs can also be parsed again, i.e. reversing
    2004           the effect of having output-types specified in <link
    2005           linkend="fragmentation.fragment-molecule">Fragmenting a molecule
    2006           </link>.</para>
    2007 
    2008           <programlisting>
    2009                 ... --parse-fragment-jobs \
    2010                     --fragment-jobs "BondFragment00.in" "BondFragment01.in" \
    2011                     --fragment-path "./" \
    2012                     --grid-level 5
    2013           </programlisting>
    2014 
     1580          the effect of having output-types specified in <link linkend="fragmentation.fragment-molecule">Fragmenting a molecule </link>.</para>
     1581          <programlisting>
     1582  ... --parse-fragment-jobs \
     1583      --fragment-jobs &quot;BondFragment00.in&quot; &quot;BondFragment01.in&quot; \
     1584      --fragment-path &quot;./&quot; \
     1585      --grid-level 5
     1586   </programlisting>
    20151587          <para>Here, we have specified two files, namely
    20161588          <filename>BondFragment00.in</filename> and
    20171589          <filename>BondFragment01.in</filename>, to be parsed from the path
    2018           "./", i.e. the current directory. Also, we have specified to sample
     1590          &quot;./&quot;, i.e. the current directory. Also, we have specified to sample
    20191591          the electronic charge density obtained from the calculated ground
    20201592          state energy solution with a resolution of 5 (see fragment molecule
    20211593          and also below).</para>
    2022 
    20231594          <para>This allows for automated and parallel calculation of all
    20241595          fragment energies and forces directly within MoleCuilder. The
    … …  
    20261597          from an internal storage wherein they are placed if in
    20271598          FragmentMolecule no output-types have been specified.</para>
    2028 
    2029           <programlisting>
    2030                 ... --fragment-automation \
    2031                     --fragment-executable mpqc \
    2032                     --fragment-resultfile BondFragment_results.dat \
    2033                     --DoLongrange 1 \
    2034                     --DoValenceOnly 1 \
    2035                     --grid-level 5 \
    2036                     --interpolation-degree 3 \
    2037                     --near-field-cells 4 \
    2038                     --server-address 127.0.0.1 \
    2039                     --server-port 1025
    2040           </programlisting>
    2041 
    2042           <para>Again, we go through each of the action's options step by
     1599          <programlisting>
     1600  ... --fragment-automation \
     1601      --fragment-executable mpqc \
     1602      --fragment-resultfile BondFragment_results.dat \
     1603      --DoLongrange 1 \
     1604      --DoValenceOnly 1 \
     1605      --grid-level 5 \
     1606      --interpolation-degree 3 \
     1607      --near-field-cells 4 \
     1608      --server-address 127.0.0.1 \
     1609      --server-port 1025
     1610   </programlisting>
     1611          <para>Again, we go through each of the action&apos;s options step by
    20431612          step.</para>
    2044 
    20451613          <para>The executable is required if you do not have a patched
    20461614          version of <productname>MPQC</productname> that may directly act as
    2047           a client to JobMarket's server. All calculated results are placed in
     1615          a client to JobMarket&apos;s server. All calculated results are placed in
    20481616          the result file. If none is given, they are instead again placed in
    20491617          an internal storage for later access.</para>
    2050 
    20511618          <note>
    20521619            <para>Long-calculations are only possible with a client that knows
    … …  
    20541621            likely that you do not have a suitable client.</para>
    20551622          </note>
    2056 
    20571623          <para>In the next line, we have all options related to calculation
    20581624          of long-range interactions. We only sample valence charges on the
    2059           grid, i.e. not core electrons and the nuclei charge is reduces
    2060           respectively. This avoids problems with sampling highly localized
     1625          grid, i.e. not core electrons and the nuclei charges are reduced
     1626suitably. This avoids problems with sampling highly localized
    20611627          charges on the grid and is in general recommended. Next, there
    20621628          follow parameters for the multi grid solver, namely the resolution
    … …  
    20651631          recommended but costly in terms of memory, the other values are at
    20661632          their recommend values.</para>
    2067 
    20681633          <para>In the last line, parameters are given on how to access the
    2069           JobMarket server, namely it address and its port.</para>
    2070         </section>
    2071 
    2072         <section xml:id='fragmentation.analyse-fragment-results'>
    2073           <title xml:id='fragmentation.analyse-fragment-results.title'>
    2074           Analyse fragment results</title>
    2075 
     1634          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>
     1635        </section>
     1636        <section xml:id="fragmentation.analyse-fragment-results">
     1637          <title xml:id="fragmentation.analyse-fragment-results.title"> Analyse fragment results</title>
    20761638          <para>After the energies and force vectors of each fragment have
    20771639          been calculated, they need to be summed up to an approximation for
    20781640          the energy and force vectors of the whole molecular system. This is
    20791641          done by calling this action.</para>
    2080 
    2081           <programlisting>
    2082                 ... --analyse-fragment-results \
    2083                     --fragment-prefix "BondFragment" \
    2084                     --fragment-resultfile BondFragment_results.dat \
    2085                     --store-grids 1
    2086           </programlisting>
    2087 
     1642          <programlisting>
     1643  ... --analyse-fragment-results \
     1644      --fragment-prefix &quot;BondFragment&quot; \
     1645      --fragment-resultfile BondFragment_results.dat \
     1646      --store-grids 1
     1647   </programlisting>
    20881648          <para>The purpose of the prefix should already be known to you, same
    20891649          with the result file that is the file parsed by MoleCuilder. The
    … …  
    20921652          stored with the summed up energies and forces. Note that this makes
    20931653          the resulting files substantially larger (Hundreds of megabyte or
    2094           even gigabytes). Fragment energies and forces are stored in
     1654          even gigabytes as currently the densities are stored on the full cartesian grid). Fragment energies and forces are stored in
    20951655          so-called internal homology containers. These are explained in the
    20961656          next section.</para>
    2097 
    20981657          <para>Note that this action sets the force vector if these have been
    20991658          calculated for the fragment. Hence, a
    … …  
    21011660          is possible afterwards.</para>
    21021661        </section>
    2103        
    2104         <section xml:id='fragmentation.store-saturated-fragment'>
    2105           <title xml:id='fragmentation.store-saturated-fragment.title'>Store
    2106           a saturated fragment</title>
    2107 
    2108           <para>After the energies and force vectors of each fragment have
    2109           been calculated, they need to be summed up to an approximation for
    2110           the energy and force vectors of the whole molecular system. This is
    2111           done by calling this action.</para>
    2112 
     1662        <section xml:id="fragmentation.store-saturated-fragment">
     1663          <title xml:id="fragmentation.store-saturated-fragment.title">Store a saturated fragment</title>
    21131664          <para>This will store the currently selected atoms as a fragment
    21141665          where all dangling bonds (by atoms that are connected in the bond
    … …  
    21161667          additional hydrogen atoms. The output formats are set to just xyz.
    21171668          </para>
    2118 
    2119           <programlisting>
    2120                 ... --store-saturated-fragment \
    2121                     --DoSaturate 1 \
    2122                     --output-types xyz
    2123               </programlisting>
    2124         </section>
    2125       </section>
    2126 
    2127       <section xml:id='homology'>
    2128         <title xml:id='homology.title'>Homologies</title>
    2129 
     1669          <programlisting>
     1670  ... --store-saturated-fragment \
     1671      --DoSaturate 1 \
     1672      --output-types xyz
     1673       </programlisting>
     1674        </section>
     1675      </section>
     1676      <section xml:id="homology">
     1677        <title xml:id="homology.title">Homologies</title>
    21301678        <para>After a fragmentation procedure has been performed fully, what
    2131         to do with the results? The forces can be used already but what about
     1679        to do with the results? The forces can be used for time integration and structure optimization but what about
    21321680        the energies? The energy value is basically the function evaluation of
    2133         the Born-Oppenheimer surface. For molecular dynamics simulations
     1681        the Born-Oppenheimer surface of the molecular system. For molecular dynamics simulations
    21341682        continuous ab-initio calculations to evaluate the Born-Oppenheimer
    2135         surface is not feasible. Instead usually empirical potential functions
     1683        surface, especially the gradient at the current position of the molecular system&apos;s configuration, is not feasible. Instead usually empirical potential functions
    21361684        are fitted as to resemble the Born-Oppenheimer surface to a sufficient
    21371685        degree.</para>
    2138 
    2139         <para>One frequent method is the many-body expansion of said surface
    2140         which is basically nothing else than the fragment ansatz described
     1686        <para>One frequently employed method is the many-body expansion of said surface
     1687        which is basically nothing else than the fragmentation ansatz described
    21411688        above. Potential functions resemble a specific term in this many-body
    21421689        expansion. These are discussed in the next section.</para>
    2143 
    21441690        <para>For each of these terms all homologous fragments (i.e. having
    21451691        the same atoms with respect to the present elements and bonded in the
    … …  
    21481694        expansion with respect to varying nuclei coordinates. Hence, it is
    21491695        appropriate to use these function evaluations in a non-linear
    2150         regression procedure. That is, we want to tune the parameter of the
     1696        regression procedure. That is, we want to tune the parameters of the
    21511697        empirical potential function in such a way as to most closely obtain
    2152         the same function evaluation as the ab-initio calculation did with the
     1698        the same function evaluation as the ab-initio calculation did using the
    21531699        same nuclear coordinates. Usually, this is done in a least-square
    21541700        sense, minimising the euclidean norm.</para>
    2155 
    2156         <para>Homologies are then nothing else but containers for a specific
     1701        <para>Homologies -- in the sense used here -- are then nothing else but containers for a specific
    21571702        type of fragment of all the different, calculated configurations (i.e.
    2158         varying nuclear coordinates of the same fragment).</para>
    2159 
     1703        varying nuclear coordinates of the same fragment, i.e. same atoms with identical bonding).</para>
    21601704        <para>Now, we explain the actions that parse and store
    21611705        homologies.</para>
    2162 
    21631706        <programlisting>... --parse-homologies homologies.dat</programlisting>
    2164 
    21651707        <para>This parses the all homologies contained in the file
    2166         <filename>homologies.dat</filename> and appends them to the homology
     1708        <filename>homologies.dat</filename> and <emphasis role="italic">appends</emphasis> them to the homology
    21671709        container.</para>
    2168 
    21691710        <programlisting>... --save-homologies homologies.dat</programlisting>
    2170 
    21711711        <para>Complementary, this stores the current contents of the homology
    2172         container, overwriting the file
     1712        container, <emphasis role="italic">overwriting</emphasis> the file
    21731713        <filename>homologies.dat</filename>.</para>
    21741714      </section>
    2175 
    2176       <section xml:id='potentials'>
    2177         <title xml:id='potentials.title'>Potentials</title>
    2178 
    2179         <para>In much the same manner, we would now ask what are homology
    2180         files or containers good for but with the just had explanation it
     1715      <section xml:id="potentials">
     1716        <title xml:id="potentials.title">Potentials</title>
     1717        <para>In much the same manner as we asked before: what are homology
     1718        files or containers good for? However, taking into account what we have just explained, it
    21811719        should be clear: We fit potential function to these function
    2182         evaluation of terms of the many-body expansion of the Born-Oppenheimer
     1720        evaluations of terms of the many-body expansion of the Born-Oppenheimer
    21831721        surface of the full system.</para>
    2184 
    2185         <section xml:id='potentials.fit-potential'>
    2186           <title xml:id='potentials.fit-potential.title'>Fitting empirical
    2187           potentials</title>
    2188 
    2189           <para>Let's take a look at an exemplary call to the fit potential
     1722        <section xml:id="potentials.fit-potential">
     1723          <title xml:id="potentials.fit-potential.title">Fitting empirical potentials</title>
     1724          <para>Let&apos;s take a look at an exemplary call to the fit potential
    21901725          action.</para>
    2191 
    2192           <programlisting>
    2193                 ... --fit-potential \
    2194                     --fragment-charges 8 1 1 \
    2195                     --potential-charges 8 1 \
    2196                     --potential-type morse \
    2197                     --take-best-of 5
    2198           </programlisting>
    2199 
     1726          <programlisting>
     1727  ... --fit-potential \
     1728      --fragment-charges 8 1 1 \
     1729      --potential-charges 8 1 \
     1730      --potential-type morse \
     1731      --take-best-of 5
     1732   </programlisting>
    22001733          <para>Again, we look at each option in turn. The first is the
    22011734          charges or elements specifying the set of homologous fragments that
    22021735          we want to look at. Here, obviously we are interested in water
    2203           molecules, consisting of a single oxygen and two hydrogen atoms.
    2204           Next, we specify the nuclei coordinates of the potential. We give
     1736          molecules, consisting of a single oxygen (8) and two hydrogen atoms (1).
     1737          Next, we specify the chemical element type of the potential, here a potential between oxygen (8) and hydrogen (1). We give
    22051738          the type of the potential as morse, which requires a single distance
    2206           or two nuclear coordinates, here between an oxygen and a hydrogen
    2207           atom. Finally, we state that the non-linear regression should be
    2208           done with five random starting positions and the set of parameters
     1739          or two nuclear coordinates and the distance taken between the two. Finally, we state that the non-linear regression should be
     1740          done with five random starting positions, i.e. five individual minimizations, and the set of parameters
    22091741          with the smallest L2 norm wins.</para>
    2210 
    22111742          <note>
    22121743            <para>Due to translational and rotational degrees of freedom for
    … …  
    22151746            the two atomic positions, here for oxygen and hydrogen, are
    22161747            converted to a single distance. If we had given an harmonic
    2217             angular potential and three charges/element, 8 1 1, i.e. oxygen
     1748            angular potential and the then required three charges/elements, &quot;8 1 1&quot;, i.e. oxygen
    22181749            and two hydrogens, we would have obtained three distances.</para>
    2219 
    22201750            <para>MoleCuilder always adds a so-called constant potential to
    22211751            the fit containing only a single parameter, the energy offset.
    22221752            This offset compensates for the interaction energy associated with
    2223             a fragment of order 1, e.g. a single hydrogen atom.</para>
     1753            a fragment of order 1, e.g. a single hydrogen atom. Essentially, this captures the atomic energy that is not associated to any bonding interactions.</para>
    22241754          </note>
    22251755        </section>
    2226 
    2227         <section xml:id='potentials.fit-compound-potential'>
    2228           <title xml:id='potentials.fit-compound-potential.title'>Fitting
    2229           many empirical potentials simultaneously</title>
    2230 
    2231 
     1756        <section xml:id="potentials.fit-compound-potential">
     1757          <title xml:id="potentials.fit-compound-potential.title">Fitting many empirical potentials simultaneously</title>
    22321758          <para>Another way is using a file containing a specific set of
    22331759          potential functions, possibly even with initial values.</para>
    2234 
    2235           <programlisting>
    2236                 ... --fit-compound-potential \
    2237                     --fragment-charges 8 1 1 \
    2238                     --potential-file water.potentials \
    2239                     --set-threshold 1e-3 \
    2240                     --training-file test.dat
    2241           </programlisting>
    2242 
     1760          <programlisting>
     1761  ... --fit-compound-potential \
     1762      --fragment-charges 8 1 1 \
     1763      --potential-file water.potentials \
     1764      --set-threshold 1e-3 \
     1765      --training-file test.dat
     1766   </programlisting>
    22431767          <para>Now, all empirical potential functions are summed up into a
    22441768          so-called compound potential over the combined set of parameters.
    2245           These are now fitted simultaneously. For example, if the potential
     1769          These are now fitted simultaneously. For example, let&apos;s say the potential
    22461770          file <filename>water.potentials</filename> contains a harmonic bond
    22471771          potential between oxygen and hydrogen and another angular potential
    2248           for the angle between hydrogen, oxygen, and hydrogen atom we would
    2249           fit a still simple function approximating the energy of a single
    2250           water molecule. Here, the threshold takes the place of the
    2251           take-best-of option. Here, random starting parameters are used as
    2252           long as the final L2 error is not below 1e-3. Also, all data used
     1772          for the angle between hydrogen, oxygen, and hydrogen atom. Then, we would
     1773          fit a function consisting of the sum of the two potentials functions in order to approximate the energy of a single
     1774          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
     1775<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
    22531776          for training, i.e. the tuples consisting of the fragments nuclei
    22541777          coordinates and the associated energy value are written to the file
    2255           <filename>test.dat</filename>. This allows for graphical or other
    2256           type of analysis.</para>
    2257 
     1778          <filename>test.dat</filename>. This allows for graphical representation or other
     1779way 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
     1780          <filename>test.dat</filename>.</para>
    22581781          <para>Note that you can combine the two ways, i.e. start with a
    22591782          fit-potential call but give an empty potential file. The resulting
    … …  
    22631786          with this file.</para>
    22641787        </section>
    2265 
    2266        
    2267         <section xml:id='potentials.parse-potential'>
    2268           <title xml:id='potentials.parse-potential.title'>Parsing an
    2269           empirical potentials file</title>
    2270 
    2271           <para>Responsible for the compound potential is every potential
     1788        <section xml:id="potentials.parse-potential">
     1789          <title xml:id="potentials.parse-potential.title">Parsing an empirical potentials file</title>
     1790          <para>Taking part in the compound potential is every potential
    22721791          function whose signature matches with the designated fragment-charges
    2273           and who is currently known to an internal instance called the
    2274           PotentialRegistry.</para>
    2275 
    2276           <para>More potentials can be registered (fit-potential will also
     1792          and who is currently known to MoleCuilder.</para>
     1793          <para>More potentials can be registered (<emphasis role="bold">fit-potential</emphasis> will also
    22771794          register the potential it fits) by parsing them from a file.</para>
    2278 
    2279           <programlisting>
    2280                 ... --parse-potentials water.potentials
    2281           </programlisting>
    2282 
    2283           <note>Currently, only <productname>TREMOLO</productname> potential
    2284           files are understood and can be parsed.</note>
    2285         </section>
    2286 
    2287         <section xml:id='potentials.save-potential'>
    2288           <title xml:id='potentials.save-potential.title'>Saving an
    2289           empirical potentials file</title>
    2290 
    2291           <para>The opposite to parse-potentials is save-potentials that writes
    2292           every potential currently known to the PotentialRegistry to the given
     1795          <programlisting>
     1796  ... --parse-potentials water.potentials
     1797   </programlisting>
     1798          <note>Currently, only <productname>TREMOLO</productname>potential files are understood and can be parsed.</note>
     1799        </section>
     1800        <section xml:id="potentials.save-potential">
     1801          <title xml:id="potentials.save-potential.title">Saving an empirical potentials file</title>
     1802          <para>The opposite to <emphasis role="bold">parse-potentials</emphasis> is to save all currently registered potential functions to the given
    22931803          file along with the currently fitted parameters</para>
    2294 
    2295           <programlisting>
    2296                 ... --save-potentials water.potentials
    2297           </programlisting>
    2298 
    2299           <note>Again, only the <productname>TREMOLO</productname> potential
    2300           format is understood currently and is written.</note>
    2301         </section>
    2302 
    2303         <section xml:id='potentials.fit-particle-charges'>
    2304           <title xml:id='potentials.fit-particle-charges.title'>Fitting
    2305           particle charges</title>
    2306 
     1804          <programlisting>
     1805  ... --save-potentials water.potentials
     1806   </programlisting>
     1807          <note>Again, only the <productname>TREMOLO</productname>potential format is understood currently and is written.</note>
     1808        </section>
     1809        <section xml:id="potentials.fit-particle-charges">
     1810          <title xml:id="potentials.fit-particle-charges.title">Fitting particle charges</title>
    23071811          <para>The above empirical potential just model the short-range
    2308           behavior in the molecular fragment, namely the bonded interaction.
    2309           In order to model the long-range interaction as well without solving
     1812          behavior in the molecular fragment, namely the (covalently) bonded interaction.
     1813          In order to model the Coulomb long-range interaction as well without solving
    23101814          for the electronic ground state in each time step, particle charges
    23111815          are used that capture to some degree the created dipoles due to
    23121816          charge transfer from one atom to another when bonded.</para>
    2313 
    2314           <para>To allow least-squares regression of these partial charges we
    2315           need the results of long-range calculations and the store-grids
    2316           option (see above under <link linkend="fragmentation">Fragmentation
    2317           </link>) must have been given. With these sampled charge density and
     1817          <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>
     1818          <para>To allow least-squares regression of these partial charges, we
     1819          need the results of long-range calculations and the <emphasis role="bold">store-grids</emphasis>
     1820          option (see above under <link linkend="fragmentation">Fragmentation </link>) must have been given. With these sampled charge density and
    23181821          Coulomb potential stored in the homology containers, we call this
    23191822          action as follows.</para>
    2320 
    2321           <programlisting>
    2322                 ... --fit-particle-charges \
    2323                     --fragment-charges 8 1 1 \
    2324                     --potential-file water.potentials \
    2325                     --radius 0.2
    2326           </programlisting>
    2327 
    2328           <para>This will again use water molecule as homologous fragment
    2329           "key" to request configurations from the container. Results are
     1823          <programlisting>
     1824  ... --fit-particle-charges \
     1825      --fragment-charges 8 1 1 \
     1826      --potential-file water.potentials \
     1827      --radius 0.2
     1828   </programlisting>
     1829          <para>This will again use a water molecule as homologous fragment
     1830          &quot;key&quot; to request all configurations of this type from the homologies container. Results are
    23301831          stored in <filename>water.potentials</filename>. The radius is used
    23311832          to mark the region directly around the nuclei from the fit
    … …  
    23361837        </section>
    23371838      </section>
    2338 
    2339       <section xml:id='dynamics'>
    2340         <title xml:id='dynamics.title'>Dynamics</title>
    2341 
    2342         <para>For fitting potentials or charges we need many homologuous but
     1839      <section xml:id="dynamics">
     1840        <title xml:id="dynamics.title">Dynamics</title>
     1841        <para>For fitting potentials or charges we need many homologous but
    23431842        different fragments, i.e. atoms with slightly different positions.
    23441843        How can we generate these?</para>
    2345 
    23461844        <para>One possibility is to use molecular dynamics. With the
    23471845        aforementioned fragmentation scheme we can quickly calculate not only
    23481846        energies but also forces if the chosen solver, such as
    2349         <link xlink:href="http://www.mpqc.org/"><productname>MPQC
    2350         </productname></link>, supports it. Integrating these forces
     1847        <link xlink:href="http://www.mpqc.org/">
     1848            <productname>MPQC </productname>
     1849          </link>, supports it. Integrating these forces
    23511850        discretely over time  gives insight into vibrational features of a
    2352         molecular system and allows to generate those positions for fitting
     1851        molecular system close to the equilibrium and allows to generate those positions for fitting
    23531852        potentials that describe these vibrations.</para>
    2354 
    2355         <section xml:id='dynamics.molecular-dynamics'>
    2356           <title xml:id='dynamics.molecular-dynamics.title'>Molecular dynamics
    2357           </title>
    2358 
     1853        <section xml:id="dynamics.molecular-dynamics">
     1854          <title xml:id="dynamics.molecular-dynamics.title">Molecular dynamics </title>
    23591855          <para>The molecular dynamics action is a so-called macro Action,
    23601856          i.e. it combines several other Actions into one, namely:</para>
    2361                   <itemizedlist>
     1857          <itemizedlist>
    23621858            <listitem>
    2363               <para>--verlet-integration</para>
     1859              <para>--<emphasis role="bold">verlet-integration</emphasis></para>
    23641860            </listitem>
    23651861            <listitem>
    2366               <para>--output</para>
     1862              <para>--<emphasis role="bold">output</emphasis></para>
    23671863            </listitem>
    23681864            <listitem>
    2369               <para>--clear-fragment-results</para>
     1865              <para>--<emphasis role="bold">clear-fragment-results</emphasis></para>
    23701866            </listitem>
    23711867            <listitem>
    2372               <para>--destroy-adjacency</para>
     1868              <para>--<emphasis role="bold">destroy-adjacency</emphasis></para>
    23731869            </listitem>
    23741870            <listitem>
    2375               <para>--create-adjacency</para>
     1871              <para>--<emphasis role="bold">create-adjacency</emphasis></para>
    23761872            </listitem>
    23771873            <listitem>
    2378               <para>--update-molecules</para>
     1874              <para>--<emphasis role="bold">update-molecules</emphasis></para>
    23791875            </listitem>
    23801876            <listitem>
    2381               <para>--fragment-molecule</para>
     1877              <para>--<emphasis role="bold">fragment-molecule</emphasis></para>
    23821878            </listitem>
    23831879            <listitem>
    2384               <para>--fragment-automation</para>
     1880              <para>--<emphasis role="bold">fragment-automation</emphasis></para>
    23851881            </listitem>
    23861882            <listitem>
    2387               <para>--analyse-fragment-results</para>
     1883              <para>--<emphasis role="bold">analyse-fragment-results</emphasis></para>
    23881884            </listitem>
    2389                   </itemizedlist>
    2390                  
    2391                   <para>The following will perform a molecular dynamics simulation
    2392                   for 100 time steps, each time step combining 0.5 atomic time units,
    2393                   i.e. 1.2 1e-17 s. The other options listed below will seem familiar
    2394                   to you if you have read about the other Actions listed above. Below
    2395                   we will not keep the bondgraph, i.e bonds and molecules may change
    2396                   over the simulation and hence also the created fragments per time
    2397                   step.
    2398                   </para>
    2399 
     1885          </itemizedlist>
     1886          <para>The following command will perform a molecular dynamics simulation
     1887    for 100 time steps, each time step continuing over <emphasis role="bold">deltat</emphasis> equal to 0.5 atomic time units,
     1888    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
     1889    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
     1890    we will not keep the bond graph, i.e bonds and molecules may change
     1891    over the simulation and hence also the created fragments per time
     1892    step.
     1893Furthermore, the forces are corrected such that the force add up to zero.    </para>
    24001894          <programlisting>
    24011895          ... --molecular-dynamics \
    … …  
    24081902          --fragment-executable mpqc \
    24091903          </programlisting>
    2410         </section>
    2411 
    2412         <section xml:id='dynamics.optimize-structure'>
    2413           <title xml:id='dynamics.optimize-structure.title'>Structure
    2414           optimization</title>
    2415 
    2416                   <para>Structure optimization is also a macro Action, it basically
    2417                   combines the same Actions as molecular-dynamics does. However, it
    2418                   uses force-annealing instead of verlet-integration.</para>
    2419 
    2420                   <para>The following performs a structure optimization of the
    2421                   currently selected atoms (may also be a subset) for up to 100 time
    2422                   steps, where each time step ist 0.5 atomic time units. The time
    2423                   step here is the initial step with for annealing.
    2424                   </para>
    2425 
     1904          <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>
     1905          <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>
     1906        </section>
     1907        <section xml:id="dynamics.optimize-structure">
     1908          <title xml:id="dynamics.optimize-structure.title">Structure optimization</title>
     1909          <para>Structure optimization is also a macro Action, it basically
     1910    combines the same Actions as <emphasis role="bold">molecular-dynamics</emphasis> does. However, it
     1911    uses the <emphasis role="bold">force-annealing</emphasis> action instead of <emphasis role="bold">verlet-integration</emphasis>.</para>
     1912          <para>The command below performs a structure optimization of the
     1913    currently selected atoms (may also be a subset) for up to 100 time
     1914    steps, where each time step is again 0.5 atomic time units. The time
     1915    step here serves as the initial step width for annealing.
     1916    </para>
    24261917          <programlisting>
    24271918          ... --optimize-structure \
    … …  
    24351926          --fragment-executable mpqc \
    24361927          </programlisting>
    2437 
    2438                   <para>Note that output-every-step will allow you to watch the
    2439                   optimization as each step is placed into a distinct time step.
    2440                   Otherwise only two time steps would be created: the initial and
    2441                   the final one containing the optimized structure.</para>
    2442         </section>
    2443 
    2444         <section xml:id='dynamics.set-world-time'>
    2445           <title xml:id='dynamics.set-world-time.title'>Set the world's time
    2446           step</title>
    2447 
    2448                   <para>In order to inspect or manipulate atoms and molecules at a
    2449                   certain time step, the World's time has to be set with the following
    2450                   Action.
    2451                   </para>
    2452                  
    2453                   <para>This will set the World's time to the fifth step (counting
    2454                   starts at zero).</para>
    2455 
     1928          <para>Note that <emphasis role="bold">output-every-step</emphasis> will allow you to watch the
     1929      optimization as each step is placed into a distinct time step.
     1930    Otherwise only two time steps would be created: the initial and
     1931    the final one containing the optimized structure.</para>
     1932        </section>
     1933        <section xml:id="dynamics.set-world-time">
     1934          <title xml:id="dynamics.set-world-time.title">Set the world&apos;s time step</title>
     1935          <para>In order to inspect or manipulate atoms and molecules at a
     1936    certain time step, the World&apos;s time has to be set with the following
     1937    Action.
     1938    </para>
     1939          <para>This will set the World&apos;s time to the fifth step (counting
     1940    starts at zero).</para>
    24561941          <programlisting>... --set-world-time 4</programlisting>
    2457         </section>
    2458 
    2459         <section xml:id='dynamics.save-temperature'>
    2460           <title xml:id='dynamics.save-temperature.title'>Save the
    2461           temperature information</title>
    2462 
    2463                   <para>For each time step the temperature (i.e. the average velocity
    2464                   per atom times its mass) will be stored to a file.</para>
    2465 
    2466           <programlisting>
    2467           ... --save-temperature temperature.dat \
    2468           </programlisting>
    2469         </section>
    2470       </section>
    2471    
    2472       <section xml:id='dynamics.tesselation'>
    2473         <title xml:id='dynamics.tesselation.title'>Tesselations</title>
    2474 
    2475         <para>Tesselations obtain molecular surfaces (and volumes) by rolling
    2476         a virtual sphere of a certain radii on a molecule until a closed
     1942          <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>
     1943        </section>
     1944        <section xml:id="dynamics.save-temperature">
     1945          <title xml:id="dynamics.save-temperature.title">Save the temperature information</title>
     1946          <para>For each present time step the temperature (i.e. the average velocity
     1947    per atom multiplied with its mass) will be stored to a file.</para>
     1948          <programlisting>          ... --save-temperature temperature.dat</programlisting>
     1949          <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>
     1950        </section>
     1951      </section>
     1952      <section xml:id="dynamics.tesselation">
     1953        <title xml:id="dynamics.tesselation.title">Tesselations</title>
     1954        <para>A tesselation is a set of triangles that form a closed surface. They are used to obtain molecular surfaces (and volumes) by rolling
     1955        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
    24771956        surface of connected triangles is created.</para>
    2478 
    2479         <section xml:id='dynamics.tesselation.nonconvex-envelope'>
    2480           <title xml:id='dynamics.tesselation.nonconvex-envelope.title'>
    2481           Non-convex envelope</title>
    2482          
     1957        <para>Note that 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.</para>
     1958        <section xml:id="dynamics.tesselation.nonconvex-envelope">
     1959          <title xml:id="dynamics.tesselation.nonconvex-envelope.title"> Non-convex envelope</title>
    24831960          <para>This will create a non-convex envelope for a molecule and store
    24841961          it to a file for viewing with external programs.</para>
    2485 
    24861962          <programlisting>
    24871963          ... --nonconvex-envelope 6. \
    24881964          --nonconvex-file nonconvex.dat
    24891965          </programlisting>
    2490 
    24911966          <para>This tesselation file can be conveniently viewed with
    24921967          <productname>TecPlot</productname> or with one of the Tcl script
    2493           in the util folder with <productname>VMD</productname>. Also,
    2494           still pictures can be produced with <productname>Raster3D
    2495           </productname>.
    2496           <note>The required file header.r3d can be found in a subfolder of
    2497           the util folder.</note>
     1968          in the <emphasis role="italic">util</emphasis> folder with <productname>VMD</productname>. Also,
     1969          still pictures can be produced with <productname>Raster3D </productname>.
     1970          <note>The required file header.r3d can be found in a subfolder of the util folder.</note>
    24981971          </para>
    24991972        </section>
    2500 
    2501         <section xml:id='dynamics.tesselation.convex-envelope'>
    2502           <title xml:id='dynamics.tesselation.convex-envelope.title'>Convex
    2503           envelope</title>
    2504          
     1973        <section xml:id="dynamics.tesselation.convex-envelope">
     1974          <title xml:id="dynamics.tesselation.convex-envelope.title">Convex envelope</title>
    25051975          <para>This will create a convex envelope for a molecule and give the
    25061976          volumes of both the non-convex and the convex envelope. This is good
    25071977          for measuring the space a molecule takes up, e.g. when filling a
    25081978          domain and taking care of correct densities.</para>
    2509 
    25101979          <programlisting>
    25111980          ... --convex-envelope 6. \
    25121981          --convex-file convex.dat
    25131982          </programlisting>
    2514 
    25151983          <para>This tesselation file can be likewise viewed with
    25161984          <productname>TecPlot</productname> or with one of the Tcl script
    … …  
    25181986        </section>
    25191987      </section>
    2520 
    2521       <section xml:id='various'>
    2522         <title xml:id='various.title'>Various commands</title>
    2523 
     1988      <section xml:id="various">
     1989        <title xml:id="various.title">Various commands</title>
    25241990        <para>Here, we gather all commands that do not fit into one of above
    25251991        categories for completeness.</para>
    2526 
    2527         <section xml:id='various.verbose'>
    2528           <title xml:id='various.verbose.title'>Changing verbosity</title>
    2529 
     1992        <section xml:id="various.verbose">
     1993          <title xml:id="various.verbose.title">Changing verbosity</title>
    25301994          <para>The verbosity level is the amount of stuff printed to screen.
    25311995          This information will in general help you to understand when
    25321996          something does not work. Mind the <emphasis>ERROR</emphasis> and
    25331997          <emphasis>WARNING</emphasis> messages in any case.</para>
    2534 
    2535           <para>This sets the verbosity from default of 2 to 4,</para>
    2536 
     1998          <para>This command below sets the verbosity from default of 2 to 4,</para>
    25371999          <programlisting>... --verbose 4</programlisting>
    2538 
    25392000          <para>or shorter,</para>
    2540 
    25412001          <programlisting>... -v 4</programlisting>
    25422002        </section>
    2543        
    2544         <section xml:id='various.dry-run'>
    2545           <title xml:id='various.dry-run.title'>Dry runs</title>
    2546 
    2547           <para>A "dry run" refers to a test run where commands are not
    2548           actually executed. You may bracket a certain set of actions by
    2549           putting --dry-run before and --no-dry-run afterwards. Then, all
    2550           action in between will be looked at but not executed, i.e. they
    2551           make it to the history but nothing is changed in the World.</para>
    2552 
    2553           <para>As an example, the following listing contains the adding of a
    2554           hydrogen atom at position (5,5,5) inside the aforementioned dry run
    2555           statements. Hence, no hydrogen atom is added but the add action is
    2556           stored in the history and will make it to a stored session.</para>
    2557 
    2558           <programlisting>
    2559           ... --dry-run \
    2560           --add-atom 1 --domain-position "5,5,5"
    2561           --no-dry-run
    2562           </programlisting>
    2563 
    2564         </section>
    2565 
    2566         <section xml:id='various.element-db'>
    2567           <title xml:id='various.element-db.title'>Loading an element
    2568           database</title>
    2569 
     2003        <section xml:id="various.dry-run">
     2004          <title xml:id="various.dry-run.title">Dry runs</title>
     2005          <para>A &quot;dry run&quot; refers to a test run where commands are not
     2006   actually executed. You may bracket a certain set of actions by
     2007   putting --<emphasis role="bold">dry-run</emphasis> before and --<emphasis role="bold">no-dry-run</emphasis> afterwards. Then, all
     2008   actions in between will be looked at but not executed, i.e. they
     2009   make it to the history but nothing is changed in the World.</para>
     2010          <para>As an example, the following listing contains the adding of a
     2011   hydrogen atom at position (5,5,5) inside the aforementioned dry run
     2012   statements. Hence, no hydrogen atom is added but the <emphasis role="bold">add-atom</emphasis> action is
     2013   stored in the history and will make it to a stored session.</para>
     2014          <programlisting>   ... --dry-run \
     2015   --add-atom 1 --domain-position &quot;5,5,5&quot;
     2016   --no-dry-run</programlisting>
     2017          <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>
     2018        </section>
     2019        <section xml:id="various.element-db">
     2020          <title xml:id="various.element-db.title">Loading an element database</title>
    25702021          <para>Element databases contain information on valency, van der
    25712022          Waals-radii and other information for each element.</para>
    2572 
    25732023          <para>This loads all element database from the current folder (in a
    25742024          unix environment):</para>
    2575 
    25762025          <programlisting>... --element-db ./</programlisting>
    2577 
    2578         </section>
    2579 
    2580         <section xml:id='various.fastparsing'>
    2581           <title xml:id='various.fastparsing.title'>Fast parsing</title>
    2582 
     2026        </section>
     2027        <section xml:id="various.fastparsing">
     2028          <title xml:id="various.fastparsing.title">Fast parsing</title>
    25832029          <para>Parsing all time steps from a given input file can take a
    25842030          while, especially for larger systems. If fast parsing is activated,
    25852031          only the first time step is loaded, all other are ignored.</para>
    2586 
    25872032          <programlisting>... --fastparsing 1</programlisting>
    25882033        </section>
    2589 
    2590         <section xml:id='various.version'>
    2591           <title xml:id='various.version.title'>Giving the version of the
    2592           program</title>
    2593 
     2034        <section xml:id="various.version">
     2035          <title xml:id="various.version.title">Giving the version of the program</title>
    25942036          <para>This prints the version information of the code, especially
    25952037          important when you request the fixing of bugs or implementation of
    25962038          features.</para>
    2597 
    25982039          <programlisting>... --version</programlisting>
    25992040        </section>
    2600 
    2601         <section xml:id='various.warranty'>
    2602           <title xml:id='various.warranty.title'>Giving warranty
    2603           information</title>
    2604 
     2041        <section xml:id="various.warranty">
     2042          <title xml:id="various.warranty.title">Giving warranty information</title>
    26052043          <para>As follows warranty information is given,</para>
    2606 
    26072044          <programlisting>... --warranty</programlisting>
    26082045        </section>
    2609 
    2610         <section xml:id='various.help-redistribute'>
    2611           <title xml:id='various.help-redistribute.title'>Giving
    2612           redistribution information</title>
    2613 
     2046        <section xml:id="various.help-redistribute">
     2047          <title xml:id="various.help-redistribute.title">Giving redistribution information</title>
    26142048          <para>This gives information on the license and how to redistribute
    26152049          the program and its source code</para>
    2616 
    26172050          <programlisting>... --help-redistribute</programlisting>
    26182051        </section>
    26192052      </section>
    2620 
    2621       <section xml:id='sessions'>
    2622         <title xml:id='sessions.title'>Sessions</title>
    2623 
     2053      <section xml:id="sessions">
     2054        <title xml:id="sessions.title">Sessions</title>
    26242055        <para>A session refers to the queue of actions you have executed.
    26252056        Together with the initial configuration (and all files required for
    2626         actions in the queue) this might be seen as a clever way of storing
    2627         the state of a molecular system. When proceeding in a try&amp;error
     2057        actions in the queue) this may be seen as a clever way of storing
     2058        the state and history of a molecular system manipulation session. When proceeding in a try&amp;error
    26282059        fashion to construct a certain system, it is a good idea, to store the
    26292060        session at the point where your attempts start to deviate from one
    26302061        another.</para>
    2631 
    2632         <section xml:id='sessions.store-session'>
    2633           <title xml:id='sessions.store-session.title'>Storing a session
    2634           </title>
    2635 
     2062        <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>
     2063        <section xml:id="sessions.store-session">
     2064          <title xml:id="sessions.store-session.title">Storing a session </title>
    26362065          <para>Storing sessions is simple,</para>
    2637 
    2638           <programlisting>
    2639                   ... --store-session "session.py" \
    2640                       --session-type python
    2641               </programlisting>
    2642 
     2066          <programlisting>
     2067    ... --store-session &quot;session.py&quot; \
     2068        --session-type python
     2069       </programlisting>
    26432070          <para>Here, the session type is given as python (the other option is
    2644           cli for in the manner of the command-line interface) and the written
     2071&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
    26452072          python script <filename>session.py</filename> can even be used with
    26462073          the python interface described below, i.e. it is a full python script
    2647           (that however requires the so-called pyMoleCuilder module).</para>
    2648         </section>
    2649 
    2650         <section xml:id='sessions.load-session'>
    2651           <title xml:id='sessions.load-session.title'>Loading a session</title>
    2652 
    2653           <para>Loading a session only works for python scripts. This actually
     2074          (that however requires the so-called <emphasis role="italic">pyMoleCuilder</emphasis> module).</para>
     2075        </section>
     2076        <section xml:id="sessions.load-session">
     2077          <title xml:id="sessions.load-session.title">Loading a session</title>
     2078          <para>Loading a session only works for python scripts, i.e. only for session type python and not for type cli. This actually
    26542079          blurs the line between the command-line interface and the python
    2655           interface a bit. But even more, MoleCuilder automatically executes a
     2080          interface a bit. Again, MoleCuilder automatically executes a
    26562081          script called <filename>molecuilder.py</filename> if such a file is
    26572082          contained in the current directory.</para>
    2658 
    2659           <programlisting>... --load-session "session.py"</programlisting>
    2660 
     2083          <programlisting>... --load-session &quot;session.py&quot;</programlisting>
    26612084          <para>This will execute every action with its options contained in the
    26622085          script <filename>session.py</filename>.</para>
    26632086        </section>
    26642087      </section>
    2665 
    2666       <section xml:id='various-specific'>
    2667         <title xml:id='various-specific.title'>Various specific commands
    2668         </title>
    2669        
     2088      <section xml:id="various-specific">
     2089        <title xml:id="various-specific.title">Various specific commands </title>
    26702090        <para>In this (final) section of the action description we list a number
    26712091        Actions that are very specific to some purposes (or other programs).
    26722092        </para>
    2673        
    2674         <section xml:id='various-specific.save-selected-atoms-as-exttypes'>
    2675           <title xml:id='various-specific.save-selected-atoms-as-exttypes.title'>
    2676           Saving exttypes of a set of atoms</title>
    2677          
     2093        <section xml:id="various-specific.save-selected-atoms-as-exttypes">
     2094          <title xml:id="various-specific.save-selected-atoms-as-exttypes.title"> Saving exttypes of a set of atoms</title>
    26782095          <para>This saves the atomic ids of all currently selected atoms in a
    2679            <link xlink:href="http://www.tremolo-x.com/"><productname>TREMOLO
    2680            </productname></link> exttypes file with the given name.</para>
    2681 
     2096           <link xlink:href="http://www.tremolo-x.com/">
     2097              <productname>TREMOLO </productname>
     2098            </link> exttypes file with the given name.</para>
    26822099          <programlisting>
    26832100          ... --save-selected-atoms-as-exttypes \
    26842101          --filename test.exttypes </programlisting>
    26852102        </section>
    2686        
    2687         <section xml:id='various-specific.set-parser-parameters'>
    2688           <title xml:id='various-specific.set-parser-parameters.title'>Setting
    2689           parser specific parameters</title>
    2690 
    2691           <para>You can also tweak the parameters stored in this file easily.
     2103        <section xml:id="various-specific.set-parser-parameters">
     2104          <title xml:id="various-specific.set-parser-parameters.title">Setting parser specific parameters</title>
     2105          <para>You can tweak the parameters stored in files associated to specific ab initio programs to some extent.
    26922106          For example, <productname>MPQC</productname> stores various
    2693           parameters modifying the specific ab-initio calculation performed.
    2694           For <link xlink:href="http://www.mpqc.org/"><productname>MPQC
    2695           </productname></link> and
    2696           <link xlink:href="http://www.psicode.org/"><productname>Psi4
    2697           </productname></link> this can be modified as follows.</para>
    2698 
    2699           <programlisting>
    2700                 ... --set-parser-parameters mpqc \
    2701                     --parser-parameters "theory=CLHF;basis=6-31*G;"
     2107          parameters modifying the specific ab-initio calculation performed, e.g. the basis set used, the level of theory, whether gradients are calculated.
     2108          For <link xlink:href="http://www.mpqc.org/">
     2109              <productname>MPQC </productname>
     2110            </link> and
     2111          <link xlink:href="http://www.psicode.org/">
     2112              <productname>Psi4 </productname>
     2113            </link> this can be modified as follows.</para>
     2114          <programlisting>
     2115  ... --set-parser-parameters mpqc \
     2116      --parser-parameters &quot;theory=CLHF;basis=6-31*G;&quot;
    27022117          </programlisting>
    2703 
    27042118          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
    2705           and the basis set to 6-31*G. Please check the
    2706           <productname>MPQC</productname> manual on specific
    2707           parameters.</para>
    2708         </section>
    2709 
    2710         <section xml:id='various-specific.set-tremolo-atomdata'>
    2711           <title xml:id='various-specific.set-tremolo-atomdata.title'>Tremolo
    2712           specific options and potential files</title>
    2713 
    2714           <para><productname>TREMOLO</productname>'s configuration files start
    2715           with a specific line telling the amount of information stored in the
    2716           file. This file can be modified, e.g. to enforce storing of
     2119          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
     2120          <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>
     2121          <itemizedlist>
     2122            <listitem>theory</listitem>
     2123            <listitem>basis</listitem>
     2124          </itemizedlist>
     2125        </section>
     2126        <section xml:id="various-specific.set-tremolo-atomdata">
     2127          <title xml:id="various-specific.set-tremolo-atomdata.title">Tremolo specific options and potential files</title>
     2128          <para><productname>TREMOLO</productname>&apos;s configuration files start
     2129          with a specific line telling the amount of information that is contained in the
     2130          file. This line can be modified, e.g. to enforce storing of
    27172131          velocities and forces as well as the atoms positions and
    27182132          element.</para>
    2719 
    2720           <programlisting>
    2721                 ... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
    2722                     --reset 1
    2723           </programlisting>
    2724 
     2133          <programlisting>
     2134  ... --set-tremolo-atomdata &quot;ATOM id element u=3 v=3 F=3&quot; \
     2135      --reset 1
     2136   </programlisting>
    27252137          <para>This will not append but reset the old line and fill it with
    27262138          the given string.</para>
    2727 
    2728           <para>One specific action is required when loading certain
     2139          <para>One further specific action is required when loading certain
    27292140          <productname>TREMOLO</productname> configuration files. These
    27302141          contain element notations that refer to parameterized names used in
    … …  
    27322143          usual chemical symbols, such as H or O. We may load an auxiliary
    27332144          file that gives the required conversion from OH1 to H, which is the
    2734           so-called potential file.</para>
    2735 
     2145          so-called potentials file.</para>
    27362146          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
    2737 
    27382147          <para>This parses the lookup table from the file
    27392148          <filename>water.potentials</filename> and it can be used in
    27402149          following load actions.</para>
     2150          <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>
    27412151        </section>
    27422152      </section>
    27432153    </section>
    2744 
    2745     <section xml:id='textmenu-interface'>
    2746       <title xml:id='textmenu-interface.title'>Text menu</title>
    2747 
     2154    <section xml:id="textmenu-interface">
     2155      <title xml:id="textmenu-interface.title">Text menu</title>
    27482156      <para>We now discuss how to use the text menu interface.</para>
    2749 
    27502157      <para>The text menu is very much the interface counterpart to the
    2751       command-line interface. Both work in a terminal session.</para>
    2752 
     2158      command-line interface. However, both work in a terminal session.</para>
    27532159      <para>In the text menu, actions can be selected from hierarchical lists.
    27542160      Note that the menus for the graphical interface are organized in the
    … …  
    27572163      been given, the action is executed and the result printed to the
    27582164      screen.</para>
    2759 
    27602165      <para>With regards to the other functionality, it is very much the same
    2761       as the command-line interface above.</para>
     2166      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>
    27622167    </section>
    2763 
    2764     <section xml:id='graphical-user-interface'>
    2765       <title xml:id='graphical-user-interface.title'>Graphical user interface
    2766       </title>
    2767 
     2168    <section xml:id="graphical-user-interface">
     2169      <title xml:id="graphical-user-interface.title">Graphical user interface </title>
    27682170      <para>The main point of the GUI is that it renders the atoms and
    27692171      molecules visually. These are represented by the common
    2770       stick-and-ball-model. Single or multiple atoms and molecules can easily
    2771       be accessed, activated and manipulated via tables. Changes made in the
     2172      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
     2173      be accessed, activated, and manipulated via tables. Changes made in the
    27722174      tables cause immediate update of the visual representation. Under the
    27732175      hood each of these manipulations is nothing but the call to an action,
    27742176      hence is fully undo- and redoable.</para>
    2775 
    2776       <para>This is mostly helpful to design more advanced structures that are
    2777       conceptually difficult to imagine without visual aid. At the end, a
    2778       session may be stored and this script can then be used to construct
     2177      <para>This interface is most helpful in designing more advanced structures that are
     2178      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
     2179file containing the      session may be stored and this script can then be used to construct
    27792180      various derived or slightly modified structures.</para>
    2780 
    2781       <section xml:id='graphical-user-interface.basic-view'>
    2782         <title xml:id='graphical-user-interface.basic-view.title'>Basic view
    2783         </title>
    2784 
    2785         <para>Let us first give an impression of the basic view of the gui
    2786         after a molecule has been loaded.</para>
    2787 
     2181      <section xml:id="graphical-user-interface.basic-view">
     2182        <title xml:id="graphical-user-interface.basic-view.title">Basic view </title>
     2183        <para>Let us first give an impression of the basic view of the GUI         after a molecule has been loaded.</para>
    27882184        <figure>
    2789           <title>Screenshot of the basic view of the GUI after loading a file
    2790           with eight water molecules.</title>
    2791 
     2185          <title>Screenshot of the basic view of the GUI after loading a file with eight water molecules.</title>
    27922186          <mediaobject>
    27932187            <imageobject>
    2794               <imagedata entityref="example_basic_view" scalefit="1" width="100%"/>
     2188              <imagedata width="100%" scalefit="1" entityref="example_basic_view"/>
    27952189            </imageobject>
    27962190          </mediaobject>
    27972191        </figure>
    2798 
    2799         <section xml:id='graphical-user-interface.3d-view'>
    2800           <title xml:id='graphical-user-interface.3d-view.title'>3D view
    2801           </title>
    2802 
     2192        <section xml:id="graphical-user-interface.3d-view">
     2193          <title xml:id="graphical-user-interface.3d-view.title">3D view </title>
    28032194          <para>In the above figure, you see the stick-and-ball representation
    2804           of the water molecules, the dreibein giving the positive axis
    2805           direction and the cuboidal domain on a black background.</para>
    2806         </section>
    2807 
    2808         <section xml:id='graphical-user-interface.information-tabs'>
    2809           <title xml:id='graphical-user-interface.information-tabs.title'>
    2810           Information Tabs</title>
    2811 
    2812           <para>Beneath this 3D view that you can rotate at will your mouse
     2195          of the water molecules, the &quot;dreibein&quot; giving the positive axis
     2196          directions and the slightly translucent cuboid of the domain on a black background.</para>
     2197        </section>
     2198        <section xml:id="graphical-user-interface.information-tabs">
     2199          <title xml:id="graphical-user-interface.information-tabs.title"> Information Tabs</title>
     2200          <para>Beneath this 3D view that you can rotate at will with your mouse
    28132201          and zoom in and out with your scroll wheel, you find to the right a
    28142202          part containing two tabs named Atom and Molecule. Look at where the
    28152203          mouse pointer is. It has colored the atom underneath in cyan
    2816           (although it's also an oxygen atom and should bne coloured in rose
     2204          (although it&apos;s also an oxygen atom and should be colored in rose
    28172205          as the rest). You can inspect its properties in the tab Atom: Name,
    28182206          element, mass, charge, position and number of bonds. If you switch
    … …  
    28202208          molecule this specific atom belongs to.</para>
    28212209        </section>
    2822 
    2823         <section xml:id='graphical-user-interface.shape'>
    2824           <title xml:id='graphical-user-interface.shape.title'>Shape section
    2825           </title>
    2826 
     2210        <section xml:id="graphical-user-interface.shape">
     2211          <title xml:id="graphical-user-interface.shape.title">Shape section </title>
    28272212          <para>Beneath these information tabs you find the shape sections.
    28282213          There you find a list of all currently created shapes and you can
    2829           manipulate them via the buttons beneath this list.</para>
    2830         </section>
    2831 
    2832         <section xml:id='graphical-user-interface.timeline'>
    2833           <title xml:id='graphical-user-interface.timeline.title'>Timeline
    2834           </title>
    2835 
     2214select 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>
     2215        </section>
     2216        <section xml:id="graphical-user-interface.timeline">
     2217          <title xml:id="graphical-user-interface.timeline.title">Timeline </title>
    28362218          <para>Directly below the 3D view there is a long slider. If a loaded
    28372219          file has multiple time step entries, this slider allows you to
    … …  
    28412223          file.</para>
    28422224        </section>
    2843 
    2844         <section xml:id='graphical-user-interface.tables'>
    2845           <title xml:id='graphical-user-interface.tables.title'>Selection
    2846           tables</title>
    2847 
     2225        <section xml:id="graphical-user-interface.tables">
     2226          <title xml:id="graphical-user-interface.tables.title">Selection tables</title>
    28482227          <para>Underneath the time line there is another place for
    28492228          tabs.</para>
    2850 
    28512229          <para>The first is on molecules, listing all present molecules of
    2852           the molecular system in a list view. If you click on a specific
     2230          the molecular system in a tree view. If you click on a specific
    28532231          molecule, the one will get selected or unselected depending on its
    28542232          current selection state (see below for details on this with respect
    2855           to the GUI).</para>
    2856 
     2233          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>
    28572234          <para>The next tab enumerates all elements known to MoleCuilder
    2858           where the ones are greyed out that are not present in the molecular
     2235          where the ones are grayed out that are not present in the molecular
    28592236          system. Clicking on a present element will select all atoms of this
    28602237          specific element. A subsequent click unselects again.</para>
    2861 
    2862           <para>Subsequent follow tabs on enumerating the fragments and their
     2238          <para>Subsequently follow tabs on enumerating the fragments and their
    28632239          fragment energies if calculated and the homologies along with
    2864           graphical depiction (via QWT) if present.</para>
    2865         </section>
    2866       </section>
    2867 
    2868       <section xml:id='graphical-user-interface.selections'>
    2869         <title xml:id='graphical-user-interface.selections.title'>Selections
    2870         </title>
    2871 
    2872         <para>Selections work generally always by selecting the respective
    2873         action from the pull-down menu.</para>
    2874 
    2875         <para>However, it may also be accessed directly. The row of icons
     2240          graphical depiction (via QWT), again if present.</para>
     2241        </section>
     2242      </section>
     2243      <section xml:id="graphical-user-interface.selections">
     2244        <title xml:id="graphical-user-interface.selections.title">Selections </title>
     2245        <para>Selections work generally always by calling a selection action from the pull-down menu and filling it with required parameters.</para>
     2246        <para>With the GUI it may also be accessed directly: The row of icons
    28762247        above the 3D view has two icons depicting the selection of individual
    28772248        atoms or molecules. If either of them is selected, clicking with the
    … …  
    28792250        associated molecule. Multiple atoms can be selected in this
    28802251        manner.</para>
    2881 
    2882         <para>Also the selection tabs may be used by clicking on the name of a
     2252        <para>Also, the selection tabs may be used by clicking on the name of a
    28832253        molecule as stated above or at an element.</para>
    2884 
    28852254        <para>Similarly, if shapes are present in the shape section, clicking
    2886         them with select them and also cause a translucent visualization to
     2255        them will select them and also cause a translucent visualization to
    28872256        appear in the 3D view. Note that this visualization is quite costly
    2888         right now and not suited to complex shapes.</para>
    2889       </section>
    2890 
    2891       <section xml:id='graphical-user-interface.dialogs'>
    2892         <title xml:id='graphical-user-interface.dialogs.title'>Dialogs</title>
    2893 
    2894         <para>Most essential, however, to the GUI are the dialogs. Each action
    2895         calls forth such a dialog even if no options are required (the
    2896         execution of the action has at least to be confirmed). Each dialog
    2897         consisting of queries for a particular option value. As each option
     2257        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>
     2258      </section>
     2259      <section xml:id="graphical-user-interface.dialogs">
     2260        <title xml:id="graphical-user-interface.dialogs.title">Dialogs</title>
     2261        <para>Most essential to the GUI are dialogs. Many action
     2262        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
    28982263        value has a specific type, we briefly go into the details of how these
    28992264        queries look like.</para>
    2900 
    29012265        <note>
    2902           <para>Each dialog's Ok is greyed out until all entered option values
     2266          <para>Each dialog&apos;s okay button is grayed out until all entered option values
    29032267          are valid.</para>
    29042268        </note>
    2905 
    2906         <section xml:id='graphical-user-interface.dialogs.domain'>
    2907           <title xml:id='graphical-user-interface.dialogs.domain.title'>Domain
    2908           query</title>
    2909 
     2269        <section xml:id="graphical-user-interface.dialogs.domain">
     2270          <title xml:id="graphical-user-interface.dialogs.domain.title">Domain query</title>
    29102271          <figure>
    29112272            <title>Screenshot of a dialog showing a domain query</title>
    2912 
    29132273            <mediaobject>
    29142274              <imageobject>
    2915                 <imagedata entityref="dialog_box" scalefit="1" width="100%"/>
     2275                <imagedata width="100%" scalefit="1" entityref="dialog_box"/>
    29162276              </imageobject>
    29172277            </mediaobject>
    2918 
    29192278            <para>In the domain query a 3x3 symmetric matrix has to be
    29202279            entered. In the above screenshots you notice that the only
    29212280            non-zero entries are on the main diagonal. Here, we have simply
    2922             specified a cube of edge length 8. The ok button will be greyed
     2281            specified a cube of edge length 8. The okay button will be grayed
    29232282            out if the matrix is either singular or not symmetric.</para>
    29242283          </figure>
    29252284        </section>
    2926 
    2927         <section xml:id='graphical-user-interface.dialogs.element'>
    2928           <title xml:id='graphical-user-interface.dialogs.element.title'>
    2929           Element query</title>
    2930 
     2285        <section xml:id="graphical-user-interface.dialogs.element">
     2286          <title xml:id="graphical-user-interface.dialogs.element.title"> Element query</title>
    29312287          <figure>
    2932             <title>Screenshot the add atom action containing an element
    2933             query</title>
    2934 
     2288            <title>Screenshot the add atom action containing an element query</title>
    29352289            <mediaobject>
    29362290              <imageobject>
    2937                 <imagedata entityref="dialog_add-atom_tooltip" scalefit="1" width="100%"/>
     2291                <imagedata width="100%" scalefit="1" entityref="dialog_add-atom_tooltip"/>
    29382292              </imageobject>
    29392293            </mediaobject>
    2940 
    29412294            <para>Elements are picked from a pull-down box where all known
    29422295            elements are listed.</para>
    2943 
    29442296            <para>In this dialog you also notice that a tooltip is given,
    29452297            briefly explaining what the action does.</para>
    29462298          </figure>
    29472299        </section>
    2948 
    2949         <section xml:id='graphical-user-interface.dialogs.action'>
    2950           <title xml:id='graphical-user-interface.dialogs.action.title'>
    2951           Complex query</title>
    2952 
     2300        <section xml:id="graphical-user-interface.dialogs.action">
     2301          <title xml:id="graphical-user-interface.dialogs.action.title"> Complex query</title>
    29532302          <figure>
    2954             <title>Screenshot of a complex dialog consisting of multiple
    2955             queries</title>
    2956 
     2303            <title>Screenshot of a complex dialog consisting of multiple queries</title>
    29572304            <mediaobject>
    29582305              <imageobject>
    2959                 <imagedata entityref="dialog_complex" scalefit="1" width="100%"/>
     2306                <imagedata width="100%" scalefit="1" entityref="dialog_complex"/>
    29602307              </imageobject>
    29612308            </mediaobject>
    2962 
    29632309            <para>Here we show a more complex dialog. It queries for strings,
    29642310            for integer values (see the increase/decrease arrows), for
    2965             booleans and for files (the "choose" buttons opens a file
     2311            booleans and for files (the &quot;choose&quot; buttons opens a file
    29662312            dialog).</para>
    29672313          </figure>
    29682314        </section>
    2969 
    2970         <section xml:id='graphical-user-interface.dialogs.exit'>
    2971           <title xml:id='graphical-user-interface.dialogs.exit.title'>Exit
    2972           query</title>
    2973 
     2315        <section xml:id="graphical-user-interface.dialogs.exit">
     2316          <title xml:id="graphical-user-interface.dialogs.exit.title">Exit query</title>
    29742317          <figure>
    29752318            <title>Screenshort showing the exit dialog</title>
    2976 
    29772319            <mediaobject>
    29782320              <imageobject>
    2979                 <imagedata entityref="dialog_exit" scalefit="1" width="100%"/>
     2321                <imagedata width="100%" scalefit="1" entityref="dialog_exit"/>
    29802322              </imageobject>
    29812323            </mediaobject>
    2982 
    29832324            <para>Finally, we show the dialog that will pop up when exiting
    29842325            the graphical interface. It will ask whether it should store the
    … …  
    29902331      </section>
    29912332    </section>
    2992 
    2993     <section xml:id='python-interface'>
    2994       <title xml:id='python-interface.title'>Python interface</title>
    2995 
     2333    <section xml:id="python-interface">
     2334      <title xml:id="python-interface.title">Python interface</title>
    29962335      <para>Last but not least we elaborate on the python interface. We have
    29972336      already discusses this interface to some extent. The current session,
    29982337      i.e. the queue of actions you have executed, can be stored as a python
    29992338      script and subsequently executed independently of the user interface it
    3000       was created with. More general, MoleCuilder can execute arbitrary python
    3001       scripts where prior to its execution a specific module is loaded by
    3002       default enabling access to MoleCuilder's actions from inside the
     2339      was created with. More generally, MoleCuilder&apos;s Actions can be executed within arbitrary python
     2340      scripts where prior to its execution a specific module has to be loaded, enabling access to MoleCuilder&apos;s actions from inside the
    30032341      script.</para>
    3004 
    3005       <para>MoleCuilder's python module is called pyMoleCuilder. it is
     2342      <para>MoleCuilder&apos;s python module is called <emphasis role="italic">pyMoleCuilder</emphasis>. It is
    30062343      essentially a library that can be imported into python just as any other
    30072344      module. Let us assume you have started the python interpreter and you
    3008       have added the destination of the <filename>pyMoleCuilder</filename>
     2345      have added the containing folder of the <filename>pyMoleCuilder</filename>
    30092346      library to the <varname>PYTHONPATH</varname> variable.</para>
    3010 
    30112347      <programlisting>import pyMoleCuilder as mol</programlisting>
    3012 
    30132348      <para>Subsequently, you can access the help via</para>
    3014 
    30152349      <programlisting>help(mol)</programlisting>
    3016 
    3017       <para>This will list all of MoleCuilder's actions with their function
    3018       signatures within python as contained in the module pyMoleCuilder named
    3019       as mol in the scope of the currently running interpreter. Note that the
     2350      <para>This will list all of MoleCuilder&apos;s actions with their function
     2351      signatures within python as contained in the module <emphasis role="italic">pyMoleCuilder</emphasis> named
     2352      as <emphasis role="bold">mol</emphasis> in the scope of the currently running interpreter. Note that the
    30202353      function names are not the names you know from the command-line
    30212354      interface, they might be called
    3022       <computeroutput>WorldChangeBox(...)</computeroutput> or alike.</para>
    3023 
    3024       <para>Let's try it out.</para>
    3025 
     2355      <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>
     2356      <para>Let&apos;s try it out.</para>
    30262357      <programlisting>print mol.CommandVersion()</programlisting>
    3027 
    30282358      <para>This will state the current version of the library.</para>
    3029 
    30302359      <para>Go ahead and try out other commands. Refer to the documentation
    30312360      under the command-line interface and look up the function name via
    … …  
    30332362    </section>
    30342363  </chapter>
    3035 
    30362364  <chapter>
    30372365    <title>Conclusions</title>
    3038 
    30392366    <para>This ends this user guide.</para>
    3040 
    30412367    <para>We have given you a brief introduction to the aim of the program and
    30422368    how each of the four interfaces are to be used. The rest is up to
    30432369    you.</para>
    3044 
    3045     <para>Tutorials and more information is available online, see <link
    3046     xlink:href="http://www.molecuilder.com/">MoleCuilder's website</link>.
     2370    <para>Tutorials and more information is available online, see <link xlink:href="http://www.molecuilder.com/">MoleCuilder&apos;s website</link>.
    30472371    </para>
    3048 
    30492372    <para>Be aware that in general knowing how the code works allows you to
    3050     understand what's going wrong if something's going wrong.</para>
    3051 
     2373    understand what&apos;s going wrong if something&apos;s going wrong.</para>
    30522374    <section>
    30532375      <title>Thanks</title>
    3054 
    30552376      <para>Huge thanks go out to Saskia Metzler who was patient enough to let
    3056       me sit next to her while riding ten hours in a bus to Berlin.</para>
     2377      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>
    30572378    </section>
    30582379  </chapter>
Note: See TracChangeset for help on using the changeset viewer.