..
    : TAMkin is a post-processing toolkit for normal mode analysis, thermochemistry
    : and reaction kinetics.
    : Copyright (C) 2008-2012 Toon Verstraelen <Toon.Verstraelen@UGent.be>, An Ghysels
    : <An.Ghysels@UGent.be> and Matthias Vandichel <Matthias.Vandichel@UGent.be>
    : Center for Molecular Modeling (CMM), Ghent University, Ghent, Belgium; all
    : rights reserved unless otherwise stated.
    :
    : This file is part of TAMkin.
    :
    : TAMkin is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : In addition to the regulations of the GNU General Public License,
    : publications and communications based in parts on this program or on
    : parts of this program are required to cite the following article:
    :
    : "TAMkin: A Versatile Package for Vibrational Analysis and Chemical Kinetics",
    : An Ghysels, Toon Verstraelen, Karen Hemelsoet, Michel Waroquier and Veronique
    : Van Speybroeck, Journal of Chemical Information and Modeling, 2010, 50,
    : 1736-1750W
    : http://dx.doi.org/10.1021/ci100099g
    :
    : TAMkin is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    :
    : --

TAMkin programmer's guide
=========================


**TODO**: introductory text

Git Basics -- Get the latest development version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**TODO**


Have a look at the structure of the package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It may be useful to understand the basic structure of the TAMkin package. Assume
TAMkin is installed in a directory ``~/code/``, then one can have a look at the
TAMkin files in the following way::

    $ cd ~/code/tamkin
    $ ls
    cleancode.sh   COPYING   HEADER.py   lib       test
    cleanfiles.sh  examples  install.sh  setup.py  uninstall.sh

* The ``install.sh`` script uses the ``setup.py`` script to install TAMkin
  (see the https://molmod.ugent.be/code/wiki/TAMkin/InstallationGuide).
  Similarly, the ``uninstall.sh`` script can be used to uninstall TAMkin.
* The ``cleancode.sh``, ``cleanfiles.sh`` and ``HEADER.py`` files are only
  relevant for code developers, but not for the general user.
* The file ``COPYING`` contains the license under which TAMKin is distributed.
* The directory ``test/`` contains the testing routines. This is mainly intended
  for developers, but a regular user can also use it to test the validity of its
  installation. ::

    $ ls test/
    input  nma.py       partf.py    rotor.py  timer.py
    io.py  nmatools.py  pftools.py  test.py   tunneling.py

* The directory ``examples/`` contains worked out examples (see further).
* The directory ``lib/`` contains the TAMkin source code itself (the files with
  lines of code, for developers). ::

    $ ls lib/
    data.py  __init__.py  nma.py       partf.py    rotor.py  tunneling.py
    geom.py  io           nmatools.py  pftools.py  timer.py


Coding guidelines
~~~~~~~~~~~~~~~~~

**TODO**


Doc-string guidelines
~~~~~~~~~~~~~~~~~~~~~

**TODO**


Test and example guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Self-explaining filenames and job titles**
  Think of filenames for scripts and data files that are self-explaining. Also
  include English titles that make sense. These titles will appear in the output
  generated by TAMkin to label the different partition functions.

**Test data size**
  The smaller the total size of the source tree, the better. Before you ``git
  commit`` an example into the git repository, try to keep the data files
  from computational chemistry packages as small as possible. Try to do at least
  the following

  1. Keep the molecular systems in the examples small, i.e. at most 20 atoms.

  2. Strip all the trailing white spaces from every line in the output files.

  3. Strip all sections from the output files that are not used by TAMkin.

Gaussian fchk files
-------------------

The script ``examples/fchkstripper.py`` takes care of steps 2 and 3. It is used
as follows::

    ./fchkstripper.py file1.fchk file2.fchk

The files will be stripped in-place. No backup copy is made. Then fill in the
title of the ``.fchk`` files, i.e. the first line.


Documentation guidelines
~~~~~~~~~~~~~~~~~~~~~~~~

**TODO**