source: doc/molecuilder.xml.in@ 710dde

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.4/EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- address will be used within (white-space sensitive) <address> markup -->
<!-- do not use for now
<!ENTITY ins-street-address "University of Bonn, Institute for Numerical Simulation
        <street>Wegelerstrasse 6</street>
        <postcode>53115</postcode> <city>Bonn</city>, <country>Germany</country>
        <phone>+49-228-73-3427</phone>, <fax>+49-228-73-7527</fax>
">
use empty replacement instead: -->
<!ENTITY ins-street-address "">
<!ENTITY ins-nolink "<orgdiv>Institute for Numerical Simulation</orgdiv>">
<!ENTITY ins "<ulink url='http://www.ins.uni-bonn.de/'>Institute for Numerical Simulation</ulink>">
<!ENTITY ins-maildom "ins.uni-bonn.de">
<!ENTITY unibn-nolink "<orgname>University of Bonn</orgname>">
<!ENTITY unibn "<ulink url='http://www.uni-bonn.de/'>University of Bonn</ulink>">
<!ENTITY tremolo "<acronym>TREMOLO</acronym>">
<!-- pull in iso-num.ent -->
<!-- <!ENTITY PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" "ent/iso-num.ent"> -->
]>
<article lang="en">

  <articleinfo>
    <title>MoleCuilder User's Guide</title>
    <authorgroup>
      <author>
        <firstname>Frederik</firstname>
        <surname>Heber</surname>
        <affiliation>
          <!-- address is white space sensitive! -->
          <address><email>heber@&ins-maildom;</email>
