source: doc/userguide.xml@ 6550cf

<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>MoleCuilder - a Molecule Builder</title>

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

      <affiliation>
        <orgname>heber@ins.uni-bonn.de</orgname>
      </affiliation>
    </author>

    <pubdate>08/11/09</pubdate>
  </info>

  <chapter>
    <title>Introduction</title>

    <section>
      <title>What is MoleCuilder?</title>

      <para><command>MoleCuilder</command> allows to construct atomic and
      molecular geometries by a simple point&amp;click approach, combined with
      a powerful library of known structures. It is intended to be a
      CAD-pendant on the nanoscale. Specific emphasis is placed on a
      simple-to-use interface, allowing for the quick-and-dirty building of
      molecular systems.</para>

      <para>Geometries should henceforth be simulated with molecular dynamics
      packages, that are either ab-initio or used specific empirical
      potentials to simulate the acting quantum-mechanical forces.</para>

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

        <para>The following packages are required to build the executables
        from its source code.</para>

        <para><simplelist>
            <member>C/C++ Compiler (such as GCC)</member>
          </simplelist></para>

        <para><simplelist>
            <member>Gnu Scientific Library
            (<uri>http://www.gnu.org/software/gsl/</uri>)</member>
          </simplelist></para>

        <para><simplelist>
            <member>Qt4 (<uri>http://qt.nokia.com/</uri>)</member>
          </simplelist>The code has been tested develeoped on Linux/GNU. It
        was also tested with Win/Cygwin.</para>

        <para>Note that there are two executables:
        <command>molecuilder</command> and <command>molecuildergui</command>.
        The former is the command-line interfaces which, if no commands are
        given, launches a interactive menu in a terminal session. The latter
        is the graphical user interface with the same functionality as the
        command-line interface but in a different approach, explained in more
        detail in the chapter on the <olink>GUI</olink>.</para>

        <para><command>MoleCuilder</command> makes uses of GNU autotools to
        allow for compilation on different platforms. Please be refered to the
        INSTALL file that is included in the archive and the web
        (<uri>http://www.gnu.org/software/autoconf</uri>).</para>
      </section>

      <section>
        <title>License</title>

        <para>As long as no other license statement is given, MoleCuilder is
        free for user under the GNU Public License (GPL) Version 2 (see
        <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>Features</title>

    <para>Basically, <command>MoleCuilder</command> parses geometries from
    files, manipulates them and stores them again in files. The manipulation
    can be done either via a command-line interface or via the graphical user
    interface.</para>

    <section>
      <title>Concepts</title>

      <para>In general, we divide the molecular systems into three different
      components or scales.</para>

      <orderedlist>
        <listitem>
          <para>Atoms</para>

          <para>Atoms are the undividable objects of the molecular systems.
          They have an element <quote>Z</quote> and three coordinates
          <quote>(x,y,z)</quote>.</para>
        </listitem>

        <listitem>
          <para>Molecules</para>

          <para>Molecules are conglomeration of atoms, bound or unbound. They
          contain a number of atoms and a specific center in the domain such
          that its atoms are placed relative to this center.</para>
        </listitem>

        <listitem>
          <para>Domain</para>

          <para>The domain refers to the simulation domain. It is either
          infinite or finite if periodic boundary conditions are to be
          applied. In the latter case, atoms are always shifted back into the
          domain periodically. A domain contains a number of molecules.</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Command-line interface</title>

      <para>The command-line interface reads options or command from the
      command line and executes them sequentially. This may be for example:
      Open an empty file, add 2 hydrogen at ... and add 1 oxygen at ...,
      choose a simulation box, fill the box with this given "filler" molecule,
      save the file. This enables the use of MoleCuilder in simple
      script-files to create a whole range of geometries that only differ in a
      few parameters automatically.</para>

      <para>Traditionally, <command>MoleCuilder</command> operates on a single
      configuration file which stores additional information to the pure
      geometry such as parameters for the ab-initio computation. An example
      for the above procedure is given below:</para>

      <screen>./molecuilder sample.conf -e &lt;path_to_db&gt; -a H 0. 0. 0. -a H 0. 0.176 0. -a O 1. 0.176 0. ...
</screen>

      <para>The first argument is the executable itself, the second the
      arbitrarilty named file <computeroutput>sample.conf</computeroutput>,
      which may be empty, the third is the command -e immediately followed by
      the path to the databases, then follow step by step each of the above
      commands. A command is always introduced via a hyphen and a single
      letter, e.g. -a for adding an atom to the system. It is followed by a
      fixed number of options.</para>

      <para><emphasis>Note that these first three arguments are always
      mandatory.</emphasis> The databases are supplied with the archive and
      usually installed in the same directory as the executables. The output
      file on finish will be <computeroutput>sample.conf</computeroutput> and
      various other formats desired.</para>

      <para>Below we have divided the various features into distinct the
      scales upon which the manipulation takes places - single atoms, multiple
      atoms organised as molecules, and all atoms organised by their
      containing domain - and explain in more detail.</para>

      <section>
        <title>Manipulate atoms</title>

        <para>Here, we explain in detail how to add, remove atoms, change its
        element type, scale the bond in between or measure the bond length or
        angle.</para>
      </section>

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

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

      <section>
        <title>Merge molecules</title>

        <para>As we may create, add and remove molecules, there can be more
        than one, joining of molecules into a single one can be done in a
        number of ways which is explained in this section in greater
        detail.</para>

        <section>
          <title>Editing molecules</title>

          <para>In this category we explain how to create new empty molecules,
          how to load them from file, how to change their names and filenames,
          how to set them active and inactive, how to parse more atoms into a
          given molecules and how to remove a molecule.</para>
        </section>

        <section>
          <title>Merging molecules</title>

          <para>As we may create, add and remove molecules, there can be more
          than one, joining of molecules into a single one can be done in a
          number of ways which is explained in this section in greater
          detail.</para>
        </section>
      </section>
    </section>

    <section>
      <title linkend="GUI">Graphical user interface</title>

      <para>The main point of the GUI is that it renders the atoms and
      molecules visually. These are either represented by the common
      stick-and-ball-model or as tesselated molecular surfaces. Single or
      multiple atoms and molecules can easily be accessed, activated and
      manipulated via tables. Changes made in the tables cause immediate
      update of the visual representation.</para>

      <para>This is mostly helpful to design more advanced structures that are
      conceptually difficult to imagine without visual aid.</para>

      <section>
        <title>The interface sections</title>

        <para></para>
      </section>
    </section>
  </chapter>
</book>