The Molecular Modelling Toolkit
===============================

This is release 2.2 of MMTK, the Molecular Modelling Toolkit. For more
information about MMTK, look at the manual (in the directories
Doc/HTML and Doc/PDF) and at the examples in the directory Examples.

Please remember that MMTK, like Python, comes with neither a price tag
nor any warranty (see the file COPYRIGHT for details). I use it for my
own work, and I consider it reasonably stable, but your mileage may
vary. If you find any problems with MMTK, please let me know, but
understand that I cannot promise extensive support (I am a scientist,
not a programmer, and much less a software distributor!). I also
gratefully accept additional example applications and other code
donations.


Installation
============

Prerequisites: Python 1.5 or higher, ScientificPython 2.2 or higher.
With Python 1.5.x, the Distutils package must be installed (starting
from Python 1.6, it is part of the Python distribution).

On most Unix systems, installation requires two commands:

      python setup.py build
      python setup.py install

The second command often requires root priviledges, as MMTK will be
installed in the Python library tree. There are many options for
building and installing, type

      python setup.py build --help

or

      python setup.py install --help

for details.

If you want MMTK's MPI support enabled, you must first install
ScientificPython with MPI support and then use mpipython instead of
python for running the compilation/installation procedure via
setup.py. Note that a version of MMTK compiled with MPI support
works only with the mpipython executable, not with an ordinary
python interpreter. However, there is no overhead for using
mpipython on a single processor.


Platform-specific notes
=======================

This section is based on information I got from MMTK users in the
past. There is a risk that it is not up to date. Any platform-specific
information is welcome!
 
Windows:
--------

MMTK can be compiled under Windows using the free MinGW compiler
(available from www.mingw.org). You will need to have MinGW setup
properly to compile python extensions, see
http://www.python.org/doc/2.2.1/inst/non-ms-compilers.html for
details. The option "--compiler=mingw32" must be added when running
setup.py.

Mac OS X 10.0.1:
----------------

You have to set the environment variable C_INCLUDE_PATH to
"/usr/include/gcc/darwin/2.95.2/g++", otherwise some include
files used by the netCDF library won't be found.

Mac OS X:
---------

Under at least some releases, the file /usr/include/pthread.h
must be modified to make MMTK compile (probably this affects all
Python extension modules that use threads). Search for the
following two lines (around 239)

   int       pthread_key_create __P((pthread_key_t *key,
                                    void (*destructor)(void *)));

and modify the second one to read

                                    void (*)(void *)));

(i.e. remove the word "destructor"). This *should* have no adverse
effects on anything.


External programs
=================

MMTK uses external programs for visualization and animation. The names
of these programs must be supplied via environment variables. If no
names are provided, the visualization functions will do nothing.
The environment variables are

- PDBVIEWER  to specify a program that can show the contents of a
  file in the PDB format. The program will be called with the name
  of a PDB file as a command line argument.

- VRMLVIEWER to specify a program that can show a file in the
  VRML format. The program will be called with the name
  of a PDB file as a command line argument.

Animation is implemented only for the programs VMD and XMol.
It is sufficient to specify one of these programs as PDBVIEWER
in order to have access to animation functions.


Documentation
=============

The MMTK manual is included in HTML (Doc/HTML) and PDF (Doc/PDF)
formats. A list of changes along MMTK development versions can
be found in Doc/CHANGELOG.


Useful tools
============

The directory Tools/TrajectoryViewer contains a small program for
viewing trajectories. It allows that quick inspection of energies,
thermodynamic quantities, etc., as well as animation via an external
viewer.


Web site
========

The MMTK home page can be found at

   http://dirac.cnrs-orleans.fr/MMTK/

or at

   http://starship.python.net/crew/hinsen/MMTK/


Mailing list
============

To be informed about updates to MMTK, and to communicate with other
MMTK users, you should subscribe to the MMTK mailing list via
the Web page

    http://starship.python.net/mailman/listinfo/mmtk

This is a low-traffic list; there is little reason not to subscribe.


License
=======

MMTK is licensed under the GNU Lesser Public License. See the file
LICENSE for the text of this license. The DPMTA library (everything in
the directory Src/dpmta-2.7) is not part of MMTK and therefore not
subject to this license.


Acknowledgements
================

The DCD reader was contributed by Lutz Ehrlich, and uses a C library
for reading DCD files (files Src/ReadDCD.c and Src/ReadDCD.h) which
was written by Mark Nelson at the University of Illinois.

The MolecularSurface module was contributed by Peter McCluskey.

The DPMTA library used for electrostatic multipole calculations
(everything in the directory Src/dpmta-2.7) was written by William T.
Rankin at Duke University. Check the file dpmta-2.7/README and the Web
page http://www.ee.duke.edu/Research/SciComp/Docs/Dpmta/dpmta.html for
more information about this library. Note that MMTK does not contain
the whole DPMTA distribution; the documentation, Fortran interface,
and test code were left out to reduce the size of the MMTK
distribution. You can obtain the full DPMTA distribution at the Web
address given above.

Patches to make MMTK work under Windows were provided by Jon Michelsen.

Routines for matrix diagonalization were taken from LAPACK, and
for the erfc function from the CEPHES library.


Konrad Hinsen
Centre de Biophysique Moleculaire (CNRS)
Rue Charles Sadron
45071 Orleans Cedex 2
France

E-Mail: hinsen@cnrs-orleans.fr
