Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/userguide/userguide.xml

    r101d2d r836972  
    1 <?xml version='1.0' encoding='UTF-8'?>
     1<?xml version='1.0' encoding='UTF-8'?>
    22<!-- 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" [
    33<!ENTITY molecuilder_logo SYSTEM "pictures/molecuilder_logo.png" NDATA PNG>
    … …  
    100100            spheres, cubes, or cylinders.</para>
    101101          </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>
     102          <listitem>World refers to the whole of the molecular system, i.e. all
     103          atoms with coordinates and element type (over all time steps), all
     104          bonds between pairs of atoms, the size of the simulation domain.
     105          This is also referred to as the state.</listitem>
     106          <listitem>Time step is the current discrete position in time. Molecular
     107          dynamics simulations are executed in discrete (but very small) time
     108          steps.  Each atom has a distinct position per time step. The discrete
     109          positions over the discrete time steps samples its trajectory during a
     110          simulation.</listitem>
    104111        </itemizedlist>
    105112      </section>
    … …  
    110117        respect to their functionality, while newer features or actions are
    111118        probably missing. This should be a clear sign to you that these are
    112         probably not safe to use yet. If you nonetheless require them, you         should acquire some familiarity with the code itself. This suggests
    113         changing to the developer documentation which is maintained along with
    114         the source code with <productname>doxygen</productname>.</para>
     119        probably not safe to use yet. If you nonetheless require them, you
     120        should acquire some familiarity with the code itself. This suggests
     121        changing to the developer documentation which is maintained along
     122        with the source code with <productname>doxygen</productname>.
     123        </para>
    115124      </section>
    116125    </section>
    … …  
    313322      </formalpara>
    314323      <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>
     324        <para>Note further that when placing a slew of commands in a script file
     325         it is generally recommended to use the above formatting: One command
     326         or option per line and each receives an extra tab for indentation.</para>
    317327      </note>
    318328      <section xml:id="preliminaries">
    … …  
    728738        </section>
    729739      </section>
     740      <section xml:id="geometry">
     741        <title xml:id="geometry.title">Geometry Objects</title>
     742        <para>Although we use the term geometry objects in the title, we
     743        actually mean vectors, i.e. a position or direction in the
     744        three-dimensional space. But maybe we have need for the more
     745        general term in the future.</para>
     746        <para>Vectors are required as input to many of the Actions further
     747        below: translating atoms, rotating atoms around a specific axis,
     748        aligning a molecule with a vector, ...</para>
     749        <para>Therefore, vectors can be stored and referenced using a given
     750        name. This allows for a very powerful and handy manipulation of the
     751       molecular system afterwards. And to give a concrete example, let's have
     752       a look at translating a set of selected atoms, see subsection on
     753       <link linkend='atoms.translate-atom'>Translating atoms</link>. </para>
     754       <programlisting>
     755... --translate-atoms &quot;unitVectorX&quot;
     756       </programlisting>
     757       <para>This would use the automatically created reference
     758       &quot;unitVectorX&quot;, i.e. the vector with components (1,0,0) as
     759       the translation vector for the given set of atoms. In other words, all
     760       selected atoms get shifted by 1 unit (e.g. Angstr&ouml;m) in +X
     761       direction.</para>
     762       <para>We have the following automatically created geometry objects
     763       whose names are self-explanatory:</para>
     764       <itemizedlist>
     765        <listitem>zeroVector</listitem>
     766        <listitem>unitVectorX</listitem>
     767        <listitem>unitVectorY</listitem>
     768        <listitem>unitVectorZ</listitem>
     769       </itemizedlist>
     770       <para>However, more vectors can be simply constructed from atomic
     771       positions, such as the position of an atom directly, the distance between
     772       two atoms (in case they are bonded, then this would be the bond vector)
     773       or from three atoms, defining a plane and giving its normal vector.
     774       </para>
     775       <remark>We have refrained from giving automated names to vectors and even
     776       keeping them up-to-date automatically, i.e. the distance between two atoms
     777       O1 and O2 could be named &quot;distance_O1_O2&quot; or similar. However, we want
     778       the user to have full control and maybe come up with more suitable names
     779       such as &quot;rotation_axis&quot; in this case.</remark>
     780       <warning>Note that names have to be unique and the Action will fail if
     781       the name is already used.</warning>
     782        <section xml:id="geometry.distance-to.vector">
     783          <title xml:id="geometry.distance-to-vector.title">Atomic distance to stored vector</title>
     784          <para>The distance between two selected atoms is stored as a vector as follows,</para>
     785          <programlisting>
     786  ... --distance-to-vector &quot;distance_vec&quot; \
     787          </programlisting>
     788          <para>where the distance vector can be referenced by &quot;distance_vec&quot;
     789          from then on in other Actions requiring a vector as input.</para>
     790        </section>
     791        <section xml:id="geometry.input-to.vector">
     792          <title xml:id="geometry.input-to-vector.title">Coordinates to stored vector</title>
     793          <para>We may also create a geometry vector simply by supplying the
     794          three coordinates of a vector.</para>
     795          <programlisting>
     796  ... --input-to-vector &quot;vector&quot; \
     797      --position &quot;1,2,3&quot;
     798          </programlisting>
     799          <para>where the vector with components (1,2,3) can be referenced
     800          by &quot;vector&quot; .</para>
     801        </section>
     802        <section xml:id="geometry.plane-to.vector">
     803          <title xml:id="geometry.plane-to-vector.title">Normal of plane to stored vector</title>
     804          <para>Three positions in space (if they are not linear dependent)
     805          define a plane in three-dimensional space.</para>
     806          <para>Therefore, when exactly three atoms are selected, this Action
     807          will construct the resulting plane and store its normal vector as a
     808          geometry object for later reference.</para>
     809          <programlisting>
     810  ... --plane-to-vector &quot;planenormal&quot; \
     811          </programlisting>
     812          <para>where the plane's normal vector can be referenced by
     813          &quot;planenormal&quot;.</para>
     814        </section>
     815        <section xml:id="geometry.position-to.vector">
     816          <title xml:id="geometry.position-to-vector.title">Atomic position to stored vector</title>
     817          <para>Storing the position of a singly selected atom as a vector is simply done as follows,</para>
     818          <programlisting>
     819  ... --position-to-vector &quot;vector_O1&quot; \
     820          </programlisting>
     821          <para>where the vector can be referenced by &quot;vector_O1&quot;
     822          from then on.</para>
     823        </section>
     824        <section xml:id="geometry.remove-geometry">
     825          <title xml:id="geometry.remove-geometry.title">Remove A stored vector</title>
     826          <para>Finally, a stored vector can also be removed.</para>
     827          <programlisting>
     828  ... --remove-geometry &quot;vector_O1&quot; \
     829          </programlisting>
     830          <para>this removes  the stored &quot;vector_O1&quot;.</para>
     831        </section>
     832      </section>
    730833      <section xml:id="randomization">
    731834        <title xml:id="randomization.title">Randomization</title>
    … …  
    772875          <para>where the element is given via its chemical symbol and the
    773876          vector gives the position within the domain</para>
     877         <para>Note that instead of giving an explicit vector you may also use
     878        a vector stored as a geometry object, see section
     879        <link linkend='geometry'>Geometry</link>.</para>
    774880        </section>
    775881        <section xml:id="atoms.remove-atom">
    … …  
    787893  ... --saturate-atoms
    788894   </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
    790           distance to this atom and approximately with same distance to their
    791    nearest neighbors. Already present bonds (i.e. the position of neighboring atoms) is taken into account.</para>
     895          <para>A number of hydrogen atoms is added around each selected atom
     896          corresponding to the valence of the chemical element. The hydrogen
     897          atoms are placed in the same distance to this atom and approximately
     898          with same distance to their nearest neighbors. Already present bonds
     899          (i.e. the position of neighboring atoms) is taken into account.</para>
    792900        </section>
    793901        <section xml:id="atoms.translate-atom">
    … …  
    802910          mind the boundary conditions, i.e. it might shift atoms outside of the
    803911          domain.</para>
     912         <para>Again, note that instead of giving an explicit vector you may
     913         also use a vector stored as a geometry object, see section
     914        <link linkend='geometry'>Geometry</link>.</para>
    804915        </section>
    805916        <section xml:id="atoms.mirror-atoms">
    … …  
    813924                    --periodic 0
    814925   </programlisting>
     926         <para>And of course instead of giving an explicit vector you may also
     927         use a vector stored as a geometry object, see section
     928        <link linkend='geometry'>Geometry</link>.</para>
    815929        </section>
    816930        <section xml:id="atoms.translate-to-origin">
    … …  
    10231137          and adds new bonds in between these copied atoms such that their
    10241138          bond subgraphs are identical.</para>
     1139         <para>Here, instead of giving an explicit vector you may also use
     1140        a vector stored as a geometry object, see section
     1141        <link linkend='geometry'>Geometry</link>.</para>
    10251142        </section>
    10261143        <section xml:id="molecule.change-molname">
    … …  
    10531170   specific offset..</para>
    10541171          <programlisting>... -translate-molecules</programlisting>
    1055           <para>As before, this is actually just an operation on all of the molecule&apos;s atoms, namely translating them.</para>
    1056         </section>
    1057         <section xml:id="molecule.rotate-around-bond">
    1058           <title xml:id="molecule.rotate-around-bond.title">Rotate around bond </title>
    1059           <para>This rotates parts of a molecule around a given bond, i.e. the
    1060           bond vector becomes the rotation axis but only atoms on the side of
    1061           second atom get rotated. This naturally does not work for bonds in a
    1062           cycle.</para>
    1063           <programlisting>
    1064   ... --rotate-around-bond &quot;90&quot; \
    1065       --bond-side 0\
    1066    </programlisting>
     1172          <para>As before, this is actually just an operation on all of the
     1173          molecule&apos;s atoms, namely translating them.</para>
     1174         <para>Same as with <link linkend='atoms.translate-atom'>translate-atoms</link>
     1175         instead of giving an explicit vector you may also use a vector stored
     1176         as a geometry object, see section
     1177        <link linkend='geometry'>Geometry</link>.</para>
    10671178        </section>
    10681179        <section xml:id="molecule.rotate-around-self">
    … …  
    10851196   </programlisting>
    10861197          <para>This rotates the molecule around an axis from the origin to
    1087           the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
     1198          the position (0,0,1), i.e. around the z axis, by 90 degrees, where
     1199          for the position you may also use a stored vector, see section
     1200        <link linkend='geometry'>Geometry</link>.</para>
    10881201        </section>
    10891202        <section xml:id="molecule.rotate-to-principal-axis-system">
    … …  
    10981211          </programlisting>
    10991212          <para>This rotates the molecule in such a manner that the ellipsoids
    1100           largest axis is aligned with the z axis. <remark>Note that &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
     1213          largest axis is aligned with the z axis. <remark>Note that
     1214          &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
     1215         <para>Again instead of giving the coordinates explicitly you may also
     1216         use a vector stored as a geometry object, see section
     1217        <link linkend='geometry'>Geometry</link>.</para>
    11011218        </section>
    11021219        <section xml:id="molecule.verlet-integration">
    … …  
    13431460      --Alignment-Axis &quot;0,0,1&quot;
    13441461   </programlisting>
     1462         <para>Note that instead of giving an explicit axis you may also use
     1463        a vector stored as a geometry object, see section
     1464        <link linkend='geometry'>Geometry</link>.</para>
    13451465        </section>
    13461466        <section xml:id="filling.suspend-in-molecule">
    … …  
    14501570          <para>This would calculate the correlation of all hydrogen and
    14511571          oxygen atoms with respect to the origin.</para>
     1572         <para>Naturally, instead of giving explicit coordinates you may also
     1573         use a vector stored as a geometry object for position, see section
     1574        <link linkend='geometry'>Geometry</link>.</para>
    14521575        </section>
    14531576        <section xml:id="analysis.surface-correlation">
    … …  
    23852508          <para>Underneath the time line there is another place for
    23862509          tabs.</para>
     2510          <itemizedlist>
     2511            <listitem>Molecules</listitem>
     2512            <listitem>All Elements</listitem>
     2513            <listitem>All Fragments</listitem>
     2514            <listitem>All Homologies</listitem>
     2515            <listitem>All Geometries</listitem>
     2516            <listitem>Logs</listitem>
     2517            <listitem>Errors</listitem>
     2518          </itemizedlist>
    23872519          <para>The first is on molecules, listing all present molecules of
    23882520          the molecular system in a tree view. If you click on a specific
    … …  
    23942526          system. Clicking on a present element will select all atoms of this
    23952527          specific element. A subsequent click unselects again.</para>
    2396           <para>Subsequently follow tabs on enumerating the fragments and their
     2528          <para>Subsequently follow two tabs on enumerating the fragments and their
    23972529          fragment energies if calculated and the homologies along with
    23982530          graphical depiction (via QWT), again if present.</para>
     2531          <para>After that, we have a tab listing all geometry objects. These
     2532          are vectors you may store via one of the Actions. If you hover over
     2533          a vector, its length is shown. If you have selected one vector and
     2534          hover over another one, then the angle between the two is shown.
     2535          </para>
     2536          <para>Finally, there are two tabs showing log messages of actions
     2537          in the first tab and general information on what is currently done. Errors and
     2538          warnings are listed in the second tab.</para>
    23992539        </section>
    24002540      </section>
    … …  
    25182658      under the command-line interface and look up the function name via
    25192659      help.</para>
    2520       <para>You can freely mix calls to the pymolecuilder module and other python commands.</para>
    2521       <note>However, be aware that all Actions are executed in another thread,
    2522       i.e. run in parallel. That means that a pymolecuilder command is not
    2523       necessarily finished when python steps on to the next line!</note>
    2524       <para>In order to make python wait for the Actions to finish before
    2525       stepping, there is the special wait() command.</para>
    2526       <programlisting>
    2527          mol.MoleculeLoad("...")
    2528          mol.wait()
    2529       </programlisting>
    2530       <para>This will continue first after the molecule has been fully loaded.
    2531       </para>
    2532       <warning>These wait()s will have no effect if the python script is loaded
    2533       via the "load-session" command inside a User Interface (command-line,
    2534       GUI, ...) as this would cause the queue to wait indefinitely, namely till
    2535       the load-session itself would have finished.</warning>
    2536       <para>Therefore, more complex python scripts need to be called with
    2537       python and a set PYTHONPATH as described above.</para>
    25382660    </section>
    25392661  </chapter>
Note: See TracChangeset for help on using the changeset viewer.