Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/userguide/userguide.xml

    r836972 r101d2d  
    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
    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>
     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>
    111104        </itemizedlist>
    112105      </section>
    … …  
    117110        respect to their functionality, while newer features or actions are
    118111        probably missing. This should be a clear sign to you that these are
    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>
     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>
    124115      </section>
    125116    </section>
    … …  
    322313      </formalpara>
    323314      <note>
    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>
     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>
    327317      </note>
    328318      <section xml:id="preliminaries">
    … …  
    738728        </section>
    739729      </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>
    833730      <section xml:id="randomization">
    834731        <title xml:id="randomization.title">Randomization</title>
    … …  
    875772          <para>where the element is given via its chemical symbol and the
    876773          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>
    880774        </section>
    881775        <section xml:id="atoms.remove-atom">
    … …  
    893787  ... --saturate-atoms
    894788   </programlisting>
    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>
     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>
    900792        </section>
    901793        <section xml:id="atoms.translate-atom">
    … …  
    910802          mind the boundary conditions, i.e. it might shift atoms outside of the
    911803          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>
    915804        </section>
    916805        <section xml:id="atoms.mirror-atoms">
    … …  
    924813                    --periodic 0
    925814   </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>
    929815        </section>
    930816        <section xml:id="atoms.translate-to-origin">
    … …  
    11371023          and adds new bonds in between these copied atoms such that their
    11381024          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>
    11421025        </section>
    11431026        <section xml:id="molecule.change-molname">
    … …  
    11701053   specific offset..</para>
    11711054          <programlisting>... -translate-molecules</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>
     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>
    11781067        </section>
    11791068        <section xml:id="molecule.rotate-around-self">
    … …  
    11961085   </programlisting>
    11971086          <para>This rotates the molecule around an axis from the origin to
    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>
     1087          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
    12011088        </section>
    12021089        <section xml:id="molecule.rotate-to-principal-axis-system">
    … …  
    12111098          </programlisting>
    12121099          <para>This rotates the molecule in such a manner that the ellipsoids
    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>
     1100          largest axis is aligned with the z axis. <remark>Note that &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
    12181101        </section>
    12191102        <section xml:id="molecule.verlet-integration">
    … …  
    14601343      --Alignment-Axis &quot;0,0,1&quot;
    14611344   </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>
    14651345        </section>
    14661346        <section xml:id="filling.suspend-in-molecule">
    … …  
    15701450          <para>This would calculate the correlation of all hydrogen and
    15711451          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>
    15751452        </section>
    15761453        <section xml:id="analysis.surface-correlation">
    … …  
    25082385          <para>Underneath the time line there is another place for
    25092386          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>
    25192387          <para>The first is on molecules, listing all present molecules of
    25202388          the molecular system in a tree view. If you click on a specific
    … …  
    25262394          system. Clicking on a present element will select all atoms of this
    25272395          specific element. A subsequent click unselects again.</para>
    2528           <para>Subsequently follow two tabs on enumerating the fragments and their
     2396          <para>Subsequently follow tabs on enumerating the fragments and their
    25292397          fragment energies if calculated and the homologies along with
    25302398          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>
    25392399        </section>
    25402400      </section>
    … …  
    26582518      under the command-line interface and look up the function name via
    26592519      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>
    26602538    </section>
    26612539  </chapter>
Note: See TracChangeset for help on using the changeset viewer.