MMTK Overview

This chapter explains the basic structure of MMTK and its view of molecular systems. Every MMTK user should read it at least once.

Using MMTK

MMTK applications are ordinary Python programs, and can be written using any standard text editor. For interactive use it is recommended to use either the special Python mode for the Emacs editor, or the Tk-based graphical user interface PTUI.

MMTK tries to be as user-friendly as possible for interactive use. For example, lengthy calculations can usually be interrupted by typing Control-C. This will result in an error message ("Keyboard Interrupt"), but you can simply go on typing other commands. Of course an incomplete operation might have left the system you are working on in an undefined or incomplete state. Interruption is particularly useful for minimization and molecular dynamics: you can interrupt the calculation at any time, look at the current state or do some analysis, and then continue. Note however that normal mode calculations cannot be interrupted.

Modules

MMTK consists of various modules, most of them written in Python, the remaining ones in C for efficiency. The individual modules are described in the developer's guide. All definitions that are typically used in application programs have been collected in the single module mmtk, meaning that the first line in Python programs that use MMTK will be

from mmtk import *

Since installing the C modules might be difficult or impossible on some systems (for example if no C compiler is available), the subset of MMTK that does not need C modules has been collected in the module mmtklight. If you use this module instead of mmtk, you won't have access to minimization and molecular dynamics, and force field calculations will be very slow. All other operations will work with no difference.

Objects

MMTK is an object-oriented system, which should not surprise anyone, since it is based on Python, which is an object-oriented language. Since objects are everywhere and everything is an object, it is useful to know the most important object types and what can be done with them. All object types in MMTK have meaningful names, so it should be easy to identify them in practice. The following list contains only those objects that a user will see directly. There are many more object types used by MMTK internally.

Chemical objects

These are the objects that represent the parts of a molecular system:

These objects form a simple hierarchy: complexes consist of molecules, molecules consist of groups and atoms, groups consist of smaller groups and atoms. All of these, except for groups, can be used directly to construct a molecular system.

A number of operations can be performed with chemical objects, which can roughly be classified into inquiry (constituent atoms, bonds, center of mass etc.) and modification (translate, rotate).

There are also specialized versions of some of these objects. MMTK defines proteins as special complexes, consisting largely of peptide chains, which are special molecules. They offer a range of special operations (such as picking residues or constructing the positions of missing hydrogen atoms) that do not make sense for molecules in general.

Collections

Collection objects represent arbitrary collections of chemical objects. They are used to be able to refer to collections as single entities. For example, you might want to call all water molecules collectively "solvent". Most of the operations on chemical objects are also available for collections.

Force fields

Force field objects represent a precise description of force fields, i.e. a complete recipe for calculating the potential energy (and its derivatives) for a given molecular system. In other words, they specify not only the functional form of the various interactions, but also all parameters and the prescriptions for applying these parameters to an actual molecular system.

Universes

Universes define complete molecular systems, i.e. they contain chemical objects. In addition, they describe interactions within the system (by a force field), boundary conditions, external fields, etc. Many of the operations that can be used on chemical objects can also be applied to complete universes.

Minimizers

A minimizer object is a special "machine" that can find local minima in the potential energy surface of a universe. You may consider this a function, if you wish, but of course functions are just special objects.

Integrators

An integrator is a special "machine" that can determine a dynamical trajectory for a system on a given potential energy surface.

Trajectories

Minimizers and integrators can produce trajectories, which are special files containing a sequence of configurations and possibly other related information. Of course trajectory objects can also be read for analysis.

Variables

Variable objects (not to be confused with standard Python variables) describe quantities that have a value for each atom in a system, for example positions or energy gradients. Their most common use is for storing various configurations of a system.

Normal modes

Normal mode objects contain normal mode frequencies and displacements for a given universe.

Non-MMTK objects

An MMTK application program will typically also make use of objects provided by Python or Python library modules. The most important ones are

Of course MMTK applications can make use of the standard Python library or any Python modules written by other people.

The chemical database

For defining the chemical objects described above, MMTK uses a database of descriptions. There is a database for atoms, one for groups, etc. When you ask MMTK to make a specific chemical object, for example a water molecule, MMTK looks for the definition of water in the database "molecules". A database entry contains everything there is to know about the object it defines: its constituents and their names, configurations, other names used e.g. for I/O, and all information force fields might need about the objects.

MMTK comes with database entries for some common objects (water, amino acids, etc.). For other objects you will have to write the definitions yourself, as described elsewhere in this manual.

Force fields

MMTK contains everything necessary to use the Amber force field on proteins. It uses the official Amber parameter file, which means that extensions can be applied as described on the AMBER Web site. MMTK was designed to make the addition of force field terms and the implementation of other force fields as easy as possible. Force field terms can be defined in Python (for ease of implementation) or in C or Fortran (for efficiency). This is described in a special chapter.

Units

Since MMTK is not a black-box program, but an extensible library, it is essential for it to use a consistent unit system in which, for example, the inverse of a frequency is a time, and the product of a mass and the square of a velocity is an energy, without additional conversion factors. Black-box programs can (and usually do) use a consistent unit system internally and convert to "conventional" units for input and output.

The unit system of MMTK consists mostly of SI units of appropriate magnitude for molecular systems:

The MMTK module Units contains convenient conversion constants for the units commonly used in computational chemistry. For example, a length of 2 Ångstrøm can be written as "2*Units.Ang", and a frequency can be printed in wavenumbers with "print frequency/Units.invcm". Look at the file Units.py for a list of all available units.

A simple example

The following simple example shows how a typical MMTK application might look like. It constructs a system consisting of a single water molecule and runs a short molecular dynamics trajectory. There are many alternative ways to do this; this particular one was chosen because it makes each step explicit and clear. The individual steps are explained in the remaining chapters of the manual.

# Import all useful MMTK definitions.
from mmtk import *

# Create an infinite universe (i.e. no boundaries).
universe = InfiniteUniverse(AmberForceField())

# Create a water molecule in the universe.
# Water is defined in the database.
universe.molecule = Molecule('water')

# Generate random velocities.
universe.initializeVelocitiesToTemperature(300*Units.K)

# Create an integrator.
integrator = VelocityVerletIntegrator(universe)

# Generate a trajectory
trajectory = Trajectory(universe, "water.nc", "w")

# Run the integrator for 50 steps of 1 fs, printing time and energy
# every fifth step and writing time, energy, temperature, and the positions
# of all atoms to the trajectory.
integrator(delta_t = 1.*Units.fs, steps = 50,
           log=(0, None, 5, stdout, ("time", "energy")),
           trajectory=(0, None, 1, trajectory, ("time", "energy", "temperature",
                                                "configuration")))

# Close the trajectory
trajectory.close()

Table of contents