&ins-street-address;</address>
        </affiliation>
      </author>
    </authorgroup>

    <date>13.08.2009</date>
    <releaseinfo role="meta">
      $Id$
    </releaseinfo>
    <copyright>
      <year>2009</year><holder>University of Bonn</holder>
    </copyright>

    <revhistory>
      <revision>
        <revnumber>0.1</revnumber>
        <date>08/13/09</date>
        <authorinitials>heber</authorinitials>
        <revremark>Initial version of documentation</revremark>
      </revision>
      <!-- could also do $ Revision $ here -->
      <revision>
        <revnumber>$Revision$</revnumber>
        <date>$Date$</date>
        <authorinitials>$Author$</authorinitials>
        <revremark>Use CVS keywords as much as possible
          (do <emphasis>not</emphasis> use $Log&#36;, however);
          use many DocBook features.
        </revremark>
      </revision>
      <!-- enter new revision summary above this line -->
    </revhistory>

    <abstract>
      <para>
        The MoleCuilder's man page describes briefly its command synopsis
      </para>
    </abstract>

    <keywordset>
      <keyword>MoleCuilder</keyword>
      <keyword>molecule</keyword>
      <keyword>builder</keyword>
      <keyword>molecular dynamics</keyword>
    </keywordset>

  </articleinfo>

  <!-- This is an example of a more or less usual unix manpage.
  It could appear by itself in a DOCTYPE refentry.  -->

  <refentry id="molecuilder">
    <refmeta>
      <refentrytitle>MoleCuilder</refentrytitle>
      <manvolnum>1</manvolnum>
    </refmeta>
    <refnamediv>
      <refname>molecuilder</refname>
      <refpurpose>Manipulate molecular geometries and construct molecular systems.</refpurpose>
    </refnamediv>
  
    <refsynopsisdiv>
      <cmdsynopsis>
        <command>molecuilder</command>
        <arg choice ="req">
         <replaceable>sample.conf</replaceable>
        </arg>
        <arg choice="req">
         <option>-e @prefix@bin</option>
        </arg>
        <arg choice="opt">
          <option>-aAbBcdDfFhHlmMnoOpPrRsStTuvV</option>
          <option>...</option>
        </arg>
      </cmdsynopsis>
    </refsynopsisdiv>
       
    <refsection>
      <title>Description</title>
      <para><command>MoleCuilder</command> is a very powerful package to manipulate nuclear geometries. It works on three different levels:</para>
      <itemizedlist>
        <listitem>
          <para>Manipulating of single atoms: adding, removing, translating, changing the element, ...</para>    
        </listitem>
        <listitem>
          <para>Manipulating of bonds: recognizing, measuring length/angle, scaling, fragmenting, ...</para>    
        </listitem>
        <listitem>
          <para>Manipulating of single molecules: parsing atoms into a molecule, translating a molecule, calculating surface and volume of a molecule...</para>    
        </listitem>
        <listitem>
          <para>Manipulating of the domain: changing the domain, specifying a periodic bounding box, centering all atoms, shifting all atoms, ...</para>    
        </listitem>
      </itemizedlist>
      <para>As it is written for the command-line, it is best suited to use in scripts in order to mass-create many structures at the same time that only differ in a few key parameters.</para>
    </refsection>  
  
    <refsection>
      <title>Options</title>
      <para>Note that multiple options may be given at the same time, i.e. we may concatenate (-a) an atom, then translate all (-t) by some vector, the center at origin (-O) and so on. </para>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-a</option>
          <option> Z x y z</option>  - add atom
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-a</option>
          <option> <replaceable>DBOND</replaceable></option> - create adjacency graph from DBOND file.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-b</option>
          <option>xx xy xz yy yz zz</option> - center atoms in domain.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-B</option>
          <option>xx xy xz yy yz zz</option> - bound atoms by domain.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-c</option>
          <option>x y z</option> - center atoms in rectangular domain with distance to boundary.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-d</option>
          <option>x y z</option> - duplicate domain along each axis by given factor.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-D</option>
          <option>distance</option> - Depth-First-Search Analysis of the system. 
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-fF</option>
          <option>distance order</option> - fragment the molecule in BOSSANOVA manner
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-[h|H|?]</option> - print help.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-L</option>
          <option>step0 step1 prefix</option> - linear interpolation between step0 and step1 in config file.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-m</option>
          <option>[0|1]</option> - calculate(0), align in(1) Principal Axis System. 
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-M</option>
          <option>basis</option> - set basis to store in mpqc config files.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-n</option> - don't parse trajectories.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-o</option>
          <option>file</option> - calculate and store convex envelope of molecule in file.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-O</option> center atoms in origin.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-p</option>
          <option>file</option> - parse XYZ file into molecule.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-P</option>
          <option>file</option> - Parse given forces file, time integrate and append as subsequent MD step.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-s</option>
          <option>x y z</option> - scale all atom coordinates by the factor per axis.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-S</option>
          <option>file</option> - Store temperatyre from config file in file.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-t</option>
          <option>x y z</option> - translate all atoms by vector.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-T</option>
          <option>x y z</option> - translate all atoms by vector in periodic domain.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-u</option>
          <option>rho</option>- suspend molecular system in watery solution such that average density is rho.
        </arg>
      </cmdsynopsis>
      <cmdsynopsis>
        <arg choice="opt">
          <option>-[v|V]</option> - print version information.
        </arg>
      </cmdsynopsis>
    </refsection>
    
    <refsection>
      <title>Files</title>
      <para></para>
      <itemizedlist>
        <listitem>
          <para><replaceable>sample.conf</replaceable> is the config file, which is needed as temporary storage. Must not begin with '-'.</para>    
        </listitem>
        <listitem>
          <para><command>-e database_path</command> is the path to the element's database. The files are provided with <command>molecuilder</command>.</para>    
        </listitem>
        <listitem>
          <para><replaceable>molecule.xyz</replaceable> is a typical XYZ file containing the geometry for a molecule.</para>    
        </listitem>
      </itemizedlist>
    </refsection>  
  
    <refsection>
      <title>Examples</title>
      <para>Below a typical examples of how to use molecuilder are given.</para>
      <itemizedlist>
        <listitem>
          <para><computeroutput>molecuilder sample.conf -e @prefix@ -p molecule.xyz -f 4 2.</computeroutput>
           - creates a number of fragmented output files up to bond order 4 with bonds between atoms at most 2 length units apart.</para>   
        </listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem>
          <para><computeroutput>molecuilder sample.conf -e @prefix@ -p molecule.xyz -t -5 0. 0. -a 1 0. 0. 0.</computeroutput>
           - parses the XYZ file <filename>molecule.xyz</filename> into the molecular system, translates the whole by (-5,0,0) and adds a hydrogen atom at the origin.</para>   
        </listitem>
      </itemizedlist>
    </refsection>  
  
    <refsection>
      <title>Exit Status</title>
      <para></para>
      <itemizedlist>
        <listitem>
          <para>0 - success.</para>    
        </listitem>
        <listitem>
          <para>1 - failure.</para>    
        </listitem>
        <listitem>
          <para>2 - adaptive refinement of fragmentation not finished.</para>    
        </listitem>
        <listitem>
          <para>255 - critical failure.</para>    
        </listitem>
      </itemizedlist>
    </refsection>  
  
    <refsection>
      <title>Reporting Bugs</title>
      <para>Please report any bugs you may encounter to <email>heber@&ins-maildom;</email>.</para>
    </refsection>  
  
  </refentry>
  
</article>