Changeset f1cacb


Ignore:
Timestamp:
Jul 3, 2017, 3:01:38 PM (7 years ago)
Author:
Frederik Heber <frederik.heber@…>
Branches:
Action_Thermostats, Add_SelectAtomByNameAction, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_StructOpt_integration_tests, AutomationFragmentation_failures, Candidate_v1.6.1, ChemicalSpaceEvaluator, EmpiricalPotential_contain_HomologyGraph_documentation, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, Fix_Verbose_Codepatterns, ForceAnnealing_oldresults, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, Gui_displays_atomic_force_velocity, IndependentFragmentGrids_IntegrationTest, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, PythonUI_with_named_parameters, Recreated_GuiChecks, StoppableMakroAction, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps
Children:
9a4772
Parents:
4dfe724
git-author:
Frederik Heber <heber@…> (04/11/17 13:51:13)
git-committer:
Frederik Heber <frederik.heber@…> (07/03/17 15:01:38)
Message:

Fixed several small issues with the userguide.

  • additional backslashes on programlistings.
  • misunderstandable wordings.
  • missing options (reverse in geometry).
  • place fastparsing with load/input.
  • made additional notes, e.g. shapes are visualized in QtGui.
  • mathml finally working.
  • fixed indentation of programlistings.
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/userguide/userguide.xml

    r4dfe724 rf1cacb  
    88<!ENTITY example_basic_view SYSTEM "pictures/example_basic_view.png" NDATA PNG>
    99]>
    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">
     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:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0">
    1111  <info>
    1212    <title>MoleCuilder - a Molecule Builder</title>
    … …  
    5353      molecular systems, and on scriptability. The last being important a eventually not a single, but
    5454      many, related molecular systems have to be created.</para>
    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>
     55      <para>We hope you will enjoy using MoleCuilder as much as we had creating
     56      it and still continue extending it. It obtains its flexibility from the use of
     57       agile programming techniques and state-of-the-art libraries such as Boost.
     58       If you feel dissatiesfied with certain parts, please do not hesitate to give
     59        feedback (see below).</para>
    5660      <section xml:id="installation">
    5761        <title xml:id="installation.title">Installation requirements</title>
    … …  
    161165          <para>Domain</para>
    162166          <para>The domain refers to the simulation domain. It is the
    163           parallelepiped in <inlineequation>
    164               <m:math display="inline">
    165                 <m:mi>\mathbb{R}^3</m:mi>
    166               </m:math>
    167             </inlineequation>where either periodic, wrapped, or open boundary
     167          parallelepiped in
     168          <inlineequation>
     169              <mml:math display="inline">
     170                <mml:mrow>
     171                  <mml:msup>
     172                    <mml:mi>R</mml:mi>
     173                    <mml:mn>3</mml:mn>
     174                  </mml:msup>
     175                </mml:mrow>
     176              </mml:math>
     177            </inlineequation>
     178            where either periodic, wrapped, or open boundary
    168179          conditions apply. The domain contains all atoms, i.e. the box
    169180          containing all atoms.</para>
    … …  
    385396          <para>This will load another file <filename>water.xyz</filename>,
    386397          however changes will still be written to files prefixed with
    387           <filename>water</filename> as designated by the <emphasis role="bold">input</emphasis> command. Note that now already two state files
    388           will stored, <filename>water.data</filename> and
     398          <filename>water</filename> as designated by the
     399          <emphasis role="bold">input</emphasis> command. Note that now already
     400          two state files will stored, <filename>water.data</filename> and
    389401          <filename>water.xyz</filename> as these two different file formats
    390           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>
     402          have been used. This is the default behavior: any additional file
     403          format used in loading is registered internally and the output file
     404           will then be written in all registered formats on exit.</para>
     405          <note>If the loaded file is empty, then no parser is registered. This
     406           means if a new state file needs to be written,then the output format
     407           has to be stated explicitly, e.g.
     408          <programlisting>... --input hydrogen.xyz \
     409    --set-output xyz \
     410    --add-atom H --domain-position "0,0,0" </programlisting>
     411           </note>
     412          <note xml:id="various.fastparsing">
     413          <para>In the case that parsing all time steps from a given input
     414          file will take too long, especially for larger systems, fast parsing
     415          may be activated, only the first time step is loaded, all other are
     416           ignored.</para>
     417          <programlisting>... --fastparsing 1</programlisting>
     418        </note>
    391419        </section>
    392420        <section xml:id="fileparsers.set-output">
    … …  
    401429        <link linkend="fileformats">File formats</link> for the list of all file formats available.</para>
    402430        </section>
    403         <section xml:id="fileparsers.output-as">
    404           <title xml:id="fileparsers.output-as.title">Output the World</title>
    405           <para>This will store the current World, i.e. all its atoms, to a
    406           given file, where the output format is determined from the file
    407           suffix.</para>
     431        <section xml:id="fileparsers.storing">
     432          <title xml:id="fileparsers.storing.title">Storing to files</title>
     433          <para>Storing the current World, i.e. all its atoms, to a
     434          given file, happens automaticallyon program exists if an
     435          <link linkend="fileparsers.parsing">input</link> file has been
     436          specified. However, this can also be forced at any point in between
     437          by using one of two actions:</para>
     438          <programlisting>... --output</programlisting>
     439          <para>This action does not use an argument and will simply use the
     440          currently registered input file and store the state of the World there
     441          This is handy if an intermediate state is required (making sense for
     442          interactive and python interfaces).</para>
    408443          <programlisting>... --output-as world.xyz</programlisting>
    409           <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>
     444          <para>This action on the other hand will be write the current state
     445          to a new file "world.xyz".</para>
    410446        </section>
    411447        <section xml:id="fileparsers.save-selected-molecules">
    … …  
    491527              </listitem>
    492528              <listitem>
    493                 <para>By Shape (all atoms inside the volume specified by the currently selected shape)</para>
     529                <para id="selections.select-atom-inside-volume">By Shape (all
     530                atoms inside the volume specified by the currently selected
     531                 shape)</para>
    494532                <programlisting>
    495533                ... --select-atom-inside-volume
    … …  
    511549              <listitem>
    512550                <para>Push/Pop the current selection to/from a stack to store
    513   it momentarily and allow modifications in MakroActions (this is very specific and used mostly internally).</para>
     551                it momentarily and allow modifications in MakroActions (this is
     552                 very specific and used mostly internally).</para>
    514553                <programlisting>
    515554                ... --push-atom-selection
    … …  
    646685        combining a sphere with the negated (<emphasis role="italic">not</emphasis> operation) of a smaller sphere, we
    647686        obtain a spherical surface of specific thickness.</para>
     687        <note>Shapes are especially useful in the QtGui where all selected
     688        shapes are visualized by their translucent boundary. This makes it
     689        especially easy to e.g. recognize all atoms that would be removed
     690        after <link linkend="selections.select-atom-inside-volume">selecting
     691        all atoms inside the volume</link> of a selected shape.</note>
    648692        <section xml:id="shapes.create-shape">
    649693          <title xml:id="shapes.create-shape.title">Creating shapes</title>
    … …  
    785829          <programlisting>
    786830  ... --distance-to-vector &quot;distance_vec&quot; \
     831      --reverse 0
    787832          </programlisting>
    788833          <para>where the distance vector can be referenced by &quot;distance_vec&quot;
    789834          from then on in other Actions requiring a vector as input.</para>
     835          <note>Since selected atoms are used in the fixed order of their ids
     836           (and not in the order they were clicked at in
     837           <link linkend="graphical-user-interface">QtGui</link>), the
     838           direction can be inverted by giving the "reverse" option. It is
     839           off (or 0) by default.</note>
    790840        </section>
    791841        <section xml:id="geometry.input-to.vector">
    … …  
    809859          <programlisting>
    810860  ... --plane-to-vector &quot;planenormal&quot; \
     861      --reverse 1
    811862          </programlisting>
    812863          <para>where the plane's normal vector can be referenced by
    813           &quot;planenormal&quot;.</para>
     864          &quot;planenormal&quot;. The additional "reverse" option will invert
     865          the plane's normal vector as this is ambiguous about the direction.</para>
    814866        </section>
    815867        <section xml:id="geometry.position-to.vector">
    … …  
    823875        </section>
    824876        <section xml:id="geometry.remove-geometry">
    825           <title xml:id="geometry.remove-geometry.title">Remove A stored vector</title>
     877          <title xml:id="geometry.remove-geometry.title">Remove a stored vector</title>
    826878          <para>Finally, a stored vector can also be removed.</para>
    827879          <programlisting>
    … …  
    859911        <para>Specifying the seed allows you to obtain the same sequence of
    860912        random numbers for testing purposes.</para>
     913        <para>Moreover, actions such as
     914        <link linkend="atoms.random-perturbation">random perturbation</link>
     915        of atoms and <link linkend="filling">filling</link> of molecules into the
     916        domain use the random number generator.</para>
    861917      </section>
    862918      <section xml:id="atoms">
    … …  
    883939          <para>The positions of a set of selected atom(s) can be randomly
    884940          perturbed by giving a maximum noise level..</para>
    885           <programlisting>
    886           ... --random-number-distribution "uniform_01"
    887       --random-perturbation 0.1</programlisting>
     941          <programlisting>... --random-number-distribution "uniform_01" \
     942    --random-perturbation 0.1</programlisting>
    888943          <para>This will perturb all atomic positions by adding a vector
    889944          with components chosen randomly from the interval [-level, level].</para>
    … …  
    910965          <para>A number of hydrogen atoms is added around each selected atom
    911966          corresponding to the valence of the chemical element. The hydrogen
    912           atoms are placed in the same distance to this atom and approximately
    913           with same distance to their nearest neighbors. Already present bonds
    914           (i.e. the position of neighboring atoms) is taken into account.</para>
     967          atoms are placed at the same distance to the selected atom which is
     968          taken from an internal database for the typical hydrogen bond length
     969          and approximately with same distance to their nearest neighbor
     970          hydrogens. Already present bonds (i.e. the position of neighboring
     971          atoms) are taken into account and left intact.</para>
    915972        </section>
    916973        <section xml:id="atoms.translate-atom">
    … …  
    936993          <programlisting>
    937994  ... --mirror-atoms &quot;1,0,0&quot; \
    938                     --plane-offset 10.1 \
    939                     --periodic 0
     995      --plane-offset 10.1 \
     996      --periodic 0
    940997   </programlisting>
    941998         <para>And of course instead of giving an explicit vector you may also
    … …  
    9701027          <para>In case you have loaded a configuration file with no bond
    9711028          information, e.g. XYZ, it is necessary to create the bond graph.
    972           This is done by a heuristic distance criterion.</para>
    973           <programlisting>... --create-adjacency</programlisting>
    974           <para>This uses by default a criterion based on van-der-Waals radii,
     1029          This is done by either of two options, based on a heuristic criterion.</para>
     1030          <para>By default it is based on van-der-Waals radii,
    9751031          i.e. if we look at two atoms indexed by &quot;a&quot; and &quot;b&quot;</para>
    9761032          <equation>
    977             <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) + \tau</title>
    978             <m:math display="block">
    979               <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>
    980             </m:math>
     1033            <title></title>
     1034            <mml:math display="block">
     1035              <mml:mrow>
     1036                <mml:mi>V(a) + V(b) - &tau; &lt;</mml:mi>
     1037                <mml:msub>
     1038                  <mml:mi>R</mml:mi>
     1039                  <mml:mn>ab</mml:mn>
     1040                </mml:msub>
     1041                <mml:mi>&lt; V(a) + V(b) + &tau;</mml:mi>
     1042              </mml:mrow>
     1043            </mml:math>
    9811044          </equation>
    982           <para>As a second option, you may load a file containing bond table
     1045          where
     1046          <inlineequation>
     1047              <mml:math display="inline">
     1048                <mml:mrow>
     1049                  <mml:mi>V(.)</mml:mi>
     1050                </mml:mrow>
     1051              </mml:math>
     1052            </inlineequation>
     1053          is the lookup table for the radii for a given element and \tau is a threshold value, set to 0.4.
     1054          <para>As a alternative option, you may load a file containing bond table
    9831055          information.</para>
    9841056          <programlisting>... --bond-table table.dat</programlisting>
    9851057          <para>which would parse a file <filename>table.dat</filename> for a
    9861058          table giving typical bond distances between elements a and b. These
    987           are used in the above criterion as <inlineequation>
    988               <m:math display="inline">
    989                 <m:mi>V(a,b)</m:mi>
    990               </m:math>
    991             </inlineequation> in place of <inlineequation>
    992               <m:math display="inline">
    993                 <m:mi>V(a)+V(b)</m:mi>
    994               </m:math>
    995             </inlineequation>.</para>
     1059          are used in the above criterion as
     1060          <inlineequation>
     1061              <mml:math display="inline">
     1062                <mml:mrow>
     1063                  <mml:mi>V(a,b)</mml:mi>
     1064                </mml:mrow>
     1065              </mml:math>
     1066            </inlineequation>
     1067            in place of
     1068            <inlineequation>
     1069              <mml:math display="inline">
     1070                <mml:mrow>
     1071                  <mml:mi>V(a) + V(b)</mml:mi>
     1072                </mml:mrow>
     1073              </mml:math>
     1074            </inlineequation>
     1075            .</para>
     1076            <para>In either case,</para>
     1077          <programlisting>... --create-adjacency</programlisting>
     1078          <para> will then create the bond graph based on above criterion.</para>
    9961079        </section>
    9971080        <section xml:id="bond.destroy-adjacency">
    … …  
    10251108          <title xml:id="bond.subgraph-dissection.title">Dissecting the molecular system into molecules</title>
    10261109          <para>The bond graph information can be used to recognize the
    1027           molecules within the system. Imagine you have just loaded a PDB file
    1028           containing bond information. However, initially all atoms are dumped
    1029           into the same molecule. Before you can start manipulating, you need
    1030           to dissect the system into individual molecules. Note that this is
    1031           just structural information and does not change the state of the
    1032           system.</para>
     1110          molecules within the system. It removes the current bond graph (if
     1111          any bonds are presents) and recreates it. Afterwards it walks it along
     1112          and finds any disconnected subgraphs, associating a molecule with
     1113          each. Note that this is just structural information and does not
     1114          change the state of the system.</para>
    10331115          <programlisting>... --subgraph-dissection</programlisting>
    1034           <para>This analyses the bond graph, removes all currently present molecules and creates new molecules that each contain a single connected
    1035           subgraph, hence the naming of the Action.</para>
    10361116        </section>
    10371117        <section xml:id="bond.update-molecules">
    … …  
    10391119          <para>When the bond information has changed, new molecules might
    10401120          have formed, this action updates all the molecules by scanning
    1041           the connectedness of the bond graph of the molecular system.
     1121          the connectedness of the bond graph of the molecular system. </para>
     1122          <para>Moreover, Imagine you have just loaded a PDB file
     1123          containing bond information. However, initially all atoms are dumped
     1124          into the same molecule. Before you can start manipulating, you need
     1125          to dissect the system into individual molecules.
    10421126          </para>
    10431127          <programlisting>... --update-molecules</programlisting>
    … …  
    10811165        <section xml:id="bond.save-bonds">
    10821166          <title xml:id="bond.save-bonds.title">Saving bond information </title>
    1083           <para>Bond information can be saved to a file in <link xlink:href="http://www.molecuilder.com/">
    1084               <productname>TREMOLO </productname>
    1085             </link>&apos;s dbond style.</para>
     1167          <para>Bond information can be saved to a file in
     1168              <productname>TREMOLO </productname>&apos;s dbond style.</para>
    10861169          <programlisting>... --save-bonds system.dbonds</programlisting>
    10871170          <para>Similarly is the following Action which saves the bond
    … …  
    12001283          <programlisting>
    12011284  ... --rotate-around-bond &quot;90&quot; \
    1202       --bond-side 0\
     1285      --bond-side 0
    12031286   </programlisting>
    12041287        </section>
    … …  
    12541337      --keep-fixed-CenterOfMass 0
    12551338   </programlisting>
    1256           <para>This will integrate with a timestep of <inlineequation>
    1257               <m:math display="inline">
    1258                 <m:mi>\Delta_t = 0.1</m:mi>
    1259               </m:math>
    1260             </inlineequation>and correcting forces and velocities such that
     1339          <para>This will integrate with a timestep of
     1340          <inlineequation>
     1341              <mml:math display="inline">
     1342                <mml:mrow>
     1343                  <mml:mi>
     1344                    <mml:msub>
     1345                      <mml:mi>&Delta;</mml:mi>
     1346                      <mml:mn>t</mml:mn>
     1347                    </mml:msub>
     1348                    <mml:mi>= V(a) + V(b)</mml:mi>
     1349                  </mml:mi>
     1350                </mml:mrow>
     1351              </mml:math>
     1352            </inlineequation>
     1353            and correcting forces and velocities such that
    12611354          the sum over all atoms is zero.</para>
     1355          <note>Although it may be useful in rare cases to use this Action
     1356          directly, most of the time it is far more convenient to use the
     1357          MakroAction <link linkend="dynamics.molecular-dynamics">molecular-dynamics</link>
     1358          which incorporates also the force calculation and allows for time
     1359          integration over more than just a single time step.</note>
    12621360        </section>
    12631361        <section xml:id="molecule.force-annealing">
    … …  
    12711369          units and do not create a new timestep for each optimization
    12721370          step.</para>
    1273           <programlisting>
    1274           ... --force-annealing \
    1275           --forces-file test.forces \
    1276           --deltat 0.5 \
    1277           --steps 1 \
    1278           --output-every-step 0
     1371          <programlisting>... --force-annealing \
     1372    --forces-file test.forces \
     1373    --deltat 0.5 \
     1374    --steps 1 \
     1375    --output-every-step 0
    12791376          </programlisting>
     1377          <note>Same as before, although in rare useful, we refer to the
     1378          MakroAction <link linkend="dynamics.optimize-structure">optimize-structure</link>
     1379          which incorporates also the force calculation and allows for
     1380          structure optimization over more than just a single step.</note>
    12801381        </section>
    12811382        <section xml:id="molecule.linear-interpolation-of-trajectories">
    … …  
    12891390          case an identity mapping is used to associated atoms in start and
    12901391          end configuration.</para>
    1291           <programlisting>
    1292           ... --linear-interpolation-of-trajectories \
    1293           --start-step 0 \
    1294           --end-step 1 \
    1295           --interpolation-steps 100 \
    1296           --id-mapping 1
     1392          <programlisting>... --linear-interpolation-of-trajectories \
     1393    --start-step 0 \
     1394    --end-step 1 \
     1395    --interpolation-steps 100 \
     1396    --id-mapping 1
    12971397          </programlisting>
    12981398        </section>
    … …  
    13551455          <programlisting>... --scale-box &quot;1,1,2.5&quot;</programlisting>
    13561456          <para>Here, the domain is stretched in the z direction by a factor
    1357           of 2.5.</para>
     1457          of 2.5. Also, all positions are scaled by the same factor.</para>
    13581458        </section>
    13591459        <section xml:id="domain.repeat-box">
    … …  
    15221622          water one might be interested what is the typical distance for
    15231623          hydrogen and oxygen atoms.</para>
    1524           <programlisting>
    1525           ... --pair-correlation \
    1526               --elements 1 8 \
    1527               --bin-start 0 \
    1528               --bin-width 0.7 \
    1529               --bin-end 10 \
    1530               --output-file histogram.dat \
    1531               --bin-output-file bins.dat \
    1532               --periodic 0
     1624          <programlisting>... --pair-correlation \
     1625    --elements 1 8 \
     1626    --bin-start 0 \
     1627    --bin-width 0.7 \
     1628    --bin-end 10 \
     1629    --output-file histogram.dat \
     1630    --bin-output-file bins.dat \
     1631    --periodic 0
    15331632          </programlisting>
    15341633          <para>This will compile a histogram for the interval [0,10] in steps
    … …  
    15441643          <para>Note that the dipole correlation works on the currently
    15451644          selected molecules, e.g. all water molecules if so selected.</para>
    1546           <programlisting>
    1547           ... --dipole-correlation \
    1548               --bin-start 0 \
    1549               --bin-width 0.7 \
    1550               --bin-end 10 \
    1551               --output-file histogram.dat \
    1552               --bin-output-file bins.dat \
    1553               --periodic 0
     1645          <programlisting>... --dipole-correlation \
     1646    --bin-start 0 \
     1647    --bin-width 0.7 \
     1648    --bin-end 10 \
     1649    --output-file histogram.dat \
     1650    --bin-output-file bins.dat \
     1651    --periodic 0
    15541652          </programlisting>
    15551653          <para>Hence, instead of calculating a function of the distance in [0,infinity), it calculates the angular histogram in [0,2pi).</para>
    … …  
    15671665          might change.
    15681666          </para>
    1569           <programlisting>
    1570           ... --dipole-angular-correlation H2O \
    1571               --bin-start 0 \
    1572               --bin-width 5 \
    1573               --bin-end 360 \
    1574               --output-file histogram.dat \
    1575               --bin-output-file bins.dat \
    1576               --periodic 0 \
    1577               --time-step-zero 0
     1667          <programlisting>... --dipole-angular-correlation H2O \
     1668    --bin-start 0 \
     1669    --bin-width 5 \
     1670    --bin-end 360 \
     1671    --output-file histogram.dat \
     1672    --bin-output-file bins.dat \
     1673    --periodic 0 \
     1674    --time-step-zero 0
    15781675          </programlisting>
    15791676        </section>
    … …  
    15831680          that it correlates not positions of atoms among one another but
    15841681          against a fixed, given point.</para>
    1585           <programlisting>
    1586           ... --point-correlation \
    1587               --elements 1 8 \
    1588               --position &quot;0,0,0&quot; \
    1589               --bin-start 0 \
    1590               --bin-width 0.7 \
    1591               --bin-end 10 \
    1592               --output-file histogram.dat \
    1593               --bin-output-file bins.dat \
    1594               --periodic 0
     1682          <programlisting>... --point-correlation \
     1683    --elements 1 8 \
     1684    --position &quot;0,0,0&quot; \
     1685    --bin-start 0 \
     1686    --bin-width 0.7 \
     1687    --bin-end 10 \
     1688    --output-file histogram.dat \
     1689    --bin-output-file bins.dat \
     1690    --periodic 0
    15951691          </programlisting>
    15961692          <para>This would calculate the correlation of all hydrogen and
    … …  
    16041700          <para>The surface correlation calculates the distance of a set
    16051701          of atoms with respect to a tesselated surface.</para>
    1606           <programlisting>
    1607           ... --surface-correlation \
    1608               --elements 1 8 \
    1609               --bin-start 0 \
    1610               --bin-width 0.7 \
    1611               --bin-end 10 \
    1612               --output-file histogram.dat \
    1613               --bin-output-file bins.dat \
    1614               --periodic 0
     1702          <programlisting>... --surface-correlation \
     1703    --elements 1 8 \
     1704    --bin-start 0 \
     1705    --bin-width 0.7 \
     1706    --bin-end 10 \
     1707    --output-file histogram.dat \
     1708    --bin-output-file bins.dat \
     1709    --periodic 0
    16151710          </programlisting>
    16161711        </section>
    … …  
    16191714          <para>This simply calculates the volume that a selected molecule
    16201715          occupies. For this the molecular surface is determined via a
    1621 (convex)           tesselation of its surface. Note that this surface is minimal is that aspect
    1622           that each node of the tesselation consists of an atom of the
    1623           molecule.</para>
     1716          tesselation of its surface. Note that this surface is minimal in
     1717          that respect that each node of the tesselation consists of an atom
     1718          of the molecule.</para>
    16241719          <programlisting>... --molecular-volume</programlisting>
     1720          <note>The rolling sphere used in the tesselation algorithm has a
     1721          default diameter of 10 angström.</note>
    16251722        </section>
    16261723        <section xml:id="analysis.average-molecule-force">
    … …  
    16511748        <para>The reason for doing this is that usual ab-initio calculations
    16521749        of molecular systems via methods such as Density Functional Theory or
    1653         Hartree-Fock scale at least as <inlineequation>
    1654             <m:math display="inline">
    1655               <m:mi>{\cal O}(M^3}</m:mi>
    1656             </m:math>
    1657           </inlineequation>with the number of atoms <inlineequation>
    1658             <m:math display="inline">
    1659               <m:mi>M</m:mi>
    1660             </m:math>
    1661           </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
     1750        Hartree-Fock scale at least as
     1751        <inlineequation>
     1752            <mml:math display="inline">
     1753              <mml:mrow>
     1754                <mml:mi>O(</mml:mi>
     1755                <mml:msup>
     1756                  <mml:mi>M</mml:mi>
     1757                  <mml:mn>3</mml:mn>
     1758                </mml:msup>
     1759                <mml:mi>)</mml:mi>
     1760              </mml:mrow>
     1761            </mml:math>
     1762          </inlineequation>
     1763          with the number of atoms
     1764          <inlineequation>
     1765            <mml:math display="inline">
     1766              <mml:mrow>
     1767                <mml:mi>M</mml:mi>
     1768              </mml:mrow>
     1769            </mml:math>
     1770          </inlineequation>
     1771          . 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
    16621772        number of fragment molecules becomes a linear scaling operation with the number of atoms. In the doctoral thesis of Frederik
    16631773        Heber, it is explained why this is a sensible ansatz mathematically
    … …  
    17021812          the whole ring becomes a fragment, we partially overcome these
    17031813          issues. This does however not work indefinitely and accuracy of the
    1704           approximation is limited (<inlineequation>
    1705               <m:math display="inline">
    1706                 <m:mi>&gt;10^{-4}</m:mi>
    1707               </m:math>
     1814          approximation is limited (
     1815          <inlineequation>
     1816              <mml:math display="inline">
     1817                <mml:mrow>
     1818                  <mml:mi>&gt;</mml:mi>
     1819                  <mml:msup>
     1820                    <mml:mi>10</mml:mi>
     1821                    <mml:mn>-4</mml:mn>
     1822                  </mml:msup>
     1823                </mml:mrow>
     1824              </mml:math>
    17081825            </inlineequation>) in systems with many interconnected aromatic
    17091826          rings, such as graphene. Next, we give a distance cutoff of 3 angstroem used
    … …  
    17171834          requires the density which is sampled on a cartesian grid whose
    17181835          resolution these parameter defines (<inlineequation>
    1719               <m:math display="inline">
    1720                 <m:mi>2^{\mathrm{level}}</m:mi>
    1721               </m:math>
     1836              <mml:math display="inline">
     1837                <mml:mrow>
     1838                  <mml:msup>
     1839                    <mml:mi>2</mml:mi>
     1840                    <mml:mn>level</mml:mn>
     1841                  </mml:msup>
     1842                </mml:mrow>
     1843              </mml:math>
    17221844            </inlineequation>). And finally, we give the output file formats,
    17231845          i.e. which file formats are used for writing each fragment
    … …  
    18221944          <note>All calculated results may be placed in a result file for
    18231945          later parsing, see
    1824           <link linkend="molecule.save-fragment-results">save fragment results</link>
     1946          <link linkend="fragmentation.save-fragment-results">save fragment results</link>
    18251947          .</note>
    18261948        </section>
    … …  
    18491971          is possible afterwards.</para>
    18501972          <note>If not obtained by
    1851           <link linkend="molecule.fragment-automation">fragment automation</link>
     1973          <link linkend="fragmentation.fragment-automation">fragment automation</link>
    18521974          then fragment results need to be parsed from file, see
    1853           <link linkend="molecule.parse-fragment-results">parse fragment results</link>
     1975          <link linkend="fragmentation.parse-fragment-results">parse fragment results</link>
    18541976          .</note>
    18551977        </section>
    … …  
    18701992          <title xml:id="fragmentation.parse-fragment-jobs.title">Parse fragment jobs from files</title>
    18711993          <para>The fragment jobs that are created by
    1872           <link linkend="molecule.fragment-molecule">fragment molecule</link>
     1994          <link linkend="fragmentation.fragment-molecule">fragment molecule</link>
    18731995          may also be placed in a file for later retrieval. See the details of
    18741996          this action on how to create one file per job.</para>
    … …  
    18892011          of the fragment jobs. Or if that has been done at some earlier
    18902012          stage and results have been written to a file, see
    1891           <link linkend="molecule.save-fragment-results">save fragment results</link>
     2013          <link linkend="fragmentation.save-fragment-results">save fragment results</link>
    18922014          , then we may also parse these results.</para>
    18932015          <programlisting>
    … …  
    21892311    step.
    21902312Furthermore, the forces are corrected such that the force add up to zero.    </para>
    2191           <programlisting>
    2192           ... --molecular-dynamics \
    2193           --steps 100 \
    2194           --keep-bondgraph 0 \
    2195           --order 3 \
    2196           --distance 3. \
    2197           --deltat 0.5 \
    2198           --keep-fixed-CenterOfMass 1 \
    2199           --fragment-executable mpqc \
     2313          <programlisting>... --molecular-dynamics \
     2314    --steps 100 \
     2315    --keep-bondgraph 0 \
     2316    --order 3 \
     2317    --distance 3. \
     2318    --deltat 0.5 \
     2319    --keep-fixed-CenterOfMass 1 \
     2320    --fragment-executable mpqc \
    22002321          </programlisting>
    22012322          <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>
    … …  
    22122333    step here serves as the initial step width for annealing.
    22132334    </para>
    2214           <programlisting>
    2215           ... --optimize-structure \
    2216           --keep-bondgraph 1 \
    2217           --output-every-step 1 \
    2218           --steps 100 \
    2219           --order 3 \
    2220           --distance 3. \
    2221           --deltat 0.5 \
    2222           --keep-fixed-CenterOfMass 1 \
    2223           --fragment-executable mpqc \
     2335    <programlisting>... --optimize-structure \
     2336    --keep-bondgraph 1 \
     2337    --output-every-step 1 \
     2338    --steps 100 \
     2339    --order 3 \
     2340    --distance 3. \
     2341    --deltat 0.5 \
     2342    --keep-fixed-CenterOfMass 1 \
     2343    --fragment-executable mpqc
    22242344          </programlisting>
    22252345          <para>Note that <emphasis role="bold">output-every-step</emphasis> will allow you to watch the
    … …  
    22532373          <para>For each present time step the temperature (i.e. the average velocity
    22542374    per atom multiplied with its mass) will be stored to a file.</para>
    2255           <programlisting>          ... --save-temperature temperature.dat</programlisting>
     2375          <programlisting> ... --save-temperature temperature.dat</programlisting>
    22562376          <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>
    22572377        </section>
    … …  
    22622382        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
    22632383        surface of connected triangles is created.</para>
    2264         <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>
     2384        <note>Tesselations are used internally by the graphical interface in
     2385        order to show molecules by their surface. This is in general faster
     2386        than displaying them as a ball-stick model consisting of spheres and
     2387        cylinders.</note>
    22652388        <section xml:id="dynamics.tesselation.nonconvex-envelope">
    22662389          <title xml:id="dynamics.tesselation.nonconvex-envelope.title"> Non-convex envelope</title>
    22672390          <para>This will create a non-convex envelope for a molecule and store
    22682391          it to a file for viewing with external programs.</para>
    2269           <programlisting>
    2270           ... --nonconvex-envelope 6. \
    2271           --nonconvex-file nonconvex.dat
     2392          <programlisting>... --nonconvex-envelope 6. \
     2393    --nonconvex-file nonconvex.dat
    22722394          </programlisting>
    22732395          <para>This tesselation file can be conveniently viewed with
    … …  
    22842406          for measuring the space a molecule takes up, e.g. when filling a
    22852407          domain and taking care of correct densities.</para>
    2286           <programlisting>
    2287           ... --convex-envelope 6. \
    2288           --convex-file convex.dat
     2408          <programlisting>... --convex-envelope 6. \
     2409    --convex-file convex.dat
    22892410          </programlisting>
    22902411          <para>This tesselation file can be likewise viewed with
    … …  
    23192440   statements. Hence, no hydrogen atom is added but the <emphasis role="bold">add-atom</emphasis> action is
    23202441   stored in the history and will make it to a stored session.</para>
    2321           <programlisting>   ... --dry-run \
    2322    --add-atom 1 --domain-position &quot;5,5,5&quot;
    2323    --no-dry-run</programlisting>
     2442          <programlisting>... --dry-run \
     2443    --add-atom 1 --domain-position &quot;5,5,5&quot;
     2444    --no-dry-run</programlisting>
    23242445          <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>
    23252446        </section>
    … …  
    23312452          unix environment):</para>
    23322453          <programlisting>... --element-db ./</programlisting>
    2333         </section>
    2334         <section xml:id="various.fastparsing">
    2335           <title xml:id="various.fastparsing.title">Fast parsing</title>
    2336           <para>Parsing all time steps from a given input file can take a
    2337           while, especially for larger systems. If fast parsing is activated,
    2338           only the first time step is loaded, all other are ignored.</para>
    2339           <programlisting>... --fastparsing 1</programlisting>
    23402454        </section>
    23412455        <section xml:id="various.version">
    … …  
    23712485          <title xml:id="sessions.store-session.title">Storing a session </title>
    23722486          <para>Storing sessions is simple,</para>
    2373           <programlisting>
    2374     ... --store-session &quot;session.py&quot; \
    2375         --session-type python
     2487          <programlisting>... --store-session &quot;session.py&quot; \
     2488    --session-type python
    23762489       </programlisting>
    23772490          <para>Here, the session type is given as python (the other option is
    … …  
    24042517              <productname>TREMOLO </productname>
    24052518            </link> exttypes file with the given name.</para>
    2406           <programlisting>
    2407           ... --save-selected-atoms-as-exttypes \
    2408           --filename test.exttypes </programlisting>
     2519          <programlisting>... --save-selected-atoms-as-exttypes \
     2520    --filename test.exttypes </programlisting>
    24092521        </section>
    24102522        <section xml:id="various-specific.set-parser-parameters">
    … …  
    24192531              <productname>Psi4 </productname>
    24202532            </link> this can be modified as follows.</para>
    2421           <programlisting>
    2422   ... --set-parser-parameters mpqc \
    2423       --parser-parameters &quot;theory=CLHF;basis=6-31*G;&quot;
     2533          <programlisting>... --set-parser-parameters mpqc \
     2534    --parser-parameters &quot;theory=CLHF;basis=6-31*G;&quot;
    24242535          </programlisting>
    24252536          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
    … …  
    24272538          <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>
    24282539          <itemizedlist>
    2429             <listitem>theory</listitem>
    2430             <listitem>basis</listitem>
     2540            <listitem>Hessian - yes/no
     2541            </listitem>
     2542            <listitem>savestate - yes/no
     2543            </listitem>
     2544            <listitem>do_gradient - yes/no
     2545            </listitem>
     2546            <listitem>maxiter - positive integer value
     2547            </listitem>
     2548            <listitem>memory - positive integer value
     2549            </listitem>
     2550            <listitem>stdapprox
     2551              <itemizedlist>
     2552                <listitem>A'</listitem>
     2553              </itemizedlist>
     2554            </listitem>
     2555            <listitem>nfzc - positive integer value
     2556            </listitem>
     2557            <listitem>basis - any basis listed in data folder, e.g.
     2558              <itemizedlist>
     2559                <listitem>3-21G</listitem>
     2560                <listitem>6-31+G*</listitem>
     2561                <listitem>...</listitem>
     2562              </itemizedlist>
     2563            </listitem>
     2564            <listitem>aux_basis - same as under basis
     2565            </listitem>
     2566            <listitem>integration
     2567              <itemizedlist>
     2568                <listitem>IntegralCints</listitem>
     2569              </itemizedlist>
     2570            </listitem>
     2571            <listitem>theory
     2572              <itemizedlist>
     2573                <listitem>CLHF</listitem>
     2574                <listitem>CLKS</listitem>
     2575                <listitem>MBPT2</listitem>
     2576                <listitem>MBPT2_R12</listitem>
     2577              </itemizedlist>
     2578              </listitem>
     2579            <listitem>jobtype
     2580              <itemizedlist>
     2581                <listitem>Default</listitem>
     2582                <listitem>Optimization</listitem>
     2583              </itemizedlist>
     2584              </listitem>
    24312585          </itemizedlist>
    24322586        </section>
    … …  
    24382592          velocities and forces as well as the atoms positions and
    24392593          element.</para>
    2440           <programlisting>
    2441   ... --set-tremolo-atomdata &quot;ATOM id element u=3 v=3 F=3&quot; \
    2442       --reset 1
     2594          <programlisting>... --set-tremolo-atomdata &quot;ATOM id element u=3 v=3 F=3&quot; \
     2595    --reset 1
    24432596   </programlisting>
    24442597          <para>This will not append but reset the old line and fill it with
Note: See TracChangeset for help on using the changeset viewer.