<?xml version="1.0" encoding='iso-8859-1'?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/usr/share/sgml/docbook/xml-dtd-4.1/docbookx.dtd" [

  <!-- Redefinition of paramdef to permit defaultvalue -->
  <!ELEMENT paramdef (#PCDATA 
		  | replaceable 
		  | parameter | defaultvalue
		  | funcparams)*>
  <!-- Additional element: defaultvalue -->
  <!ELEMENT defaultvalue (#PCDATA)>
  <!-- Additional markup for classes -->
  <!ELEMENT classdescription (classdef, (para | itemizedlist
                                         | methoddescription)*)>
  <!ATTLIST classdescription id ID #IMPLIED
                             role CDATA #IMPLIED
                             xreflabel CDATA #IMPLIED>
  <!ENTITY % local.synop.class "|classdescription">
  <!ELEMENT classdef (#PCDATA | class | classinfo)*>
  <!ELEMENT class (#PCDATA)>
  <!ELEMENT classinfo (#PCDATA)>
  <!ELEMENT methoddescription (methoddef, (void | varargs | paramdef+),
                               (para | itemizedlist)*)>
  <!ELEMENT methoddef (#PCDATA | method)*>
  <!ELEMENT method (#PCDATA)>

  <!ENTITY mmtk-url "http://starship.python.net/mmtk.html">
  <!ENTITY python-url "http://www.python.org">
  <!ENTITY python-tutorial-url "http://www.python.org/doc/tut/tut.html">
  <!ENTITY python-books-url "http://www.python.org/doc/Books.html">
  <!ENTITY amber-url "http://www.amber.ucsf.edu/amber/amber.html">
  <!ENTITY ptui-url "http://starship.skyport.net/crew/zack/ptui/">
  <!ENTITY dpmta-url "http://www.ee.duke.edu/Research/SciComp/Docs/Dpmta/users_guide/dpmta.html">
  <!ENTITY netcdf-url "http://www.unidata.ucar.edu/packages/netcdf/">
  <!ENTITY xmol-url "http://www.msc.edu/msc/docs/xmol/">
  <!ENTITY vmd-url "http://www.ks.uiuc.edu/Research/vmd/">

  <!ENTITY Modules SYSTEM "MMTK.xml">

]>


<book id="mmtk-user">

<bookinfo>
  <date>2002-6-14</date>
  <title>MMTK User's Guide</title>
  <releaseinfo>for MMTK 2.2</releaseinfo>
  <author>
    <firstname>Konrad</firstname><surname>Hinsen</surname>
    <affiliation>
      <orgname>Centre National de la Recherche Scientifique</orgname>
      <orgdiv>Centre de Biophysique Mol&eacute;culaire</orgdiv>
      <address>
        <street>Rue Charles Sadron</street>
        <postcode>45071</postcode><city>Orl&eacute;ans</city>
        <postcode>Cedex 2</postcode>
        <country>France</country>
        <email>hinsen@cnrs-orleans.fr</email>
      </address>
    </affiliation>
  </author>
  <copyright>
    <year>1999</year>
    <holder>Konrad Hinsen</holder>
  </copyright>
</bookinfo>

<toc/>


<preface id="introduction">
<title>Introduction</title>
<para>
The Molecular Modelling Toolkit (MMTK)
presents a new approach to molecular simulations. It is not a
"simulation program" with a certain set of functions that can be used
by writing more or less flexible "input files", but a collection of
library modules written in an easy-to-learn high-level programming
language, <ulink url="&python-url;">Python</ulink>. This approach
offers three important advantages:
<itemizedlist>
<listitem><para>
Application programs can use the full power of a general and well-designed
programming language.
</para></listitem>
<listitem><para>
Application programs can profit from the large set of other libraries
that are available for Python. These may be scientific or
non-scientific; for example, it is very easy to write simulation or
analysis programs with graphical user interfaces (using the module
<literal>Tkinter</literal> in the Python standard library),
or couple scientific calculations with a Web server.
</para></listitem>
<listitem><para>
Any user can provide useful additions in separate modules, whereas adding
features to a monolithic program requires at least the cooperation of
the original author.
</para></listitem>
</itemizedlist>
To further encourage collaborative code development, MMTK uses a very
unrestrictive licensing policy, just like Python. Although MMTK is
copyrighted, anyone is allowed to use it for any purpose, including
commercial ones, as well as to modify and redistribute it (a more
precise description is given in the copyright statement that comes
with the code).
</para>
<para>
This manual describes version 2.2 of MMTK. The 2.x versions contain
some incompatible changes with respect to earlier versions (1.x), most
importantly a package structure that reduces the risk of name
conflicts with other Python packages, and facilitates future
enhancements. There are also many new features and improvements to
existing functions.
</para>
<para>
Using MMTK requires a basic knowledge of object-oriented programming
and Python. Newcomers to this subject should have a look at the 
introductory section in this manual and at the <ulink
url="&python-tutorial-url;">Python tutorial</ulink> (which also comes
with the Python interpreter). There are also numerous
<ulink url="&python-books-url;">books on Python</ulink>
that are useful in getting started. Even without MMTK, Python is a very
useful programming language for scientific use, allowing rapid development
and testing and easy interfacing to code written in low-level languages such
as Fortran or C.
</para>
<para>
This manual consists of several introductory chapters and a <xref
linkend="module_reference"/>. The introductory chapters explain how
common tasks are handled with MMTK, but they do not describe
all of its features, nor do they contain a full documentation of
functions or classes. This information can be found in
the <xref linkend="module_reference"/>, which describes all classes
and functions intended for end-user applications module by module,
using documentation extracted directly from the source code.
References from the introductory sections to the module reference
facilitate finding the relevant documentation.
</para>

</preface>

<chapter id="overview">
<title>Overview</title>

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

<sect1>
<title>Using MMTK</title>
<para>
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 one of the
Tk-based graphical user interfaces for Python, IDLE (comes with the
Python interpreter from version 1.5.2) or
<ulink url="&ptui-url;">PTUI</ulink>.
</para>
<para>
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.
Interruption is particularly useful for energy minimization and
molecular dynamics: you can interrupt the calculation at any time,
look at the current state or do some analysis, and then continue.
</para>
</sect1>

<sect1>
<title>Modules</title>
<para>
MMTK is a package consisting of various modules, most of them written
in Python, and some in C for efficiency. The individual modules are
described in the <xref linkend="module_reference"/>. The basic
definitions that almost every application needs are collected in the
top-level module, MMTK. The first line of most applications is
therefore
<programlisting role="Python">
from MMTK import *
</programlisting>
</para>
<para>
The definitions that are specific to particular applications reside in
submodules within the package MMTK. For example, force fields are
defined in <xref linkend="Module:MMTK.ForceFields"/>, and peptide
chain and protein objects are defined in <xref
linkend="Module:MMTK.Proteins"/>.
</para>
<para>
Python provides two ways to access objects in modules and submodules.
The first one is importing a module and referring to objects in it,
e.g.:
<programlisting role="Python">
import MMTK
import MMTK.ForceFields
universe = MMTK.InfiniteUniverse(MMTK.ForceFields.Amber94ForceField())
</programlisting>
The second method is importing all or some objects <emphasis>from</emphasis>
a module:
<programlisting role="Python">
from MMTK import InfiniteUniverse
from MMTK.ForceFields import Amber94ForceField
universe = InfiniteUniverse(Amber94ForceField())
</programlisting>
These two import styles can also be mixed according to convience.
In order to prevent any confusion, all objects are referred to by
their full names in this manual. The Amber force field object
is thus called <xref linkend="Class:MMTK.ForceFields.Amber94ForceField"/>.
Of course the user is free to use selective imports in order to
be able to use such objects with shorter names.
</para>
</sect1>

<sect1>
<title>Objects</title>
<para>
MMTK is an object-oriented system.  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 is easy to identify them in practice. The
following overview contains only those objects that a user will see
directly. There are many more object types used by MMTK internally,
and also some less common user objects that are not mentioned here.
</para>

<simplesect>
<title>Chemical objects</title>
<para>
These are the objects that represent the parts of a molecular system:
<itemizedlist>
<listitem><para>atoms</para></listitem>
<listitem><para>groups</para></listitem>
<listitem><para>molecules</para></listitem>
<listitem><para>molecular complexes</para></listitem>
</itemizedlist>
</para>
<para>
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. Groups can
only be used in the definitions of other groups and molecules in the
<xref linkend="overview-database"/>.
</para>
<para>
A number of operations can be performed on chemical objects, which
can roughly be classified into inquiry (constituent atoms, bonds, center
of mass etc.) and modification (translate, rotate).
</para>
<para>
There are also specialized versions of some of these objects. For example,
MMTK defines proteins as special complexes, consisting of peptide
chains, which are special molecules. They offer a range of special
operations (such as selecting residues or constructing the positions of
missing hydrogen atoms) that do not make sense for molecules in
general.
</para>
</simplesect>

<simplesect>
<title>Collections</title>
<para>
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.
</para>
</simplesect>

<simplesect>
<title>Force fields</title>
<para>
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.
</para>
</simplesect>

<simplesect>
<title>Universes</title>
<para>
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.
</para>
</simplesect>

<simplesect>
<title>Minimizers and integrators</title>
<para>
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. Similarly, an integrator is a special "machine" that can
determine a dynamical trajectory for a system on a given potential
energy surface.
</para>
</simplesect>

<simplesect>
<title>Trajectories</title>
<para>
Minimizers and integrators can produce trajectories, which are special
files containing a sequence of configurations and/or other related
information. Of course trajectory objects can also be read for
analysis.
</para>
</simplesect>

<simplesect>
<title>Variables</title>
<para>
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, masses, or energy gradients. Their most common use
is for storing various configurations of a system.
</para>
</simplesect>

<simplesect>
<title>Normal modes</title>
<para>
Normal mode objects contain normal mode frequencies and atomic
displacements for a given universe.
</para>
</simplesect>

<simplesect>
<title>Non-MMTK objects</title>
<para>
An MMTK application program will typically also make use of objects
provided by Python or Python library modules. A particularly useful
library is the package Scientific, which
is also used by MMTK itself. The most important objects are
<itemizedlist>
<listitem><para>
numbers (integers, real number, complex numbers), provided by Python
</para></listitem>
<listitem><para>
vectors (in 3D coordinate space) provided by the module Scientific.Geometry.
</para></listitem>
<listitem><para>character strings, provided by Python</para></listitem>
<listitem><para>files, provided by Python</para></listitem>
</itemizedlist>
Of course MMTK applications can make use of the Python standard
library or any other Python modules. For example, it is possible
to write a simulation program that provides status reports via an
integrated Web server, using the Python standard module SimpleHTTPServer.
</para></simplesect>
</sect1>


<sect1 id ="overview-database" xreflabel="chemical database">
<title>The chemical database</title>
<para>
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 molecule database. 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.
</para>
<para>
MMTK comes with database entries for many common objects (water,
amino acids, etc.). For other objects you will have to write the definitions
yourself, as described in the section on the <xref linkend="database"/>.
</para>
</sect1>

<sect1>
<title>Force fields</title>
<para>
MMTK contains everything necessary to use the <ulink
url="&amber-url;">Amber 94 force field</ulink> on proteins, DNA, and
water molecules. It uses the standard Amber parameter and modification
file format. In addition to the Amber force field, there is a simple
Lennard-Jones force field for noble gases, and a deformation force
field for normal mode calculations on large proteins.
</para>
<para>
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 the developer's guide.
</para>
</sect1>

<sect1>
<title>Units</title>
<para>
Since MMTK is not a black-box program, but a modular 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.
</para>
<para>
The unit system of MMTK consists mostly of SI units of appropriate
magnitude for molecular systems:
<itemizedlist>
<listitem><para>nm for lengths</para></listitem>
<listitem><para>ps for times</para></listitem>
<listitem><para>atomic mass units (g/mol) for masses</para></listitem>
<listitem><para>kJ/mol for energies</para></listitem>
<listitem><para>THz (1/ps) for frequencies</para></listitem>
<listitem><para>K for temperatures</para></listitem>
<listitem><para>elementary charges</para></listitem>
</itemizedlist>
</para>
<para>
The module <xref linkend="Module:MMTK.Units"/> contains convenient
conversion constants for the units commonly used in computational
chemistry. For example, a length of 2 &Aring;ngstr&ouml;m can be
written as <literal>2*Units.Ang</literal>, and a frequency can be
printed in wavenumbers with <literal>print
frequency/Units.invcm</literal>.
</para>
</sect1>

<sect1>
<title>A simple example</title>
<para>
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.
</para>
<programlisting role="Python">
# Import the necessary MMTK definitions.
from MMTK import *
from MMTK.ForceFields import Amber94ForceField
from MMTK.Trajectory import Trajectory, TrajectoryOutput, \
                            StandardLogOutput
from MMTK.Dynamics import VelocityVerletIntegrator

# Create an infinite universe (i.e. no boundaries, non-periodic).
universe = InfiniteUniverse(Amber94ForceField())

# 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 at each step.
integrator(delta_t = 1.*Units.fs, steps = 50,
           actions = [StandardLogOutput(5),
                      TrajectoryOutput(trajectory, ("time", "energy",
                                                    "thermodynamic",
                                                    "configuration"),
                                       0, None, 1)])

# Close the trajectory
trajectory.close()
</programlisting>
</sect1>

</chapter>


<chapter id="setup">
<title>Constructing a molecular system</title>
<para>
The construction of a complete system for simulation or analysis
involves some or all of the following operations:
<itemizedlist>
<listitem><para>
Creating molecules and other chemical objects.
</para></listitem>
<listitem><para>
Defining the configuration of all objects.
</para></listitem>
<listitem><para>
Defining the "surroundings" (e.g. boundary conditions).
</para></listitem>
<listitem><para>
Choosing a force field.
</para></listitem>
</itemizedlist>
MMTK offers a large range of functions to deal with these tasks.
</para>

<sect1>
<title>Creating chemical objects</title>
<para>
Chemical objects (atoms, molecules, complexes) are created from
definitions in the <xref linkend="database"/>. Since
these definitions contain most of the necessary information, the
subsequent creation of the objects is a simple procedure.
</para>
<para>
All objects are created by their class name
(<xref linkend="Class:MMTK.Atom"/>, <xref linkend="Class:MMTK.Molecule"/>, and
<xref linkend="Class:MMTK.Complex"/>) with the name
of the definition file as first parameter. Additional optional parameters
can be specified to modify the object being created. The following optional
parameters can be used for all object types:
<itemizedlist>
<listitem><para>
 <literal>name=</literal>string
Specifies a name for the object. The default name is the one given in
the definition file.
</para></listitem>
<listitem><para>
 <literal>position=</literal>vector
Specifies the position of the center of mass. The default is the origin.
</para></listitem>
<listitem><para>
 <literal>configuration=</literal>string
Indicates a configuration from the configuration dictionary in the
definition file. The default is 'default' if such an entry exists in the
configuration dictionary. Otherwise the object is created without atomic
positions.
</para></listitem>
</itemizedlist>
</para>
<para>
Some examples with additional explanations for specific types:
<itemizedlist>
<listitem><para>
 <literal>Atom('C')</literal> creates a carbon atom.
</para></listitem>
<listitem><para>
 <literal>Molecule('water', position=Vector(0.,0.,1.))</literal>
creates a water molecule using configuration 'default' and moves the
center of mass to the indicated position.
</para></listitem>
</itemizedlist>
</para>

<sect2>
<title>Proteins, peptide chains, and nucleotide chains</title>

<para>
MMTK contains special support for working with proteins, peptide
chains, and nucleotide chains. As described in the chapter on the
<xref linkend="database"/>, proteins can be described by a special
database definition file. However, it is often simpler to create
protein objects directly in an application program. The classes
are <xref linkend="Class:MMTK.Proteins.PeptideChain"/>,
<xref linkend="Class:MMTK.Proteins.Protein"/>,
and <xref linkend="Class:MMTK.NucleicAcids.NucleotideChain"/>.
</para>
<para>
Proteins can be created from definition files in the database,
from previously constructed peptide chain objects, or directly
from PDB files if no special manipulations are necessary.
</para>
<para>
Examples: <literal>Protein('insulin')</literal> creates a
protein object for insulin from a database file.
<literal>Protein('1mbd.pdb')</literal> creates a protein
object for myoglobin directly from a PDB file, but leaving out the
heme group, which is not a peptide chain.
</para>
<para>
Peptide chains are created from a sequence of residues, which can be a
<xref linkend="Class:MMTK.PDB.PDBPeptideChain"/> object, a list of three-letter
residue codes, or a string containing one-letter residue codes. In the
last two cases the atomic positions are not defined. MMTK provides
several models for the residues which provide different levels of
detail: an all-atom model, a model without hydrogen atoms, two models
containing only polar hydrogens (using different definitions of polar
hydrogens), and a model containing only the C-alpha atoms, with each
C-alpha atom having the mass of the entire residue. The last model
is useful for conformational analyses in which only the backbone
conformations are important.
</para>
<para>
The construction of nucleotide chains is very similar. The residue
list can be either a <xref
linkend="Class:MMTK.PDB.PDBNucleotideChain"/> object or a list of
two-letter residue names. The first letter of a residue name indicates
the sugar type (<literal>'R'</literal> for ribose and
<literal>'D'</literal> for desoxyribose), and the second letter
defines the base (<literal>'A'</literal>, <literal>'C'</literal>, and
<literal>'G'</literal>, plus <literal>'T'</literal> for DNA and
<literal>'U'</literal> for RNA). The models are the same as for
peptide chains, except that the C-alpha model does not exist.
</para>
<para>
Most frequently proteins and nucleotide chains are created from a PDB
file. The PDB files often contain solvent (water) as well, and perhaps
some other molecules. MMTK provides convenient functions for extracting
information from PDB files and for building molecules from them in the
module <xref linkend="Module:MMTK.PDB"/>. The first step is
the creation of a <xref linkend="Class:MMTK.PDB.PDBConfiguration"/>
object from the PDB file:
<programlisting role="Python">
from MMTK.PDB import PDBConfiguration
configuration = PDBConfiguration('some_file.pdb')
</programlisting>
The easiest way to generate MMTK objects for all molecules in the
PDB file is then
<programlisting role="Python">
molecules = configuration.createAll()
</programlisting>
The result is a collection of molecules, peptide chains, and
nucleotide chains, depending on the contents of the PDB files.
There are also methods for modifying the PDBConfiguration before
creating MMTK objects from it, and for creating objects
selectively. See the documentation for the modules
<xref linkend="Module:MMTK.PDB"/> and Scientific.IO.PDB for details,
as well as the <xref linkend="Example:Proteins"/> and 
<xref linkend="Example:DNA"/> examples.
</para>
</sect2>

<sect2>
<title>Lattices</title>
<para>
Sometimes it is necessary to generate objects (atoms or molecules)
positioned on a lattice. To facilitate this task, MMTK defines lattice
objects which are essentially sequence objects containing points or
objects at points. Lattices can therefore be used like lists with
indexing and <literal>for</literal>-loops. The lattice classes
are <xref linkend="Class:MMTK.Geometry.RhombicLattice"/>,
<xref linkend="Class:MMTK.Geometry.BravaisLattice"/>, and
<xref linkend="Class:MMTK.Geometry.SCLattice"/>.
</para>
</sect2>

<sect2>
<title>Random numbers</title>
<para>
The Python standard library and the Numerical Python package provide
random number generators, and more are available in seperate packages.
MMTK provides some convenience functions that return more specialized
random quantities: random points in a universe, random velocities,
random particle displacement vectors, random orientations. These
functions are defined in module <xref linkend="Module:MMTK.Random"/>.
</para>
</sect2>

<sect2>
<title>Collections</title>
<para>
Often it is useful to treat a collection of several objects as a
single entity.  Examples are a large number of solvent molecules
surrounding a solute, or all sidechains of a protein. MMTK has special
collection objects for this purpose, defined as class
<xref linkend="Class:MMTK.Collection"/>. Most of the methods
available for molecules can also be used on collections.
</para>
<para>
A variant of a collection is the partitioned collection, implemented in
class <xref linkend="Class:MMTK.PartitionedCollection"/>. This class
acts much like a standard collection, but groups its elements by
geometrical position in small sub-boxes. As a consequence, some geometrical
algorithms (e.g. pair search within a cutoff) are much faster, but
other operations become somewhat slower.
</para>
</sect2>

<sect2>
<title>Creating universes</title>
<para>
A universe describes a complete molecular system consisting of any
number of chemical objects and a specification of their interactions
(i.e. a force field) and surroundings: boundary conditions, external
fields, thermostats, etc. The universe classes are defined in module
MMTK:
<itemizedlist>
<listitem><para>
<xref linkend="Class:MMTK.InfiniteUniverse"/> represents an infinite universe,
without any boundary or periodic boundary conditions.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.OrthorhombicPeriodicUniverse"/> represents a periodic
universe with an orthorhombic elementary cell, whose size is defined
by the three edge lengths.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.CubicPeriodicUniverse"/> is a special case
of <xref linkend="Class:MMTK.OrthorhombicPeriodicUniverse"/> in which the
elementary cell is cubic.
</para></listitem>
</itemizedlist>
</para>
<para>
Universes are created empty; the contents are then added to them.
Three types of objects can be added to a universe: chemical objects
(atoms, molecules, etc.), collections, and environment objects
(thermostats etc.). It is also possible to remove objects from a
universe.
</para>
</sect2>

<sect2>
<title>Force fields</title>

<para>
MMTK comes with several force fields, and permits the definition of
additional force fields. Force fields are defined in module <xref
linkend="Module:MMTK.ForceFields"/>. The most import built-in force
field is the <ulink url="&amber-url;">Amber 94 force field</ulink>,
represented by the class <xref
linkend="Class:MMTK.ForceFields.Amber94ForceField"/>. It offers
several strategies for electrostatic interactions, including Ewald
summation, a fast multipole method [<xref linkend="Article:DPMTA"/>],
and cutoff with charge neutralization and optional screening [<xref
linkend="Article:Wolf1999"/>].
</para>
<para>
In addition to the Amber 94 force field, there is a Lennard-Jones
force field for noble gases (Class <xref
linkend="Class:MMTK.ForceFields.LennardJonesForceField"/>) and a
deformation force field for protein normal mode calculations (Class
<xref linkend="Class:MMTK.ForceFields.DeformationForceField"/>).
</para>
</sect2>
</sect1>

<sect1>
<title>Referring to objects and parts of objects</title>
<para>
Most MMTK objects (in fact all except for atoms) have a hierarchical
structure of parts of which they consist. For many operations it is
necessary to access specific parts in this hierarchy.
</para>
<para>
In most cases, parts are attributes with a specific name. For example,
the oxygen atom in every water molecule is an attribute with the name
"O". Therefore if <literal>w</literal> refers to a water
molecule, then <literal>w.O</literal> refers to its oxygen
atom. For a more complicated example, if <literal>m</literal>
refers to a molecule that has a methyl group called "M1", then <literal>m.M1.C</literal>
refers to the carbon atom of that methyl group. The names of attributes
are defined in the database.
</para>
<para>
Some objects consist of parts that need not have unique names, for
example the elements of a collection, the residues in a peptide chain,
or the chains in a protein. Such parts are accessed by indices; the
objects that contain them are Python sequence types. Some examples:
<itemizedlist>
<listitem><para>
Asking for the number of items: if <literal>c</literal>
refers to a collection, then <literal>len(c)</literal> is
the number of its elements.
</para></listitem>
<listitem><para>
Extracting an item: if <literal>p</literal> refers to a
protein, then <literal>p[0]</literal> is its first peptide
chain.
</para></listitem>
<listitem><para>
Iterating over items: if <literal>p</literal> refers to a
peptide chain, then <literal>for residue in p: print
residue.position()</literal> will print the center of mass positions of
all its residues.
</para></listitem>
</itemizedlist>
</para>
<para>
Peptide and nucleotide chains also allow the operation of slicing: if <literal>p</literal>
refers to a peptide chain, then <literal>p[1:-1]</literal>
is a subchain extending from the second to the next-to-last residue.
</para>

<sect2>
<title>The structure of peptide and nucleotide chains</title>
<para>
Since peptide and nucleotide chains are not constructed from an explicit
definition file in the database, it is not evident where their
hierarchical structure comes from. But it is only the top-level
structure that is treated in a special way. The constituents of peptide
and nucleotide chains, residues, are normal group objects. The
definition files for these group objects are in the MMTK standard
database and can be freely inspected and even modified or overriden by
an entry in a database that is listed earlier in MMTKDATABASE.
</para>
<para>
Peptide chains are made up of amino acid residues, each of which is a
group consisting of two other groups, one being called "peptide" and the
other "sidechain". The first group contains the peptide group and the C
and H atoms; everything else is contained in the sidechain. The C atom
of the fifth residue of peptide chain <literal>p</literal>
is therefore referred to as <literal>p[4].peptide.C_alpha</literal>.
</para>
<para>
Nucleotide chains are made up of nucleotide residues, each of which is
a group consisting of two or three other groups. One group is called
"sugar" and is either a ribose or a desoxyribose group, the second one
is called "base" and is one the five standard bases. All but the first
residue in a nucleotide chain also have a subgroup called "phosphate"
describing the phosphate group that links neighbouring residues.
</para>
</sect2>
</sect1>


<sect1>
<title>Analyzing and modifying atom properties</title>

<sect2>
<title>General operations</title>
<para>
Many inquiry and modification operations act at the atom level and
can equally well be applied to any object that is made up of
atoms, i.e. atoms, molecules, collections, universes, etc.
These operations are defined once in a <xref linkend="Glossary:MixInClass"/>
called <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>, but are available
for all objects for which they make sense. They include inquiry-type
functions (total mass, center of mass, moment of inertia, bounding box,
total kinetic energy etc.), coordinate modifications (translation, rotation,
application of <xref linkend="transformation"/> objects) and coordinate
comparisons (RMS difference, optimal fits).
</para>
</sect2>

<sect2 id="transformation" xreflabel="transformation">
<title>Coordinate transformations</title>
<para>
The most common coordinate manipulations involve translations and
rotations of specific parts of a system. It is often useful to refer
to such an operation by a special kind of object, which permits the
combination and analysis of transformations as well as its application
to atomic positions.
</para>
<para>
Transformation objects specify a general displacement consisting of a
rotation around the origin of the coordinate system followed by a
translation. They are defined in the module Scientific.Geometry, but
for convenience the module MMTK contains a reference to them as well.
Transformation objects corresponding to pure translations can be
created with
<literal>Translation(</literal><parameter>displacement</parameter><literal>)</literal>;
transformation objects describing pure rotations with
<literal>Rotation(</literal><parameter>axis</parameter><literal>,
</literal><parameter>angle</parameter><literal>)</literal> or
<literal>Rotation(</literal><parameter>rotation</parameter><literal>_matrix)</literal>.
Multiplication of transformation objects returns a composite
transformation.
</para>
<para>
The translational component of any transformation can be obtained by
calling the method <literal>translation()</literal>; the
rotational component is obtained analogously with <literal>rotation()</literal>.
The displacement vector for a pure translation can be extracted with the
method <literal>displacement()</literal>, a tuple of axis
and angle can be extracted from a pure rotation by calling <literal>axisAndAngle()</literal>.
</para>
</sect2>

<sect2 id="atom_property" xreflabel="atom property">
<title>Atomic property objects</title>
<para>
Many properties in a molecular system are defined for each individual atom:
position, velocity, mass, etc. Such properties are represented in special
objects, defined in module MMTK: <xref linkend="Class:MMTK.ParticleScalar"/>
for scalar quantities, <xref linkend="Class:MMTK.ParticleVector"/> for vector
quantities, and <xref linkend="Class:MMTK.ParticleTensor"/> for rank-2 tensors.
All these objects can be indexed with an atom object to retrieve or change
the corresponding value. Standard arithmetic operations are also defined,
as well as some useful methods.
</para>
</sect2>

<sect2 id="configuration" xreflabel="configuration">
<title>Configurations</title>
<para>
A configuration object, represented by the class <xref
linkend="Class:MMTK.Configuration"/> is a special variant of a
<xref linkend="Class:MMTK.ParticleVector"/> object. In addition to
the atomic coordinates of a universe, it stores geometric parameters
of a universe that are subject to change, e.g. the edge lengths
of the elementary cell of a periodic universe.
Every universe has a current configuration, which is what all operations
act on by default. It is also the configuration that is updated by
minimizations, molecular dynamics, etc. The current configuration can be
obtained by calling the method <literal>configuration()</literal>.
</para>
<para>
There are two ways to create configuration objects: by making a copy
of the current configuration (with
<literal>copy(universe.configuration())</literal>, or by reading a
configuration from a <xref linkend="trajectory"/> file.
</para>
</sect2>

</sect1>
</chapter>

<chapter>
<title>Minimization and Molecular Dynamics</title>

<sect1 id="trajectory" xreflabel="trajectory">
<title>Trajectories</title>
<para>
Minimization and dynamics algorithms produce sequences of configurations
that are often stored for later analysis. In fact, they are often the
most valuable result of a lengthy simulation run. To make sure that the
use of trajectory files is not limited by machine compatibility, MMTK
stores trajectories in <ulink url="&netcdf-url;">netCDF</ulink>
files. These files contain binary data, minimizing disk space usage, but
are freely interchangeable between different machines. In addition,
there are a number of programs that can perform standard operations on
arbitrary netCDF files, and which can therefore be used directly on MMTK
trajectory files. Finally, netCDF files are self-describing, i.e.
contain all the information needed to interpret their contents.
An MMTK trajectory file can thus be inspected and processed without
requiring any further information.
</para>
<para>
For illustrations of trajectory operations, see the
<xref linkend="Example:Trajectories"/> examples.
</para>
<para>
Trajectory file objects are represented by the class <xref
linkend="Class:MMTK.Trajectory.Trajectory"/>. They can be opened for
reading, writing, or modification. The data in trajectory files can be
stored in single precision or double precision; single-precision is
usually sufficient, but double-precision files are required to
reproduce a given state of the system exactly.
</para>
<para>
A trajectory is closed by calling the method <literal>close()</literal>.
If anything has been written to a trajectory, closing it is required to
guarantee that all data has been written to the file. Closing a
trajectory after reading is recommended in order to prevent memory
leakage, but is not strictly required.
</para>
<para>
Newly created trajectories can contain all
objects in a universe or any subset; this is useful for limiting the
amount of disk space occupied by the file by not storing uninteresting
parts of the system, e.g. the solvent surrounding a protein. It is
even possible to create a trajectory for a subset of the atoms in a
molecule, e.g. for only the C-alpha atoms of a protein. The universe
description that is stored in the trajectory file contains all
chemical objects of which at least one atom is represented.
</para>
<para>
When a trajectory is opened for reading, no universe object needs
to be specified. In that case, MMTK creates a universe from
the description contained in the trajectory file. This universe will
contain the same objects as the one for which the trajectory file was
created, but not necessarily have all the properties of the original
universe (the description contains only the names and types of the
objects in the universe, but not, for example, the force field). The
universe can be accessed via the attribute <literal>universe</literal>
of the trajectory.
</para>
<para>
If the trajectory was created with partial data for some of the objects,
reading data from it will set the data for the missing parts to
"undefined". Analysis operations on such systems must be done very
carefully. In most cases, the trajectory data will contain the atomic
configurations, and in that case the "defined" atoms can be extracted
with the method <literal>atomsWithDefinedPositions()</literal>.
</para>
<para>
MMTK trajectory files can store various data: atomic positions,
velocities, energies, energy gradients etc. Each trajectory-producing
algorithm offers a set of quantities from which the user can choose what
to put into the trajectory. Since a detailed selection would be
tedious, the data is divided into classes, e.g. the class "energy"
stands for potential energy, kinetic energy, and whatever other
energy-related quantities an algorithm produces.
</para>
<para>
For optimizing I/O efficiency, the data layout in a trajectory file
can be modified by the <literal>block_size</literal> parameter. Small
block sizes favour reading or writing all data for one time step,
whereas large block sizes (up to the number of steps in the trajectory)
favour accessing a few values for all time steps, e.g. scalar
variables like energies or trajectories for individual atoms. The
default value of the block size is one.
</para>
<para>
Every trajectory file contains a history of its creation. The creation
of the file is logged with time and date, as well as each operation that
adds data to it with parameters and the time/date of start and end. This
information, together with the comment and the number of atoms and steps
contained in the file, can be obtained with the function
<xref linkend="Function:MMTK.Trajectory.trajectoryInfo"/>.
</para>
<para>
It is possible to read data from a trajectory file that is being
written to by another process. For efficiency, trajectory data is not
written to the file at every time step, but only approximately every
15 minutes. Therefore the amount of data available for reading may be
somewhat less than what has been produced already.
</para>
</sect1>

<sect1>
<title>Options for minimization and dynamics</title>

<para>
Minimizers and dynamics integrators accept various optional parameter
specifications. All of them are selected by keywords, have reasonable
default values, and can be specified when the minimizer or integrator
is created or when it is called. In addition to parameters that are
specific to each algorithm, there is a general parameter
<parameter>actions</parameter> that specifies actions that are
executed periodically, including trajectory and console output.
</para>

<sect2>
<title>Periodic actions</title>
<para>
Periodic actions are specified by the keyword parameter
<parameter>actions</parameter> whose value is a list of periodic
actions, which defaults to an empty list. Some of these actions are
applicable to any trajectory-generating algorithm, especially the
output actions. Others make sense only for specific algorithms or
specific universes, e.g. the periodic rescaling of velocities during a
Molecular Dynamics simulation.
</para>
<para>
Each action is described by an action object. The step numbers for which
an action is executed are specified by three parameters. The
parameter <parameter>first</parameter> indicates the number of the
first step for which the action is executed, and defaults to 0. The
parameter <parameter>last</parameter> indicates the last step for
which the action is executed, and default to <literal>None</literal>,
meaning that the action is executed indefinitely. The parameter
<parameter>skip</parameter> speficies how many steps are skipped
between two executions of the action. The default value of 1 means
that the action is executed at each step. Of course an action object
may have additional parameters that are specific to its action.
</para>
<para>
The output actions are defined in the module <xref
linkend="Module:MMTK.Trajectory"/> and can be used with any
trajectory-generating algorithm. They are:
<itemizedlist>
<listitem><para>
<xref linkend="Class:MMTK.Trajectory.TrajectoryOutput"/> for writing
data to a trajectory. Note that it is possible to use
several trajectory output actions simultaneously to write to multiple
trajectories. It is thus possible, for example, to write a short
dense trajectory during a dynamics run for analyzing short-time
dynamics, and simultaneously a long-time trajectory with a larger
step spacing, for analyzing long-time dynamics.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Trajectory.RestartTrajectoryOutput"/>,
which is a specialized version of
<xref linkend="Class:MMTK.Trajectory.TrajectoryOutput"/>.
It writes the data that the
algorithm needs in order to be restarted to a restart trajectory file.
A restart trajectory is a trajectory that stores a fixed
number of steps which are reused cyclically, such that it always
contain the last few steps of a trajectory.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Trajectory.LogOutput"/> for text output
of data to a file.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Trajectory.StandardLogOutput"/>, a specialized
version of <xref linkend="Class:MMTK.Trajectory.LogOutput"/> that
writes the data classes "time" and "energy" during the whole
simulation run to standard output.
</para></listitem>
</itemizedlist>
</para>
<para>
The other periodic actions are meaningful only for Molecular Dynamics
simulations:
<itemizedlist>
<listitem><para>
<xref linkend="Class:MMTK.Dynamics.VelocityScaler"/> is used for
rescaling the velocities to force the kinetic energy to the value
defined by some temperature. This is usually done during initial
equilibration.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Dynamics.BarostatReset"/> resets the
barostat coordinate to zero and is during initial equilibration
of systems in the NPT ensemble.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Dynamics.Heater"/> rescales the velocities
like  <xref linkend="Class:MMTK.Dynamics.VelocityScaler"/>, but
increases the temperature step by step.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Dynamics.TranslationRemover"/> subtracts
the global translational velocity of the system from all individual
atomic velocities. This prevents a slow but systematic energy flow
into the degrees of freedom of global translation, which occurs
with most MD integrators due to non-perfect conservation of momentum.
</para></listitem>
<listitem><para>
<xref linkend="Class:MMTK.Dynamics.RotationRemover"/> subtracts
the global angular velocity of the system from all individual
atomic velocities. This prevents a slow but systematic energy flow
into the degrees of freedom of global rotation, which occurs
with most MD integrators due to non-perfect conservation of angular
momentum.
</para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title>Fixed atoms</title>
<para>
During the course of a minimization or molecular dynamics algorithm, the
atoms move to different positions. It is possible to exclude specific
atoms from this movement, i.e. fixing them at their initial positions.
This has no influence whatsoever on energy or force calculations; the
only effect is that the atoms' positions never change. Fixed atoms are
specified by giving them an attribute <literal>fixed</literal>
with a value of one. Atoms that do not have an attribute
<literal>fixed</literal>, or one with a value of zero, move according
to the selected algorithm.
</para>
</sect2>
</sect1>

<sect1 id="energy_minimization" xreflabel="energy minimization">
<title>Energy minimization</title>
<para>
MMTK has two energy minimizers using different algorithms: steepest
descent (<xref
linkend="Class:MMTK.Minimization.SteepestDescentMinimizer"/>) and
conjugate gradient (<xref
linkend="Class:MMTK.Minimization.ConjugateGradientMinimizer"/>)
. Steepest descent minimization is very inefficient if the goal is to
find a local minimum of the potential energy. However, it has the
advantage of always moving towards the minimum that is closest to the
starting point and is therefore ideal for removing bad contacts in a
unreasonably high energy configuration. For finding local minima, the
conjugate gradient algorithm should be used.
</para>
<para>
Both minimizers accept three specific optional parameters:
<itemizedlist>
<listitem><para>
<parameter>steps</parameter> (an integer) to specify the maximum number of
steps (default is 100)
</para></listitem>
<listitem><para>
<parameter>step_size</parameter> (a number)
to specify an initial step length used in the search for a minimum
(default is 2 pm)
</para></listitem>
<listitem><para>
<parameter>convergence</parameter> (a number)
to specify the gradient norm (more precisely the root-mean-square
length) at which the minimization should stop (default is 0.01
kJ/mol/nm)
</para></listitem>
</itemizedlist>
</para>
<para>
There are three classes of trajectory data: "energy" includes the
potential energy and the norm of its gradient, "configuration" stands
for the atomic positions, and "gradients" stands for the energy
gradients at each atom position.
</para>
<para>
The following example performs 100 steps of steepest descent
minimization without producing any trajectory or printed output:
<programlisting role="Python">
from MMTK import *
from MMTK.ForceFields import Amber94ForceField
from MMTK.Minimization import SteepestDescentMinimizer

universe = InfiniteUniverse(Amber94ForceField())
universe.protein = Protein('insulin')

minimizer = SteepestDescentMinimizer(universe)
minimizer(steps = 100)
</programlisting>
</para>
<para>
See also the example file <xref linkend="Example:NormalModes:modes.py"/>.
</para>
</sect1>

<sect1>
<title>Molecular dynamics</title>

<para>
The techniques described in this section are illustrated by several
<xref linkend="Example:MolecularDynamics"/> examples.
</para>

<sect2>
<title>Velocities</title>
<para>
The integration of the classical equations of motion for an atomic
system requires not only positions, but also velocities for all atoms.
Usually the velocities are initialized to random values drawn from a
normal distribution with a variance corresponding to a certain
temperature. This is done by calling the method
<literal>initializeVelocitiesToTemperature(temperature)</literal>
on a universe. Note that the velocities are assigned atom by atom; no
attempt is made to remove global translation or rotation of the total
system or any part of the system.
</para>
<para>
During equilibration of a system, it is common to multiply all
velocities by a common factor to restore the intended temperature. This
can done explicitly by calling the method
<literal>scaleVelocitiesToTemperature(temperature)</literal>
on a universe, or by using the action object
<xref linkend="Class:MMTK.Dynamics.VelocityScaler"/>.
</para>
</sect2>

<sect2>
<title>Distance constraints</title>
<para>
A common technique to eliminate the fastest (usually uninteresting)
degrees of freedom, permitting a larger integration time step,
is the use of distance constraints on some or all chemical bonds.
MMTK allows the use of distance constraints on any pair of
atoms, even though constraining anything but chemical bonds
is not recommended due to considerable modifications of the
dynamics of the system [<xref linkend="Article:vanGunsteren1982"/>,
<xref linkend="Article:Hinsen1995"/>].
</para>
<para>
MMTK permits the definition of distance constraints on all atom pairs
in an object that are connected by a chemical bond by calling the
method <literal>setBondConstraints</literal>. Usually this is called
for a complete universe, but it can also be called for a chemical
object or a collection of chemical objects. The method
<literal>removeDistanceConstraints</literal> removes all distance
constraints from the object for which it is called.
</para>
<para>
Constraints defined as described above are automatically taken into
account by Molecular Dynamics integrators. It is also possible to
enforce the constraints explicitly by calling the method
<literal>enforceConstraints</literal> for a universe. This has the
effect of modifying the configuration and the velocities (if
velocities exist) in order to make them compatible with the
constraints.
</para>
</sect2>

<sect2>
<title>Thermostats and barostats</title>
<para>
A standard Molecular Dynamics integration allows time averages
corresponding to the NVE ensemble, in which the number of molecules,
the system volume, and the total energy are constant. This ensemble
does not represent typical experimental conditions very well.
Alternative ensembles are the NVT ensemble, in which the temperature
is kept constant by a thermostat, and the NPT ensemble, in which
temperature and pressure are kept constant by a thermostat and a
barostat. To obtain these ensembles in MMTK, thermostat and barostat
objects must be added to a universe. In the presence of these objects,
the Molecular Dynamics integrator will use the extended-systems method
for producing the correct ensemble. The classes to be used are
<xref linkend="Class:MMTK.Environment.NoseThermostat"/> and
<xref linkend="Class:MMTK.Environment.AndersenBarostat"/>.
</para>
</sect2>

<sect2>
<title>Integration</title>
<para>
A Molecular Dynamics integrator based on the "Velocity Verlet"
algorithm [<xref linkend="Article:Swope1982"/>], which was extended
to handle distance constraints as well as thermostats and
barostats [<xref linkend="Article:Kneller1996"/>], is implemented by the
class <xref linkend="Class:MMTK.Dynamics.VelocityVerletIntegrator"/>.
It has two optional keyword parameters:
<itemizedlist>
<listitem><para>
<parameter>steps</parameter> (an integer) to specify the number
of steps (default is 100)
</para></listitem>
<listitem><para>
<parameter>delta_t</parameter> (a number) to specify the time step
(default 1 fs)
</para></listitem>
</itemizedlist>
</para>
<para>
There are three classes of trajectory data: "energy" includes the
potential energy and the kinetic energy, as well as the energies of
thermostat and barostat coordinates if they exist, "time" stands for the time,
"thermodynamic" stand for temperature and pressure,
"configuration" stands for the atomic positions, "velocities" stands for
the atomic velocities, and "gradients" stands for the energy gradients
at each atom position.
</para>
<para>
The following example performs a 1000 step dynamics integration, storing
every 10th step in a trajectory file and removing the total translation
and rotation every 50th step:
<programlisting role="Python">
from MMTK import *
from MMTK.ForceFields import Amber94ForceField
from MMTK.Dynamics import VelocityVerletIntegrator, TranslationRemover, \
                          RotationRemover
from MMTK.Trajectory import TrajectoryOutput

universe = InfiniteUniverse(Amber94ForceField())
universe.protein = Protein('insulin')

universe.initializeVelocitiesToTemperature(300.*Units.K)

actions = [TranslationRemover(0, None, 50),
           RotationRemover(0, None, 50),
           TrajectoryOutput("insulin.nc",
                            ("configuration", "energy", "time"),
                            0, None, 10)]

integrator = VelocityVerletIntegrator(universe, delta_t = 1.*Units.fs,
                                      actions = actions)

integrator(steps = 1000)
</programlisting>
</para>
</sect2>
</sect1>

<sect1>
<title>Snapshots</title>
<para>
A snapshot generator allows writing the current system state to a
trajectory. It works much like a zero-step minimization or dynamics run,
i.e. it takes the same optional arguments for specifying the trajectory
and protocol output. A snapshot generator is created using the
class <xref linkend="Class:MMTK.Trajectory.SnapshotGenerator"/>.
</para>
</sect1>
</chapter>

<chapter id="normal_modes">
<title>Normal modes</title>
<para>
Normal mode analysis provides an analytic description of the dynamics
of a system near a minimum using an harmonic approximation to the
potential. Before a normal mode analysis can be started, the system
must be brought to a local minimum of the potential energy by <xref
linkend="energy_minimization"/>, except when special force fields
designed only for normal mode analysis are used (e.g. <xref
linkend="Class:MMTK.ForceFields.DeformationForceField"/>). See also
the <xref linkend="Example:NormalModes"/> examples.
</para>
<para>
A standard normal mode analysis is performed by creating a normal mode
object, implemented in class <xref
linkend="Class:MMTK.NormalModes.NormalModes"/>. A normal mode object
behaves like a sequence of <xref linkend="Class:MMTK.NormalModes.Mode"/>
objects which store the atomic displacement vectors corresponding
to each mode and its vibrational frequency.
</para>
<para>
For short-ranged potentials, it is advantageous to store the second
derivatives of the potential in a sparse-matrix form and to use
an iterative method to determine some or all modes. This permits
the treatments of larger systems that would normally require huge
amounts of memory. A sparse-matrix method is implemented in class
<xref linkend="Class:MMTK.NormalModes.SparseMatrixNormalModes"/>.
</para>
<para>
Another approach to deal with large systems is the restriction to
low-frequency modes which are supposed to be well representable by
linear combinations of a given set of basis vectors. The basis vectors
can be obtained from a basis for the full Cartesian space by
elimination of known fast degrees of freedom (e.g. bonds); the module
<xref linkend="Module:MMTK.Subspace"/> contains support classes for
this approach. It is also possible to construct a suitable basis
vector set from small-deformation vector fields (e.g. <xref
linkend="Class:MMTK.FourierBasis.FourierBasis"/>). The normal mode
analysis for a given set of basis vectors is performed by the class
<xref linkend="Class:MMTK.NormalModes.SubspaceNormalModes"/>. There is
also a variant using finite difference differentiation (<xref
linkend="Class:MMTK.NormalModes.FiniteDifferenceSubspaceNormalModes"/>)
and another one using a sparse-matrix representation of the second
derivatives (<xref
linkend="Class:MMTK.NormalModes.SparseMatrixSubspaceNormalModes"/>).
</para>
</chapter>


<chapter id="analysis">
<title>Analysis operations</title>
<para>
Analysis is the most non-standard part of molecular simulations.
The quantities that must be calculated depend strongly on the
system and the problem under study. MMTK provides a wide range
of elementary operations that inquire the state of the system,
as well as several more complex analysis tools. Some of them are
demonstrated in the <xref linkend="examples"/> section.
</para>

<sect1>
<title>Properties of chemical objects and universes</title>
<para>
Many operations access and modify various properties of an object. They
are defined for the most general type of object: anything that can be
broken down to atoms, i.e. atoms, molecules, collections, universes,
etc., i.e. in the class <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>.
</para>
<para>
The most elementary operations are inquiries about specific properties
of an object: number of atoms, total mass, center of mass, total momentum,
total charge, etc. There are also operations that compare two different
conformations of a system. Finally, there are special operations
for analyzing conformations of peptide chains and proteins.
</para>
<para>
Geometrical operations in periodic universes require special care.
Whenever a distance vector between two points in a systems is
evaluated, the minimum-image convention must be used in order to
obtain consistent results. MMTK provides routines for finding
these distance vectors as well as distances, angles, and dihedral
angles between any points. Because these operations depend on the
topology and geometry of the universe, they are implemented as
methods in class <xref linkend="Class:MMTK.Universe.Universe"/>
and its subclasses. Of course they are available for non-periodic
universes as well.
</para>
<para>
Universes also provide methods for obtaining <xref linkend="atom_property"/>
objects that describe the state of the system (configurations, velocities,
masses), and for restoring the system state from a <xref linkend="trajectory"/>
file. 
</para>
</sect1>

<sect1>
<title>Energy evaluation</title>
<para>
Energy evaluation requires a force field, and therefore all the
methods in this section are defined only for universe objects, i.e. in
class <xref linkend="Class:MMTK.Universe.Universe"/>.  However, they
all take an optional arguments (anything that can be broken down into
atoms) that indicates for which subset of the universe the energy is
to be evaluated. In addition to the potential energy, energy gradients
and second derivatives (force constants) can be obtained, if the
force field implements them. There is also a method that returns
a dictionary containing the values for all the individual force field
terms, which is often useful for analysis.
</para>
</sect1>

<sect1>
<title>Surfaces and volumes</title>
<para>
Surfaces and volumes can be analyzed for anything consisting of
atoms. Both quantities are defined by assigning a radius to each atom;
the surface of the resulting conglomerate of overlapping spheres is
taken to be the surface of the atom group. Atom radii for surface
determination are usually called "van der Waals radii", but there is
no unique method for determining them. MMTK uses the values from
[<xref linkend="Article:Bondi1964"/>]. However,
users can change these values for each individual atom by assigning a
new value to the attribute "vdW_radius".
</para>
<para>
Surface and volume calculations are implemented in the module <xref
linkend="Module:MMTK.MolecularSurface"/> and make use of the NSC
library by Frank Eisenhabes [<xref linkend="Article:Eisenhaber1993"/>,
<xref linkend="Article:Eisenhaber1995"/>]. Because this library is
subject to stricter copyright conditions than MMTK (it can be freely
used only for non-commercial purposes), the whole molecular surface
package (NSC and the module MolecularSurface) is distributed separately
from the main MMTK distribution. If you get error messages when
trying to evaluate surfaces or values, please verify that you
have installed this separate package.
</para>
<para>
The operations provided in <xref linkend="Module:MMTK.MolecularSurface"/>
include basic surface and volume calculation, determination of
exposed atoms, and identification of contacts between two objects.
</para>
</sect1>

</chapter>

<chapter id="misc">
<title>Miscellaneous operations</title>

<sect1>
<title>Saving, loading, and copying objects</title>
<para>
MMTK provides an easy way to store (almost) arbitrary objects in files
and retrieve them later. All objects of interest to users can be
stored, including chemical objects, collections, universes, normal
modes, configurations, etc. It is also possible to store standard
Python objects such as numbers, lists, dictionaries etc., as well as
practically any user-defined objects. Storage is based on the standard
Python module <literal>pickle</literal>.
</para>
<para>
Objects are saved with <xref linkend="Function:MMTK.save"/> and
restored with <xref linkend="Function:MMTK.load"/>.  If several
objects are to be stored in a single file, use tuples:
<literal>save((object1, object2), filename)</literal> and
<literal>object1, object2 = load(filename)</literal> to retrieve the
objects.
</para>
<para>
Note that storing an object in a file implies storing all objects
referenced by it as well, such that the size of the file can become
larger than expected. For example, a configuration object contains
a reference to the universe for which it is defined. Therefore
storing a configuration object means storing the whole universe
as well. However, nothing is ever written twice to the same
file. If you store a list or a tuple containing a universe and
a configuration for it, the universe is written only once.
</para>
<para>
It should be noted that when saving an object, all objects that this
object refers to are also saved in the same file (otherwise the restored
object would be missing some references). In practice this means that
saving any chemical object, even a single atom, involves saving the
whole universe that this object is part of. However, when saving several
objects in one file, objects referenced several times are saved only
once.
</para>
<para>
Frequently it is also useful to copy an object, such as a molecule or
a configuration. There are two functions (which are actually taken
from the Python standard library module <literal>copy</literal>) for
this purpose, which have a somewhat different behaviour for
container-type objects (lists, dictionaries, collections
etc.). <literal>MMTK.copy(object)</literal> returns a copy of the given
object. For a container object, it returns a new container object
which contains the same objects as the original one. If the intention
is to get a container object which contains copies of the original
contents, then <literal>MMTK.deepcopy(object)</literal> should be used. For
objects that are not container-type objects, there is no difference
between the two functions.
</para>
</sect1>

<sect1>
<title>Exporting to specific file formats and visualization</title>
<para>
MMTK can write objects in specific file formats that can be used by
other programs. Three file formats are supported: the PDB format,
widely used in computational chemistry, the DCD format for
trajectories, written by the programs CHARMM and X-Plor and read by
many visualization programs, and the VRML format, understood by VRML
browsers as a representation of a three-dimensional scene for
visualization. MMTK also provides a more general interface that can
generate graphics objects in any representation if a special module
for that representation exists. In addition to facilitating the
implementation of new graphics file formats, this approach also
permits the addition of custom graphics elements (lines, arrows,
spheres, etc.)  to molecular representations.
</para>

<sect2>
<title>PDB, VRML, and DCD files</title>
<para>
Any chemical object, collection, or universe can be written to a PDB
or VRML file by calling the method <literal>writeToFile</literal>,
defined in class <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>.  PDB
files are read via the class <xref
linkend="Class:MMTK.PDB.PDBConfiguration"/>.  DCD files can be read by a
<xref linkend="Class:MMTK.DCD.DCDReader"/> object.  For writing DCD files,
there is the function <xref linkend="Function:MMTK.DCD.writeDCDPDB"/>, which
also creates a compatible PDB file without which the DCD file could
not be interpreted.
</para>
<para>
Special care must be taken to ensure a correct mapping of atom numbers
when reading from a DCD file. In MMTK, each atom object has a unique
identity and atom numbers, also used internally for efficiency, are
not strictly necessary and are not used anywhere in MMTK's application
programming interface. DCD file, however, simply list coordinates
sorted by atom number. For interpreting DCD files, another file must
be available which allows the identification of atoms from their
number and vice versa; this can for example be a PDB file.
</para>
<para>
When reading DCD files, MMTK assumes that the atom order in the DCD
file is identical to the internal atom numbering of the universe for
which the DCD file is read. This assumption is in general valid only
if the universe has been created from a PDB file that is compatible
with the DCD file, without any additions or removals.
</para>
</sect2>

<sect2>
<title>Visualization and animation</title>
<para>
The most common need for file export is visualization. All objects
that can be visualized (chemical systems and subsets thereof, normal
mode objects, trajectories) provide a method <literal>view</literal>
which creates temporary export files, starts a visualization program,
and deletes the temporary files. Depending on the object type there are
various optional parameters.
</para>
<para>
MMTK also allows visualization of normal modes and trajectories using
animation. Since not all visualization programs permit animation, and
since there is no standard way to ask for it, animation is implemented
only for the programs <ulink url="&xmol-url;">XMol</ulink>
and <ulink url="&vmd-url;">VMD</ulink>. Animation is available for
normal modes, trajectories, and arbitrary sequences of configurations
(see function <xref linkend="Function:MMTK.Visualization.viewSequence"/>).
</para>
<para>
For more specialized needs, MMTK permits the creation of graphical
representations of most of its objects via general graphics modules that
have to be provided externally. Suitable modules are provided in the
package Scientific.Visualization and cover VRML (version 1), VRML2
(aka VRML97), and the molecular visualization program VMD. Modules for other
representations (e.g. rendering programs) can be written easily; it is
recommended to use the existing modules as an example. The generation
of graphics objects is handled by the method <literal>graphicsObjects</literal>,
defined in the class <xref linkend="Class:MMTK.Visualization.Viewable"/>,
which is a <xref linkend="Glossary:MixInClass"/> that makes
graphics objects generation available for all objects that define
chemical systems or parts thereof, as well as for certain other objects
that are viewable.
</para>
<para>
The explicit generation of graphics objects permits the mixture of
different graphical representations for various parts of a system,
as well as the combination of MMTK-generated graphics objects with
arbitrary other graphics objects, such as lines, arrows, or spheres.
All graphics objects are finally combined into a scene object (also
defined in the various graphics modules) in order to be displayed.
See also the <xref linkend="Example:Visualization"/> examples.
</para>
</sect2>
</sect1>

<sect1>
<title>Fields</title>
<para>
For analyzing or visualizing atomic properties that change little over
short distances, it is often convenient to represent these properties as
functions of position instead of one value per atom. Functions of
position are also known as fields, and mathematical techniques for the
analysis of fields have proven useful in many branches of physics. Such
a field can be obtained by averaging over the values corresponding to
the atoms in a small region of space. MMTK provides classes for
scalar and vector field in module <xref linkend="Module:MMTK.Field"/>.
See also the example <xref linkend="Example:Miscellaneous:vector_field.py"/>.
</para>
</sect1>

<sect1>
<title>Charge fitting</title>
<para>
A frequent problem in determining force field parameters is the
determination of partial charges for the atoms of a molecule by fitting
to the electrostatic potential around the molecule, which is obtained
from quantum chemistry programs. Although this is essentially a
straightforward linear least-squares problem, many procedures that are
in common use do not use state-of-the-art techniques and may yield
erroneous results. MMTK provides a charge fitting method that is
numerically stable and allows the imposition of constraints on the
charges. It is implemented in module <xref linkend="Module:MMTK.ChargeFit"/>.
See also the example <xref linkend="Example:Miscellaneous:charge_fit.py"/>.
</para>
</sect1>

</chapter>


<chapter id="database" xreflabel="database">
<title>Constructing the database</title>

<para>
MMTK uses a database of chemical entities to define the properties of
atoms, molecules, and related objects. This database consists of plain
text files, more precisely short Python programs, whose names are the
names of the object types. This chapter explains how to construct and
manage these files. Note that the standard database already contains
many definitions, in particular for proteins and nucleic acids.
You do not need to read this chapter unless you want to add your
own molecule definitions.
</para>
<para>
MMTK's database does not have to reside in a single place. It can
consist of any number of subdatabases, each of which can be a
directory or a URL. Typically the database consists of at least two
parts: MMTK's standard definitions and a user's personal definitions.
When looking up an object type in the database, MMTK checks the value
of the environment variable <literal>MMTKDATABASE</literal>. The value
of this variable must be a list of subdatabase locations seperated by
white space. If the variable <literal>MMTKDATABASE</literal> is not
defined, MMTK uses a default value that contains the path
".mmtk/Database" in the user's home directory followed by MMTK's
standard database, which resides in the directory
<literal>Database</literal> within the MMTK package directory (on many
Unix systems this is /usr/local/lib/python2.2/site-packages/MMTK).
MMTK checks the subdatabases in the order in which they are mentioned
in <literal>MMTKDATABASE</literal>.
</para>
<para>
Each subdatabase contains directories corresponding to the object
classes, i.e. Atoms (atom definitions), Groups (group definitions),
Molecules (molecule definitions), Complexes (complex definitions),
Proteins (protein definitions), and PDB (Protein Data Bank files).
These directories contain the definition files, whose names may
not contain any upper-case letters. These file names correspond
to the object types, e.g. the call <literal>MMTK.Molecule('Water')</literal>
will cause MMTK to look for the file Molecules/water in the database
(note that the names are converted to lower case).
</para>
<para>
The remaining sections of this chapter explain how the individual
definition files are constructed. Keep in mind that each file is
actually a Python program, so of course standard Python syntax rules
apply.
</para>

<sect1>
<title>Atom definitions</title>
<para>
An atom definition in MMTK describes a chemical element, such as
"hydrogen". This should not be confused with the "atom types" used in
force field descriptions and in some modelling programs. As a
consequence, it is rarely necessary to add atom definitions to MMTK.
</para>
<para>
Atom definition files are short and of essentially identical format.
This is the definition for carbon:
<programlisting role="Python">
name = 'carbon'
symbol = 'C'

mass = [(12, 98.90), (13.003354826, 1.10)]

color = 'black'

vdW_radius = 0.17
</programlisting>
</para>
<para>
The name should be meaningful to users, but is not used by MMTK
itself. The symbol, however, is used to identify chemical elements. It
must be exactly equal to the symbol defined by IUPAC, including
capitalization (e.g. 'Cl' for chlorine). The mass can be either a number
or a list of tuples, as shown above. Each tuple defines an isotope by
its mass and its percentage of occurrence; the percentages must add up
to 100. The color is used for VRML output and must equal one of the
color names defined in the module VRML. The van der Waals radius is used
for the calculation of molecular volumes and surfaces; the values are
taken from [<xref linkend="Article:Bondi1964"/>].
</para>
<para>
An application program can create an isolated atom with
<literal>Atom('c')</literal> or, specifying an initial position, with
<literal>Atom('c', position=Vector(0.,1.,0.))</literal>. The element
name can use any combination of upper and lower case letters, which
are considered equivalent.
</para>
</sect1>
<sect1>
<title>Group definitions</title>
<para>
Group definitions in MMTK exist to facilitate the definition of
molecules by avoiding the frequent repetition of common combinations.
MMTK doesn't give any physical meaning to groups. Groups can contain
atoms and other groups. Their definitions look exactly like molecule
definitions; the only difference between groups and molecules is the way
they are used.
</para>
<para>
This is the definition of a methyl group:
<programlisting role="Python">
name = 'methyl group'

C  = Atom('C')
H1 = Atom('H')
H2 = Atom('H')
H3 = Atom('H')

bonds = [Bond(C, H1), Bond(C, H2), Bond(C, H3)]

pdbmap = [('MTH', {'C': C, 'H1': H1, 'H2': H2, 'H3': H3})]

amber_atom_type = {C: 'CT', H1: 'HC', H2: 'HC', H3: 'HC'}
amber_charge = {C: 0., H1: 0.1, H2: 0.1, H3: 0.1}
</programlisting>
</para>
<para>
The name should be meaningful to users, but is not used by MMTK
itself. The following lines create the atoms in the group and assign
them to variables. These variables become attributes of whatever
object uses this group; their names can be anything that is a legal
Python name. The list of bonds, however, must be assigned to the
variable "bonds". The bond list is used by force fields and for
visualization.
</para>
<para>
The variable "pdbmap" is used for reading and writing PDB files. Its
value must be a list of tuples, where each tuple defines one PDB
residue. The first element of the tuple is the residue name, which is
used only for output. The second element is a dictionary that maps PDB
atom names to the actual atoms. The pdbmap entry of any object can be
overridden by an entry in a higher-level object. Therefore the entry for
a group is only used for atoms that do not occur in the entry for a
molecule that contains this group.
</para>
<para>
The remaining lines in the definition file contain information specific
to force fields, in this case the Amber force field. The dictionary
"amber_atom_type" defines the atom type for each atom; the dictionary
"amber_charge" defines the partial charges. As for pdbmap entries, these
definitions can be overridden by higher-level definitions.
</para>
</sect1>
<sect1>
<title>Molecule definitions</title>
<para>
Molecules are typically used directly in application programs, but they
can also be used in the definition of complexes. Molecule definitions
can use atoms and groups.
</para>
<para>
This is the definition of a water molecule:
<programlisting role="Python">
name = 'water'

structure = \
   "  O\n" + \
   " / \\\n" + \
   "H   H\n"

O  = Atom('O')
H1 = Atom('H')
H2 = Atom('H')

bonds = [Bond(O, H1), Bond(O, H2)]

pdbmap = [('HOH', {'O': O, 'H1': H1, 'H2': H2})]
pdb_alternative = {'OH2': 'O'}

amber_atom_type = {O: 'OW', H1: 'HW', H2: 'HW'}
amber_charge = {O: -0.83400, H1: 0.41700, H2: 0.41700}

configurations = {
    'default': ZMatrix([[H1],
			[O,  H1,  0.9572*Ang],
			[H2, O,   0.9572*Ang,  H1,  104.52*deg]])
    }
</programlisting>
</para>
<para>
The name should be meaningful to users, but is not used by MMTK
itself. The structure is optional and not used by MMTK either. The
following lines create the atoms in the group and assign them to
variables. These variables become attributes
of the molecule, i.e. when a water molecule is created in an application
program by <literal>w = Molecule('water')</literal>, then <literal>w.H1</literal>
will refer to its first hydrogen atom. The names of these variables can
be any legal Python names. The list of bonds, however, must be assigned to the
variable "bonds". The bond list is used by force fields and for
visualization.
</para>
<para>
The variable "pdbmap" is used for reading and writing PDB files. Its
value must be a list of tuples, where each tuple defines one PDB
residue. The first element of the tuple is the residue name, which is
used only for output. The second element is a dictionary that maps PDB
atom names to the actual atoms. The pdbmap entry of any object can be
overridden by an entry in a higher-level object, i.e. in the case of a
molecule a complex containing it. The variable "pdb_alternative" allows
to read PDB files that use non-standard names. When a
PDB atom name is not found in the pdbmap, an attempt is made to
translate it to another name using pdb_alternative.
</para>
<para>
The two following lines in the definition file contain information
specific to force fields, in this case the Amber force field. The
dictionary "amber_atom_type" defines the atom type for each atom; the
dictionary "amber_charge" defines the partial charges. As for pdbmap
entries, these definitions can be overridden by higher-level
definitions.
</para>
<para>
The variable "configurations" can be defined to be a dictionary of
configurations for the molecule. During the construction of a molecule,
a configuration can be specified via an optional parameter, e.g. <literal>w
= Molecule('water', configuration='default')</literal>. The names of the
configurations can be arbitrary; only the name "default" has a special
meaning; it is applied by default if no other configuration is specified
when constructing the molecule. If there is no default configuration,
and no other configuration is explicitly specified, then the molecule is
created with undefined atomic positions.
</para>
<para>
There are three ways of describing configurations:
<itemizedlist>
<listitem><para>
By a Z-Matrix:
<programlisting role="Python">
ZMatrix([[H1],
         [O,  H1,  0.9572*Ang],
         [H2, O,   0.9572*Ang,  H1,  104.52*deg]])
</programlisting>

</para></listitem>
<listitem><para>
By Cartesian coordinates:
<programlisting role="Python">
Cartesian({O:  ( 0.004, -0.00518, 0.0),
           H1: (-0.092, -0.00518, 0.0),
           H2: ( 0.028,  0.0875,  0.0)})
</programlisting>

</para></listitem>
<listitem><para>
By a PDB file:
<programlisting role="Python">
PDBFile('water.pdb')
</programlisting>
The PDB file must be in the database subdirectory PDB, unless a full
path name is specified for it.
</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1>
<title>Complex definitions</title>
<para>
Complexes are defined much like molecules, except that they are composed
of molecules and atoms; no groups are allowed, and neither are bonds.
</para>
</sect1>
<sect1>
<title>Protein definitions</title>
<para>
Protein definitions can take many different forms, depending on the
source of input data and the type of information that is to be stored.
For proteins it is particularly useful that database definition files
are Python programs with all their flexibility.
</para>
<para>
The most common way of constructing a protein is from a PDB file. This
is an example for a protein definition:
<programlisting role="Python">
name = 'insulin'

# Read the PDB file.
conf = PDBConfiguration('insulin.pdb')

# Construct the peptide chains.
chains = conf.createPeptideChains()

# Clean up
del conf
</programlisting>
</para>
<para>
The name should be meaningful to users, but is not used by MMTK
itself. The second command reads the sequences of all peptide chains
from a PDB file. Everything which is not a peptide chain is ignored.
The following line constructs a PeptideChain object (a special
molecule) for each chain from the PDB sequence. This involves
constructing positions for any missing hydrogen atoms.
Finally, the temporary data ("conf") is deleted, otherwise
it would remain in memory forever.
</para>
<para>
The net result of a protein definition file is the assignment of a list
of molecules (usually PeptideChain objects) to the variable "chains".
MMTK then constructs a protein object from it. To use the above example,
an application program would use the command <literal>p =
Protein('insulin')</literal>. The construction of the protein involves
one nontrivial (but automatic) step: the construction of disulfide
bridges for pairs of cystein residues whose sulfur atoms have a distance
of less then 2.5 Angstrom.
</para>
</sect1>
</chapter>

<chapter id="parallelization">
<title>Threads and parallelization</title>

<para>
This chapter explains the use of threads by MMTK and MMTK's
parallelization support. This is an advanced topic, and not essential
for the majority MMTK applications. You need to read this chapter only
if you use multiprocessor computers, or if you want to implement
multi-threaded programs that use MMTK.
</para>

<para>
Threads are different execution paths through a program that are
executed in parallel, at least in principle; real parallel execution
is possible only on multiprocessor systems. MMTK makes use of threads
in two ways, which are conceptually unrelated: parallelization of
energy evaluation on shared-memory multiprocessor computers, and
support for multithreaded applications. Thread support is not
available on all machines; you can check if yous system supports
threads by starting a Python interpreter and typing <literal>import
threading</literal>. If this produces an error message, then your
system does not support threads, otherwise it is available in Python
and also in MMTK. If you do not have thread support in Python although
you know that your operating system supports threads, you might have
compiled your Python interpreter without thread support; in that case,
MMTK does not have thread support either.
</para>

<para>
Another approach to parallelization is message passing: several
processors work on a program and communicate via a fast network to
share results. A standard library, called MPI (Message Passing
Interface), has been developped for sharing data by message passing,
and implementations are available for all parallel computers currently
on the market. MMTK contains elementary support for parallelization by
message passing: only the energy evaluation has been paralellized,
using a data-replication strategy, which is simple but not the most
efficient for large systems. MPI support is disabled by default.
Enabling it involves modifying the file Src/Setup.template prior
to compilation of MMTK. Furthermore, an MPI-enabled installation of
ScientificPython is required, and the mpipython executable must
be used instead of the standard Python interpreter.
</para>

<para>
Threads and message passing can be used together to use a cluster of
shared-memory machines most efficiently. However, this requires that
the thread and MPI implementations being used work together; sometimes
there are conflicts, for example due to the use of the same signal in
both libraries. Refer to your system documentation for details.
</para>

<para>
The use of threads for parallelization on shared-memory systems is
very simple: Just set the environment variable
<literal>MMTK_ENERGY_THREADS</literal> to the desired value.  If this
variable is not defined, the default value is 1, i.e. energy
evaluations are performed serially. For choosing an appropriate
value for this environment variable, the following points should
be considered:
<itemizedlist>
<listitem><para>
The number of energy evaluation threads should not be larger than the
number of processors that are fully dedicated to the MMTK application.
A larger number of threads does not lead to wrong results,
but it can increase the total execution time.
</para></listitem>
<listitem><para>
MMTK assumes that all processors are equally fast. If you use a
heteregenous multiprocessor machine, in which the processors have
different speeds, you might find that the total execution time is
larger than without threads.
</para></listitem>
<listitem><para>
The use of threads incurs some computational overhead. For very small
systems, it might be faster not to use threads.
</para></listitem>
<listitem><para>
Not all energy terms necessarily support threads. Of the force field
terms that part of MMTK, only the multipole algorithms for
electrostatic interactions does not support threads, but additional
force fields defined outside MMTK might also be affected. MMTK
automatically evaluates such energy terms with a single thread, such
that there is no risk of getting wrong results. However, you might not
get the performance you expect.
</para></listitem>
<listitem><para>
If second derivatives of the potential energy are requested, energy
evaluation is handled by a single thread. An efficient implementation
of multi-threaded energy evaluation would require a separate copy of
the second-derivative matrix per thread. This approach needs too much
memory for big systems to be feasible. Since second derivatives are
almost exclusively used for normal mode calculations, which need only
a single energy evaluation, multi-thread support is not particularly
important anyway.
</para></listitem>
</itemizedlist>
</para>

<para>
Parallelization via message passing is somewhat more complicated.
In the current MMTK parallelization model, all processors execute
the same program and replicate all tasks, with the important exception
of energy evaluation. Energy terms are divided evenly between the
processors, and at the end the energy and gradient values are shared
by all machines. This is the only step involving network communication.
Like thread-based parallelization, message-passing parallelization
does not support the evaluation of second derivatives.
</para>

<para>
A special problem with message-passing systems is input and output.
The MMTK application must ensure that output files are written by
only one processor, and that all processors correctly access input
files, especially in the case of each processor having its own
disk space. See the example <xref linkend="Example:MPI:md.py"/>
for illustration.
</para>

<para>
Multithreaded applications are applications that use multiple threads
in order to simplify the implementation of certain algorithms, i.e.
not necessarily with the goal of profiting from multiple processors.
If you plan to write a multithreaded application that uses MMTK,
you should first make sure you understand threading support in
Python. In particular, you should keep in mind that the global
interpreter lock prevents the effective use of multiple processors
by Python code; only one thread at a time can execute interpreted
Python code. C code called from Python can permit other threads
to execute simultaneously; MMTK does this for energy evaluation,
molecular dynamics integration, energy minimization, and normal
mode calculation.
</para>

<para>
A general problem in multithreaded applications is access to resources
that are shared among the threads. In MMTK applications, the most
important shared resource is the description of the chemical systems,
i.e. universe objects and their contents. Chaos would result if two
threads tried to modify the state of a universe simultaneously, or
even if one thread uses information that is simultaneously being
modified by another thread. Synchronization is therefore a critical
part of multithreaded application. MMTK provides two synchronization
aids, both of which described in the documentation of the class <xref
linkend="Class:MMTK.Universe.Universe"/>: the configuration change
lock (methods <literal>acquireConfigurationChangeLock</literal> and
<literal>releaseConfigurationChangeLock</literal>), and the universe
state lock (methods <literal>acquireReadStateChangeLock</literal>,
<literal>releaseReadStateChangeLock</literal>,
<literal>acquireWriteStateChangeLock</literal>, and
<literal>releaseWriteStateChangeLock</literal>). Only a few common
universe operations manipulate the universe state lock in order to
avoid conflicts with other threads; these methods are marked as
thread-safe in the description. All other operations should only be
used inside a code section that is protected by the appropriate
manipulation of the state lock. The configuration change lock is less
critical; it is used only by the molecular dynamics and energy
minimization algorithms in MMTK.
</para>

</chapter>

<!-- &Modules; -->

<!-- Generated by pythondoc.DocBookFormatter 0.6 -->

<chapter id="module_reference" xreflabel="Module Reference">
<title>Reference for Module MMTK</title>

<para>MMTK is the base module of the Molecular Modelling Toolkit.
It contains the most common objects and all submodules. As a convenience
to the user, it also imports some commonly used objects from other
libraries:</para>
<itemizedlist>
<listitem><para>
<literal role="Python">Vector</literal> from <literal role="Python">Scientific.Geometry</literal>
</para></listitem>
<listitem><para>
<literal role="Python">Translation</literal> and <literal role="Python">Rotation</literal> from <literal role="Python">Scientific.Geometry.Transformation</literal>
</para></listitem>
<listitem><para>
<literal role="Python">copy</literal> and <literal role="Python">deepcopy</literal> from <literal role="Python">copy</literal>
</para></listitem>
<listitem><para>
<literal role="Python">stdin</literal>, <literal role="Python">stdout</literal>, and <literal role="Python">stderr</literal> from <literal role="Python">sys</literal>
</para></listitem>
</itemizedlist>
<classdescription role="Python" id="Class:MMTK.ParticleScalar" xreflabel="MMTK.ParticleScalar">
<classdef><class>ParticleScalar</class><classinfo>Scalar property defined for each particle</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ParticleProperties.ParticleProperty"/>.</para>
<para>ParticleScalar objects can be added to each other and
multiplied with scalars.
</para>
<methoddescription><methoddef><method>maximum</method></methoddef>
<void/><para>Returns the highest value for any particle.</para>
</methoddescription>
<methoddescription><methoddef><method>minimum</method></methoddef>
<void/><para>Returns the smallest value for any particle.</para>
</methoddescription>
<methoddescription><methoddef><method>applyFunction</method></methoddef>
<paramdef><parameter>function</parameter></paramdef>
<para>Applies <parameter>function</parameter> to each value and returns the result
as a new ParticleScalar object.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ParticleVector" xreflabel="MMTK.ParticleVector">
<classdef><class>ParticleVector</class><classinfo>Vector property defined for each particle</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ParticleProperties.ParticleProperty"/>.</para>
<para>ParticleVector objects can be added to each other and
multiplied with scalars or <xref linkend="Class:MMTK.ParticleScalar"/> objects; all
of these operations result in another ParticleVector
object. Multiplication with a vector or another ParticleVector object
yields a <xref linkend="Class:MMTK.ParticleScalar"/> object containing the dot products
for each particle. Multiplications that treat ParticleVectors
as vectors in a 3N-dimensional space are implemented as methods.
</para>
<methoddescription><methoddef><method>length</method></methoddef>
<void/><para>Returns a ParticleScalar containing the length of the vector
for each particle.</para>
</methoddescription>
<methoddescription><methoddef><method>norm</method></methoddef>
<void/><para>Returns the norm of the ParticleVector seen as a
3N-dimensional vector.</para>
</methoddescription>
<methoddescription><methoddef><method>dotProduct</method></methoddef>
<paramdef><parameter>other</parameter></paramdef>
<para>Returns the dot product with <parameter>other</parameter> (a ParticleVector)
treating both operands as 3N-dimensional vectors.</para>
</methoddescription>
<methoddescription><methoddef><method>massWeightedDotProduct</method></methoddef>
<paramdef><parameter>other</parameter></paramdef>
<para>Returns the mass-weighted dot product with <parameter>other</parameter>
(a ParticleVector object) treating both operands as
3N-dimensional vectors.</para>
</methoddescription>
<methoddescription><methoddef><method>dyadicProduct</method></methoddef>
<paramdef><parameter>other</parameter></paramdef>
<para>Returns a <xref linkend="Class:MMTK.ParticleTensor"/> object representing the dyadic
product with <parameter>other</parameter> (a ParticleVector).</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Configuration" xreflabel="MMTK.Configuration">
<classdef><class>Configuration</class><classinfo>Configuration of a universe</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ParticleVector"/>.</para>
<para>Its instances represent a configuration of a universe, consisting
of positions for all atoms (like in a ParticleVector) plus
the geometry of the universe itself, e.g. the cell shape for
periodic universes.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ParticleTensor" xreflabel="MMTK.ParticleTensor">
<classdef><class>ParticleTensor</class><classinfo>Rank-2 tensor property defined for each particle</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ParticleProperties.ParticleProperty"/>.</para>
<para>ParticleTensor objects can be added to each other and
multiplied with scalars or <xref linkend="Class:MMTK.ParticleScalar"/> objects; all
of these operations result in another ParticleTensor
object.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Atom" xreflabel="MMTK.Atom">
<classdef><class>Atom</class><classinfo>Atom</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/>.</para>
<para>Constructor: Atom(<parameter>element</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>element</parameter></term>
<listitem><para>
a string (not case sensitive) specifying the chemical element</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:<itemizedlist>
<listitem><para>
position: the atom position (a vector)
</para></listitem>
<listitem><para>
name: the atom name (a string)
</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>setPosition</method></methoddef>
<paramdef><parameter>position</parameter></paramdef>
<para>Changes the position to <parameter>position</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>position</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the position in configuration <parameter>conf</parameter>. If <parameter>conf</parameter> is
<literal role="Python">None</literal>, use the current configuration. If the atom has not been
assigned a position, the return value is <literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>setMass</method></methoddef>
<paramdef><parameter>mass</parameter></paramdef>
<para>Set the atom mass to <parameter>mass</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>bondedTo</method></methoddef>
<void/><para>Returns a list of all atoms to which a chemical bond exists.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Collection" xreflabel="MMTK.Collection">
<classdef><class>Collection</class><classinfo>Collection of chemical objects</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>
and <xref linkend="Class:MMTK.Visualization.Viewable"/>.</para>
<para>Collections permit the grouping of arbitrary chemical objects
(atoms, molecules, etc.) into one object for the purpose of analysis
or manipulation.</para>
<para>Constructor: Collection(<parameter>objects</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>objects</parameter></term>
<listitem><para>
a chemical object or a sequence of chemical objects that
             define the initial content of the collection.</para></listitem></varlistentry>
</variablelist></para>
<para>Collections permit length inquiry, item extraction by indexing,
and iteration, like any Python sequence object. Two collections
can be added to yield a collection that contains the combined
elements.
</para>
<methoddescription><methoddef><method>addObject</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<para>Adds <parameter>object</parameter> to the collection. If <parameter>object</parameter> is another collection
or a list, all of its elements are added.</para>
</methoddescription>
<methoddescription><methoddef><method>removeObject</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<para>Removes <parameter>object</parameter> from the collection. If <parameter>object</parameter> is a collection
or a list, each of its elements is removed. The object to be removed
must be an element of the collection.</para>
</methoddescription>
<methoddescription><methoddef><method>selectShell</method></methoddef>
<paramdef><parameter>point</parameter></paramdef>
<paramdef><parameter>r1</parameter></paramdef>
<paramdef><parameter>r2</parameter><defaultvalue>0.0</defaultvalue></paramdef>
<para>Return a collection of all elements whose
distance from <parameter>point</parameter> is between <parameter>r1</parameter> and <parameter>r2</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>selectBox</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<para>Return a collection of all elements that lie
within a box whose corners are given by <parameter>p1</parameter> and <parameter>p2</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>objectList</method></methoddef>
<paramdef><parameter>klass</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a list of all objects in the collection.
If <parameter>klass</parameter> is not None, only objects whose class is equal
to <parameter>klass</parameter> are returned.</para>
</methoddescription>
<methoddescription><methoddef><method>atomList</method></methoddef>
<void/><para>Returns a list containing all atoms of all objects in the collection.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfAtoms</method></methoddef>
<void/><para>Returns the total number of atoms in the objects of the collection.</para>
</methoddescription>
<methoddescription><methoddef><method>universe</method></methoddef>
<void/><para>Returns the universe of which the objects in the collection
are part. If no such universe exists, the return value is <literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>map</method></methoddef>
<paramdef><parameter>function</parameter></paramdef>
<para>Applies <parameter>function</parameter> to all objects in the collection and
returns the list of the results. If the results are chemical
objects, a Collection object is returned instead of a list.</para>
</methoddescription>
<methoddescription><methoddef><method>distanceConstraintList</method></methoddef>
<void/><para>Returns the list of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfDistanceConstraints</method></methoddef>
<void/><para>Returns the number of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>setBondConstraints</method></methoddef>
<paramdef><parameter>universe</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Sets distance constraints for all bonds.</para>
</methoddescription>
<methoddescription><methoddef><method>removeDistanceConstraints</method></methoddef>
<paramdef><parameter>universe</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Removes all distance constraints.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Molecule" xreflabel="MMTK.Molecule">
<classdef><class>Molecule</class><classinfo>Molecule</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/>.</para>
<para>Molecules consist of atoms and groups linked by bonds.</para>
<para>Constructor: Molecule(<parameter>species</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>species</parameter></term>
<listitem><para>
a string (not case sensitive) that specifies the molecule
             name in the chemical database</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:<itemizedlist>
<listitem><para>
position: the center-of-mass position (a vector)
</para></listitem>
<listitem><para>
configuration: the name of a configuration listed in the database
                   definition of the molecule, which is used to
                   initialize the atom positions. If no configuration
                   is specified, the configuration named "default" will
                   be used, if it exists. Otherwise the atom positions
                   are undefined.
</para></listitem>
<listitem><para>
name: the atom name (a string)
</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>findHydrogenPositions</method></methoddef>
<void/><para>Find reasonable positions for hydrogen atoms that have no
position assigned.</para>
<para>This method uses a heuristic approach based on standard geometry
data. It was developed for proteins and DNA and may not give
good results for other molecules. It raises an exception
if presented with a topology it cannot handle.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PartitionedCollection" xreflabel="MMTK.PartitionedCollection">
<classdef><class>PartitionedCollection</class><classinfo>Collection with cubic partitions</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Collection"/>.</para>
<para>A PartitionedCollection differs from a plain Collection by
sorting its elements into small cubic cells. This makes adding
objects slower, but geometrical operations like 
selectShell become much faster for a large number of
objects.</para>
<para>Constructor: PartitionedCollection(<parameter>partition_size</parameter>, <parameter>objects</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>partition_size</parameter></term>
<listitem><para>
the edge length of the cubic cells</para></listitem></varlistentry>
<varlistentry><term><parameter>objects</parameter></term>
<listitem><para>
a chemical object or a sequence of chemical objects that
             define the initial content of the collection.
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>partitions</method></methoddef>
<void/><para>Returns a list of cubic partitions. Each partition is specified
by a tuple containing two vectors (describing the diagonally
opposite corners) and the list of objects in the partition.</para>
</methoddescription>
<methoddescription><methoddef><method>pairsWithinCutoff</method></methoddef>
<paramdef><parameter>cutoff</parameter></paramdef>
<para>Returns a list containing all pairs of objects in the
collection whose center-of-mass distance is less than <parameter>cutoff</parameter>.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PartitionedAtomCollection" xreflabel="MMTK.PartitionedAtomCollection">
<classdef><class>PartitionedAtomCollection</class><classinfo>Partitioned collection of atoms</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.PartitionedCollection"/>.</para>
<para>PartitionedAtomCollection objects behave like PartitionedCollection
atoms, except that they store only atoms. When a composite chemical
object is added, its atoms are stored instead.</para>
<para>Constructor: PartitionedAtomCollection(<parameter>partition_size</parameter>, <parameter>objects</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>partition_size</parameter></term>
<listitem><para>
the edge length of the cubic cells</para></listitem></varlistentry>
<varlistentry><term><parameter>objects</parameter></term>
<listitem><para>
a chemical object or a sequence of chemical objects that
             define the initial content of the collection.
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.InfiniteUniverse" xreflabel="MMTK.InfiniteUniverse">
<classdef><class>InfiniteUniverse</class><classinfo>Infinite (unbounded and nonperiodic) universe.</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Universe.Universe"/>.</para>
<para>Constructor: InfiniteUniverse(<parameter>forcefield</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>forcefield</parameter></term>
<listitem><para>
a force field object, or <literal role="Python">None</literal> for no force field
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Complex" xreflabel="MMTK.Complex">
<classdef><class>Complex</class><classinfo>Complex</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/>.</para>
<para>A complex is an assembly of molecules that are not connected by
chemical bonds.</para>
<para>Constructor: Complex(<parameter>species</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>species</parameter></term>
<listitem><para>
a string (not case sensitive) that specifies the complex
             name in the chemical database</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:<itemizedlist>
<listitem><para>
position: the center-of-mass position (a vector)
</para></listitem>
<listitem><para>
configuration: the name of a configuration listed in the database
                   definition of the complex
</para></listitem>
<listitem><para>
name: the atom name (a string)
</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.AtomCluster" xreflabel="MMTK.AtomCluster">
<classdef><class>AtomCluster</class><classinfo>An agglomeration of atoms</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/>.</para>
<para>An atom cluster acts like a molecule without any bonds or atom
properties. It can be used to represent a group of atoms that
are known to form a chemical unit but whose chemical properties
are not sufficiently known to define a molecule.</para>
<para>Constructor: AtomCluster(<parameter>atoms</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>atoms</parameter></term>
<listitem><para>
a list of atom objects</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:<itemizedlist>
<listitem><para>
position: the center-of-mass position (a vector)
</para></listitem>
<listitem><para>
name: the atom name (a string)
</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.OrthorhombicPeriodicUniverse" xreflabel="MMTK.OrthorhombicPeriodicUniverse">
<classdef><class>OrthorhombicPeriodicUniverse</class><classinfo>Periodic universe with orthorhombic elementary cell.</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Universe.Universe"/>.</para>
<para>Constructor: OrthorhombicPeriodicUniverse(<parameter>shape</parameter>, <parameter>forcefield</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>shape</parameter></term>
<listitem><para>
a sequence of length three specifying the edge
           lengths along the x, y, and z directions</para></listitem></varlistentry>
<varlistentry><term><parameter>forcefield</parameter></term>
<listitem><para>
a force field object, or <literal role="Python">None</literal> for no force field
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>scaleSize</method></methoddef>
<paramdef><parameter>factor</parameter></paramdef>
<para>Multiplies all edge lengths by <parameter>factor</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>setVolume</method></methoddef>
<paramdef><parameter>volume</parameter></paramdef>
<para>Multiplies all edge lengths by the same factor such that the cell
volume becomes <parameter>volume</parameter>.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.CubicPeriodicUniverse" xreflabel="MMTK.CubicPeriodicUniverse">
<classdef><class>CubicPeriodicUniverse</class><classinfo>Periodic universe with cubic elementary cell.</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Universe.Universe"/>.</para>
<para><variablelist>
<varlistentry><term><parameter>shape</parameter></term>
<listitem><para>
a number specifying the edge
           length along the x, y, and z directions</para></listitem></varlistentry>
<varlistentry><term><parameter>forcefield</parameter></term>
<listitem><para>
a force field object, or <literal role="Python">None</literal> for no force field
Constructor: CubicPeriodicUniverse(<parameter>shape</parameter>, <parameter>forcefield</parameter>=None)
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<sect1>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.save" xreflabel="MMTK.save" role="Python"><funcprototype><funcdef><function>save</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>filename</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Writes <parameter>object</parameter> to a newly created file with the name <parameter>filename</parameter>,
for later retrieval by <literal role="Python">load()</literal>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.load" xreflabel="MMTK.load" role="Python"><funcprototype><funcdef><function>load</function></funcdef>
<paramdef><parameter>filename</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Loads the file indicated by <parameter>filename</parameter>, which must have been produced
by <literal role="Python">save()</literal>, and returns the object stored in that file.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="Module:MMTK.Biopolymers" xreflabel="MMTK.Biopolymers">
<title>Module MMTK.Biopolymers</title>

<classdescription role="Python" id="Class:MMTK.Biopolymers.ResidueChain" xreflabel="MMTK.Biopolymers.ResidueChain">
<classdef><class>ResidueChain</class><classinfo>A chain of residues</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Molecule"/>.</para>
<para>This is an <xref linkend="Glossary:AbstractBaseClass"/> that defines operations
common to peptide chains and nucleic acid chains.
</para>
<methoddescription><methoddef><method>residuesOfType</method></methoddef>
<paramdef><parameter>*types</parameter></paramdef>
<para>Returns a collection that contains all residues whose type
(residue code) is contained in <parameter>types</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>residues</method></methoddef>
<void/><para>Returns a collection containing all residues.</para>
</methoddescription>
<methoddescription><methoddef><method>sequence</method></methoddef>
<void/><para>Returns the sequence as a list of residue code.</para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Biopolymers.defineAminoAcidResidue" xreflabel="MMTK.Biopolymers.defineAminoAcidResidue" role="Python"><funcprototype><funcdef><function>defineAminoAcidResidue</function></funcdef>
<paramdef><parameter>full_name</parameter></paramdef>
<paramdef><parameter>code3</parameter></paramdef>
<paramdef><parameter>code1</parameter><defaultvalue>None</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Adds a non-standard amino acid residue to the residue table.
The definition of the residue must be accesible by <parameter>full_name</parameter>
in the chemical database. The three-letter code is specified
by <parameter>code3</parameter>, and an optional one-letter code can be specified by
<parameter>code1</parameter>.</para>
<para>Once added to the residue table, the new residue can be used
like any of the standard residues in the creation of peptide chains.
</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Biopolymers.defineNucleicAcidResidue" xreflabel="MMTK.Biopolymers.defineNucleicAcidResidue" role="Python"><funcprototype><funcdef><function>defineNucleicAcidResidue</function></funcdef>
<paramdef><parameter>full_name</parameter></paramdef>
<paramdef><parameter>code</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Adds a non-standard nucleic acid residue to the residue table.
The definition of the residue must be accesible by <parameter>full_name</parameter>
in the chemical database. The residue code is specified
by <parameter>code</parameter>.</para>
<para>Once added to the residue table, the new residue can be used
like any of the standard residues in the creation of nucleotide
chains.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.ChargeFit" xreflabel="MMTK.ChargeFit">
<title>Module MMTK.ChargeFit</title>

<para>This module implements a numerically stable method (based on
Singular Value Decomposition) to fit point charges to values of an
electrostatic potential surface. Two types of constraints are
avaiable: a constraint on the total charge of the system or a subset
of the system, and constraints that force the charges of several atoms
to be equal. There is also a utility function that selects suitable
evaluation points for the electrostatic potential surface. For the
potential evaluation itself, some quantum chemistry program is needed.</para>
<para>The charge fitting method is described in [<xref linkend="Article:Hinsen1997"/>].
See also <xref linkend="Example:Miscellaneous:charge_fit.py"/>.
</para>
<classdescription role="Python" id="Class:MMTK.ChargeFit.ChargeFit" xreflabel="MMTK.ChargeFit.ChargeFit">
<classdef><class>ChargeFit</class><classinfo>Fit of point charges to an electrostatic potential surface</classinfo></classdef>
<para>Constructor: ChargeFit(<parameter>system</parameter>, <parameter>points</parameter>, <parameter>constraints</parameter>=None)</para>
<para><variablelist>
<varlistentry><term><parameter>system</parameter></term>
<listitem><para>
any chemical object, usually a molecule</para></listitem></varlistentry>
<varlistentry><term><parameter>points</parameter></term>
<listitem><para>
a list of point/potential pairs (a vector for the
            evaluation point, a number for the potential),
            or a dictionary whose keys are Configuration objects
            and whose values are lists of point/potential pairs.
            The latter case permits combined fits for several
            conformations of the system.</para></listitem></varlistentry>
<varlistentry><term><parameter>constraints</parameter></term>
<listitem><para>
a list of constraint objects (TotalChargeConstraint
                 and/or EqualityConstraint objects). If the constraints
                 are inconsistent, a warning is printed and the result
                 will satisfy the constraints only in a least-squares
                 sense.</para></listitem></varlistentry>
</variablelist></para>
<para>A ChargeFit object acts like a dictionary that stores the fitted charge
value for each atom in the system.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ChargeFit.TotalChargeConstraint" xreflabel="MMTK.ChargeFit.TotalChargeConstraint">
<classdef><class>TotalChargeConstraint</class><classinfo>Constraint on the total system charge</classinfo></classdef>
<para>To be used with <xref linkend="Class:MMTK.ChargeFit.ChargeFit"/>.</para>
<para>Constructor:  TotalChargeConstraint(<parameter>object</parameter>, <parameter>charge</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>object</parameter></term>
<listitem><para>
any object whose total charge is to be constrained</para></listitem></varlistentry>
<varlistentry><term><parameter>charge</parameter></term>
<listitem><para>
the total charge value
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ChargeFit.EqualityConstraint" xreflabel="MMTK.ChargeFit.EqualityConstraint">
<classdef><class>EqualityConstraint</class><classinfo>Constraint forcing two charges to be equal</classinfo></classdef>
<para>To be used with <xref linkend="Class:MMTK.ChargeFit.ChargeFit"/>.</para>
<para>Constructor:  EqualityConstraint(<parameter>atom1</parameter>, <parameter>atom2</parameter>), where
<parameter>atom1</parameter> and <parameter>atom2</parameter> are the two atoms whose charges should be
equal.</para>
<para>Any atom may occur in more than one EqualityConstraint object,
in order to keep the charges of more than two atoms equal.
</para>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.ChargeFit.evaluationPoints" xreflabel="MMTK.ChargeFit.evaluationPoints" role="Python"><funcprototype><funcdef><function>evaluationPoints</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>n</parameter></paramdef>
<paramdef><parameter>smallest</parameter><defaultvalue>0.29999999999999999</defaultvalue></paramdef>
<paramdef><parameter>largest</parameter><defaultvalue>0.5</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a list of <parameter>n</parameter> points suitable for the evaluation of
the electrostatic potential around <parameter>object</parameter>. The points are chosen
at random and uniformly in a shell around the object such that
no point has a distance larger than <parameter>largest</parameter> from any atom or
smaller than <parameter>smallest</parameter> from any non-hydrogen atom.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.ChemicalObjects" xreflabel="MMTK.ChemicalObjects">
<title>Module MMTK.ChemicalObjects</title>

<classdescription role="Python" id="Class:MMTK.ChemicalObjects.ChemicalObject" xreflabel="MMTK.ChemicalObjects.ChemicalObject">
<classdef><class>ChemicalObject</class><classinfo>General chemical object</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>
and <xref linkend="Class:MMTK.Visualization.Viewable"/>.</para>
<para>This is an Glossary:abstract-base-class that implements methods which
are applicable to any chemical object (atom, molecule, etc.).
</para>
<methoddescription><methoddef><method>topLevelChemicalObject</method></methoddef>
<void/><para>Returns the highest-level chemical object of which
the current object is a part.</para>
</methoddescription>
<methoddescription><methoddef><method>universe</method></methoddef>
<void/><para>Returns the universe to which the object belongs.</para>
</methoddescription>
<methoddescription><methoddef><method>bondedUnits</method></methoddef>
<void/><para>Returns a list containing the subobjects which can
contain bonds. There are no bonds between any of the
subobjects in the list.</para>
</methoddescription>
<methoddescription><methoddef><method>fullName</method></methoddef>
<void/><para>Returns the full name of the object. The full name
consists of the proper name of the object preceded by
the full name of its parent separated by a dot.</para>
</methoddescription>
<methoddescription><methoddef><method>distanceConstraintList</method></methoddef>
<void/><para>Returns the list of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfDistanceConstraints</method></methoddef>
<void/><para>Returns the number of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>setBondConstraints</method></methoddef>
<paramdef><parameter>universe</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Sets distance constraints for all bonds.</para>
</methoddescription>
<methoddescription><methoddef><method>removeDistanceConstraints</method></methoddef>
<paramdef><parameter>universe</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Removes all distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>setRigidBodyConstraints</method></methoddef>
<paramdef><parameter>universe</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Sets distance constraints that make the object fully rigid.</para>
</methoddescription>
<methoddescription><methoddef><method>getAtomProperty</method></methoddef>
<paramdef><parameter>atom</parameter></paramdef>
<paramdef><parameter>property</parameter></paramdef>
<para>Returns the value of the specified <parameter>property</parameter> for the
given <parameter>atom</parameter> from the chemical database.</para>
<para>Note: the property is first looked up in the database entry
for the object on which the method is called. If the lookup
fails, the complete hierarchy from the atom to the top-level
object is constructed and traversed starting from the top-level
object until the property is found. This permits database entries
for higher-level objects to override property definitions in
its constituents.</para>
<para>At the atom level, the property is retrieved from an attribute
with the same name. This means that properties at the atom
level can be defined both in the chemical database and for
each atom individually by assignment to the attribute.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ChemicalObjects.CompositeChemicalObject" xreflabel="MMTK.ChemicalObjects.CompositeChemicalObject">
<classdef><class>CompositeChemicalObject</class><classinfo>Chemical object with subobjects</classinfo></classdef>
<para>This is an Glossary:abstract-base-class that implements methods
which can be used with any composite chemical object,
i.e. any chemical object that is not an atom.
</para>
<methoddescription><methoddef><method>atomList</method></methoddef>
<void/><para>Returns a list containing all atoms in the object.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ChemicalObjects.Group" xreflabel="MMTK.ChemicalObjects.Group">
<classdef><class>Group</class><classinfo>Group of bonded atoms</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/>.</para>
<para>Groups can contain atoms and other groups, and link them by chemical
bonds. They are used to represent functional groups or any other
part of a molecule that has a well-defined identity.</para>
<para>Groups cannot be created in application programs, but only in
database definitions for molecules.</para>
<para>Constructor: Group(<parameter>species</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>species</parameter></term>
<listitem><para>
a string (not case sensitive) that specifies the group
             name in the chemical database</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:<itemizedlist>
<listitem><para>
position: the center-of-mass position (a vector)
</para></listitem>
<listitem><para>
name: the atom name (a string)
</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.ChemicalObjects.isChemicalObject" xreflabel="MMTK.ChemicalObjects.isChemicalObject" role="Python"><funcprototype><funcdef><function>isChemicalObject</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>object</parameter> is a chemical object.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Collection" xreflabel="MMTK.Collection">
<title>Module MMTK.Collection</title>

<classdescription role="Python" id="Class:MMTK.Collection.GroupOfAtoms" xreflabel="MMTK.Collection.GroupOfAtoms">
<classdef><class>GroupOfAtoms</class><classinfo>Anything that consists of atoms</classinfo></classdef>
<para>This class is a <xref linkend="Glossary:MixInClass"/> that defines a large set
of operations which are common to all objects that consist of
atoms, i.e. any subset of a chemical system. Examples are
atoms, molecules, collections, or universes.
</para>
<methoddescription><methoddef><method>numberOfAtoms</method></methoddef>
<void/><para>Returns the number of atoms.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfPoints</method></methoddef>
<void/><para>Returns the number of geometrical points that define the
object. It is currently always equal to the number of atoms,
but could be different e.g. for quantum systems, in which
each atom is described by a wave function or a path integral.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfFixedAtoms</method></methoddef>
<void/><para>Returns the number of atoms that are fixed, i.e. cannot move.</para>
</methoddescription>
<methoddescription><methoddef><method>degreesOfFreedom</method></methoddef>
<void/><para>Returns the number of mechanical degrees of freedom.</para>
</methoddescription>
<methoddescription><methoddef><method>atomCollection</method></methoddef>
<void/><para>Returns a collection containing all atoms in the object.</para>
</methoddescription>
<methoddescription><methoddef><method>atomsWithDefinedPositions</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a collection of all atoms that have a definite position.</para>
</methoddescription>
<methoddescription><methoddef><method>mass</method></methoddef>
<void/><para>Returns the total mass.</para>
</methoddescription>
<methoddescription><methoddef><method>centerOfMass</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the center of mass.</para>
</methoddescription>
<methoddescription><methoddef><method>centerAndMomentOfInertia</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the center of mass and the moment of inertia tensor.</para>
</methoddescription>
<methoddescription><methoddef><method>rotationalConstants</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a sorted array of rotational constants A, B, C
in internal units.</para>
</methoddescription>
<methoddescription><methoddef><method>boundingBox</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns two opposite corners of a bounding box around the
object. The bounding box is the smallest rectangular bounding box
with edges parallel to the coordinate axes.</para>
</methoddescription>
<methoddescription><methoddef><method>boundingSphere</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a sphere that contains all atoms in the object.
This is <emphasis>not</emphasis> the minimal bounding sphere, just <emphasis>some</emphasis>
bounding sphere.</para>
</methoddescription>
<methoddescription><methoddef><method>rmsDifference</method></methoddef>
<paramdef><parameter>conf1</parameter></paramdef>
<paramdef><parameter>conf2</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the RMS (root-mean-square) difference between the
conformations of the object in two universe configurations, <parameter>conf1</parameter>
and <parameter>conf2</parameter> (the latter defaults to the current configuration).</para>
</methoddescription>
<methoddescription><methoddef><method>findTransformation</method></methoddef>
<paramdef><parameter>conf1</parameter></paramdef>
<paramdef><parameter>conf2</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the linear transformation that, when applied to
the object in configuration <parameter>conf1</parameter>, minimizes the RMS distance
to the conformation in <parameter>conf2</parameter>, and the minimal RMS distance.
If <parameter>conf2</parameter> is <literal role="Python">None</literal>, returns the transformation from the
current configuration to <parameter>conf1</parameter> and the associated RMS distance.
The algorithm is described in [<xref linkend="Article:Kneller1990"/>].</para>
</methoddescription>
<methoddescription><methoddef><method>translateBy</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Translates the object by the displacement <parameter>vector</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>translateTo</method></methoddef>
<paramdef><parameter>position</parameter></paramdef>
<para>Translates the object such that its center of mass is at <parameter>position</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>normalizeConfiguration</method></methoddef>
<paramdef><parameter>repr</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Applies a linear transformation such that the coordinate
origin becomes the center of mass of the object and its
principal axes of inertia are parallel to the three coordinate
axes.</para>
<para>A specific representation can be chosen by setting <parameter>repr</parameter> to
  Ir    : x y z &lt;--&gt; b c a
  IIr   : x y z &lt;--&gt; c a b
  IIIr  : x y z &lt;--&gt; a b c
  Il    : x y z &lt;--&gt; c b a
  IIl   : x y z &lt;--&gt; a c b
  IIIl  : x y z &lt;--&gt; b a c
</para>
</methoddescription>
<methoddescription><methoddef><method>applyTransformation</method></methoddef>
<paramdef><parameter>t</parameter></paramdef>
<para>Applies the transformation <parameter>t</parameter> to the object.</para>
</methoddescription>
<methoddescription><methoddef><method>displacementUnderTransformation</method></methoddef>
<paramdef><parameter>t</parameter></paramdef>
<para>Returns the displacement vectors (in a ParticleVector)
for the atoms in the object that correspond to the
transformation <parameter>t</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>rotateAroundCenter</method></methoddef>
<paramdef><parameter>axis_direction</parameter></paramdef>
<paramdef><parameter>angle</parameter></paramdef>
<para>Rotates the object by the given <parameter>angle</parameter> around an axis
that passes through its center of mass and has the given
<parameter>direction</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>rotateAroundOrigin</method></methoddef>
<paramdef><parameter>axis</parameter></paramdef>
<paramdef><parameter>angle</parameter></paramdef>
<para>Rotates the object by the given <parameter>angle</parameter> around an axis
that passes through the coordinate origin and has the given
<parameter>direction</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>rotateAroundAxis</method></methoddef>
<paramdef><parameter>point1</parameter></paramdef>
<paramdef><parameter>point2</parameter></paramdef>
<paramdef><parameter>angle</parameter></paramdef>
<para>Rotates the object by the given <parameter>angle</parameter> around the axis
that passes through <parameter>point1</parameter> and <parameter>point2</parameter></para>
</methoddescription>
<methoddescription><methoddef><method>writeToFile</method></methoddef>
<paramdef><parameter>filename</parameter></paramdef>
<paramdef><parameter>configuration</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>format</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Writes a representation of the object in the given
<parameter>configuration</parameter> to the file identified by <parameter>filename</parameter>.
The <parameter>format</parameter> can be either "pdb" or "vrml"; if no format is
specified, it is deduced from the filename. An optional subformat
specification can be added to the format name, separated
by a dot. The subformats of "pdb" are defined by the
module <literal role="Python">Scientific.IO.PDB</literal>, the subformats of "vrml" are
"wireframe" (the default, yielding a wireframe representation),
"ball_and_stick" (yielding a ball-and-stick representation),
"highlight" (like wireframe, but with a small sphere for
all atoms that have an attribute "highlight" with a non-zero value),
and "charge" (wireframe plus small spheres for the atoms with colors
from a red-to-green color scale to indicate the charge).
</para>
</methoddescription>
<methoddescription><methoddef><method>view</method></methoddef>
<paramdef><parameter>configuration</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>format</parameter><defaultvalue>'pdb'</defaultvalue></paramdef>
<para>Starts an external viewer for the object in the given
<parameter>configuration</parameter>. The optional parameter <parameter>format</parameter> indicates
which format (and hence which viewer) should be used;
the formats are "pdb" and "vrml". An optional subformat
specification can be added to the format name, separated
by a dot. The subformats of "pdb" are defined by the
module <literal role="Python">Scientific.IO.PDB</literal>, the subformats of "vrml" are
"wireframe" (the default, yielding a wireframe representation),
"ball_and_stick" (yielding a ball-and-stick representation),
"highlight" (like wireframe, but with a small sphere for
all atoms that have an attribute "highlight" with a non-zero value),
and "charge" (wireframe plus small spheres for the atoms with colors
from a red-to-green color scale to indicate the charge).</para>
</methoddescription>
<methoddescription><methoddef><method>kineticEnergy</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the kinetic energy.</para>
</methoddescription>
<methoddescription><methoddef><method>temperature</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the temperature.</para>
</methoddescription>
<methoddescription><methoddef><method>momentum</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the momentum.</para>
</methoddescription>
<methoddescription><methoddef><method>angularMomentum</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the angular momentum.</para>
</methoddescription>
<methoddescription><methoddef><method>angularVelocity</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the angular velocity.</para>
</methoddescription>
<methoddescription><methoddef><method>universe</method></methoddef>
<void/><para>Returns the universe of which the object is part. For an
object that is not part of a universe, the result is <literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>charge</method></methoddef>
<void/><para>Returns the total charge of the object. This is defined only
for objects that are part of a universe with a force field that
defines charges.</para>
</methoddescription>
<methoddescription><methoddef><method>dipole</method></methoddef>
<paramdef><parameter>reference</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the total dipole moment of the object. This is defined only
for objects that are part of a universe with a force field that
defines charges.</para>
</methoddescription>
<methoddescription><methoddef><method>booleanMask</method></methoddef>
<void/><para>Returns a ParticleScalar object that contains a value of 1
for each atom that is in the object and a value of 0 for all
other atoms in the universe.</para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Collection.isCollection" xreflabel="MMTK.Collection.isCollection" role="Python"><funcprototype><funcdef><function>isCollection</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Return 1 if <parameter>object</parameter> is a Collection.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.DCD" xreflabel="MMTK.DCD">
<title>Module MMTK.DCD</title>

<classdescription role="Python" id="Class:MMTK.DCD.DCDReader" xreflabel="MMTK.DCD.DCDReader">
<classdef><class>DCDReader</class><classinfo>Reader for DCD trajectories (CHARMM/X-Plor)</classinfo></classdef>
<para>A DCDReader reads a DCD trajectory and "plays back" the
data as if it were generated directly by an integrator.
The universe for which the DCD file is read must be
perfectly compatible with the data in the file, including
an identical internal atom numbering. This can be guaranteed
only if the universe was created from a PDB file that is
compatible with the DCD file without leaving out any
part of the system.</para>
<para>Constructor: DCDReader(<parameter>universe</parameter>, <parameter>**options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the information from the
              trajectory file is read</para></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter></term>
<listitem><para>
keyword options:<itemizedlist>
<listitem><para>
dcd_file:  the name of the DCD trajecory file to be read
</para></listitem>
<listitem><para>
actions: a list of actions to be executed periodically (default is
             none)</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>Reading is started by calling the reader object.
All the keyword options listed above can be specified either when
creating the reader or when calling it.</para>
<para>The following data categories and variables are available for
output:</para>
<itemizedlist>
<listitem><para>
category "time": time</para></listitem>
<listitem><para>
category "configuration": configuration
</para></listitem>
</itemizedlist>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.DCD.writeDCDPDB" xreflabel="MMTK.DCD.writeDCDPDB" role="Python"><funcprototype><funcdef><function>writeDCDPDB</function></funcdef>
<paramdef><parameter>conf_list</parameter></paramdef>
<paramdef><parameter>dcd_file_name</parameter></paramdef>
<paramdef><parameter>pdb_file_name</parameter></paramdef>
<paramdef><parameter>delta_t</parameter><defaultvalue>0.10000000000000001</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Write the configurations in <parameter>conf_list</parameter> (any sequence of Configuration
objects) to a newly created DCD trajectory file with the name
<parameter>dcd_file_name</parameter>. Also write the first configuration to a PDB file
with the name <parameter>pdb_file_name</parameter>; this PDB file has the same atom order
as the DCD file. The time step between configurations can be specified
by <parameter>delta_t</parameter>.
</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.DCD.writeVelocityDCDPDB" xreflabel="MMTK.DCD.writeVelocityDCDPDB" role="Python"><funcprototype><funcdef><function>writeVelocityDCDPDB</function></funcdef>
<paramdef><parameter>vel_list</parameter></paramdef>
<paramdef><parameter>dcd_file_name</parameter></paramdef>
<paramdef><parameter>pdb_file_name</parameter></paramdef>
<paramdef><parameter>delta_t</parameter><defaultvalue>0.10000000000000001</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Write the velocities in <parameter>vel_list</parameter> (any sequence of ParticleVector
objects) to a newly created DCD trajectory file with the name
<parameter>dcd_file_name</parameter>. Also write the first configuration to a PDB file
with the name <parameter>pdb_file_name</parameter>; this PDB file has the same atom order
as the DCD file. The time step between configurations can be specified
by <parameter>delta_t</parameter>.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Deformation" xreflabel="MMTK.Deformation">
<title>Module MMTK.Deformation</title>

<para>This module implements deformational energies for use in the analysis
of motions and conformational changes in macromolecules. A description
of the techniques can be found in [<xref linkend="Article:Hinsen1998"/>] and
[<xref linkend="Article:Hinsen1999"/>].
</para>
<classdescription role="Python" id="Class:MMTK.Deformation.DeformationFunction" xreflabel="MMTK.Deformation.DeformationFunction">
<classdef><class>DeformationFunction</class><classinfo>Infinite-displacement deformation function</classinfo></classdef>
<para>Constructor:  DeformationFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                  <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation function should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A DeformationFunction object must be called with a single parameter,
which is a ParticleVector object containing the infinitesimal displacements
of the atoms for which the deformation is to be evaluated.
The return value is a ParticleScalar object containing the
deformation value for each atom.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.NormalizedDeformationFunction" xreflabel="MMTK.Deformation.NormalizedDeformationFunction">
<classdef><class>NormalizedDeformationFunction</class><classinfo>Normalized infinite-displacement deformation function</classinfo></classdef>
<para>Constructor:  NormalizedDeformationFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                            <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation function should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.
The normalization is defined by equation 10 of reference 1.</para>
<para>A NormalizedDeformationFunction object must be called with a single
parameter, which is a ParticleVector object containing the infinitesimal
displacements of the atoms for which the deformation is to be evaluated.
The return value is a ParticleScalar object containing the
deformation value for each atom.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.FiniteDeformationFunction" xreflabel="MMTK.Deformation.FiniteDeformationFunction">
<classdef><class>FiniteDeformationFunction</class><classinfo>Finite-displacement deformation function</classinfo></classdef>
<para>Constructor:  FiniteDeformationFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                        <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation function should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A FiniteDeformationFunction object must be called with a single parameter,
which is a Configuration or a ParticleVector object containing the
alternate configuration of the universe for which the deformation is to be
evaluated.
The return value is a ParticleScalar object containing the
deformation value for each atom.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.DeformationEnergyFunction" xreflabel="MMTK.Deformation.DeformationEnergyFunction">
<classdef><class>DeformationEnergyFunction</class><classinfo>Infinite-displacement deformation energy function</classinfo></classdef>
<para>The deformation energy is the sum of the deformation values over
all atoms of a system.</para>
<para>Constructor:  DeformationEnergyFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                        <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation energy should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation energy calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A DeformationEnergyFunction is called with one or two parameters.
The first parameter is a ParticleVector object containing the
infinitesimal displacements of the atoms for which the deformation
energy is to be evaluated. The optional second argument can be
set to a non-zero value to request the gradients of the energy
in addition to the energy itself. In that case there are two
return values (energy and the gradients in a ParticleVector
object), otherwise only the energy is returned.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.NormalizedDeformationEnergyFunction" xreflabel="MMTK.Deformation.NormalizedDeformationEnergyFunction">
<classdef><class>NormalizedDeformationEnergyFunction</class><classinfo>Normalized infinite-displacement deformation energy function</classinfo></classdef>
<para>The normalized deformation energy is the sum of the normalized
deformation values over all atoms of a system.</para>
<para>Constructor: NormalizedDeformationEnergyFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                                 <parameter>cutoff</parameter>=1.2,
                                                 <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation energy should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation energy calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.
The normalization is defined by equation 10 of reference 1.</para>
<para>A NormalizedDeformationEnergyFunction is called with one or two parameters.
The first parameter is a ParticleVector object containing the
infinitesimal displacements of the atoms for which the deformation
energy is to be evaluated. The optional second argument can be
set to a non-zero value to request the gradients of the energy
in addition to the energy itself. In that case there are two
return values (energy and the gradients in a ParticleVector
object), otherwise only the energy is returned.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.FiniteDeformationEnergyFunction" xreflabel="MMTK.Deformation.FiniteDeformationEnergyFunction">
<classdef><class>FiniteDeformationEnergyFunction</class><classinfo>Finite-displacement deformation energy function</classinfo></classdef>
<para>The deformation energy is the sum of the
deformation values over all atoms of a system.</para>
<para>Constructor: FiniteDeformationEnergyFunction(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                             <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation energy should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation energy calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A FiniteDeformationEnergyFunction is called with one or two parameters.
The first parameter is a ParticleVector object containing the
alternate configuration of the universe for which the deformation
energy is to be evaluated. The optional second argument can be
set to a non-zero value to request the gradients of the energy
in addition to the energy itself. In that case there are two
return values (energy and the gradients in a ParticleVector
object), otherwise only the energy is returned.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.DeformationReducer" xreflabel="MMTK.Deformation.DeformationReducer">
<classdef><class>DeformationReducer</class><classinfo>Iterative reduction of the deformation energy</classinfo></classdef>
<para>Constructor:  DeformationReducer(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                 <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation function should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A DeformationReducer is called with two arguments. The first
is a ParticleVector containing the initial infinitesimal displacements
for all atoms. The second is an integer indicating the number of
iterations. The result is a modification of the displacements
by steepest-descent minimization of the deformation energy.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Deformation.FiniteDeformationReducer" xreflabel="MMTK.Deformation.FiniteDeformationReducer">
<classdef><class>FiniteDeformationReducer</class><classinfo>Iterative reduction of the finite-displacement deformation energy</classinfo></classdef>
<para>Constructor:  FiniteDeformationReducer(<parameter>universe</parameter>, <parameter>range</parameter>=0.7,
                                       <parameter>cutoff</parameter>=1.2, <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the deformation function should be
              defined</para></listitem></varlistentry>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter r_0 in the pair interaction term</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff used in the deformation calculation</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor</para></listitem></varlistentry>
</variablelist></para>
<para>The default values are appropriate for a C_alpha model of a protein
with the global scaling described in the reference cited above.</para>
<para>A FiniteDeformationReducer is called with two arguments. The first
is a ParticleVector or Configuration containing the alternate
configuration for which the deformation energy is evaluated.
The second is the RMS distance that defines the termination
condition. The return value a configuration that differs from
the input configuration by approximately the specified RMS distance,
and which is obtained by iterative steepest-descent minimization of
the finite-displacement deformation energy.
</para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.Dynamics" xreflabel="MMTK.Dynamics">
<title>Module MMTK.Dynamics</title>

<para>See also the <xref linkend="Example:MolecularDynamics"/> example applications.
</para>
<classdescription role="Python" id="Class:MMTK.Dynamics.VelocityVerletIntegrator" xreflabel="MMTK.Dynamics.VelocityVerletIntegrator">
<classdef><class>VelocityVerletIntegrator</class><classinfo>Velocity-Verlet molecular dynamics integrator</classinfo></classdef>
<para>The integrator can handle fixed atoms, distance constraints,
a thermostat, and a barostat, as well as any combination.
It is fully thread-safe.</para>
<para>Constructor: VelocityVerletIntegrator(<parameter>universe</parameter>, <parameter>**options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe on which the integrator acts</para></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter></term>
<listitem><para>
keyword options:<itemizedlist>
<listitem><para>
steps: the number of integration steps (default is 100)
</para></listitem>
<listitem><para>
delta_t: the time step (default is 1 fs)
</para></listitem>
<listitem><para>
actions: a list of actions to be executed periodically (default is
             none)
</para></listitem>
<listitem><para>
threads: the number of threads to use in energy evaluation
             (default set by MMTK_ENERGY_THREADS)
</para></listitem>
<listitem><para>
background: if true, the integration is executed as a separate thread
                (default: 0)
</para></listitem>
<listitem><para>
mpi_communicator: an MPI communicator object, or None, meaning
                      no parallelization (default: None)</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>The integration is started by calling the integrator object.
All the keyword options listed above can be specified either when
creating the integrator or when calling it.</para>
<para>The following data categories and variables are available for
output:</para>
<itemizedlist>
<listitem><para>
category "time": time</para></listitem>
<listitem><para>
category "configuration": configuration and box size (for
  periodic universes)</para></listitem>
<listitem><para>
category "velocities": atomic velocities</para></listitem>
<listitem><para>
category "gradients": energy gradients for each atom</para></listitem>
<listitem><para>
category "energy": potential and kinetic energy, plus
  extended-system energy terms if a thermostat and/or barostat
  are used</para></listitem>
<listitem><para>
category "thermodynamic": temperature, volume (if a barostat
  is used) and pressure</para></listitem>
<listitem><para>
category "auxiliary": extended-system coordinates if a thermostat
  and/or barostat are used
</para></listitem>
</itemizedlist>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Dynamics.VelocityScaler" xreflabel="MMTK.Dynamics.VelocityScaler">
<classdef><class>VelocityScaler</class><classinfo>Periodic velocity scaling action</classinfo></classdef>
<para>A VelocityScaler object is used in the action list of
a VelocityVerletIntegrator. It rescales all atomic velocities
by a common factor to make the temperature of the system equal
to a predefined value.</para>
<para>Constructor: VelocityScaler(<parameter>temperature</parameter>, <parameter>temperature_window</parameter>=0.,
                            <parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature value to which the velocities should
                 be scaled</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature_window</parameter></term>
<listitem><para>
the deviation from the ideal temperature that
                        is tolerated in either direction before rescaling
                        takes place</para></listitem></varlistentry>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Dynamics.Heater" xreflabel="MMTK.Dynamics.Heater">
<classdef><class>Heater</class><classinfo>Periodic heating action</classinfo></classdef>
<para>A Heater object us used in the action list of a VelocityVerletIntegrator.
It scales the velocities to a temperature that increases with time.</para>
<para>Constructor: Heater(<parameter>temperature1</parameter>, <parameter>temperature2</parameter>, <parameter>gradient</parameter>,
                    <parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>temperature1</parameter></term>
<listitem><para>
the temperature value to which the velocities should
                  be scaled initially</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature2</parameter></term>
<listitem><para>
the final temperature value to which the velocities
                  should be scaled</para></listitem></varlistentry>
<varlistentry><term><parameter>gradient</parameter></term>
<listitem><para>
the temperature gradient (in K/ps)</para></listitem></varlistentry>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Dynamics.BarostatReset" xreflabel="MMTK.Dynamics.BarostatReset">
<classdef><class>BarostatReset</class><classinfo>Barostat reset action</classinfo></classdef>
<para>A BarostatReset object is used in the action list of a
VelocityVerletIntegrator. It resets the barostat coordinate
to zero.</para>
<para>Constructor: BarostatReset(<parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Dynamics.TranslationRemover" xreflabel="MMTK.Dynamics.TranslationRemover">
<classdef><class>TranslationRemover</class><classinfo>Action that eliminates global translation</classinfo></classdef>
<para>A TranslationRemover object is used in the action list of a
VelocityVerletIntegrator. It subtracts the total velocity
from the system from each atomic velocity.</para>
<para>Constructor: TranslationRemover(<parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Dynamics.RotationRemover" xreflabel="MMTK.Dynamics.RotationRemover">
<classdef><class>RotationRemover</class><classinfo>Action that eliminates global rotation</classinfo></classdef>
<para>A RotationRemover object is used in the action list of a
VelocityVerletIntegrator. It adjusts the atomic velocities
such that the total angular momentum is zero.</para>
<para>Constructor: RotationRemover(<parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.Environment" xreflabel="MMTK.Environment">
<title>Module MMTK.Environment</title>

<classdescription role="Python" id="Class:MMTK.Environment.NoseThermostat" xreflabel="MMTK.Environment.NoseThermostat">
<classdef><class>NoseThermostat</class><classinfo>Nose thermostat for Molecular Dynamics</classinfo></classdef>
<para>A thermostat object can be added to a universe and will then
modify the integration algorithm to a simulation of an NVT
ensemble.</para>
<para>Constructor:  NoseThermostat(<parameter>temperature</parameter>, <parameter>relaxation_time</parameter>=0.2)</para>
<para><variablelist>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature set by the thermostat</para></listitem></varlistentry>
<varlistentry><term><parameter>relaxation_time</parameter></term>
<listitem><para>
the relaxation time of the thermostat coordinate
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Environment.AndersenBarostat" xreflabel="MMTK.Environment.AndersenBarostat">
<classdef><class>AndersenBarostat</class><classinfo>Andersen barostat for Molecular Dynamics</classinfo></classdef>
<para>A barostat object can be added to a universe and will then
together with a thermostat object modify the integration algorithm
to a simulation of an NPT ensemble.</para>
<para>Constructor:  AndersenBarostat(<parameter>pressure</parameter>, <parameter>relaxation_time</parameter>=1.5)</para>
<para><variablelist>
<varlistentry><term><parameter>pressure</parameter></term>
<listitem><para>
the pressure set by the barostat</para></listitem></varlistentry>
<varlistentry><term><parameter>relaxation_time</parameter></term>
<listitem><para>
the relaxation time of the barostat coordinate
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.Field" xreflabel="MMTK.Field">
<title>Module MMTK.Field</title>

<para>This module defines field objects that are useful in the analysis
and visualization of collective motions in molecular systems. Atomic
quantities characterizing collective motions vary slowly in space, and
can be considered functions of position instead of values per atom.
Functions of position are called fields, and mathematical techniques
for the analysis of fields have proven useful in many branches of
physics. Fields can be described numerically by values on a
regular grid. In addition to permitting the application of vector
analysis methods to atomic quantities, the introduction of
fields is a valuable visualization aid, because information defined on
a coarse regular grid can be added to a picture of a molecular system
without overloading it. See also the example
<xref linkend="Example:Miscellaneous:vector_field.py"/>.
</para>
<classdescription role="Python" id="Class:MMTK.Field.AtomicField" xreflabel="MMTK.Field.AtomicField">
<classdef><class>AtomicField</class><classinfo>A field whose values are determined by atomic quantities</classinfo></classdef>
<para>This is an Glossary:abstract-base-class. To create field objects,
use one of its subclasses.
</para>
<methoddescription><methoddef><method>particleValues</method></methoddef>
<void/><para>Returns the values of the field at the positions of the
atoms in an appropriate subclass of
<xref linkend="Class:MMTK.ParticleProperties.ParticleProperty"/>.</para>
</methoddescription>
<methoddescription><methoddef><method>writeToFile</method></methoddef>
<paramdef><parameter>filename</parameter></paramdef>
<paramdef><parameter>scale</parameter><defaultvalue>1.0</defaultvalue></paramdef>
<paramdef><parameter>color</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Writes a graphical representation of the field
to the VRML file named by <parameter>filename</parameter>, multiplying
all values by <parameter>scale</parameter>. <parameter>color</parameter> permits the choice
of a color for the graphics objects.</para>
</methoddescription>
<methoddescription><methoddef><method>view</method></methoddef>
<paramdef><parameter>scale</parameter><defaultvalue>1.0</defaultvalue></paramdef>
<paramdef><parameter>color</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Shows a graphical representation of the field using
a VRML viewer. All values are multiplied by <parameter>scale</parameter>. <parameter>color</parameter>
permits the choice of a color for the graphics objects.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Field.AtomicScalarField" xreflabel="MMTK.Field.AtomicScalarField">
<classdef><class>AtomicScalarField</class><classinfo>Scalar field defined by atomic quantities</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Field.AtomicField"/> and
<xref linkend="Class:MMTK.Visualization.Viewable"/>.</para>
<para>Constructor: AtomicScalarField(<parameter>system</parameter>, <parameter>grid_size</parameter>, <parameter>values</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>system</parameter></term>
<listitem><para>
any subset of a molecular system</para></listitem></varlistentry>
<varlistentry><term><parameter>grid_size</parameter></term>
<listitem><para>
the spacing of a cubic grid on which the field values
               are stored</para></listitem></varlistentry>
<varlistentry><term><parameter>values</parameter></term>
<listitem><para>
an object of class <xref linkend="Class:MMTK.ParticleScalar"/> containing
            the atomic values that define the field</para></listitem></varlistentry>
</variablelist></para>
<para>The field values are obtained by averaging the atomic quantities
over all atoms in a cube of edge length <parameter>grid_size</parameter> surrounding
each grid point.</para>
<para>The method graphicsObjects, defined in class
<xref linkend="Class:MMTK.Visualization.Viewable"/>, returns a small cube for each
grid point, whose color indicates the field's value on a symmetric
red-to-green color scale defined by the range of the field values.
Additional keyword options are:</para>
<para>-- <parameter>scale</parameter>=factor, to multiply all field values by a factor</para>
<para>-- <parameter>range</parameter>=(min, max), to eliminate graphics objects for values
   that are smaller than min or larger than max
</para>
<methoddescription><methoddef><method>gradient</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicVectorField"/> object representing
the gradient of the field.</para>
</methoddescription>
<methoddescription><methoddef><method>laplacian</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicScalarField"/> object representing
the laplacian of the field.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Field.AtomicVectorField" xreflabel="MMTK.Field.AtomicVectorField">
<classdef><class>AtomicVectorField</class><classinfo>Vector field defined by atomic quantities</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Field.AtomicField"/> and
<xref linkend="Class:MMTK.Visualization.Viewable"/>.</para>
<para>Constructor: AtomicVectorField(<parameter>system</parameter>, <parameter>grid_size</parameter>, <parameter>values</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>system</parameter></term>
<listitem><para>
any subset of a molecular system</para></listitem></varlistentry>
<varlistentry><term><parameter>grid_size</parameter></term>
<listitem><para>
the spacing of a cubic grid on which the field values
               are stored</para></listitem></varlistentry>
<varlistentry><term><parameter>values</parameter></term>
<listitem><para>
an object of class <xref linkend="Class:MMTK.ParticleVector"/> containing
            the atomic values that define the field</para></listitem></varlistentry>
</variablelist></para>
<para>The field values are obtained by averaging the atomic quantities
over all atoms in a cube of edge length <parameter>grid_size</parameter> surrounding
each grid point.</para>
<para>The method graphicsObjects, defined in class
<xref linkend="Class:MMTK.Visualization.Viewable"/>, returns a small arrow for each
grid point. The arrow starts at the grid point and represents
the vector value at that point.
Additional keyword options are:</para>
<para>-- <parameter>scale</parameter>=factor, to multiply all field values by a factor</para>
<para>-- <parameter>diameter</parameter>=number, to define the diameter of the arrow
   objects (default: 1.)</para>
<para>-- <parameter>range</parameter>=(min, max), to eliminate graphics objects for values
   whose lengths are smaller than min or larger than max</para>
<para>-- <parameter>color</parameter>=string, to define the color of the arrows
</para>
<methoddescription><methoddef><method>length</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicScalarField"/> object representing
the length of the field vectors.</para>
</methoddescription>
<methoddescription><methoddef><method>divergence</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicScalarField"/> object representing
the divergence of the field.</para>
</methoddescription>
<methoddescription><methoddef><method>curl</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicVectorField"/> object representing
the curl of the field.</para>
</methoddescription>
<methoddescription><methoddef><method>laplacian</method></methoddef>
<void/><para>Returns an <xref linkend="Class:MMTK.Field.AtomicVectorField"/> object representing
the laplacian of the field.</para>
</methoddescription>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.ForceFields" xreflabel="MMTK.ForceFields">
<title>Module MMTK.ForceFields</title>

<classdescription role="Python" id="Class:MMTK.ForceFields.CalphaForceField" xreflabel="MMTK.ForceFields.CalphaForceField">
<classdef><class>CalphaForceField</class><classinfo>Effective harmonic force field for a C-alpha protein model</classinfo></classdef>
<para>Constructor: CalphaForceField(<parameter>cutoff</parameter>=None, <parameter>scale_factor</parameter>=1.)</para>
<para><variablelist>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff for pair interactions, should be
            at least 2.5 nm</para></listitem></varlistentry>
<varlistentry><term><parameter>scale_factor</parameter></term>
<listitem><para>
a global scaling factor.</para></listitem></varlistentry>
</variablelist></para>
<para>Pair interactions in periodic systems are calculated using the
minimum-image convention; the cutoff should therefore never be
larger than half the smallest edge length of the elementary
cell.</para>
<para>See [<xref linkend="Article:Hinsen2000"/>] for a description of this force field.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ForceFields.DeformationForceField" xreflabel="MMTK.ForceFields.DeformationForceField">
<classdef><class>DeformationForceField</class><classinfo>Deformation force field for protein normal mode calculations</classinfo></classdef>
<para>Constructor: DeformationForceField(<parameter>range</parameter>=0.7, <parameter>cutoff</parameter>=1.2,
                                   <parameter>factor</parameter>=46402.)</para>
<para><variablelist>
<varlistentry><term><parameter>range</parameter></term>
<listitem><para>
the range parameter</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the cutoff for pair interactions, should be significantly
            larger than <parameter>range</parameter>.</para></listitem></varlistentry>
<varlistentry><term><parameter>factor</parameter></term>
<listitem><para>
a global scaling factor.</para></listitem></varlistentry>
</variablelist></para>
<para>Pair interactions in periodic systems are calculated using the
minimum-image convention; the cutoff should therefore never be
larger than half the smallest edge length of the elementary
cell.</para>
<para>The pair interaction energy has the form
U(r)=|factor|*exp(-(r-0.01)**2/|range|**2). The default value
for <parameter>range</parameter> is appropriate for a C-alpha model of a protein.
See [<xref linkend="Article:Hinsen1998"/>] for details.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ForceFields.LennardJonesForceField" xreflabel="MMTK.ForceFields.LennardJonesForceField">
<classdef><class>LennardJonesForceField</class><classinfo>Lennard-Jones force field for noble gases</classinfo></classdef>
<para>Constructor: LennardJonesForceField(<parameter>cutoff</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
a cutoff value or <literal role="Python">None</literal>, meaning no cutoff</para></listitem></varlistentry>
</variablelist></para>
<para>Pair interactions in periodic systems are calculated using the
minimum-image convention; the cutoff should therefore never be
larger than half the smallest edge length of the elementary
cell.</para>
<para>The Lennard-Jones parameters are taken from the atom attributes
LJ_radius and LJ_energy. The pair interaction energy has the form
U(r)=4*LJ_energy*((LJ_radius/r)**12-(LJ_radius/r)**6).
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ForceFields.Amber94ForceField" xreflabel="MMTK.ForceFields.Amber94ForceField">
<classdef><class>Amber94ForceField</class><classinfo>Amber 94 force field</classinfo></classdef>
<para>Constructor: Amber94ForceField(<parameter>lennard_jones_options</parameter>,
                               <parameter>electrostatic_options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>lennard_jones_options</parameter></term>
<listitem><para>
parameters for Lennard-Jones interactions;
                           one of:<itemizedlist>
<listitem><para>
a number, specifying the cutoff
</para></listitem>
<listitem><para>
<literal role="Python">None</literal>, meaning the default method (no cutoff; inclusion of all
    pairs, using the minimum-image conventions for periodic universes)
</para></listitem>
<listitem><para>
a dictionary with an entry "method" which specifies the
    calculation method as either "direct" (all pair terms)
    or "cutoff", with the cutoff specified by the dictionary
    entry "cutoff".</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
<varlistentry><term><parameter>electrostatic_options</parameter></term>
<listitem><para>
parameters for electrostatic interactions;
                           one of:<itemizedlist>
<listitem><para>
a number, specifying the cutoff
</para></listitem>
<listitem><para>
<literal role="Python">None</literal>, meaning the default method (all pairs without cutoff for
    non-periodic system, Ewald summation for periodic systems)
</para></listitem>
<listitem><para>
a dictionary with an entry "method" which specifies the
    calculation method as either "direct" (all pair terms),
    "cutoff" (with the cutoff specified by the dictionary
    entry "cutoff"), "ewald" (Ewald summation, only for periodic
    universes), "screened" (see below),
    or "multipole" (fast-multipole method).</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>Pair interactions in periodic systems are calculated using the
minimum-image convention; the cutoff should therefore never be
larger than half the smallest edge length of the elementary
cell.</para>
<para>For Lennard-Jones interactions, all terms for pairs whose distance
exceeds the cutoff are set to zero, without any form of correction.
For electrostatic interactions, a charge-neutralizing surface charge
density is added around the cutoff sphere in order to reduce
cutoff effects [<xref linkend="Article:Wolf1999"/>].</para>
<para>For Ewald summation, there are some additional parameters that can
be specified by dictionary entries:</para>
<itemizedlist>
<listitem><para>
"beta" specifies the Ewald screening parameter
</para></listitem>
<listitem><para>
"real_cutoff" specifies the cutoff for the real-space sum.
  It should be significantly larger than 1/beta to ensure that
  the neglected terms are small.
</para></listitem>
<listitem><para>
"reciprocal_cutoff" specifies the cutoff for the reciprocal-space sum.
  Note that, like the real-space cutoff, this is a distance; it describes
  the smallest wavelength of plane waves to take into account.
  Consequently, a smaller value means a more precise (and more expensive)
  calculation.</para></listitem>
</itemizedlist>
<para>MMTK provides default values for these parameter which are calculated
as a function of the system size. However, these parameters are
exaggerated in most cases of practical interest and can lead to excessive
calculation times for large systems. It is preferable to determine
suitable values empirically for the specific system to be simulated.</para>
<para>The method "screened" uses the real-space part of the Ewald sum
with a charge-neutralizing surface charge density around the
cutoff sphere, and no reciprocal sum [<xref linkend="Article:Wolf1999"/>]. It requires
the specification of the dictionary entries "cutoff" and "beta".</para>
<para>The fast-multipole method uses the DPMTA library [<xref linkend="Article:DPMTA"/>].
Note that this method provides only energy and forces, but no
second-derivative matrix. There are several optional dictionary
entries for this method, all of which are set to reasonable default
values. The entries are "spatial_decomposition_levels",
"multipole_expansion_terms", "use_fft", "fft_blocking_factor",
"macroscopic_expansion_terms", and "multipole_acceptance".
For an explanation of these options, refer to the
DPMTA manual [<xref linkend="Article:DPMTA"/>].
</para>
</classdescription>

<sect2 id="Module:MMTK.ForceFields.BondFF" xreflabel="MMTK.ForceFields.BondFF">
<title>Module MMTK.ForceFields.BondFF</title>

<classdescription role="Python" id="Class:MMTK.ForceFields.BondFF.HarmonicForceField" xreflabel="MMTK.ForceFields.BondFF.HarmonicForceField">
<classdef><class>HarmonicForceField</class><classinfo>Simplified harmonic force field for normal mode calculations</classinfo></classdef>
<para>Constructor: HarmonicForceField()</para>
<para>This force field is made up of the bonded terms from the Amber 94
force field with the equilibrium positions of all terms changed
to the corresponding values in the input configuration, such that
the input configuration becomes an energy minimum by construction.
The nonbonded terms are replaced by a generic short-ranged
deformation term.</para>
<para>See [<xref linkend="Article:Hinsen1999b"/>] for a description of this force field,
and [<xref linkend="Article:Viduna2000"/>] for an application to DNA.
</para>
</classdescription>

</sect2>

<sect2 id="Module:MMTK.ForceFields.ForceFieldTest" xreflabel="MMTK.ForceFields.ForceFieldTest">
<title>Module MMTK.ForceFields.ForceFieldTest</title>

<para>Force field consistency tests</para>
<para>To be documented later!
</para>
</sect2>

<sect2 id="Module:MMTK.ForceFields.Restraints" xreflabel="MMTK.ForceFields.Restraints">
<title>Module MMTK.ForceFields.Restraints</title>

<para>This module contains harmonic restraint terms that can be added
to any force field.</para>
<para>Example:</para>
<para>from MMTK import *
from MMTK.ForceFields import Amber94ForceField
from MMTK.ForceFields.Restraints import HarmonicDistanceRestraint</para>
<para>universe = InfiniteUniverse()
universe.protein = Protein(<literal role="Python">bala1</literal>)
force_field = Amber94ForceField() +               HarmonicDistanceRestraint(universe.protein[0][1].peptide.N,
                                        universe.protein[0][1].peptide.O,
                                        0.5, 10.)
universe.setForceField(force_field)
</para>
<classdescription role="Python" id="Class:MMTK.ForceFields.Restraints.HarmonicDistanceRestraint" xreflabel="MMTK.ForceFields.Restraints.HarmonicDistanceRestraint">
<classdef><class>HarmonicDistanceRestraint</class><classinfo>Harmonic distance restraint between two atoms</classinfo></classdef>
<para>Constructor: HarmonicDistanceRestraint(<parameter>atom1</parameter>, <parameter>atom2</parameter>,
                                       <parameter>distance</parameter>, <parameter>force_constant</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>atom1</parameter>, <parameter>atom2</parameter></term>
<listitem><para>
the two atoms whose distance is restrained</para></listitem></varlistentry>
<varlistentry><term><parameter>distance</parameter></term>
<listitem><para>
the distance at which the restraint is zero</para></listitem></varlistentry>
<varlistentry><term><parameter>force_constant</parameter></term>
<listitem><para>
the force constant of the restraint term</para></listitem></varlistentry>
</variablelist></para>
<para>The functional form of the restraint is
|force_constant|*((r1-r2).length()-|distance|)**2, where
r1 and r2 are the positions of the two atoms.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ForceFields.Restraints.HarmonicAngleRestraint" xreflabel="MMTK.ForceFields.Restraints.HarmonicAngleRestraint">
<classdef><class>HarmonicAngleRestraint</class><classinfo>Harmonic angle restraint between three atoms</classinfo></classdef>
<para>Constructor: HarmonicAngleRestraint(<parameter>atom1</parameter>, <parameter>atom2</parameter>, <parameter>atom3</parameter>,
                                    <parameter>angle</parameter>, <parameter>force_constant</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>atom1</parameter>, <parameter>atom2</parameter>, <parameter>atom3</parameter></term>
<listitem><para>
the three atoms whose angle is restrained;
<parameter>atom2</parameter> is the central atom</para></listitem></varlistentry>
<varlistentry><term><parameter>angle</parameter></term>
<listitem><para>
the angle at which the restraint is zero</para></listitem></varlistentry>
<varlistentry><term><parameter>force_constant</parameter></term>
<listitem><para>
the force constant of the restraint term</para></listitem></varlistentry>
</variablelist></para>
<para>The functional form of the restraint is
|force_constant|*(phi-|angle|)**2, where
phi is the angle |atom1|-|atom2|-|atom3|.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.ForceFields.Restraints.HarmonicDihedralRestraint" xreflabel="MMTK.ForceFields.Restraints.HarmonicDihedralRestraint">
<classdef><class>HarmonicDihedralRestraint</class><classinfo>Harmonic dihedral angle restraint between three atoms</classinfo></classdef>
<para>Constructor: HarmonicDihedralRestraint(<parameter>atom1</parameter>, <parameter>atom2</parameter>, <parameter>atom3</parameter>, <parameter>atom4</parameter>,
                                       <parameter>angle</parameter>, <parameter>force_constant</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>atom1</parameter>, <parameter>atom2</parameter>, <parameter>atom3</parameter>, <parameter>atom4</parameter></term>
<listitem><para>
the four atoms whose dihedral angle
is restrained; <parameter>atom2</parameter> and <parameter>atom3</parameter> are on the common axis</para></listitem></varlistentry>
<varlistentry><term><parameter>angle</parameter></term>
<listitem><para>
the dihedral angle at which the restraint is zero</para></listitem></varlistentry>
<varlistentry><term><parameter>force_constant</parameter></term>
<listitem><para>
the force constant of the restraint term</para></listitem></varlistentry>
</variablelist></para>
<para>The functional form of the restraint is
|force_constant|*(phi-|distance|)**2, where
phi is the dihedral angle |atom1|-|atom2|-|atom3|-|atom4|.
</para>
</classdescription>

</sect2>

<sect2 id="Module:MMTK.ForceFields.SPCEFF" xreflabel="MMTK.ForceFields.SPCEFF">
<title>Module MMTK.ForceFields.SPCEFF</title>

<classdescription role="Python" id="Class:MMTK.ForceFields.SPCEFF.SPCEForceField" xreflabel="MMTK.ForceFields.SPCEFF.SPCEForceField">
<classdef><class>SPCEForceField</class><classinfo>Force field for water simulations with the SPC/E model</classinfo></classdef>
<para>Constructor: SPCEForceField(<parameter>lennard_jones_options</parameter>,
                            <parameter>electrostatic_options</parameter>)</para>
<para>The meaning of the arguments is the same as for the class
[<xref linkend="Class:MMTK.ForceFields.Amber94ForceField"/>]
</para>
</classdescription>

</sect2>

</sect1>

<sect1 id="Module:MMTK.FourierBasis" xreflabel="MMTK.FourierBasis">
<title>Module MMTK.FourierBasis</title>

<para>This module provides a basis that is suitable for the
calculation of low-frequency normal modes. The basis is
derived from vector fields whose components are stationary
waves in a box surrounding the system. For a description
see [<xref linkend="Article:Hinsen1998"/>].
</para>
<classdescription role="Python" id="Class:MMTK.FourierBasis.FourierBasis" xreflabel="MMTK.FourierBasis.FourierBasis">
<classdef><class>FourierBasis</class><classinfo>Collective-motion basis for low-frequency normal mode calculations</classinfo></classdef>
<para>To be used with <xref linkend="Class:MMTK.NormalModes.SubspaceNormalModes"/>.</para>
<para>Constructor: FourierBasis(<parameter>universe</parameter>, <parameter>cutoff</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the basis will be used</para></listitem></varlistentry>
<varlistentry><term><parameter>cutoff</parameter></term>
<listitem><para>
the wavelength cutoff. A smaller value means a larger basis.</para></listitem></varlistentry>
</variablelist></para>
<para>A FourierBasis object behaves like a sequence of
<xref linkend="Class:MMTK.ParticleVector"/> objects. The vectors are <emphasis>not</emphasis>
orthonormal, because orthonormalization is handled automatically
by the class <xref linkend="Class:MMTK.NormalModes.SubspaceNormalModes"/>.
</para>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.FourierBasis.countBasisVectors" xreflabel="MMTK.FourierBasis.countBasisVectors" role="Python"><funcprototype><funcdef><function>countBasisVectors</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>cutoff</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns the number of basis vectors in a FourierBasis for
the given <parameter>universe</parameter> and <parameter>cutoff</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.FourierBasis.estimateCutoff" xreflabel="MMTK.FourierBasis.estimateCutoff" role="Python"><funcprototype><funcdef><function>estimateCutoff</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>nmodes</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns an estimate for the cutoff that will yield a basis of
<parameter>nmodes</parameter> vectors for the given <parameter>universe</parameter>. The two return values
are the cutoff and the precise number of basis vectors for this cutoff.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Geometry" xreflabel="MMTK.Geometry">
<title>Module MMTK.Geometry</title>

<para>This module defines several elementary geometrical objects, which
can be useful in the construction and analysis of molecular systems.
There are essentially two kinds of geometrical objects: shape objects
(spheres, planes, etc.), from which intersections can be calculated,
and lattice objects, which define a regular arrangements of points.
</para>
<classdescription role="Python" id="Class:MMTK.Geometry.GeometricalObject3D" xreflabel="MMTK.Geometry.GeometricalObject3D">
<classdef><class>GeometricalObject3D</class><classinfo>3D shape object</classinfo></classdef>
<para>This is an Glossary:abstract-base-class. To create 3D objects,
use one of its subclasses.
</para>
<methoddescription><methoddef><method>intersectWith</method></methoddef>
<paramdef><parameter>other</parameter></paramdef>
<para>Return a 3D object that represents the intersection with <parameter>other</parameter>
(another 3D object).</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Box" xreflabel="MMTK.Geometry.Box">
<classdef><class>Box</class><classinfo>Box</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Box(<parameter>corner1</parameter>, <parameter>corner2</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>corner1</parameter>, <parameter>corner2</parameter></term>
<listitem><para>
diagonally opposite corner points
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Sphere" xreflabel="MMTK.Geometry.Sphere">
<classdef><class>Sphere</class><classinfo>Sphere</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Sphere(<parameter>center</parameter>, <parameter>radius</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>center</parameter></term>
<listitem><para>
the center of the sphere (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>radius</parameter></term>
<listitem><para>
the radius of the sphere (a number)
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Cylinder" xreflabel="MMTK.Geometry.Cylinder">
<classdef><class>Cylinder</class><classinfo>Cylinder</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Cylinder(<parameter>center1</parameter>, <parameter>center2</parameter>, <parameter>radius</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>center1</parameter></term>
<listitem><para>
the center of the bottom circle (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>center2</parameter></term>
<listitem><para>
the center of the top circle (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>radius</parameter></term>
<listitem><para>
the radius (a number)
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Plane" xreflabel="MMTK.Geometry.Plane">
<classdef><class>Plane</class><classinfo>2D plane in 3D space</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Plane(<parameter>point</parameter>, <parameter>normal</parameter>)
             or Plane(<parameter>point1</parameter>, <parameter>point2</parameter>, <parameter>point3</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>point</parameter></term>
<listitem><para>
any point in the plane</para></listitem></varlistentry>
<varlistentry><term><parameter>normal</parameter></term>
<listitem><para>
the normal vector of the plane</para></listitem></varlistentry>
<varlistentry><term><parameter>point1</parameter>, <parameter>point2</parameter>, <parameter>point3</parameter></term>
<listitem><para>
three points in the plane that
                                are not collinear.
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Cone" xreflabel="MMTK.Geometry.Cone">
<classdef><class>Cone</class><classinfo>Cone</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Cone(<parameter>center</parameter>, <parameter>axis</parameter>, <parameter>angle</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>center</parameter></term>
<listitem><para>
the center (tip) of the cone (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>axis</parameter></term>
<listitem><para>
the direction of the axis of rotational symmetry (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>angle</parameter></term>
<listitem><para>
the angle between any straight line on the cone surface and
           the axis of symmetry (a number)
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Circle" xreflabel="MMTK.Geometry.Circle">
<classdef><class>Circle</class><classinfo>2D circle in 3D space</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Circle(<parameter>center</parameter>, <parameter>normal</parameter>, <parameter>radius</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>center</parameter></term>
<listitem><para>
the center of the circle (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>normal</parameter></term>
<listitem><para>
the normal vector of the plane of the sphere (vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>radius</parameter></term>
<listitem><para>
the radius of the circle (a number)
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Line" xreflabel="MMTK.Geometry.Line">
<classdef><class>Line</class><classinfo>Line</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.GeometricalObject3D"/>.</para>
<para>Constructor: Line(<parameter>point</parameter>, <parameter>direction</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>point</parameter></term>
<listitem><para>
any point on the line (a vector)</para></listitem></varlistentry>
<varlistentry><term><parameter>direction</parameter></term>
<listitem><para>
the direction of the line (a vector)
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>distanceFrom</method></methoddef>
<paramdef><parameter>point</parameter></paramdef>
<para>Returns the smallest distance of <parameter>point</parameter> from the line.</para>
</methoddescription>
<methoddescription><methoddef><method>projectionOf</method></methoddef>
<paramdef><parameter>point</parameter></paramdef>
<para>Returns the orthogonal projection of <parameter>point</parameter> onto the line.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.Lattice" xreflabel="MMTK.Geometry.Lattice">
<classdef><class>Lattice</class><classinfo>General lattice</classinfo></classdef>
<para>Lattices are special sequence objects that contain vectors
(points on the lattice) or objects that are constructed as
functions of these vectors. Lattice objects behave like
lists, i.e. they permit indexing, length inquiry, and iteration
by 'for'-loops. See also the example <xref linkend="Example:Miscellaneous:lattice.py"/>.</para>
<para>This is an Glossary:abstract-base-class. To create lattice objects,
use one of its subclasses.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.RhombicLattice" xreflabel="MMTK.Geometry.RhombicLattice">
<classdef><class>RhombicLattice</class><classinfo>Rhombic lattice</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.Lattice"/>.</para>
<para>Constructor: RhombicLattice(<parameter>elementary_cell</parameter>, <parameter>lattice_vectors</parameter>,
                            <parameter>cells</parameter>, <parameter>function</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>elementary_cell</parameter></term>
<listitem><para>
a list of points (vectors) in the elementary cell</para></listitem></varlistentry>
<varlistentry><term><parameter>lattice_vectors</parameter></term>
<listitem><para>
a list of lattice vectors. Each lattice
                     vector defines a lattice dimension (only values
                     from one to three make sense) and indicates the
                     displacement along this dimension from one
                     cell to the next.</para></listitem></varlistentry>
<varlistentry><term><parameter>cells</parameter></term>
<listitem><para>
a list of integers, whose length must equal the number
           of dimensions. Each entry specifies how often a cell is
           repeated along this dimension.</para></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter></term>
<listitem><para>
a function that is called for every lattice point with
              the vector describing the point as argument. The return
              value of this function is stored in the lattice object.
              If the function is <literal role="Python">None</literal>, the vector is directly stored
              in the lattice object.</para></listitem></varlistentry>
</variablelist></para>
<para>The number of objects in the lattice is equal to the product of the
values in <parameter>cells</parameter> times the number of points in <parameter>elementary_cell</parameter>.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.BravaisLattice" xreflabel="MMTK.Geometry.BravaisLattice">
<classdef><class>BravaisLattice</class><classinfo>Bravais lattice</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.Lattice"/>.</para>
<para>A Bravais lattice is a special case of a general rhombic lattice
in which the elementary cell contains only one point.</para>
<para>Constructor: BravaisLattice(<parameter>lattice_vectors</parameter>,
                            <parameter>cells</parameter>, <parameter>function</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>lattice_vectors</parameter></term>
<listitem><para>
a list of lattice vectors. Each lattice
                     vector defines a lattice dimension (only values
                     from one to three make sense) and indicates the
                     displacement along this dimension from one
                     cell to the next.</para></listitem></varlistentry>
<varlistentry><term><parameter>cells</parameter></term>
<listitem><para>
a list of integers, whose length must equal the number
           of dimensions. Each entry specifies how often a cell is
           repeated along this dimension.</para></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter></term>
<listitem><para>
a function that is called for every lattice point with
              the vector describing the point as argument. The return
              value of this function is stored in the lattice object.
              If the function is <literal role="Python">None</literal>, the vector is directly stored
              in the lattice object.</para></listitem></varlistentry>
</variablelist></para>
<para>The number of objects in the lattice is equal to the product of the
values in <parameter>cells</parameter>.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.SCLattice" xreflabel="MMTK.Geometry.SCLattice">
<classdef><class>SCLattice</class><classinfo>Simple Cubic lattice</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.Lattice"/>.</para>
<para>A Simple Cubic lattice is a special case of a Bravais lattice
in which the elementary cell is a cube.</para>
<para>Constructor: SCLattice(<parameter>cell_size</parameter>, <parameter>cells</parameter>, <parameter>function</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>cell_size</parameter></term>
<listitem><para>
the edge length of the elementary cell</para></listitem></varlistentry>
<varlistentry><term><parameter>cells</parameter></term>
<listitem><para>
a list of integers, whose length must equal the number
           of dimensions. Each entry specifies how often a cell is
           repeated along this dimension.</para></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter></term>
<listitem><para>
a function that is called for every lattice point with
              the vector describing the point as argument. The return
              value of this function is stored in the lattice object.
              If the function is <literal role="Python">None</literal>, the vector is directly stored
              in the lattice object.</para></listitem></varlistentry>
</variablelist></para>
<para>The number of objects in the lattice is equal to the product of the
values in <parameter>cells</parameter>.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.BCCLattice" xreflabel="MMTK.Geometry.BCCLattice">
<classdef><class>BCCLattice</class><classinfo>Body-Centered Cubic lattice</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.Lattice"/>.</para>
<para>A Body-Centered Cubic lattice has two points per elementary cell.</para>
<para>Constructor: BCCLattice(<parameter>cell_size</parameter>, <parameter>cells</parameter>, <parameter>function</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>cell_size</parameter></term>
<listitem><para>
the edge length of the elementary cell</para></listitem></varlistentry>
<varlistentry><term><parameter>cells</parameter></term>
<listitem><para>
a list of integers, whose length must equal the number
           of dimensions. Each entry specifies how often a cell is
           repeated along this dimension.</para></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter></term>
<listitem><para>
a function that is called for every lattice point with
              the vector describing the point as argument. The return
              value of this function is stored in the lattice object.
              If the function is <literal role="Python">None</literal>, the vector is directly stored
              in the lattice object.</para></listitem></varlistentry>
</variablelist></para>
<para>The number of objects in the lattice is equal to the product of the
values in <parameter>cells</parameter>.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Geometry.FCCLattice" xreflabel="MMTK.Geometry.FCCLattice">
<classdef><class>FCCLattice</class><classinfo>Face-Centered Cubic lattice</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Geometry.Lattice"/>.</para>
<para>A Face-Centered Cubic lattice has four points per elementary cell.</para>
<para>Constructor: FCCLattice(<parameter>cell_size</parameter>, <parameter>cells</parameter>, <parameter>function</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>cell_size</parameter></term>
<listitem><para>
the edge length of the elementary cell</para></listitem></varlistentry>
<varlistentry><term><parameter>cells</parameter></term>
<listitem><para>
a list of integers, whose length must equal the number
           of dimensions. Each entry specifies how often a cell is
           repeated along this dimension.</para></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter></term>
<listitem><para>
a function that is called for every lattice point with
              the vector describing the point as argument. The return
              value of this function is stored in the lattice object.
              If the function is <literal role="Python">None</literal>, the vector is directly stored
              in the lattice object.</para></listitem></varlistentry>
</variablelist></para>
<para>The number of objects in the lattice is equal to the product of the
values in <parameter>cells</parameter>.
</para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.Minimization" xreflabel="MMTK.Minimization">
<title>Module MMTK.Minimization</title>

<classdescription role="Python" id="Class:MMTK.Minimization.SteepestDescentMinimizer" xreflabel="MMTK.Minimization.SteepestDescentMinimizer">
<classdef><class>SteepestDescentMinimizer</class><classinfo>Steepest-descent minimizer</classinfo></classdef>
<para>The minimizer can handle fixed atoms, but no distance constraints.
It is fully thread-safe.</para>
<para>Constructor: SteepestDescentMinimizer(<parameter>universe</parameter>, <parameter>**options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe on which the minimizer acts</para></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter></term>
<listitem><para>
keyword options:<itemizedlist>
<listitem><para>
steps: the number of minimization steps (default is 100)
</para></listitem>
<listitem><para>
step_size: the initial size of a minimization step
               (default is 0.002 nm)
</para></listitem>
<listitem><para>
convergence: the root-mean-square gradient length at which
                 minimization stops (default is 0.01 kJ/mol/nm)
</para></listitem>
<listitem><para>
actions: a list of actions to be executed periodically (default is
             none)
</para></listitem>
<listitem><para>
threads: the number of threads to use in energy evaluation
             (default set by MMTK_ENERGY_THREADS)
</para></listitem>
<listitem><para>
background: if true, the minimization is executed as a separate thread
                (default: 0)
</para></listitem>
<listitem><para>
mpi_communicator: an MPI communicator object, or None, meaning
                      no parallelization (default: None)</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>The minimization is started by calling the minimizer object.
All the keyword options listed above can be specified either when
creating the minimizer or when calling it.</para>
<para>The following data categories and variables are available for
output:</para>
<itemizedlist>
<listitem><para>
category "configuration": configuration and box size (for
  periodic universes)</para></listitem>
<listitem><para>
category "gradients": energy gradients for each atom</para></listitem>
<listitem><para>
category "energy": potential energy and
                     norm of the potential energy gradient
</para></listitem>
</itemizedlist>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Minimization.ConjugateGradientMinimizer" xreflabel="MMTK.Minimization.ConjugateGradientMinimizer">
<classdef><class>ConjugateGradientMinimizer</class><classinfo>Conjugate gradient minimizer</classinfo></classdef>
<para>The minimizer can handle fixed atoms, but no distance constraints.
It is fully thread-safe.</para>
<para>Constructor: ConjugateGradientMinimizer(<parameter>universe</parameter>, <parameter>**options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe on which the minimizer acts</para></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter></term>
<listitem><para>
keyword options:<itemizedlist>
<listitem><para>
steps: the number of minimization steps (default is 100)
</para></listitem>
<listitem><para>
step_size: the initial size of a minimization step
               (default is 0.002 nm)
</para></listitem>
<listitem><para>
convergence: the root-mean-square gradient length at which
                 minimization stops (default is 0.01 kJ/mol/nm)
</para></listitem>
<listitem><para>
actions: a list of actions to be executed periodically (default is
             none)
</para></listitem>
<listitem><para>
threads: the number of threads to use in energy evaluation
             (default set by MMTK_ENERGY_THREADS)
</para></listitem>
<listitem><para>
background: if true, the minimization is executed as a separate thread
                (default: 0)</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>The minimization is started by calling the minimizer object.
All the keyword options listed above can be specified either when
creating the minimizer or when calling it.</para>
<para>The following data categories and variables are available for
output:</para>
<itemizedlist>
<listitem><para>
category "configuration": configuration and box size (for
  periodic universes)</para></listitem>
<listitem><para>
category "gradients": energy gradients for each atom</para></listitem>
<listitem><para>
category "energy": potential energy and
                     norm of the potential energy gradient
</para></listitem>
</itemizedlist>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.MolecularSurface" xreflabel="MMTK.MolecularSurface">
<title>Module MMTK.MolecularSurface</title>

<para>This module provides functions that calculate molecular surfaces
and volumes.
</para>
<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.MolecularSurface.surfaceAndVolume" xreflabel="MMTK.MolecularSurface.surfaceAndVolume" role="Python"><funcprototype><funcdef><function>surfaceAndVolume</function></funcdef>
<paramdef><parameter>self</parameter></paramdef>
<paramdef><parameter>probe_radius</parameter><defaultvalue>0.0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns the molecular surface and volume of <parameter>object</parameter>,
defining the surface at a distance of <parameter>probe_radius</parameter> from
the van-der-Waals surfaces of the atoms.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.MolecularSurface.surfaceAtoms" xreflabel="MMTK.MolecularSurface.surfaceAtoms" role="Python"><funcprototype><funcdef><function>surfaceAtoms</function></funcdef>
<paramdef><parameter>self</parameter></paramdef>
<paramdef><parameter>probe_radius</parameter><defaultvalue>0.0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a dictionary that maps the surface atoms to their
exposed surface areas.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.MolecularSurface.surfacePointsAndGradients" xreflabel="MMTK.MolecularSurface.surfacePointsAndGradients" role="Python"><funcprototype><funcdef><function>surfacePointsAndGradients</function></funcdef>
<paramdef><parameter>self</parameter></paramdef>
<paramdef><parameter>probe_radius</parameter><defaultvalue>0.0</defaultvalue></paramdef>
<paramdef><parameter>point_density</parameter><defaultvalue>258</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a dictionary that maps the surface atoms to a tuple
containing three surface-related quantities: the exposed surface
are, a list of points in the exposed surface, and a gradient vector
pointing outward from the surface.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.MolecularSurface.findContacts" xreflabel="MMTK.MolecularSurface.findContacts" role="Python"><funcprototype><funcdef><function>findContacts</function></funcdef>
<paramdef><parameter>object1</parameter></paramdef>
<paramdef><parameter>object2</parameter></paramdef>
<paramdef><parameter>contact_factor</parameter><defaultvalue>1.0</defaultvalue></paramdef>
<paramdef><parameter>cutoff</parameter><defaultvalue>0.0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a list of MMTK.MolecularSurface.Contact objects
that describe atomic contacts between <parameter>object1</parameter> and <parameter>object2</parameter>.
A contact is defined as a pair of atoms whose distance is less than
|contact_factor|*(r1+r2+|cutoff|) where r1 and r2 are the atomic
van-der-Waals radii.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.NormalModes" xreflabel="MMTK.NormalModes">
<title>Module MMTK.NormalModes</title>

<para>See also the <xref linkend="Example:NormalModes"/> example applications.
</para>
<classdescription role="Python" id="Class:MMTK.NormalModes.Mode" xreflabel="MMTK.NormalModes.Mode">
<classdef><class>Mode</class><classinfo>Single normal mode</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ParticleVector"/>.</para>
<para>Mode objects are created by indexing a NormalModes object.
They contain the atomic displacements corresponding to a
single mode.</para>
<para>Mode objects are specializations of <xref linkend="Class:MMTK.ParticleVector"/>
objects and support all their operations. In addition, the
frequency corresponding to the mode is stored in the attribute
"frequency".</para>
<para>Note: the normal mode vectors are <emphasis>not</emphasis> mass weighted, and therefore
not orthogonal to each other.
</para>
<methoddescription><methoddef><method>view</method></methoddef>
<paramdef><parameter>factor</parameter><defaultvalue>1.0</defaultvalue></paramdef>
<paramdef><parameter>subset</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Start an animation of the mode. The displacements can be
scaled by a <parameter>factor</parameter> to make them better visible, and
a <parameter>subset</parameter> of the total system can be specified as well.
This function requires an external viewer, see module
<xref linkend="Module:MMTK.Visualization"/> for details.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NormalModes.NormalModes" xreflabel="MMTK.NormalModes.NormalModes">
<classdef><class>NormalModes</class><classinfo>Normal modes</classinfo></classdef>
<para>Constructor: NormalModes(<parameter>universe</parameter>, <parameter>temperature</parameter>=300)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the system for which the normal modes are calculated;
              it must have a force field which provides the second
              derivatives of the potential energy</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature for which the amplitudes of the
                 atomic displacement vectors are calculated. A
                 value of <literal role="Python">None</literal> can be specified to have no scaling
                 at all. In that case the mass-weighted norm
                 of each normal mode is one.</para></listitem></varlistentry>
</variablelist></para>
<para>In order to obtain physically reasonable normal modes, the configuration
of the universe must correspond to a local minimum of the potential
energy.</para>
<para>A NormalModes object behaves like a sequence of modes. Individual
modes (see class <xref linkend="Class:MMTK.NormalModes.Mode"/>) can be extracted by
indexing with an integer. Looping over the modes is possible as
well.
</para>
<methoddescription><methoddef><method>reduceToRange</method></methoddef>
<paramdef><parameter>first</parameter></paramdef>
<paramdef><parameter>last</parameter></paramdef>
<para>Discards all modes except for those whose numbers are between
<parameter>first</parameter> (inclusive) and <parameter>last</parameter> (exclusive). This is done to
reduce memory requirements, especially before saving the modes
to a file.</para>
</methoddescription>
<methoddescription><methoddef><method>fluctuations</method></methoddef>
<void/><para>Returns a <xref linkend="Class:MMTK.ParticleScalar"/> containing the thermal
fluctuations for each atom in the universe.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NormalModes.SparseMatrixNormalModes" xreflabel="MMTK.NormalModes.SparseMatrixNormalModes">
<classdef><class>SparseMatrixNormalModes</class><classinfo>Normal modes using a sparse matrix</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.NormalModes.NormalModes"/>.</para>
<para>This class differs from the class NormalModes in that it obtains
the Cartesian force constant matrix in a sparse-matrix format and
uses a sparse-matrix eigenvalue solver from the ARPACK library.
This is advantageous if the Cartesian force constant matrix is
sparse (as it is for force fields without long-range terms), but
for non-sparse matrices the memory requirements are higher than
for NormalModes. Note that the calculation time depends not only
on the size of the system, but also on its frequency spectrum,
because an iterative algorithm is used.</para>
<para>Constructor: SparseMatrixNormalModes(<parameter>universe</parameter>, <parameter>nmodes</parameter>,
                                     <parameter>temperature</parameter>=300)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the system for which the normal modes are calculated;
              it must have a force field which provides the second
              derivatives of the potential energy</para></listitem></varlistentry>
<varlistentry><term><parameter>nmodes</parameter></term>
<listitem><para>
the number of modes that is calculated. The calculation
            time can grow significantly with an increasing number
            of modes.</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature for which the amplitudes of the
                 atomic displacement vectors are calculated. A
                 value of <literal role="Python">None</literal> can be specified to have no scaling
                 at all. In that case the mass-weighted norm
                 of each normal mode is one.</para></listitem></varlistentry>
</variablelist></para>
<para>In order to obtain physically reasonable normal modes, the configuration
of the universe must correspond to a local minimum of the potential
energy.</para>
<para>A SparseMatrixNormalModes object behaves like a sequence of modes.
Individual modes (see class <xref linkend="Class:MMTK.NormalModes.Mode"/>) can be
extracted by indexing with an integer. Looping over the modes is
possible as well.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NormalModes.SubspaceNormalModes" xreflabel="MMTK.NormalModes.SubspaceNormalModes">
<classdef><class>SubspaceNormalModes</class><classinfo>Normal modes in a subspace</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.NormalModes.NormalModes"/>.</para>
<para>Constructor: SubspaceNormalModes(<parameter>universe</parameter>, <parameter>basis</parameter>, <parameter>temperature</parameter>=300)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the system for which the normal modes are calculated;
              it must have a force field which provides the second
              derivatives of the potential energy</para></listitem></varlistentry>
<varlistentry><term><parameter>basis</parameter></term>
<listitem><para>
the basis for the subspace in which the normal modes
           are calculated (or, more precisely, a set of vectors
           spanning the subspace; it does not have to be
           orthogonal). This can either be a sequence of
           <xref linkend="Class:MMTK.ParticleVector"/> objects or a tuple of two
           such sequences. In the second case, the subspace is
           defined by the space spanned by the first set of
           vectors projected on the complement of the space
           spanned by the second set of vectors. The second set
           thus defines directions that are excluded from the
           subspace.</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature for which the amplitudes of the
                 atomic displacement vectors are calculated. A
                 value of <literal role="Python">None</literal> can be specified to have no scaling
                 at all. In that case the mass-weighted norm
                 of each normal mode is one.</para></listitem></varlistentry>
</variablelist></para>
<para>In order to obtain physically reasonable normal modes, the configuration
of the universe must correspond to a local minimum of the potential
energy.</para>
<para>A SubspaceNormalModes object behaves like a sequence of modes.
Individual modes (see class <xref linkend="Class:MMTK.NormalModes.Mode"/>) can be
extracted by indexing with an integer. Looping over the modes is
possible as well.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NormalModes.FiniteDifferenceSubspaceNormalModes" xreflabel="MMTK.NormalModes.FiniteDifferenceSubspaceNormalModes">
<classdef><class>FiniteDifferenceSubspaceNormalModes</class><classinfo>Normal modes in a subspace with numerical differentiation</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.NormalModes.SubspaceNormalModes"/>.</para>
<para>This class differs from SubspaceNormalModes in the way it obtains
the force constant matrix. Instead of obtaining the full Cartesian
force constant matrix from the force field and projecting it on
the subspace, it performs a numerical differentiation of the
gradients along the basis vectors of the subspace. This is useful
in two cases:</para>
<itemizedlist>
<listitem><para>
for small subspaces this approach uses less memory, because
  the full Cartesian force constant matrix is not needed</para></listitem>
<listitem><para>
it can be used even if the force field does not provide second
  derivatives</para></listitem>
</itemizedlist>
<para>Constructor: FiniteDifferenceSubspaceNormalModes(<parameter>universe</parameter>,
                    <parameter>basis</parameter>, <parameter>delta</parameter>=0.0001, <parameter>temperature</parameter>=300)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the system for which the normal modes are calculated</para></listitem></varlistentry>
<varlistentry><term><parameter>basis</parameter></term>
<listitem><para>
the basis for the subspace in which the normal modes
           are calculated (or, more precisely, a set of vectors
           spanning the subspace; it does not have to be orthogonal).
           This can either be a sequence of ParticleVector objects
           or a tuple of two such sequences. In the second case,
           the subspace is defined by the space spanned by the
           first set of vectors projected on the complement of the
           space spanned by the second set of vectors. The second
           set thus defines directions that are excluded from
           the subspace.</para></listitem></varlistentry>
<varlistentry><term><parameter>delta</parameter></term>
<listitem><para>
the length of the displacement used for numerical
           differentiation</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature for which the amplitudes of the
                 atomic displacement vectors are calculated. A
                 value of <literal role="Python">None</literal> can be specified to have no scaling
                 at all. In that case the mass-weighted norm
                 of each normal mode is one.</para></listitem></varlistentry>
</variablelist></para>
<para>In order to obtain physically reasonable normal modes, the configuration
of the universe must correspond to a local minimum of the potential
energy.</para>
<para>A FiniteDifferenceSubspaceNormalModes object behaves like a
sequence of modes.
Individual modes (see class <xref linkend="Class:MMTK.NormalModes.Mode"/>) can be
extracted by indexing with an integer. Looping over the modes is
possible as well.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NormalModes.SparseMatrixSubspaceNormalModes" xreflabel="MMTK.NormalModes.SparseMatrixSubspaceNormalModes">
<classdef><class>SparseMatrixSubspaceNormalModes</class><classinfo>Normal modes in a subspace using a sparse matrix</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.NormalModes.SubspaceNormalModes"/>.</para>
<para>This class differs from SubspaceNormalModes in that it obtains
the Cartesian force constant matrix in a sparse-matrix format.
This is advantageous if the Cartesian force constant matrix
is sparse (as it is for force fields without long-range terms),
but for non-sparse matrices the memory requirements are
higher than for SubspaceNormalModes.</para>
<para>Constructor: SparseMatrixSubspaceNormalModes(<parameter>universe</parameter>, <parameter>basis</parameter>,
                                             <parameter>temperature</parameter>=300)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the system for which the normal modes are calculated;
              it must have a force field which provides the second
              derivatives of the potential energy</para></listitem></varlistentry>
<varlistentry><term><parameter>basis</parameter></term>
<listitem><para>
the basis for the subspace in which the normal modes
           are calculated (or, more precisely, a set of vectors
           spanning the subspace; it does not have to be orthogonal).
           This can either be a sequence of ParticleVector objects
           or a tuple of two such sequences. In the second case,
           the subspace is defined by the space spanned by the
           first set of vectors projected on the complement of the
           space spanned by the second set of vectors. The second
           set thus defines directions that are excluded from
           the subspace.</para></listitem></varlistentry>
<varlistentry><term><parameter>temperature</parameter></term>
<listitem><para>
the temperature for which the amplitudes of the
                 atomic displacement vectors are calculated. A
                 value of <literal role="Python">None</literal> can be specified to have no scaling
                 at all. In that case the mass-weighted norm
                 of each normal mode is one.</para></listitem></varlistentry>
</variablelist></para>
<para>In order to obtain physically reasonable normal modes, the configuration
of the universe must correspond to a local minimum of the potential
energy.</para>
<para>A SparseMatrixSubspaceNormalModes object behaves like a sequence
of modes.
Individual modes (see class <xref linkend="Class:MMTK.NormalModes.Mode"/>) can be
extracted by indexing with an integer. Looping over the modes is
possible as well.
</para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.NucleicAcids" xreflabel="MMTK.NucleicAcids">
<title>Module MMTK.NucleicAcids</title>

<classdescription role="Python" id="Class:MMTK.NucleicAcids.Nucleotide" xreflabel="MMTK.NucleicAcids.Nucleotide">
<classdef><class>Nucleotide</class><classinfo>Nucleic acid residue</classinfo></classdef>
<para>A subclass of <xref linkend="Class:MMTK.ChemicalObjects.Group"/>.</para>
<para>Nucleotides are a special kind of group. Like any other
group, they are defined in the chemical database. Each residue
has two or three subgroups (<literal role="Python">sugar</literal> and <literal role="Python">base</literal>, plus <literal role="Python">phosphate</literal>
except for 5'-terminal residues) and is usually
connected to other residues to form a nucleotide chain. The database
contains three variants of each residue (5'-terminal, 3'-terminal,
non-terminal).</para>
<para>Constructor: Nucleotide(<parameter>kind</parameter>, <parameter>model</parameter>="all")</para>
<para><variablelist>
<varlistentry><term><parameter>kind</parameter></term>
<listitem><para>
the name of the nucleotide in the chemical database. This
          is the full name of the residue plus the suffix
          "_5ter" or "_3ter" for the terminal variants.</para></listitem></varlistentry>
<varlistentry><term><parameter>model</parameter></term>
<listitem><para>
one of "all" (all-atom), "none" (no hydrogens),
           "polar" (united-atom with only polar hydrogens),
           "polar_charmm" (like "polar", but defining
           polar hydrogens like in the CHARMM force field).
           Currently the database has definitions only for "all".
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>backbone</method></methoddef>
<void/><para>Returns the sugar and phosphate groups.</para>
</methoddescription>
<methoddescription><methoddef><method>bases</method></methoddef>
<void/><para>Returns the base group.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NucleicAcids.NucleotideChain" xreflabel="MMTK.NucleicAcids.NucleotideChain">
<classdef><class>NucleotideChain</class><classinfo>Nucleotide chain</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Biopolymers.ResidueChain"/>.</para>
<para>Nucleotide chains consist of nucleotides that are linked together.
They are a special kind of molecule, i.e. all molecule operations
are available.</para>
<para>Constructor: NucleotideChain(<parameter>sequence</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>sequence</parameter></term>
<listitem><para>
the nucleotide sequence. This can be a list
              of two-letter codes (a "d" or "r" for the type of
              sugar, and the one-letter base code), or a
              PDBNucleotideChain object.
              If a PDBNucleotideChain object is supplied, the atomic
              positions it contains are assigned to the atoms
              of the newly generated nucleotide chain, otherwise the
              positions of all atoms are undefined.</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:</para></listitem></varlistentry>
</variablelist></para>
<itemizedlist>
<listitem><para>
model: one of "all" (all-atom), "no_hydrogens" or "none" (no hydrogens),
         "polar_hydrogens" or "polar" (united-atom with only polar
         hydrogens), "polar_charmm" (like "polar", but defining
         polar hydrogens like in the CHARMM force field). Default
         is "all". Currently the database contains definitions only
         for "all".</para></listitem>
<listitem><para>
terminus_5: 1 if the first nucleotide should be constructed using the
              5'-terminal variant, 0 if the non-terminal version should
              be used. Default is 1.</para></listitem>
<listitem><para>
terminus_3: 1 if the last residue should be constructed using the
              3'-terminal variant, 0 if the non-terminal version should
              be used. Default is 1.</para></listitem>
<listitem><para>
circular: 1 if a bond should be constructed between the first
            and the last residue. Default is 0.</para></listitem>
<listitem><para>
name: a name for the chain (a string)</para></listitem>
</itemizedlist>
<para>Nucleotide chains act as sequences of residues. If <literal role="Python">n</literal> is a NucleotideChain
object, then</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(n)</literal> yields the number of nucleotides</para></listitem>
<listitem><para>
<literal role="Python">n[i]</literal> yields nucleotide number <literal role="Python">i</literal> (counting from zero)</para></listitem>
<listitem><para>
<literal role="Python">n[i:j]</literal> yields the subchain from nucleotide number <literal role="Python">i</literal> up to but
           excluding nucleotide number <literal role="Python">j</literal>
</para></listitem>
</itemizedlist>
<methoddescription><methoddef><method>backbone</method></methoddef>
<void/><para>Returns a collection containing the sugar and phosphate groups
of all nucleotides.</para>
</methoddescription>
<methoddescription><methoddef><method>bases</method></methoddef>
<void/><para>Returns a collection containing the base groups of all nucleotides.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.NucleicAcids.NucleotideSubChain" xreflabel="MMTK.NucleicAcids.NucleotideSubChain">
<classdef><class>NucleotideSubChain</class><classinfo>A contiguous part of a nucleotide chain</classinfo></classdef>
<para>NucleotideSubChain objects are the result of slicing operations on
NucleotideChain objects. They cannot be created directly.
NucleotideSubChain objects permit all operations of NucleotideChain
objects, but cannot be added to a universe.
</para>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.NucleicAcids.isNucleotideChain" xreflabel="MMTK.NucleicAcids.isNucleotideChain" role="Python"><funcprototype><funcdef><function>isNucleotideChain</function></funcdef>
<paramdef><parameter>x</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>x</parameter> is a NucleotideChain.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.PDB" xreflabel="MMTK.PDB">
<title>Module MMTK.PDB</title>

<para>This module provides classes that represent molecules in PDB file.
They permit various manipulations and the creation of MMTK objects.
Note that the classes defined in this module are specializations
of classed defined in Scientific.IO.PDB; the methods defined in
that module are also available.
</para>
<classdescription role="Python" id="Class:MMTK.PDB.PDBPeptideChain" xreflabel="MMTK.PDB.PDBPeptideChain">
<classdef><class>PDBPeptideChain</class><classinfo>Peptide chain in a PDB file</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of Scientific.IO.PDB.PeptideChain.
See the description of that class for the constructor and
additional methods. In MMTK, PDBPeptideChain objects
are usually obtained from a PDBConfiguration object
via its attribute peptide_chains (see the documentation
of Scientific.IO.PDB.Structure).
</para>
<methoddescription><methoddef><method>createPeptideChain</method></methoddef>
<paramdef><parameter>model</parameter><defaultvalue>'all'</defaultvalue></paramdef>
<paramdef><parameter>n_terminus</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>c_terminus</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a PeptideChain object corresponding to the
peptide chain in the PDB file. The parameter <parameter>model</parameter>
has the same meaning as for the PeptideChain constructor.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PDB.PDBNucleotideChain" xreflabel="MMTK.PDB.PDBNucleotideChain">
<classdef><class>PDBNucleotideChain</class><classinfo>Nucleotide chain in a PDB file</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of Scientific.IO.PDB.NucleotideChain. See
the description of that class for the constructor and
additional methods. In MMTK, PDBNucleotideChain objects
are usually obtained from a PDBConfiguration object
via its attribute nucleotide_chains (see the documentation
of Scientific.IO.PDB.Structure).
</para>
<methoddescription><methoddef><method>createNucleotideChain</method></methoddef>
<paramdef><parameter>model</parameter><defaultvalue>'all'</defaultvalue></paramdef>
<para>Returns a NucleotideChain object corresponding to the
nucleotide chain in the PDB file. The parameter <parameter>model</parameter>
has the same meaning as for the NucleotideChain constructor.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PDB.PDBMolecule" xreflabel="MMTK.PDB.PDBMolecule">
<classdef><class>PDBMolecule</class><classinfo>Molecule in a PDB file</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of Scientific.IO.PDB.Molecule. See
the description of that class for the constructor and
additional methods. In MMTK, PDBMolecule objects
are usually obtained from a PDBConfiguration object
via its attribute molecules (see the documentation
of Scientific.IO.PDB.Structure). A molecule is by definition
any residue in a PDB file that is not an amino acid or
nucleotide residue.
</para>
<methoddescription><methoddef><method>createMolecule</method></methoddef>
<paramdef><parameter>name</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a Molecule object corresponding to the molecule
in the PDB file. The parameter <parameter>name</parameter> specifies the molecule
name as defined in the chemical database. It can be left out
for known molecules (currently only water).</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PDB.PDBConfiguration" xreflabel="MMTK.PDB.PDBConfiguration">
<classdef><class>PDBConfiguration</class><classinfo>Everything in a PDB file</classinfo></classdef>
<para>A PDBConfiguration object represents the full contents of a PDB
file. It can be used to create MMTK objects for all or part
of the molecules, or to change the configuration of an existing
system.</para>
<para>Constructor: PDBConfiguration(<parameter>filename</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>filename</parameter></term>
<listitem><para>
the name of a PDB file
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>createPeptideChains</method></methoddef>
<paramdef><parameter>model</parameter><defaultvalue>'all'</defaultvalue></paramdef>
<para>Returns a list of PeptideChain objects, one for each
peptide chain in the PDB file. The parameter <parameter>model</parameter>
has the same meaning as for the PeptideChain constructor.</para>
</methoddescription>
<methoddescription><methoddef><method>createNucleotideChains</method></methoddef>
<paramdef><parameter>model</parameter><defaultvalue>'all'</defaultvalue></paramdef>
<para>Returns a list of NucleotideChain objects, one for each
nucleotide chain in the PDB file. The parameter <parameter>model</parameter>
has the same meaning as for the NucleotideChain constructor.</para>
</methoddescription>
<methoddescription><methoddef><method>createMolecules</method></methoddef>
<paramdef><parameter>names</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>permit_undefined</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Returns a collection of Molecule objects, one for each
molecule in the PDB file. Each PDB residue not describing
an amino acid or nucleotide residue is considered a molecule.</para>
<para>The parameter <parameter>names</parameter> allows the selective construction of
certain molecule types and the construction of unknown
molecules. If its value is a list of molecule names
(as defined in the chemical database) and/or PDB residue
names, only molecules mentioned in this list will be
constructed. If its value is a dictionary, it is used
to map PDB residue names to molecule names. By default only
water molecules are recognizes (under various common PDB residue
names); for all other molecules a molecule name must be provided
by the user.</para>
<para>The parameter <parameter>permit_undefined</parameter> determines how PDB residues
without a corresponding molecule name are handled. A value
of 0 causes an exception to be raised. A value of 1 causes
an AtomCluster object to be created for each unknown residue.
</para>
</methoddescription>
<methoddescription><methoddef><method>createAll</method></methoddef>
<paramdef><parameter>molecule_names</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>permit_undefined</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Returns a collection containing all objects contained in
the PDB file, i.e. the combination of the objects returned
by createPeptideChains(), createNucleotideChains(), and
createMolecules(). The parameters have the same meaning
as for createMolecules().</para>
</methoddescription>
<methoddescription><methoddef><method>applyTo</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<para>Sets the configuration of <parameter>object</parameter> from the coordinates in the
PDB file. The object must be compatible with the PDB file, i.e.
contain the same subobjects and in the same order. This is usually
only guaranteed if the object was created by the method
createAll() from a PDB file with the same layout.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.PDB.PDBOutputFile" xreflabel="MMTK.PDB.PDBOutputFile">
<classdef><class>PDBOutputFile</class><classinfo>PDB file for output</classinfo></classdef>
<para>Constructor: PDBOutputFile(<parameter>filename</parameter>, <parameter>subformat</parameter>=<literal role="Python">None</literal>)</para>
<para><variablelist>
<varlistentry><term><parameter>filename</parameter></term>
<listitem><para>
the name of the PDB file that is created</para></listitem></varlistentry>
<varlistentry><term><parameter>subformat</parameter></term>
<listitem><para>
a variant of the PDB format; these subformats
               are defined in module Scientific.IO.PDB. The
               default is the standard PDB format.
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>write</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>configuration</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>tag</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Writes <parameter>object</parameter> to the file, using coordinates from
<parameter>configuration</parameter> (defaults to the current configuration).
The parameter <parameter>tag</parameter> is reserved for internal use.</para>
</methoddescription>
<methoddescription><methoddef><method>close</method></methoddef>
<void/><para>Closes the file. Must be called in order to prevent data loss.</para>
</methoddescription>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.ParticleProperties" xreflabel="MMTK.ParticleProperties">
<title>Module MMTK.ParticleProperties</title>

<classdescription role="Python" id="Class:MMTK.ParticleProperties.ParticleProperty" xreflabel="MMTK.ParticleProperties.ParticleProperty">
<classdef><class>ParticleProperty</class><classinfo>Property defined for each particle</classinfo></classdef>
<para>This is an abstract base class; for creating instances, use one of
its subclasses: <xref linkend="Class:MMTK.ParticleScalar"/>, <xref linkend="Class:MMTK.ParticleVector"/>,
<xref linkend="Class:MMTK.ParticleTensor"/>.</para>
<para>ParticleProperty objects store properties that are defined per
particle, such as mass, position, velocity, etc. The value
corresponding to a particular atom can be retrieved or changed by
indexing with the atom object.
</para>
<methoddescription><methoddef><method>zero</method></methoddef>
<void/><para>Returns an object of the element type (scalar, vector, etc.)
with the value 0.</para>
</methoddescription>
<methoddescription><methoddef><method>sumOverParticles</method></methoddef>
<void/><para>Returns the sum of the values for all particles.</para>
</methoddescription>
<methoddescription><methoddef><method>assign</method></methoddef>
<paramdef><parameter>other</parameter></paramdef>
<para>Copy all values from <parameter>other</parameter>, which must be a compatible
ParticleProperty object.</para>
</methoddescription>
<methoddescription><methoddef><method>scaleBy</method></methoddef>
<paramdef><parameter>factor</parameter></paramdef>
<para>Multiply all values by <parameter>factor</parameter> (a number).</para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.ParticleProperties.isParticleProperty" xreflabel="MMTK.ParticleProperties.isParticleProperty" role="Python"><funcprototype><funcdef><function>isParticleProperty</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>object</parameter> is a ParticleProperty.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.ParticleProperties.isConfiguration" xreflabel="MMTK.ParticleProperties.isConfiguration" role="Python"><funcprototype><funcdef><function>isConfiguration</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>object</parameter> is a Configuration.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Proteins" xreflabel="MMTK.Proteins">
<title>Module MMTK.Proteins</title>

<classdescription role="Python" id="Class:MMTK.Proteins.Residue" xreflabel="MMTK.Proteins.Residue">
<classdef><class>Residue</class><classinfo>Amino acid residue</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.ChemicalObjects.Group"/>.</para>
<para>Amino acid residues are a special kind of group. Like any other
group, they are defined in the chemical database. Each residue
has two subgroups (<literal role="Python">peptide</literal> and <literal role="Python">sidechain</literal>) and is usually
connected to other residues to form a peptide chain. The database
contains three variants of each residue (N-terminal, C-terminal,
non-terminal) and various models (all-atom, united-atom,
C_alpha).</para>
<para>Constructor: Residue(<parameter>kind</parameter>, <parameter>model</parameter>="all")</para>
<para><variablelist>
<varlistentry><term><parameter>kind</parameter></term>
<listitem><para>
the name of the residue in the chemical database. This
          is the full name of the residue plus the suffix
          "_nt" or "_ct" for the terminal variants.</para></listitem></varlistentry>
<varlistentry><term><parameter>model</parameter></term>
<listitem><para>
one of "all" (all-atom), "none" (no hydrogens),
           "polar" (united-atom with only polar hydrogens),
           "polar_charmm" (like "polar", but defining
           polar hydrogens like in the CHARMM force field),
           "polar_opls" (like "polar", but defining
           polar hydrogens like in the latest OPLS force field),
           "calpha" (only the C_alpha atom)
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>backbone</method></methoddef>
<void/><para>Returns the peptide group.</para>
</methoddescription>
<methoddescription><methoddef><method>sidechains</method></methoddef>
<void/><para>Returns the sidechain group.</para>
</methoddescription>
<methoddescription><methoddef><method>phiPsi</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the values of the backbone dihedral angles phi and psi.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Proteins.PeptideChain" xreflabel="MMTK.Proteins.PeptideChain">
<classdef><class>PeptideChain</class><classinfo>Peptide chain</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Biopolymers.ResidueChain"/>.</para>
<para>Peptide chains consist of amino acid residues that are linked
by peptide bonds. They are a special kind of molecule, i.e.
all molecule operations are available.</para>
<para>Constructor: PeptideChain(<parameter>sequence</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>sequence</parameter></term>
<listitem><para>
the amino acid sequence. This can be a string
              containing the one-letter codes, or a list
              of three-letter codes, or a PDBPeptideChain object.
              If a PDBPeptideChain object is supplied, the atomic
              positions it contains are assigned to the atoms
              of the newly generated peptide chain, otherwise the
              positions of all atoms are undefined.</para></listitem></varlistentry>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:</para></listitem></varlistentry>
</variablelist></para>
<itemizedlist>
<listitem><para>
model: one of "all" (all-atom), "no_hydrogens" or "none" (no hydrogens),
         "polar_hydrogens" or "polar" (united-atom with only polar
         hydrogens), "polar_charmm" (like "polar", but defining
         polar hydrogens like in the CHARMM force field),
         "polar_opls" (like "polar", but defining
         polar hydrogens like in the latest OPLS force field),
         "calpha" (only the C_alpha atom of each residue). Default
         is "all".</para></listitem>
<listitem><para>
n_terminus: 1 if the first residue should be constructed using the
              N-terminal variant, 0 if the non-terminal version should
              be used. Default is 1.</para></listitem>
<listitem><para>
c_terminus: 1 if the last residue should be constructed using the
              C-terminal variant, 0 if the non-terminal version should
              be used. Default is 1.</para></listitem>
<listitem><para>
circular: 1 if a peptide bond should be constructed between the first
            and the last residue. Default is 0.</para></listitem>
<listitem><para>
name: a name for the chain (a string)</para></listitem>
</itemizedlist>
<para>Peptide chains act as sequences of residues. If <literal role="Python">p</literal> is a PeptideChain
object, then</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(p)</literal> yields the number of residues</para></listitem>
<listitem><para>
<literal role="Python">p[i]</literal> yields residue number <literal role="Python">i</literal> (counting from zero)</para></listitem>
<listitem><para>
<literal role="Python">p[i:j]</literal> yields the subchain from residue number <literal role="Python">i</literal> up to but excluding
           residue number <literal role="Python">j</literal>
</para></listitem>
</itemizedlist>
<methoddescription><methoddef><method>sequence</method></methoddef>
<void/><para>Returns the primary sequence as a list of three-letter residue
codes.</para>
</methoddescription>
<methoddescription><methoddef><method>backbone</method></methoddef>
<void/><para>Returns a collection containing the peptide groups of all residues.</para>
</methoddescription>
<methoddescription><methoddef><method>sidechains</method></methoddef>
<void/><para>Returns a collection containing the sidechain groups of all residues.</para>
</methoddescription>
<methoddescription><methoddef><method>phiPsi</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a list of the (phi, psi) backbone angle pairs
for each residue.</para>
</methoddescription>
<methoddescription><methoddef><method>replaceResidue</method></methoddef>
<paramdef><parameter>r_old</parameter></paramdef>
<paramdef><parameter>r_new</parameter></paramdef>
<para>Replaces residue <parameter>r_old</parameter>, which must be a residue object that
is part of the chain, by the residue object <parameter>r_new</parameter>.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Proteins.SubChain" xreflabel="MMTK.Proteins.SubChain">
<classdef><class>SubChain</class><classinfo>A contiguous part of a peptide chain</classinfo></classdef>
<para>SubChain objects are the result of slicing operations on
PeptideChain objects. They cannot be created directly.
SubChain objects permit all operations of PeptideChain
objects, but cannot be added to a universe.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Proteins.Protein" xreflabel="MMTK.Proteins.Protein">
<classdef><class>Protein</class><classinfo>Protein</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Complex"/>.</para>
<para>A Protein object is a special kind of a Complex object which
is made up of peptide chains.</para>
<para>Constructor: Protein(<parameter>specification</parameter>, **|properties|)</para>
<para><variablelist>
<varlistentry><term><parameter>specification</parameter></term>
<listitem><para>
one of:</para></listitem></varlistentry>
</variablelist></para>
<itemizedlist>
<listitem><para>
a list of peptide chain objects</para></listitem>
<listitem><para>
a string, which is interpreted as the name of a database definition
  for a protein. If that definition does not exist, the string
  is taken to be the name of a PDB file, from which all peptide chains
  are constructed and assembled into a protein.</para></listitem>
</itemizedlist>
<para><variablelist>
<varlistentry><term><parameter>properties</parameter></term>
<listitem><para>
optional keyword properties:</para></listitem></varlistentry>
</variablelist></para>
<itemizedlist>
<listitem><para>
model: one of "all" (all-atom), "no_hydrogens" or "none" (no hydrogens),
         "polar_hydrogens" or "polar" (united-atom with only polar
         hydrogens), "polar_charmm" (like "polar", but defining
         polar hydrogens like in the CHARMM force field),
         "polar_opls" (like "polar", but defining
         polar hydrogens like in the latest OPLS force field),
         "calpha" (only the C_alpha atom of each residue). Default
         is "all".</para></listitem>
<listitem><para>
position: the center-of-mass position of the protein (a vector)</para></listitem>
<listitem><para>
name: a name for the protein (a string)</para></listitem>
</itemizedlist>
<para>If the atoms in the peptide chains that make up a protein have
defined positions, sulfur bridges within chains and between
chains will be constructed automatically during protein generation
based on a distance criterion between cystein sidechains.</para>
<para>Proteins act as sequences of chains. If <literal role="Python">p</literal> is a Protein object, then</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(p)</literal> yields the number of chains</para></listitem>
<listitem><para>
<literal role="Python">p[i]</literal> yields chain number <literal role="Python">i</literal> (counting from zero)
</para></listitem>
</itemizedlist>
<methoddescription><methoddef><method>residuesOfType</method></methoddef>
<paramdef><parameter>*types</parameter></paramdef>
<para>Returns a collection that contains all residues whose type
(one- or three-letter code) is contained in <parameter>types</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>backbone</method></methoddef>
<void/><para>Returns a collection containing the peptide groups of all residues
in all chains.</para>
</methoddescription>
<methoddescription><methoddef><method>sidechains</method></methoddef>
<void/><para>Returns a collection containing the sidechain groups of all
residues in all chains.</para>
</methoddescription>
<methoddescription><methoddef><method>residues</method></methoddef>
<void/><para>Returns a collection containing all residues in all chains.</para>
</methoddescription>
<methoddescription><methoddef><method>phiPsi</method></methoddef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a list containing the phi/psi backbone dihedrals for
all chains.</para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Proteins.isPeptideChain" xreflabel="MMTK.Proteins.isPeptideChain" role="Python"><funcprototype><funcdef><function>isPeptideChain</function></funcdef>
<paramdef><parameter>x</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 f <parameter>x</parameter> is a peptide chain.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Proteins.isProtein" xreflabel="MMTK.Proteins.isProtein" role="Python"><funcprototype><funcdef><function>isProtein</function></funcdef>
<paramdef><parameter>x</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 f <parameter>x</parameter> is a protein.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Random" xreflabel="MMTK.Random">
<title>Module MMTK.Random</title>

<para>This module defines various random quantities that are useful in
molecular simulations. For obtaining random numbers, it tries to use
the RNG module, which is part of the LLNL package distribution, which
also contains Numerical Python. If RNG is not available, it
uses the random number generators in modules RandomArray (part of
Numerical Python) and whrandom (in the Python standard library).
</para>
<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomPointInBox" xreflabel="MMTK.Random.randomPointInBox" role="Python"><funcprototype><funcdef><function>randomPointInBox</function></funcdef>
<paramdef><parameter>a</parameter></paramdef>
<paramdef><parameter>b</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>c</parameter><defaultvalue>None</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a vector drawn from a uniform distribution within a
rectangular box with edge lengths <parameter>a</parameter>, <parameter>b</parameter>, <parameter>c</parameter>. If <parameter>b</parameter> and/or <parameter>c</parameter>
are omitted, they are taken to be equal to <parameter>a</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomPointInSphere" xreflabel="MMTK.Random.randomPointInSphere" role="Python"><funcprototype><funcdef><function>randomPointInSphere</function></funcdef>
<paramdef><parameter>r</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a vector drawn from a uniform distribution within
a sphere of radius <parameter>r</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomDirection" xreflabel="MMTK.Random.randomDirection" role="Python"><funcprototype><funcdef><function>randomDirection</function></funcdef>
<void/></funcprototype></funcsynopsis>
</para>
<para>Returns a vector drawn from a uniform distribution on
the surface of a unit sphere.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomDirections" xreflabel="MMTK.Random.randomDirections" role="Python"><funcprototype><funcdef><function>randomDirections</function></funcdef>
<paramdef><parameter>n</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a list of <parameter>n</parameter> vectors drawn from a uniform distribution on
the surface of a unit sphere. If <parameter>n</parameter> is negative, return a deterministic
list of not more than -|n| vectors of unit length (useful for
testing purposes).</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomRotation" xreflabel="MMTK.Random.randomRotation" role="Python"><funcprototype><funcdef><function>randomRotation</function></funcdef>
<paramdef><parameter>max_angle</parameter><defaultvalue>3.1415926535897931</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a Rotation object describing a random rotation
with a uniform axis distribution and angles drawn from
a uniform distribution between -|max_angle| and <parameter>max_angle</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomVelocity" xreflabel="MMTK.Random.randomVelocity" role="Python"><funcprototype><funcdef><function>randomVelocity</function></funcdef>
<paramdef><parameter>temperature</parameter></paramdef>
<paramdef><parameter>mass</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a random velocity vector for a particle of a given
<parameter>mass</parameter>, drawn from a Boltzmann distribution for the given
<parameter>temperature</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Random.randomParticleVector" xreflabel="MMTK.Random.randomParticleVector" role="Python"><funcprototype><funcdef><function>randomParticleVector</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>width</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns a ParticleVector object in which each vector is
drawn from a Gaussian distribution with a given <parameter>width</parameter> centered
around zero.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Solvation" xreflabel="MMTK.Solvation">
<title>Module MMTK.Solvation</title>

<para>See also the example <xref linkend="Example:MolecularDynamics:solvation.py"/>.
</para>
<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Solvation.numberOfSolventMolecules" xreflabel="MMTK.Solvation.numberOfSolventMolecules" role="Python"><funcprototype><funcdef><function>numberOfSolventMolecules</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>solvent</parameter></paramdef>
<paramdef><parameter>density</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns the number of solvent molecules of type <parameter>solvent</parameter>
that must be added to <parameter>universe</parameter>, in addition to whatever it
contains already, to obtain the specified solvent <parameter>density</parameter>.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Solvation.addSolvent" xreflabel="MMTK.Solvation.addSolvent" role="Python"><funcprototype><funcdef><function>addSolvent</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>solvent</parameter></paramdef>
<paramdef><parameter>density</parameter></paramdef>
<paramdef><parameter>scale_factor</parameter><defaultvalue>4.0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Scales up the universe by <parameter>scale_factor</parameter> and adds as many
molecules of type <parameter>solvent</parameter> (a molecul object or a string)
as are necessary to obtain the specified solvent <parameter>density</parameter>,
taking account of the solute molecules that are already present
in the universe. The molecules are placed at random positions
in the scaled-up universe, but without overlaps between
any two molecules.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Solvation.shrinkUniverse" xreflabel="MMTK.Solvation.shrinkUniverse" role="Python"><funcprototype><funcdef><function>shrinkUniverse</function></funcdef>
<paramdef><parameter>universe</parameter></paramdef>
<paramdef><parameter>temperature</parameter><defaultvalue>300.0</defaultvalue></paramdef>
<paramdef><parameter>trajectory</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>scale_factor</parameter><defaultvalue>0.94999999999999996</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Shrinks <parameter>universe</parameter>, which must have been scaled up by
Function:MMTK.Solvation.addSolvent, back to its original size.
The compression is performed in small steps, in between which
some energy minimization and molecular dynamics steps are executed.
The molecular dynamics is run at the given <parameter>temperature</parameter>, and
an optional <parameter>trajectory</parameter> (a MMTK.Trajectory.Trajectory object or
a string, interpreted as a file name) can be specified in which
intermediate configurations are stored.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Subspace" xreflabel="MMTK.Subspace">
<title>Module MMTK.Subspace</title>

<para>This module implements subspaces for infinitesimal (or finite
small-amplitude) atomic motions. They can be used in normal mode
calculations (see example <xref linkend="Example:NormalModes:constrained_modes.py"/>) or
for analyzing complex motions [<xref linkend="Article:Hinsen1999a"/>].
</para>
<classdescription role="Python" id="Class:MMTK.Subspace.Subspace" xreflabel="MMTK.Subspace.Subspace">
<classdef><class>Subspace</class><classinfo>Subspace of infinitesimal atomic motions</classinfo></classdef>
<para>Constructor: Subspace(<parameter>universe</parameter>, <parameter>vectors</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the subspace is created</para></listitem></varlistentry>
<varlistentry><term><parameter>vectors</parameter></term>
<listitem><para>
a list of <xref linkend="Class:MMTK.ParticleVector"/> objects
             that define the subspace. They need not be orthogonal
             or linearly independent.
</para></listitem></varlistentry>
</variablelist></para>
<methoddescription><methoddef><method>getBasis</method></methoddef>
<void/><para>Returns a basis for the subspace, which is obtained
by orthonormalization of the input vectors using Singular
Value Decomposition. The basis consists of a sequence
of <xref linkend="Class:MMTK.ParticleVector"/> objects that are orthonormal
in configuration space.</para>
</methoddescription>
<methoddescription><methoddef><method>projectionOf</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Returns the projection of <parameter>vector</parameter> (a <xref linkend="Class:MMTK.ParticleVector"/>
object) onto the subspace.</para>
</methoddescription>
<methoddescription><methoddef><method>projectionComplementOf</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Returns the projection of <parameter>vector</parameter> (a <xref linkend="Class:MMTK.ParticleVector"/>
object) onto the orthogonal complement of the subspace.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Subspace.RigidMotionSubspace" xreflabel="MMTK.Subspace.RigidMotionSubspace">
<classdef><class>RigidMotionSubspace</class><classinfo>Subspace of rigid-body motions</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Subspace.Subspace"/>.</para>
<para>A rigid-body motion subspace is the subspace which contains
the rigid-body motions of any number of chemical objects.</para>
<para>Constructor: RigidMotionSubspace(<parameter>universe</parameter>, <parameter>objects</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the subspace is created</para></listitem></varlistentry>
<varlistentry><term><parameter>objects</parameter></term>
<listitem><para>
a sequence of objects whose rigid-body motion is
             included in the subspace
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Subspace.PairDistanceSubspace" xreflabel="MMTK.Subspace.PairDistanceSubspace">
<classdef><class>PairDistanceSubspace</class><classinfo>Subspace of pair-distance motions</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Subspace.Subspace"/>.</para>
<para>A pair-distance motion subspace is the subspace which contains
the relative motions of any number of atom pairs along
their distance vector, e.g. bond elongation between two
bonded atoms.</para>
<para>Constructor: PairDistanceSubspace(<parameter>universe</parameter>, <parameter>atom_pairs</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe for which the subspace is created</para></listitem></varlistentry>
<varlistentry><term><parameter>atom_pairs</parameter></term>
<listitem><para>
a sequence of atom pairs whose distance-vector
                motion is included in the subspace
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

</sect1>

<sect1 id="Module:MMTK.Trajectory" xreflabel="MMTK.Trajectory">
<title>Module MMTK.Trajectory</title>

<classdescription role="Python" id="Class:MMTK.Trajectory.Trajectory" xreflabel="MMTK.Trajectory.Trajectory">
<classdef><class>Trajectory</class><classinfo>Trajectory file</classinfo></classdef>
<para>Constructor: Trajectory(<parameter>object</parameter>, <parameter>filename</parameter>, <parameter>mode</parameter>="r",
                        <parameter>comment</parameter>=None, <parameter>double_precision</parameter>=0, <parameter>cycle</parameter>=0,
                        <parameter>block_size</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>object</parameter></term>
<listitem><para>
the object whose data is stored in the trajectory file.
            This can be <literal role="Python">None</literal> when opening a file for reading;
            in that case, a universe object is constructed from the
            description stored in the trajectory file. This universe
            object can be accessed via the attribute <literal role="Python">universe</literal>
            of the trajectory object.</para></listitem></varlistentry>
<varlistentry><term><parameter>filename</parameter></term>
<listitem><para>
the name of the trajectory file</para></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter></term>
<listitem><para>
one of "r" (read-only), "w" (create new file for writing),
          or "a" (append to existing file or create if the file does
          not exist)</para></listitem></varlistentry>
<varlistentry><term><parameter>comment</parameter></term>
<listitem><para>
optional comment that is stored in the file; allowed only
             with mode="r"</para></listitem></varlistentry>
<varlistentry><term><parameter>double_precision</parameter></term>
<listitem><para>
if non-zero, data in the file is stored using
                      double precision; default is single precision.
                      Note that all I/O via trajectory objects is
                      double precision; conversion from and to single
                      precision file variables is handled automatically.</para></listitem></varlistentry>
<varlistentry><term><parameter>cycle</parameter></term>
<listitem><para>
if non-zero, a trajectory is created for a fixed number
           of steps equal to the value of <parameter>cycle</parameter>, and these steps
           are used cyclically. This is meant for restart trajectories.</para></listitem></varlistentry>
<varlistentry><term><parameter>block_size</parameter></term>
<listitem><para>
an optimization parameter that influences the file
                structure and the I/O performance for very large
                files. A block size of 1 is optimal for sequential
                access to configurations etc., whereas a block size
                equal to the number of steps is optimal for reading
                coordinates or scalar variables along the time axis.
                The default value is 1. Note that older MMTK releases
                always used a block size of 1 and cannot handle
                trajectories with different block sizes.</para></listitem></varlistentry>
</variablelist></para>
<para>The data in a trajectory file can be accessed by step or by
variable. If <literal role="Python">t</literal> is a Trajectory object, then:</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(t)</literal> is the number of steps</para></listitem>
<listitem><para>
<literal role="Python">t[i]</literal> is the data for step i, in the form of a dictionary that
  maps variable names to data</para></listitem>
<listitem><para>
<literal role="Python">t[i:j]</literal> and <literal role="Python">t[i:j:n]</literal> return a SubTrajectory object that refers
   to a subset of the total number of steps (no data is copied)</para></listitem>
<listitem><para>
<literal role="Python">t.variable</literal> returns the value of the named variable at all
  time steps. If the variable is a simple scalar, it is read
  completely and returned as an array. If the variable contains
  data for each atom, a TrajectoryVariable object is returned
  from which data at specific steps can be obtained by further
  indexing operations.</para></listitem>
</itemizedlist>
<para>The routines that generate trajectories decide what variables
are used and what they contain. The most frequently used variable
is "configuration", which stores the positions of all atoms.
Other common variables are "time", "velocities", "temperature",
"pressure", and various energy terms whose name end with "_energy".
</para>
<methoddescription><methoddef><method>close</method></methoddef>
<void/><para>Close the trajectory file. Must be called after writing to
ensure that all buffered data is written to the file. No data
access is possible after closing a file.</para>
</methoddescription>
<methoddescription><methoddef><method>readParticleTrajectory</method></methoddef>
<paramdef><parameter>atom</parameter></paramdef>
<paramdef><parameter>first</parameter><defaultvalue>0</defaultvalue></paramdef>
<paramdef><parameter>last</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>skip</parameter><defaultvalue>1</defaultvalue></paramdef>
<paramdef><parameter>variable</parameter><defaultvalue>'configuration'</defaultvalue></paramdef>
<para>Read the values of the specified <parameter>variable</parameter> for the specified
<parameter>atom</parameter> at all time steps from <parameter>first</parameter> to <parameter>last</parameter> with an
increment of <parameter>skip</parameter>. The result is a ParticleTrajectory object.
If the variable is "configuration", the resulting trajectory
is made continuous by eliminating all jumps caused by periodic
boundary conditions. The pseudo-variable "box_coordinates"
can be read to obtain the values of the variable "configuration"
scaled to box coordinates. For non-periodic universes there is
no difference between box coordinates and real coordinates.</para>
</methoddescription>
<methoddescription><methoddef><method>readRigidBodyTrajectory</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>first</parameter><defaultvalue>0</defaultvalue></paramdef>
<paramdef><parameter>last</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>skip</parameter><defaultvalue>1</defaultvalue></paramdef>
<paramdef><parameter>reference</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Read the positions for the specified <parameter>object</parameter> at all time steps
from <parameter>first</parameter> to <parameter>last</parameter> with an increment of <parameter>skip</parameter> and extract
the rigid-body motion (center-of-mass position plus orientation as
a quaternion) by an optimal-transformation fit. The result is a
RigidBodyTrajectory object.</para>
</methoddescription>
<methoddescription><methoddef><method>variables</method></methoddef>
<void/><para>Returns a list of the names of all variables that are stored
in the trajectory.</para>
</methoddescription>
<methoddescription><methoddef><method>view</method></methoddef>
<paramdef><parameter>first</parameter><defaultvalue>0</defaultvalue></paramdef>
<paramdef><parameter>last</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>step</parameter><defaultvalue>1</defaultvalue></paramdef>
<paramdef><parameter>object</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Show an animation of <parameter>object</parameter> using the positions in the
trajectory at all time steps from <parameter>first</parameter> to <parameter>last</parameter> with an
increment of <parameter>skip</parameter>. <parameter>object</parameter> defaults to the entire universe.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.SubTrajectory" xreflabel="MMTK.Trajectory.SubTrajectory">
<classdef><class>SubTrajectory</class><classinfo>Reference to a subset of a trajectory</classinfo></classdef>
<para>A SubTrajectory object is created by slicing a Trajectory object
or another SubTrajectory object. It provides all the operations
defined on Trajectory objects.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.TrajectoryVariable" xreflabel="MMTK.Trajectory.TrajectoryVariable">
<classdef><class>TrajectoryVariable</class><classinfo>Variable in a trajectory</classinfo></classdef>
<para>A TrajectoryVariable object is created by extracting a variable from
a Trajectory object if that variable contains data for each atom and
is thus potentially large. No data is read from the trajectory file
when a TrajectoryVariable object is created; the read operation
takes place when the TrajectoryVariable is indexed with a specific
step number.</para>
<para>If <literal role="Python">t</literal> is a TrajectoryVariable object, then:</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(t)</literal> is the number of steps</para></listitem>
<listitem><para>
<literal role="Python">t[i]</literal> is the data for step i, in the form of a ParticleScalar,
  a ParticleVector, or a Configuration object, depending on the
  variable</para></listitem>
<listitem><para>
<literal role="Python">t[i:j]</literal> and <literal role="Python">t[i:j:n]</literal> return a SubVariable object that refers
   to a subset of the total number of steps
</para></listitem>
</itemizedlist>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.SubVariable" xreflabel="MMTK.Trajectory.SubVariable">
<classdef><class>SubVariable</class><classinfo>Reference to a subset of a TrajectoryVariable</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Trajectory.TrajectoryVariable"/>.</para>
<para>A SubVariable object is created by slicing a TrajectoryVariable
object or another SubVariable object. It provides all the operations
defined on TrajectoryVariable objects.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.TrajectorySet" xreflabel="MMTK.Trajectory.TrajectorySet">
<classdef><class>TrajectorySet</class><classinfo>Trajectory file set</classinfo></classdef>
<para>A trajectory set permits to treat a sequence of trajectory files
like a single trajectory for reading data. It behaves like an
object of the class <xref linkend="Class:MMTK.Trajectory.Trajectory"/>. The
trajectory files must all contain data for the same system.
The variables stored in the individual files need not be the
same, but only variables common to all files can be accessed.</para>
<para>Constructor: TrajectorySet(<parameter>object</parameter>, <parameter>filename_list</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>object</parameter></term>
<listitem><para>
the object whose data is stored in the trajectory files.
            This can be (and usually is) <literal role="Python">None</literal>;
            in that case, a universe object is constructed from the
            description stored in the first trajectory file. This universe
            object can be accessed via the attribute <literal role="Python">universe</literal>
            of the trajectory set object.</para></listitem></varlistentry>
<varlistentry><term><parameter>filename_list</parameter></term>
<listitem><para>
a list of trajectory file names or
                   (filename, first_step, last_step, increment)
                   tuples.</para></listitem></varlistentry>
</variablelist></para>
<para>Note: depending on how the sequence of trajectories was constructed,
the first configuration of each trajectory might be the same as the
last one in the preceding trajectory. To avoid counting it twice,
specify (filename, 1, None, 1) for all but the first trajectory in
the set.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.TrajectorySetVariable" xreflabel="MMTK.Trajectory.TrajectorySetVariable">
<classdef><class>TrajectorySetVariable</class><classinfo>Variable in a trajectory set</classinfo></classdef>
<para>A TrajectorySetVariable object is created by extracting a variable from
a TrajectorySet object if that variable contains data for each atom and
is thus potentially large. It behaves exactly like a TrajectoryVariable
object.
</para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.ParticleTrajectory" xreflabel="MMTK.Trajectory.ParticleTrajectory">
<classdef><class>ParticleTrajectory</class><classinfo>Trajectory data for a single particle</classinfo></classdef>
<para>A ParticleTrajectory object is created by calling the method
<literal role="Python">readParticleTrajectory</literal> on a Trajectory object.
If <literal role="Python">pt</literal> is a ParticleTrajectory object, then</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(pt)</literal> is the number of steps stored in it</para></listitem>
<listitem><para>
<literal role="Python">pt[i]</literal> is the value at step <literal role="Python">i</literal> (a vector)
</para></listitem>
</itemizedlist>
<methoddescription><methoddef><method>translateBy</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Adds <parameter>vector</parameter> to the values at all steps. This does <emphasis>not</emphasis>
change the data in the trajectory file.</para>
</methoddescription>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.RigidBodyTrajectory" xreflabel="MMTK.Trajectory.RigidBodyTrajectory">
<classdef><class>RigidBodyTrajectory</class><classinfo>Rigid-body trajectory data</classinfo></classdef>
<para>A RigidBodyTrajectory object is created by calling the method
<literal role="Python">readRigidBodyTrajectory</literal> on a Trajectory object.
If <literal role="Python">rbt</literal> is a RigidBodyTrajectory object, then</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(rbt)</literal> is the number of steps stored in it</para></listitem>
<listitem><para>
<literal role="Python">rbt[i]</literal> is the value at step <literal role="Python">i</literal> (a vector for the center of mass
           and a quaternion for the orientation)
</para></listitem>
</itemizedlist>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.TrajectoryOutput" xreflabel="MMTK.Trajectory.TrajectoryOutput">
<classdef><class>TrajectoryOutput</class><classinfo>Trajectory output action</classinfo></classdef>
<para>A TrajectoryOutput object is used in the action list of any
trajectory-generating operation. It writes any of the available
data to a trajectory file. It is possible to use several
TrajectoryOutput objects at the same time in order to produce
multiple trajectories from a single run.</para>
<para>Constructor: TrajectoryOutput(<parameter>trajectory</parameter>, <parameter>data</parameter>=None,
                              <parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>trajectory</parameter></term>
<listitem><para>
a trajectory object or a string, which is interpreted
                as the name of a file that is opened as a trajectory
                in append mode</para></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter></term>
<listitem><para>
a list of data categories. All variables provided by the
          trajectory generator that fall in any of the listed categories
          are written to the trajectory file. See the descriptions of
          the trajectory generators for a list of variables and
          categories. By default (<parameter>data</parameter> = <literal role="Python">None</literal>) the categories
          "configuration", "energy", "thermodynamic", and "time"
          are written.</para></listitem></varlistentry>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.RestartTrajectoryOutput" xreflabel="MMTK.Trajectory.RestartTrajectoryOutput">
<classdef><class>RestartTrajectoryOutput</class><classinfo>Restart trajectory output action</classinfo></classdef>
<para>A RestartTrajectoryOutput object is used in the action list of any
trajectory-generating operation. It writes those variables to a
trajectory that the trajectory generator declares as necessary
for restarting.</para>
<para>Constructor: RestartTrajectoryOutput(<parameter>trajectory</parameter>, <parameter>skip</parameter>=100, <parameter>length</parameter>=3)</para>
<para><variablelist>
<varlistentry><term><parameter>trajectory</parameter></term>
<listitem><para>
a trajectory object or a string, which is interpreted
                as the name of a file that is opened as a trajectory
                in append mode with a cycle length of <parameter>length</parameter> and
                double-precision variables</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps between two write operations to the
          restart trajectory</para></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter></term>
<listitem><para>
the number of steps stored in the restart trajectory;
            used only if <parameter>trajectory</parameter> is a string
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.LogOutput" xreflabel="MMTK.Trajectory.LogOutput">
<classdef><class>LogOutput</class><classinfo>Protocol file output action</classinfo></classdef>
<para>A LogOutput object is used in the action list of any
trajectory-generating operation. It writes any of the available
data to a text file.</para>
<para>Constructor: LogOutput(<parameter>file</parameter>, <parameter>data</parameter>, <parameter>first</parameter>=0, <parameter>last</parameter>=None, <parameter>skip</parameter>=1)</para>
<para><variablelist>
<varlistentry><term><parameter>file</parameter></term>
<listitem><para>
a file object or a string, which is interpreted as the name
          of a file that is opened in write mode</para></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter></term>
<listitem><para>
a list of data categories. All variables provided by the
          trajectory generator that fall in any of the listed categories
          are written to the trajectory file. See the descriptions of
          the trajectory generators for a list of variables and
          categories. By default (<parameter>data</parameter> = <literal role="Python">None</literal>) the categories
          "energy" and "time" are written.</para></listitem></varlistentry>
<varlistentry><term><parameter>first</parameter></term>
<listitem><para>
the number of the first step at which the action is executed</para></listitem></varlistentry>
<varlistentry><term><parameter>last</parameter></term>
<listitem><para>
the number of the last step at which the action is executed.
          A value of <literal role="Python">None</literal> indicates that the action should be
          executed indefinitely.</para></listitem></varlistentry>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.StandardLogOutput" xreflabel="MMTK.Trajectory.StandardLogOutput">
<classdef><class>StandardLogOutput</class><classinfo>Standard protocol output action</classinfo></classdef>
<para>A StandardLogOutput object is used in the action list of any
trajectory-generating operation. It is a specialization of
LogOutput to the most common case and writes data in the categories
"time" and "energy" to the standard output stream.</para>
<para>Constructor: StandardLogOutput(<parameter>skip</parameter>=50)</para>
<para><variablelist>
<varlistentry><term><parameter>skip</parameter></term>
<listitem><para>
the number of steps to skip between two applications of the
          action
</para></listitem></varlistentry>
</variablelist></para>
</classdescription>

<classdescription role="Python" id="Class:MMTK.Trajectory.SnapshotGenerator" xreflabel="MMTK.Trajectory.SnapshotGenerator">
<classdef><class>SnapshotGenerator</class><classinfo>Trajectory generator for single steps</classinfo></classdef>
<para>A SnapshotGenerator is used for manual assembly of trajectory
files. At each call it writes one step to the trajectory,
using the current state of the universe (configuration, velocities, etc.)
and data provided explicitly with the call.</para>
<para>Constructor: SnapshotGenerator(<parameter>universe</parameter>, <parameter>**options</parameter>)</para>
<para><variablelist>
<varlistentry><term><parameter>universe</parameter></term>
<listitem><para>
the universe on which the integrator acts</para></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter></term>
<listitem><para>
keyword options:<itemizedlist>
<listitem><para>
data: a dictionary that supplies values for variables
          that are not part of the universe state (e.g. potential energy)
</para></listitem>
<listitem><para>
actions: a list of actions to be executed periodically (default is
             none)</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist></para>
<para>Each call to the SnapshotGenerator object produces one step.
All the keyword options listed above can be specified either when
creating the generator or when calling it.
</para>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Trajectory.isTrajectory" xreflabel="MMTK.Trajectory.isTrajectory" role="Python"><funcprototype><funcdef><function>isTrajectory</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>object</parameter> is a trajectory.</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Trajectory.trajectoryInfo" xreflabel="MMTK.Trajectory.trajectoryInfo" role="Python"><funcprototype><funcdef><function>trajectoryInfo</function></funcdef>
<paramdef><parameter>filename</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Return a string with summarial information about the trajectory
file identified by <parameter>filename</parameter>.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Units" xreflabel="MMTK.Units">
<title>Module MMTK.Units</title>

<para>This module defines constants and prefactors that convert between
MMTK's internal unit system and other units. There are also some
common physical constants.</para>
<para>SI Prefixes: ato, femto, pico, nano, micro, milli, centi, deci, deca,
hecto, kilo, mega, giga, tera, peta</para>
<para>Length units: m, cm, mm, nm, pm, fm, Ang, Bohr</para>
<para>Angle units: rad, deg</para>
<para>Volume units: l</para>
<para>Time units: s, ns, ps, fs</para>
<para>Frequency units: Hz, invcm (wavenumbers)</para>
<para>Mass units: amu, g, kg</para>
<para>Quantity-of-matter units: mol</para>
<para>Energy units:
J, kJ, cal, kcal, Hartree</para>
<para>Temperature units:
K</para>
<para>Pressure units:
Pa, bar, atm</para>
<para>Electrostatic units:
C, A, V, D, eV, e</para>
<para>Physical constants:
c (speed of light),
Nav (Avogadro number),
h = (Planck constant),
hbar = (Planck constant divided by 2*Pi),
k_B = (Boltzmann constant),
eps0 = (permittivity of vacuum),
me = (electron mass)
</para>
</sect1>

<sect1 id="Module:MMTK.Universe" xreflabel="MMTK.Universe">
<title>Module MMTK.Universe</title>

<classdescription role="Python" id="Class:MMTK.Universe.Universe" xreflabel="MMTK.Universe.Universe">
<classdef><class>Universe</class><classinfo>Complete model of chemical system</classinfo></classdef>
<para>A <xref linkend="Glossary:Subclass"/> of <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>
and <xref linkend="Class:MMTK.Visualization.Viewable"/>.</para>
<para>A universe represents a complete model of a chemical system, i.e.
the molecules, their environment (topology, boundary conditions,
thermostats, etc.), and optionally a force field.</para>
<para>The class Universe is an Glossary:abstract-base-class that defines
properties common to all kinds of universes. To create universe
objects, use one of its subclasses.</para>
<para>In addition to the methods listed below, universe objects support
the following operations (<literal role="Python">u</literal> is any universe object, <literal role="Python">o</literal> is any
chemical object):</para>
<itemizedlist>
<listitem><para>
<literal role="Python">len(u)</literal> yields the number of chemical objects in the universe
</para></listitem>
<listitem><para>
<literal role="Python">u[i]</literal> returns object number <literal role="Python">i</literal>
</para></listitem>
<listitem><para>
<literal role="Python">u.name = o</literal> adds <literal role="Python">o</literal> to the universe and also makes it accessible as
  an attribute
</para></listitem>
<listitem><para>
<literal role="Python">del u.name</literal> removes the object that was assigned to <literal role="Python">u.name</literal> from
   the universe
</para></listitem>
</itemizedlist>
<methoddescription><methoddef><method>objectList</method></methoddef>
<paramdef><parameter>klass</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a list of all chemical objects in the universe.
If <parameter>klass</parameter> is not None, only objects whose class is equal
to <parameter>klass</parameter> are returned.</para>
</methoddescription>
<methoddescription><methoddef><method>environmentObjectList</method></methoddef>
<paramdef><parameter>klass</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns a list of all environment objects in the universe.
If <parameter>klass</parameter> is not None, only objects whose class is equal
to <parameter>klass</parameter> are returned.</para>
</methoddescription>
<methoddescription><methoddef><method>atomList</method></methoddef>
<void/><para>Returns a list of all atoms in the universe. This includes
atoms that make up the compound chemical objects (molecules etc.).</para>
</methoddescription>
<methoddescription><methoddef><method>universe</method></methoddef>
<void/><para>Returns the universe itself.</para>
</methoddescription>
<methoddescription><methoddef><method>addObject</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<para>Adds <parameter>object</parameter> to the universe. If <parameter>object</parameter> is a Collection,
all elements of the Collection are added to the universe. An
object can only be added to a universe if it is not already
part of another universe.</para>
</methoddescription>
<methoddescription><methoddef><method>removeObject</method></methoddef>
<paramdef><parameter>object</parameter></paramdef>
<para>Removes <parameter>object</parameter> from the universe. If <parameter>object</parameter> is a Collection,
each of its elements is removed. The object to be removed must
be in the universe.</para>
</methoddescription>
<methoddescription><methoddef><method>selectShell</method></methoddef>
<paramdef><parameter>point</parameter></paramdef>
<paramdef><parameter>r1</parameter></paramdef>
<paramdef><parameter>r2</parameter><defaultvalue>0.0</defaultvalue></paramdef>
<para>Return a Collection of all objects in the universe whose
distance from <parameter>point</parameter> is between <parameter>r1</parameter> and <parameter>r2</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>selectBox</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<para>Return a Collection of all objects in the universe that lie
within a box whose corners are given by <parameter>p1</parameter> and <parameter>p2</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>acquireReadStateLock</method></methoddef>
<void/><para>Acquire the universe read state lock. Any application that
uses threading must acquire this lock prior to accessing the
current state of the universe, in particular its configuration
(particle positions). This guarantees the consistency of the
data; while any thread holds the read state lock, no other
thread can obtain the write state lock that permits modifying
the state. The read state lock should be released as soon as
possible.</para>
<para>The read state lock can be acquired only if no thread holds
the write state lock. If the read state lock cannot be
acquired immediately, the thread will be blocked until
it becomes available. Any number of threads can acquire
the read state lock simultaneously.</para>
</methoddescription>
<methoddescription><methoddef><method>acquireWriteStateLock</method></methoddef>
<void/><para>Acquire the universe write state lock. Any application that
uses threading must acquire this lock prior to modifying the
current state of the universe, in particular its configuration
(particle positions). This guarantees the consistency of the
data; while any thread holds the write state lock, no other
thread can obtain the read state lock that permits accessing
the state. The write state lock should be released as soon as
possible.</para>
<para>The write state lock can be acquired only if no other thread
holds either the read state lock or the write state lock. If
the write state lock cannot be acquired immediately, the
thread will be blocked until it becomes available.</para>
</methoddescription>
<methoddescription><methoddef><method>releaseReadStateLock</method></methoddef>
<paramdef><parameter>write</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Release the universe read state lock.</para>
</methoddescription>
<methoddescription><methoddef><method>releaseWriteStateLock</method></methoddef>
<paramdef><parameter>write</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Release the universe write state lock.</para>
</methoddescription>
<methoddescription><methoddef><method>acquireConfigurationChangeLock</method></methoddef>
<paramdef><parameter>waitflag</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Acquire the configuration change lock. This lock should be
acquired before starting an algorithm that changes the
configuration continuously, e.g. minimization or molecular dynamics
algorithms. This guarantees the proper order of execution when
several such operations are started in succession. For example,
when a minimization should be followed by a dynamics run,
the use of this flag permits both operations to be started
as background tasks which will be executed one after the other,
permitting other threads to run in parallel.</para>
<para>The configuration change lock should not be confused with
the universe state lock. The former guarantees the proper
sequence of long-running algorithms, whereas the latter
guarantees the consistency of the data. A dynamics algorithm,
for example, keeps the configuration change lock from the
beginning to the end, but acquires the universe state lock
only immediately before modifying configuration and velocities,
and releases it immediately afterwards.</para>
<para>If <parameter>waitflag</parameter> is true, the method waits until the lock
becomes available; this is the most common operation. If
<parameter>waitflag</parameter> is false, the method returns immediately even
if another thread holds the lock. The return value indicates
if the lock could be acquired (1) or not (0).</para>
</methoddescription>
<methoddescription><methoddef><method>releaseConfigurationChangeLock</method></methoddef>
<void/><para>Releases the configuration change lock.</para>
</methoddescription>
<methoddescription><methoddef><method>setForceField</method></methoddef>
<paramdef><parameter>forcefield</parameter></paramdef>
<para>Assign a new <parameter>forcefield</parameter> to the universe.</para>
</methoddescription>
<methoddescription><methoddef><method>configuration</method></methoddef>
<void/><para>Return the configuration object describing the current configuration
of the universe. Note that this is not a copy of the current state;
the positions in the configuration object will change when coordinate
changes are applied to the universe in whatever way.</para>
</methoddescription>
<methoddescription><methoddef><method>copyConfiguration</method></methoddef>
<void/><para>Returns a copy of the current configuration.</para>
<para>This operation is thread-safe; it won't return inconsistent
data even when another thread is modifying the
configuration.</para>
</methoddescription>
<methoddescription><methoddef><method>setConfiguration</method></methoddef>
<paramdef><parameter>configuration</parameter></paramdef>
<paramdef><parameter>block</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Copy all positions are from <parameter>configuration</parameter> (which must be
a Configuration object) to the current universe configuration.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the configuration while the data is being
updated. If this is not desired (e.g. when calling from
a routine that handles locking itself), the optional parameter
<parameter>block</parameter> should be set to 0.</para>
</methoddescription>
<methoddescription><methoddef><method>addToConfiguration</method></methoddef>
<paramdef><parameter>displacement</parameter></paramdef>
<paramdef><parameter>block</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Add <parameter>displacement</parameter> (a ParticleVector object) to the current
configuration of the universe.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the configuration while the data is being
updated. If this is not desired (e.g. when calling from
a routine that handles locking itself), the optional parameter
<parameter>block</parameter> should be set to 0.</para>
</methoddescription>
<methoddescription><methoddef><method>getParticleScalar</method></methoddef>
<paramdef><parameter>name</parameter></paramdef>
<paramdef><parameter>datatype</parameter><defaultvalue>'d'</defaultvalue></paramdef>
<para>Return a ParticleScalar object containing the values of the
attribute <parameter>name</parameter> for each atom in the universe.</para>
</methoddescription>
<methoddescription><methoddef><method>getParticleBoolean</method></methoddef>
<paramdef><parameter>name</parameter></paramdef>
<para>Return a ParticleScalar object containing the boolean values
(0 or 1) of the attribute <parameter>name</parameter> for each atom in the universe.
An atom that does not have the attribute <parameter>name</parameter> is assigned
a value of zero.</para>
</methoddescription>
<methoddescription><methoddef><method>masses</method></methoddef>
<void/><para>Return a ParticleScalar object containing the atom masses.</para>
</methoddescription>
<methoddescription><methoddef><method>charges</method></methoddef>
<void/><para>Return a ParticleScalar object containing the atom charges.
Since charges are parameters defined by a force field, this
method will raise an exception if no force field is defined or
if the current force field defines no charges.</para>
</methoddescription>
<methoddescription><methoddef><method>velocities</method></methoddef>
<void/><para>Returns ParticleVector object containing the current velocities of
all atoms. If no velocities are defined, the return value is <literal role="Python">None</literal>.
Note that the return value is not a copy of the current state but
a reference to it; its data will change when any changes are made
to the current velocities.</para>
</methoddescription>
<methoddescription><methoddef><method>setVelocities</method></methoddef>
<paramdef><parameter>velocities</parameter></paramdef>
<paramdef><parameter>block</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Set the current atom velocities to the values contained in
the ParticleVector object <parameter>velocities</parameter>. If <parameter>velocities</parameter> is
None, the velocity information is removed from the universe.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the velocities while the data is being
updated. If this is not desired (e.g. when calling from
a routine that handles locking itself), the optional parameter
<parameter>block</parameter> should be set to 0.</para>
</methoddescription>
<methoddescription><methoddef><method>initializeVelocitiesToTemperature</method></methoddef>
<paramdef><parameter>temperature</parameter></paramdef>
<para>Generate random velocities for all atoms from a Boltzmann
distribution at the given <parameter>temperature</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>scaleVelocitiesToTemperature</method></methoddef>
<paramdef><parameter>temperature</parameter></paramdef>
<paramdef><parameter>block</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Scale all velocities by a common factor in order to obtain
the specified <parameter>temperature</parameter>.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the velocities while the data is being
updated.  If this is not desired (e.g. when calling from
a routine that handles locking itself), the optional parameter
<parameter>block</parameter> should be set to 0.</para>
</methoddescription>
<methoddescription><methoddef><method>distanceConstraintList</method></methoddef>
<void/><para>Returns the list of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>numberOfDistanceConstraints</method></methoddef>
<void/><para>Returns the number of distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>setBondConstraints</method></methoddef>
<void/><para>Sets distance constraints for all bonds.</para>
</methoddescription>
<methoddescription><methoddef><method>removeDistanceConstraints</method></methoddef>
<void/><para>Removes all distance constraints.</para>
</methoddescription>
<methoddescription><methoddef><method>enforceConstraints</method></methoddef>
<paramdef><parameter>configuration</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Enforces the previously defined distance constraints
by modifying the configuration and velocities.</para>
</methoddescription>
<methoddescription><methoddef><method>adjustVelocitiesToConstraints</method></methoddef>
<paramdef><parameter>velocities</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>block</parameter><defaultvalue>1</defaultvalue></paramdef>
<para>Modifies the velocities to be compatible with
the distance constraints, i.e. projects out the velocity
components along the constrained distances.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the velocities while the data is being
updated. If this is not desired (e.g. when calling from
a routine that handles locking itself), the optional parameter
<parameter>block</parameter> should be set to 0.</para>
</methoddescription>
<methoddescription><methoddef><method>forcefield</method></methoddef>
<void/><para>Returns the force field.</para>
</methoddescription>
<methoddescription><methoddef><method>energy</method></methoddef>
<paramdef><parameter>subset1</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>subset2</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>small_change</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns the energy. Without any parameters, the energy is
calculated for the whole universe. If <parameter>subset1</parameter> is given,
only the energy terms within the atoms in <parameter>subset1</parameter> are calculated.
If <parameter>subset1</parameter> and <parameter>subset2</parameter> are given, only the energy terms
between atoms of the two subsets are evaluated. The parameter
<parameter>small_change</parameter> can be set to one in order to obtain a faster
energy evaluation when the current configuration differs from
the one during the last energy evaluation only by small displacements.
</para>
</methoddescription>
<methoddescription><methoddef><method>energyAndGradients</method></methoddef>
<paramdef><parameter>subset1</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>subset2</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>small_change</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns the energy and the energy gradients (a ParticleVector).</para>
</methoddescription>
<methoddescription><methoddef><method>energyAndForceConstants</method></methoddef>
<paramdef><parameter>subset1</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>subset2</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>small_change</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns the energy and the force constants
(a SymmetricParticleTensor).</para>
</methoddescription>
<methoddescription><methoddef><method>energyGradientsAndForceConstants</method></methoddef>
<paramdef><parameter>subset1</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>subset2</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>small_change</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns the energy, the energy gradients (a ParticleVector),
and the force constants (a SymmetricParticleTensor).</para>
</methoddescription>
<methoddescription><methoddef><method>energyTerms</method></methoddef>
<paramdef><parameter>subset1</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>subset2</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>small_change</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns a dictionary containing the energy values for each
energy term separately. The energy terms are defined by the
force field.</para>
</methoddescription>
<methoddescription><methoddef><method>distanceVector</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the distance vector between <parameter>p1</parameter> and <parameter>p2</parameter> (i.e. the
vector from <parameter>p1</parameter> to <parameter>p2</parameter>) in the
configuration <parameter>conf</parameter>. <parameter>p1</parameter> and <parameter>p2</parameter> can be vectors
or subsets of the universe, in which case their center-of-mass
positions are used. If <parameter>conf</parameter> is <literal role="Python">None</literal>, the current configuration
of the universe is used. The result takes the universe topology
(periodic boundary conditions etc.) into account.</para>
</methoddescription>
<methoddescription><methoddef><method>distance</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the distance between <parameter>p1</parameter> and <parameter>p2</parameter>, i.e. the length
of the distance vector.</para>
</methoddescription>
<methoddescription><methoddef><method>angle</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<paramdef><parameter>p3</parameter></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the angle between the distance vectors |p1|-|p2| and
|p3|-|p2|.</para>
</methoddescription>
<methoddescription><methoddef><method>dihedral</method></methoddef>
<paramdef><parameter>p1</parameter></paramdef>
<paramdef><parameter>p2</parameter></paramdef>
<paramdef><parameter>p3</parameter></paramdef>
<paramdef><parameter>p4</parameter></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns the dihedral angle between the plane containing the
distance vectors |p1|-|p2| and |p3|-|p2| and the plane containing the
distance vectors |p2|-|p3| and |p4|-|p3|.</para>
</methoddescription>
<methoddescription><methoddef><method>basisVectors</method></methoddef>
<void/><para>Returns the basis vectors of the elementary cell of a periodic
universe. For a non-periodic universe the return value is <literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>reciprocalBasisVectors</method></methoddef>
<void/><para>Returns the reciprocal basis vectors of the elementary cell of a
periodic universe. For a non-periodic universe the return value is
<literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>cellVolume</method></methoddef>
<void/><para>Returns the volume of the elementary cell of a periodic
universe. For a non-periodic universe the return value is <literal role="Python">None</literal>.</para>
</methoddescription>
<methoddescription><methoddef><method>largestDistance</method></methoddef>
<void/><para>Returns the largest possible distance that any two points
can have in the universe. Returns <literal role="Python">None</literal> if no such upper limit
exists.</para>
</methoddescription>
<methoddescription><methoddef><method>contiguousObjectOffset</method></methoddef>
<paramdef><parameter>objects</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>box_coordinates</parameter><defaultvalue>0</defaultvalue></paramdef>
<para>Returns a ParticleVector with displacements relative to
the configuration <parameter>conf</parameter> which when added to the configuration
create a configuration in which none of the <parameter>objects</parameter> is split
across the edge of the elementary cell. For nonperiodic universes
the return value is <literal role="Python">None</literal>. If no object list is specified, the
list of elements of the universe is used. The configuration
defaults to the current configuration of the universe.</para>
</methoddescription>
<methoddescription><methoddef><method>contiguousObjectConfiguration</method></methoddef>
<paramdef><parameter>objects</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>conf</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Returns configuration <parameter>conf</parameter> (default: current configuration)
corrected by the contiguous object offsets for that
configuration.</para>
</methoddescription>
<methoddescription><methoddef><method>realToBoxCoordinates</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Returns the box coordinate equivalent of <parameter>vector</parameter>.
Box coordinates are defined only for periodic universes;
their components have values between -0.5 and 0.5; these
extreme values correspond to the walls of the simulation box.
For a nonperiodic universe, <parameter>vector</parameter> is returned unchanged.</para>
</methoddescription>
<methoddescription><methoddef><method>boxToRealCoordinates</method></methoddef>
<paramdef><parameter>vector</parameter></paramdef>
<para>Returns the real-space equivalent of the box coordinate
<parameter>vector</parameter>.</para>
</methoddescription>
<methoddescription><methoddef><method>randomPoint</method></methoddef>
<void/><para>Returns a random point from a uniform distribution within
the universe. This operation is defined only for finite-volume
universes, e.g. periodic universes.</para>
</methoddescription>
<methoddescription><methoddef><method>map</method></methoddef>
<paramdef><parameter>function</parameter></paramdef>
<para>Applies <parameter>function</parameter> to all objects in the universe and
returns the list of the results. If the results are chemical
objects, a Collection is returned instead of a list.</para>
</methoddescription>
<methoddescription><methoddef><method>setFromTrajectory</method></methoddef>
<paramdef><parameter>trajectory</parameter></paramdef>
<paramdef><parameter>step</parameter><defaultvalue>None</defaultvalue></paramdef>
<para>Set the state of the universe to the one stored in
the given <parameter>step</parameter> of the given <parameter>trajectory</parameter>. If no step number
is given, the most recently written step is used for a restart
trajectory, and the first step (number zero) for a normal
trajectory.</para>
<para>This operation is thread-safe; it blocks other threads that
want to access the configuration or velocities while the data is
being updated.</para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Universe.isUniverse" xreflabel="MMTK.Universe.isUniverse" role="Python"><funcprototype><funcdef><function>isUniverse</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Returns 1 if <parameter>object</parameter> is a Universe.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Visualization" xreflabel="MMTK.Visualization">
<title>Module MMTK.Visualization</title>

<para>This module provides visualization of chemical objects and animated
visualization of normal modes and sequences of configurations, including
trajectories. Visualization depends on external visualization programs.
On Unix systems, these programs are defined by environment variables.
Under Windows NT, the system definitions for files with extension
"pdb" and "wrl" are used.</para>
<para>A viewer for PDB files can be defined by the environment variable
<literal role="Python">PDBVIEWER</literal>. For showing a PDB file, MMTK will execute a command
consisting of the value of this variable followed by a space
and the name of the PDB file.</para>
<para>A viewer for VRML files can be defined by the environment variable
<literal role="Python">VRMLVIEWER</literal>. For showing a VRML file, MMTK will execute a command
consisting of the value of this variable followed by a space
and the name of the VRML file.</para>
<para>Since there is no standard for launching viewers for animation,
MMTK supports only two programs: VMD and XMol. MMTK detects
these programs by inspecting the value of the environment variable
<literal role="Python">PDBVIEWER</literal>. This value must be the file name of the executable,
and must give "vmd" or "xmol" after stripping off an optional
directory specification.
</para>
<classdescription role="Python" id="Class:MMTK.Visualization.Viewable" xreflabel="MMTK.Visualization.Viewable">
<classdef><class>Viewable</class><classinfo>Any viewable chemical object</classinfo></classdef>
<para>This class is a <xref linkend="Glossary:MixInClass"/> that defines a general
visualization method for all viewable objects, i.e. chemical
objects (atoms, molecules, etc.), collections, and universes.
</para>
<methoddescription><methoddef><method>graphicsObjects</method></methoddef>
<paramdef><parameter>**options</parameter></paramdef>
<para>Returns a list of graphics objects that represent
the object for which the method is called. All options
are specified as keyword arguments:</para>
<para><variablelist>
<varlistentry><term><parameter>configuration</parameter></term>
<listitem><para>
the configuration in which the objects
                   are drawn (default: the current configuration)</para></listitem></varlistentry>
<varlistentry><term><parameter>model</parameter></term>
<listitem><para>
a string specifying one of several graphical
           representations ("wireframe", "tube", "ball_and_stick").
           Default is "wireframe".</para></listitem></varlistentry>
<varlistentry><term><parameter>ball_radius</parameter></term>
<listitem><para>
the radius of the balls representing the atoms
                 in a ball-and-stick model, default: 0.03</para></listitem></varlistentry>
<varlistentry><term><parameter>stick_radius</parameter></term>
<listitem><para>
the radius of the sticks representing the bonds
                  in a ball-and-stick or tube model, default: 0.02
                  for the tube model, 0.01 for the ball-and-stick model</para></listitem></varlistentry>
<varlistentry><term><parameter>graphics_module</parameter></term>
<listitem><para>
the module in which the elementary graphics
                     objects are defined
                     (default: Scientific.Visualization.VRML)</para></listitem></varlistentry>
<varlistentry><term><parameter>color_values</parameter></term>
<listitem><para>
a <xref linkend="Class:MMTK.ParticleScalar"/> object that defines
                  a value for each atom which defines that
                  atom's color via the color scale object specified
                  by the option <parameter>color_scale</parameter>. If no value is
                  given for <parameter>color_values</parameter>, the atoms' colors are
                  taken from the attribute <literal role="Python">color</literal> of each
                  atom object (default values for each chemical
                  element are provided in the chemical database).</para></listitem></varlistentry>
<varlistentry><term><parameter>color_scale</parameter></term>
<listitem><para>
an object that returns a color object (as defined
                 in the module Scientific.Visualization.Color)
                 when called with a number argument. Suitable
                 objects are defined by
                 Scientific.Visualization.Color.ColorScale and
                 Scientific.Visualization.Color.SymmetricColorScale.
                 The object is used only when the option
                 <parameter>color_values</parameter> is specified as well. The default
                 is a blue-to-red color scale that covers the
                 range of the values given in <parameter>color_values</parameter>.</para></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter></term>
<listitem><para>
a color name predefined in the module
           Scientific.Visualization.Color. The corresponding
           color is applied to all graphics objects that are
           returned.
</para></listitem></varlistentry>
</variablelist></para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization.view" xreflabel="MMTK.Visualization.view" role="Python"><funcprototype><funcdef><function>view</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>*parameters</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Equivalent to <parameter>object</parameter>.view(parameters).</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization.viewTrajectory" xreflabel="MMTK.Visualization.viewTrajectory" role="Python"><funcprototype><funcdef><function>viewTrajectory</function></funcdef>
<paramdef><parameter>trajectory</parameter></paramdef>
<paramdef><parameter>first</parameter><defaultvalue>0</defaultvalue></paramdef>
<paramdef><parameter>last</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>step</parameter><defaultvalue>1</defaultvalue></paramdef>
<paramdef><parameter>subset</parameter><defaultvalue>None</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Launches an external viewer with animation capabilities
to display the configurations from <parameter>first</parameter> to <parameter>last</parameter> in increments
of <parameter>step</parameter> in <parameter>trajectory</parameter>. The trajectory can be specified by
a <xref linkend="Class:MMTK.Trajectory.Trajectory"/> object or by a string which
is interpreted as the file name of a trajectory file. An optional
parameter <parameter>subset</parameter> can specify an object which is a subset of the
universe contained in the trajectory, in order to restrict
visualization to this subset.
</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization.viewSequence" xreflabel="MMTK.Visualization.viewSequence" role="Python"><funcprototype><funcdef><function>viewSequence</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>conf_list</parameter></paramdef>
<paramdef><parameter>periodic</parameter><defaultvalue>0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Launches an external viewer with animation capabilities
to display <parameter>object</parameter> in the configurations given in
<parameter>conf_list</parameter>, which can be any sequence of configurations,
including the variable "configuration" from a
<xref linkend="Class:MMTK.Trajectory.Trajectory"/> object. If <parameter>periodic</parameter>
is 1, the configurations will be repeated periodically,
provided that the external viewers supports this operation.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="Module:MMTK.Visualization_win32" xreflabel="MMTK.Visualization_win32">
<title>Module MMTK.Visualization_win32</title>

<para>This module provides visualization of chemical objects and animated
visualization of normal modes and sequences of configurations, including
trajectories. Visualization depends on external visualization programs.
On Unix systems, these programs are defined by environment variables.
Under Windows NT, the system definitions for files with extension
"pdb" and "wrl" are used.</para>
<para>A viewer for PDB files can be defined by the environment variable
<literal role="Python">PDBVIEWER</literal>. For showing a PDB file, MMTK will execute a command
consisting of the value of this variable followed by a space
and the name of the PDB file.</para>
<para>A viewer for VRML files can be defined by the environment variable
<literal role="Python">VRMLVIEWER</literal>. For showing a VRML file, MMTK will execute a command
consisting of the value of this variable followed by a space
and the name of the VRML file.</para>
<para>Since there is no standard for launching viewers for animation,
MMTK supports only two programs: VMD and XMol. MMTK detects
these programs by inspecting the value of the environment
<literal role="Python">PDBVIEWER</literal>. This value must be the file name of the executable,
and must give "vmd" or "xmol" after stripping off an optional
directory specification.
</para>
<classdescription role="Python" id="Class:MMTK.Visualization_win32.Viewable" xreflabel="MMTK.Visualization_win32.Viewable">
<classdef><class>Viewable</class><classinfo>Any viewable chemical object</classinfo></classdef>
<para>This class is a <xref linkend="Glossary:MixInClass"/> that defines a general
visualization method for all viewable objects, i.e. chemical
objects (atoms, molecules, etc.), collections, and universes.
</para>
<methoddescription><methoddef><method>graphicsObjects</method></methoddef>
<paramdef><parameter>**options</parameter></paramdef>
<para>Returns a list of graphics objects that represent
the object for which the method is called. All options
are specified as keyword arguments:</para>
<para><variablelist>
<varlistentry><term><parameter>configuration</parameter></term>
<listitem><para>
the configuration in which the objects
                   are drawn (default: the current configuration)</para></listitem></varlistentry>
<varlistentry><term><parameter>model</parameter></term>
<listitem><para>
a string specifying one of several graphical
           representations ("wireframe", "tube", "ball_and_stick").
           Default is "wireframe".</para></listitem></varlistentry>
<varlistentry><term><parameter>ball_radius</parameter></term>
<listitem><para>
the radius of the balls representing the atoms
                 in a ball-and-stick model, default: 0.03</para></listitem></varlistentry>
<varlistentry><term><parameter>stick_radius</parameter></term>
<listitem><para>
the radius of the sticks representing the bonds
                  in a ball-and-stick or tube model, default: 0.02
                  for the tube model, 0.01 for the ball-and-stick model</para></listitem></varlistentry>
<varlistentry><term><parameter>graphics_module</parameter></term>
<listitem><para>
the module in which the elementary graphics
                     objects are defined
                     (default: Scientific.Visualization.VRML)</para></listitem></varlistentry>
<varlistentry><term><parameter>color_values</parameter></term>
<listitem><para>
a <xref linkend="Class:MMTK.ParticleScalar"/> object that defines
                  a value for each atom which defines that
                  atom's color via the color scale object specified
                  by the option <parameter>color_scale</parameter>. If no value is
                  given for <parameter>color_values</parameter>, the atoms' colors are
                  taken from the attribute <literal role="Python">color</literal> of each
                  atom object (default values for each chemical
                  element are provided in the chemical database).</para></listitem></varlistentry>
<varlistentry><term><parameter>color_scale</parameter></term>
<listitem><para>
an object that returns a color object (as defined
                 in the module Scientific.Visualization.Color)
                 when called with a number argument. Suitable
                 objects are defined by
                 Scientific.Visualization.Color.ColorScale and
                 Scientific.Visualization.Color.SymmetricColorScale.
                 The object is used only when the option
                 <parameter>color_values</parameter> is specified as well. The default
                 is a blue-to-red color scale that covers the
                 range of the values given in <parameter>color_values</parameter>.</para></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter></term>
<listitem><para>
a color name predefined in the module
           Scientific.Visualization.Color. The corresponding
           color is applied to all graphics objects that are
           returned.
</para></listitem></varlistentry>
</variablelist></para>
</methoddescription>
</classdescription>

<sect2>
<title>Functions</title>
<itemizedlist>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization_win32.view" xreflabel="MMTK.Visualization_win32.view" role="Python"><funcprototype><funcdef><function>view</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>*parameters</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Equivalent to <parameter>object</parameter>.view(parameters).</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization_win32.viewTrajectory" xreflabel="MMTK.Visualization_win32.viewTrajectory" role="Python"><funcprototype><funcdef><function>viewTrajectory</function></funcdef>
<paramdef><parameter>trajectory</parameter></paramdef>
<paramdef><parameter>first</parameter><defaultvalue>0</defaultvalue></paramdef>
<paramdef><parameter>last</parameter><defaultvalue>None</defaultvalue></paramdef>
<paramdef><parameter>step</parameter><defaultvalue>1</defaultvalue></paramdef>
<paramdef><parameter>subset</parameter><defaultvalue>None</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Launches an external viewer with animation capabilities
to display the configurations from <parameter>first</parameter> to <parameter>last</parameter> in increments
of <parameter>step</parameter> in <parameter>trajectory</parameter>. The trajectory can be specified by
a <xref linkend="Class:MMTK.Trajectory.Trajectory"/> object or by a string which
is interpreted as the file name of a trajectory file. An optional
parameter <parameter>subset</parameter> can specify an object which is a subset of the
universe contained in the trajectory, in order to restrict
visualization to this subset.
</para>
</listitem>
<listitem><para>
<funcsynopsis id="Function:MMTK.Visualization_win32.viewSequence" xreflabel="MMTK.Visualization_win32.viewSequence" role="Python"><funcprototype><funcdef><function>viewSequence</function></funcdef>
<paramdef><parameter>object</parameter></paramdef>
<paramdef><parameter>conf_list</parameter></paramdef>
<paramdef><parameter>periodic</parameter><defaultvalue>0</defaultvalue></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>Launches an external viewer with animation capabilities
to display <parameter>object</parameter> in the configurations given in
<parameter>conf_list</parameter>, which can be any sequence of configurations,
including the variable "configuration" from a
<xref linkend="Class:MMTK.Trajectory.Trajectory"/> object. If <parameter>periodic</parameter>
is 1, the configurations will be repeated periodically,
provided that the external viewers supports this operation.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

</chapter>



<!-- end of &Modules; -->


<chapter id="examples" xreflabel="examples">
<title>Examples</title>

<para>
One of the best ways to learn how to use a new tool is to look at
examples. The examples given in this manual were adapted from
real-life MMTK applications. They are also contained in the
MMTK distribution (directory "Examples") for direct use and modification.
</para>
<para>
The example molecules, system sizes, parameters, etc.,
were chosen to reduce execution time as much as possible, in order to
enable you to run the examples interactively step by step to see how
they work. If you plan to modify an example program for your own use,
don't forget to check all parameters carefully to make sure that you
obtain reasonable results.
</para>

<itemizedlist>

<listitem id="Example:MolecularDynamics" xreflabel="Molecular Dynamics"><para>
Molecular Dynamics examples
  <itemizedlist>

  <listitem id="Example:MolecularDynamics:argon.py"
            xreflabel="MolecularDynamics/argon.py">
    <para> The file
    <ulink url="Examples/MolecularDynamics/argon.py.html">argon.py</ulink>
    contains a simulation of liquid argon at constant temperature and
    pressure.
  </para></listitem>

  <listitem id="Example:MolecularDynamics:protein.py"
            xreflabel="MolecularDynamics/protein.py">
    <para> The file
    <ulink url="Examples/MolecularDynamics/protein.py.html">protein.py</ulink>
    contains a simulation of a small (very small) protein in vacuum.
  </para></listitem>

  <listitem id="Example:MolecularDynamics:restart.py"
            xreflabel="MolecularDynamics/restart.py">
    <para> The file
    <ulink url="Examples/MolecularDynamics/restart.py.html">restart.py</ulink>
    shows how the simulation started in 
    <ulink url="Examples/MolecularDynamics/protein.py.html">protein.py</ulink>
    can be continued.
  </para></listitem>

  <listitem id="Example:MolecularDynamics:solvation.py"
            xreflabel="MolecularDynamics/solvation.py">
    <para> The file
    <ulink url="Examples/MolecularDynamics/solvation.py.html">solvation.py</ulink>
    contains the solvation of a protein by water molecules.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:MonteCarlo" xreflabel="Monte-Carlo"><para>
Monte-Carlo examples
  <itemizedlist>

  <listitem id="Example:MonteCarlo:backbone.py"
            xreflabel="MonteCarlo/backbone.py">
    <para> The program
    <ulink url="Examples/MonteCarlo/backbone.py.html">backbone.py</ulink>
    generates an ensemble of backbone configuration (C-alpha atoms only)
    for a protein.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:Trajectories" xreflabel="trajectory"><para>
Trajectory examples
  <itemizedlist>

  <listitem id="Example:Trajectories:snapshot.py"
            xreflabel="Trajectories/snapshot.py">
    <para> The file
    <ulink url="Examples/Trajectories/snapshot.py.html">snapshot.py</ulink>
    shows how a trajectory can be built up step by step from arbitrary
    data.
  </para></listitem>

  <listitem id="Example:Trajectories:dcd_import.py"
            xreflabel="Trajectories/dcd_import.py">
    <para> The file
    <ulink url="Examples/Trajectories/dcd_import.py.html">dcd_import.py</ulink>
    converts a trajectory in DCD format (used by the programs CHARMM and
    X-Plor) to MMTK's format.
  </para></listitem>

  <listitem id="Example:Trajectories:dcd_export.py"
            xreflabel="Trajectories/dcd_export.py">
    <para> The file
    <ulink url="Examples/Trajectories/dcd_export.py.html">dcd_export.py</ulink>
    converts an MMTK trajectory to DCD format (used by the programs CHARMM and
    X-Plor).
  </para></listitem>

  <listitem id="Example:Trajectories:trajectory_average.py"
            xreflabel="Trajectories/trajectory_average.py">
    <para> The file
    <ulink url="Examples/Trajectories/trajectory_average.py.html">trajectory_average.py</ulink>
    calculates an average structure from a trajectory.
  </para></listitem>

  <listitem id="Example:Trajectories:trajectory_extraction.py"
            xreflabel="Trajectories/trajectory_extraction.py">
    <para> The file
    <ulink url="Examples/Trajectories/trajectory_extraction.py.html">trajectory_extraction.py</ulink>
    reads a trajectory and writes a new one containing only a subset of the
    original universe.
  </para></listitem>

  <listitem id="Example:Trajectories:view_trajectory.py"
            xreflabel="Trajectories/view_trajectory.py">
    <para> The file
    <ulink url="Examples/Trajectories/view_trajectory.py.html">view_trajectory.py</ulink>
    shows an animation of a trajectory, provided that an external molecule
    viewer with animation is available.
  </para></listitem>

  <listitem id="Example:Trajectories:calpha_trajectory.py"
            xreflabel="Trajectories/calpha_trajectory.py">
    <para> The file
    <ulink url="Examples/Trajectories/calpha_trajectory.py.html">calpha_trajectory.py</ulink>
    shows how a much smaller C_alpha-only trajectory can be extracted from
    a trajectory containing one or more proteins.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:NormalModes" xreflabel="normal mode"><para>
Normal mode examples
  <itemizedlist>

  <listitem id="Example:NormalModes:modes.py"
            xreflabel="NormalModes/modes.py">
    <para> The file
    <ulink url="Examples/NormalModes/modes.py.html">modes.py</ulink>
    contains a standard normal mode calculation for a small protein.
  </para></listitem>

  <listitem id="Example:NormalModes:constrained_modes.py"
            xreflabel="NormalModes/constrained_modes.py">
    <para> The file
    <ulink url="Examples/NormalModes/constrained_modes.py.html">constrained_modes.py</ulink>
    contains a normal mode calculation for a small protein using a model
    in which each amino acid residue is rigid.
  </para></listitem>

  <listitem id="Example:NormalModes:deformation_modes.py"
            xreflabel="NormalModes/deformation_modes.py">
    <para> The file
    <ulink url="Examples/NormalModes/deformation_modes.py.html">deformation_modes.py</ulink>
    contains a normal mode calculation for a mid-size protein using a
    simplified model and a deformation force field.
  </para></listitem>

  <listitem id="Example:NormalModes:harmonic_force_field.py"
            xreflabel="NormalModes/harmonic_force_field.py">
    <para> The file
    <ulink url="Examples/NormalModes/harmonic_force_field.py.html">harmonic_force_field.py</ulink>
    contains a normal mode calculation for a protein using a detailed
    but still simple harmonic force field.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:Proteins" xreflabel="protein"><para>
Protein examples
  <itemizedlist>

  <listitem id="Example:Proteins:construction.py"
            xreflabel="Proteins/construction.py">
    <para> The file
    <ulink url="Examples/Proteins/construction.py.html">construction.py</ulink>
    shows some more complex examples of protein construction from PDB files.
  </para></listitem>

  <listitem id="Example:Proteins:analysis.py"
            xreflabel="Proteins/analysis.py">
    <para> The file
    <ulink url="Examples/Proteins/analysis.py.html">analysis.py</ulink>
    demonstrates a few analysis techniques for comparing protein
    conformations.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:DNA" xreflabel="DNA"><para>
DNA examples
  <itemizedlist>

  <listitem id="Example:DNA:construction.py"
            xreflabel="DNA/construction.py">
    <para> The file
    <ulink url="Examples/DNA/construction.py.html">construction.py</ulink>
    contains the construction of a DNA strand with a ligand.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:MPI" xreflabel="MPI"><para>
MPI examples (parallelization)
  <itemizedlist>

  <listitem id="Example:MPI:md.py"
            xreflabel="MPI/md.py">
    <para> The file
    <ulink url="Examples/MPI/md.py.html">md.py</ulink>
    contains a parallelized version of
    <xref linkend="Example:MolecularDynamics:solvation.py"/>.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:LangevinDynamics">
<para>Langevin dynamics integrator</para>
<para>
The files <ulink url="Examples/LangevinDynamics/LangevinDynamics.py.html">LangevinDynamics.py</ulink> and <ulink url="Examples/LangevinDynamics/MMTK_langevinmodule.c">MMTK_langevinmodule.c</ulink> implement a simple integrator for
Langevin dynamics. It is meant as an example of how to write integrators
etc. in C, but of course it can also be used directly.
</para></listitem>

<listitem id="Example:Visualization" xreflabel="visualization"><para>
Visualization examples
  <itemizedlist>

  <listitem id="Example:Visualization:additional_objects.py"
            xreflabel="Visualization:additional_objects.py">
    <para> The file
    <ulink url="Examples/Visualization/additional_objects.py.html">additional_objects.py</ulink>
    describes the addition of custom graphics objects to the representation
    of a molecular system.
  </para></listitem>

  </itemizedlist>
</para></listitem>

<listitem id="Example:Miscellaneous"><para>
Micellaneous examples
  <itemizedlist>

  <listitem id="Example:Miscellaneous:charge_fit.py"
            xreflabel="Miscellaneous/charge_fit.py">
    <para> The example
    <ulink url="Examples/Miscellaneous/charge_fit.py.html">charge_fit.py</ulink>
    demonstrates fitting point charges to an electrostatic potential
    energy surface.
  </para></listitem>

  <listitem id="Example:Miscellaneous:construct_from_pdb.py"
            xreflabel="Miscellaneous/construct_from_pdb.py">
    <para> The file
    <ulink url="Examples/Miscellaneous/construct_from_pdb.py.html">construct_from_pdb.py</ulink>
    shows how a universe can be built from a PDB file in such a way that
    the internal atom ordering is compatible. This is important for exchanging
    data with other programs.
  </para></listitem>

  <listitem id="Example:Miscellaneous:lattice.py"
            xreflabel="Miscellaneous/lattice.py">
    <para> The file
    <ulink url="Examples/Miscellaneous/lattice.py.html">lattice.py</ulink>
    constructs molecules placed on a lattice.
  </para></listitem>

  <listitem id="Example:Miscellaneous:vector_field.py"
            xreflabel="Miscellaneous/vector_field.py">
    <para> The file
    <ulink url="Examples/Miscellaneous/vector_field.py.html">vector_field.py</ulink>
    shows how vector fields can be used in the analysis and visualization
    of collective motions.
  </para></listitem>

  </itemizedlist>
</para></listitem>

</itemizedlist>

</chapter>

<glossary id="glossary" xreflabel="glossary">

<glossentry>
<glossterm id="Glossary:AbstractBaseClass" xreflabel="abstract base class">
  Abstract base class
</glossterm>
<glossdef><para> A <xref linkend="Glossary:BaseClass"/> that is not
  directly usable by itself, but which defines the common properties
  of several subclasses. Example: the class <xref
  linkend="Class:MMTK.ChemicalObjects.ChemicalObject"/> is an abstract
  base class which defines the common properties of its subclasses
  <xref linkend="Class:MMTK.Atom"/>, <xref
  linkend="Class:MMTK.ChemicalObjects.Group"/>, <xref
  linkend="Class:MMTK.Molecule"/>, <xref
  linkend="Class:MMTK.Complex"/>, and <xref
  linkend="Class:MMTK.AtomCluster"/>. A <xref
  linkend="Glossary:MixInClass"/> is a special kind of abstract base
  class. </para></glossdef>
</glossentry>

<glossentry>
<glossterm id="Glossary:BaseClass" xreflabel="base class">
  Base class
</glossterm>
<glossdef><para> A class from which another class inherits. In most
  cases, the inheriting class is a specialization of the base class.
  For example, the class <xref linkend="Class:MMTK.Molecule"/> is a
  base class of <xref linkend="Class:MMTK.Proteins.PeptideChain"/>,
  because peptide chains are special molecules. Another common
  application is the <xref linkend="Glossary:AbstractBaseClass"/>.
  </para></glossdef>
</glossentry>

<glossentry>
<glossterm id="Glossary:MixInClass" xreflabel="mix-in class">
  Mix-in class
</glossterm>
<glossdef><para>
  A class that is used as a <xref linkend="Glossary:BaseClass"/>
  in other classes with the sole intention of providing methods
  that are common to these classes. Mix-in classes cannot be used
  to create instances. They are a special kind of
  <xref linkend="Glossary:AbstractBaseClass"/>.
  Example: class <xref linkend="Class:MMTK.Collection.GroupOfAtoms"/>.
</para></glossdef>
</glossentry>

<glossentry>
<glossterm id="Glossary:Subclass" xreflabel="subclass">
  Subclass
</glossterm>
<glossdef><para>
  A class that has another class as its <xref linkend="Glossary:BaseClass"/>.
  The subclass is usually a specialization of the base class, and can
  use all of the methods defined in the base class.
  Example: class <xref linkend="Class:MMTK.Proteins.Residue"/> is
  a subclass of <xref linkend="Class:MMTK.ChemicalObjects.Group"/>.
</para></glossdef>
</glossentry>

</glossary>

<bibliography>

<bibliodiv>
<title>References</title>

<biblioentry id="Article:Bondi1964" xreflabel="Bondi1964">
<author><firstname>A.</firstname><surname>Bondi</surname></author>
<title>van der Waals Volumes and Radii</title>
<bibliomisc>J. Phys. Chem.</bibliomisc>
<volumenum>68</volumenum>
<artpagenums>441-451</artpagenums>
<pubdate>1964</pubdate>
</biblioentry>

<biblioentry id="Article:DPMTA" xreflabel="DPMTA">
<authorgroup>
  <author><firstname>William T.</firstname><surname>Rankin</surname></author>
</authorgroup>
<title>
  DPMTA - A Distributed Implementation of the Parallel Multipole Tree
  Algorithm - Version 3.0
</title>
<bibliomisc><ulink url="&dpmta-url;">&dpmta-url;</ulink></bibliomisc>
</biblioentry>

<biblioentry id="Article:Eisenhaber1993" xreflabel="Eisenhaber1993">
<authorgroup>
  <author><firstname>F.</firstname><surname>Eisenhaber</surname></author>
  <author><firstname>P.</firstname><surname>Argos</surname></author>
</authorgroup>
<title>Improved Strategy in Analytic Surface Calculation for Molecular
Systems: Handling of Singularities and Computational Efficiency</title>
<bibliomisc>J. Comp. Chem.</bibliomisc>
<volumenum>14</volumenum>
<issuenum>11</issuenum>
<artpagenums>1272-1280</artpagenums>
<pubdate>1993</pubdate>
</biblioentry>

<biblioentry id="Article:Eisenhaber1995" xreflabel="Eisenhaber1995">
<authorgroup>
  <author><firstname>F.</firstname><surname>Eisenhaber</surname></author>
  <author><firstname>P.</firstname><surname>Lijnzaad</surname></author>
  <author><firstname>P.</firstname><surname>Argos</surname></author>
  <author><firstname>M.</firstname><surname>Scharf</surname></author>
</authorgroup>
<title>The Double Cubic Lattice Method: Efficient Approaches to
Numerical Integration of Surface Area and Volume and to Dot
Surface Contouring of Molecular Assemblies</title>
<bibliomisc>J. Comp. Chem.</bibliomisc>
<volumenum>16</volumenum>
<issuenum>3</issuenum>
<artpagenums>273-284</artpagenums>
<pubdate>1995</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1995" xreflabel="Hinsen1995">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>Influence of constraints on the dynamics of polypeptide chains</title>
<bibliomisc>Phys. Rev. E</bibliomisc>
<volumenum>52</volumenum>
<issuenum></issuenum>
<artpagenums>6868</artpagenums>
<pubdate>1995</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1997" xreflabel="Hinsen1997">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Benoit</firstname><surname>Roux</surname></author>
</authorgroup>
<title>An accurate potential for simulating proton transfer in acetylacetone</title>
<bibliomisc>J. Comp. Chem.</bibliomisc>
<volumenum>18</volumenum>
<artpagenums>368</artpagenums>
<pubdate>1997</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1998" xreflabel="Hinsen1998">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
</authorgroup>
<title>Analysis of domain motions by approximate normal mode
       calculations</title>
<bibliomisc>Proteins</bibliomisc>
<volumenum>33</volumenum>
<issuenum>3</issuenum>
<artpagenums>417-429</artpagenums>
<pubdate>1998</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1999" xreflabel="Hinsen1999">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Aline</firstname><surname>Thomas</surname></author>
  <author><firstname>Martin J.</firstname><surname>Field</surname></author>
</authorgroup>
<title>Analysis of domain motions in large proteins</title>
<bibliomisc>Proteins</bibliomisc>
<volumenum>34</volumenum>
<issuenum>3</issuenum>
<artpagenums>369-382</artpagenums>
<pubdate>1999</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1999a" xreflabel="Hinsen1999a">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>Projection methods for the analysis of complex motions in
       macromolecules</title>
<bibliomisc>Molecular Simulations</bibliomisc>
<volumenum>23</volumenum>
<issuenum>3</issuenum>
<artpagenums>203-241</artpagenums>
<pubdate>1999</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen1999b" xreflabel="Hinsen1999b">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>A simplified force field for describing vibrational protein dynamics
       over the whole frequency range</title>
<bibliomisc>J. Chem. Phys.</bibliomisc>
<volumenum>111</volumenum>
<issuenum>24</issuenum>
<artpagenums>10766-10769</artpagenums>
<pubdate>1999</pubdate>
</biblioentry>

<biblioentry id="Article:Hinsen2000" xreflabel="Hinsen2000">
<authorgroup>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Andrei J.</firstname><surname>Petrescu</surname></author>
  <author><firstname>Serge</firstname><surname>Dellerue</surname></author>
  <author><firstname>Marie-Claire</firstname>
          <surname>Bellissent-Funel</surname></author>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>Harmonicity in slow protein dynamics</title>
<bibliomisc>submitted</bibliomisc>
</biblioentry>

<biblioentry id="Article:Kneller1990" xreflabel="Kneller1990">
<authorgroup>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>Superposition of molecular structures using quaternions</title>
<bibliomisc>Mol. Sim.</bibliomisc>
<volumenum>7</volumenum>
<artpagenums>113-119</artpagenums>
<pubdate>1990</pubdate>
</biblioentry>

<biblioentry id="Article:Kneller1996" xreflabel="Kneller1996">
<authorgroup>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
  <author><firstname>Thomas</firstname><surname>Mülders</surname></author>
</authorgroup>
<title>Nosé-Andersen dynamics of partially rigid molecules: Coupling
       of all degrees of freedom to heat and pressure baths</title>
<bibliomisc>Phys. Rev. E</bibliomisc>
<volumenum>54</volumenum>
<artpagenums>6825-6837</artpagenums>
<pubdate>1996</pubdate>
</biblioentry>

<biblioentry id="Article:Swope1982" xreflabel="Swope1982">
<authorgroup>
  <author><firstname>W.C.</firstname><surname>Swope</surname></author>
  <author><firstname>H.C.</firstname><surname>Andersen</surname></author>
  <author><firstname>P.H.</firstname><surname>Berens</surname></author>
  <author><firstname>K.R.</firstname><surname>Wilson</surname></author>
</authorgroup>
<title>A computer simulation method for the calculation of equilibrium
       constants for the formation of physical clusters of molecules:
       application to small water clusters</title>
<bibliomisc>J. Chem. Phys.</bibliomisc>
<volumenum>76</volumenum>
<artpagenums>637--649</artpagenums>
<pubdate>1982</pubdate>
</biblioentry>

<biblioentry id="Article:vanGunsteren1982" xreflabel="vanGunsteren1982">
<authorgroup>
  <author><firstname>Wilfred F.</firstname>
  <surname>van Gunsteren</surname></author>
  <author><firstname>Martin</firstname><surname>Karplus</surname></author>
</authorgroup>
<title>Effect of Constraints on the Dynamics of Macromolecules</title>
<bibliomisc>Macromolecules</bibliomisc>
<volumenum>15</volumenum>
<issuenum></issuenum>
<artpagenums>1528-1544</artpagenums>
<pubdate>1982</pubdate>
</biblioentry>

<biblioentry id="Article:Viduna2000" xreflabel="Viduna2000">
<authorgroup>
  <author><firstname>David</firstname><surname>Viduna</surname></author>
  <author><firstname>Konrad</firstname><surname>Hinsen</surname></author>
  <author><firstname>Gerald R.</firstname><surname>Kneller</surname></author>
</authorgroup>
<title>The influence of molecular flexibility on DNA radiosensitivity:
       A simulation study</title>
<bibliomisc>Phys. Rev. E, in print</bibliomisc>
</biblioentry>

<biblioentry id="Article:Wolf1999" xreflabel="Wolf1999">
<authorgroup>
  <author><firstname>D.</firstname><surname>Wolf</surname></author>
  <author><firstname>P.</firstname><surname>Keblinski</surname></author>
  <author><firstname>S.R.</firstname><surname>Philpot</surname></author>
  <author><firstname>J.</firstname><surname>Eggebrecht</surname></author>
</authorgroup>
<title>Exact method for the simulation of Coulombic systems by spherically
truncated, pairwise r<superscript>-1</superscript> summation</title>
<bibliomisc>J. Chem. Phys.</bibliomisc>
<volumenum>110</volumenum>
<issuenum>17</issuenum>
<artpagenums>8254-8282</artpagenums>
<pubdate>1999</pubdate>
</biblioentry>

</bibliodiv>

</bibliography>

</book>
