Analysis and manipulation
This chapter describes operations that are used to analyze molecular
systems and to apply specific manipulations.
Properties of chemical objects and collections
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. All operations are methods to be called on an object.
Only operations not already treated in the section
"Analyzing and modifying coordinates"
are described here.
- numberOfAtoms() returns the number of atoms in the object.
- atomList() returns a list of the atoms in the object.
- atomCollection() returns a collection of the atoms in the object.
- mass() returns the total mass of all atoms in the object.
- temperature() returns the temperature of the object.
An optional argument indicates a universe velocity variable (default is
the current velocity set).
- momentum() returns the momentum of the object.
An optional argument indicates a universe velocity variable (default is
the current velocity set).
- angularMomentum() returns the angular momentum of the object.
Two optional arguments indicate a universe velocity variable (default is
the current velocity set) and a universe configuration variable (default
is the current configuration).
- charge() returns the total charge of the object. This
function is available only if the object is in a universe with a force field
that supports atomic charge calculation.
- dipole() returns the total dipole moment of the object.
An optional argument specifies the reference point; the default is the
center of mass. This function is available only if the object is in a
universe with a force field that supports atomic charge calculation.
- writeToFile(filename) writes the object to a file. Optional
arguments are a universe configuration variable (default is the current
configuration) and a string indicating the file format as either
'pdb' (default) or 'vrml'.
- view() displays the object by running an external
visualization program. This method is equivalent to the function
view(object) described
elsewhere.
- universe() returns the universe to which an object belongs.
It returns None if the object belongs to no universe.
Some additional operations are available only for all chemical objects
(atoms, molecules, etc.):
- fullName() returns the full name of the object, i.e. including
the names of all parent objects.
- topLevelChemicalObject() returns the top-level chemical object
of which the object is a part.
Other operations are defined only for collections and universes:
- map(function) applies the function to all chemical objects
in the collection. The result is a collection if the return values are
chemical objects, otherwise it is a list.
- objectList() returns a list of all chemical objects in the
collection.
Collections and universes can also be used as sequence objects, i.e.
len() returns the number of chemical objects they contain,
indexing extracts individual chemical objects, and for-loops
can be used to iterate over the objects.
Operations on peptide chains and proteins
A number of operations defined on proteins or peptide chains
make use of the special structure of these objects. Of course,
peptide chains are special molecules, and proteins are special
complexes; therefore, all the operations on the basic types are
also available for peptide chains and proteins.
The following methods are defined on peptide chains and proteins:
- residues() returns a collection of all residues.
- residuesOfType(types) returns a collection of all
residues whose type (the three-letter amino acid name) is in the
list of types supplied as argument.
- backbone() returns a collection of all peptide groups.
- sidechain() returns a collection of all sidechain groups.
- phiPsi() returns a tuple (phi, psi) of backbone
dihedral angles for each residue.
Peptide chains have three additional methods:
- sequence() returns the amino acid sequence as a list
of three-letter residue names.
- replaceResidue(old, new) replaces residue old
(a residue object, which must be in this peptide chain) by residue
new (also a residue object, which however may not be in any
peptide chain).
- findHydrogenPositions() determines the positions of hydrogen
atoms which are undefined in the current configuration. It uses a
heuristic method based on typical configurations for amino acids;
it does not make use of any force field.
Proteins offer the method setConfiguration(configuration),
which sets the current configuration of the protein. The parameter
must be either a PDB configuration read from a PDB file, or a filename
indicating a PDB file from which the configuration is to be read.
Both proteins and peptide chains are sequence objects, i.e. they
can be asked for their length, asked for a specific element, and
iterated over with a for-loop. The items of a protein are
its chains; the items of a peptide chain are the residues, starting
at the C terminus.
Surfaces and volumes
Surfaces and volumes can be analyzed for any collection 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 A.
Bondi, van der Waals Volumes and Radii, J. Phys. Chem. 68
(1964), p. 441-451. However, users can change these values for
each individual atom by assigning a new value to the attribute
"vdW_radius".
The method surfaceAndVolume() returns the surface and its
enclosed volume as a tuple. An optional argument specifies a probe
radius, i.e. a radius added to each atom radius before the
calculation. Its default value is zero. The method
surfaceAtoms() (also with an optional probe radius argument)
returns a dictionary whose keys are the surface atoms and whose values
are the exposed surface areas of the individual atoms.
A related operation is the determination of contacts between two
groups of atoms. The method findContacts(other_group) returns
a list of contacts. Two optional arguments determine which distances
are counted as contacts: a factor f (default 1) and an offset
o (default 0). Two atoms are considered to form a contact if
their distance is less than
f*(r1+r2+o),
with r1 and r2 being the van
der Waals radii of the two atoms. Each contact is described by a
special two-element sequence object (containing the two atoms) that
defines an order relation between contacts based on the interatomic
distance.
Energy evaluation
Energy evaluation requires a force field, and therefore all the
methods in this section are defined only for universe objects.
However, they all take optional arguments (anything that can be broken
down into atoms) that indicate which subset of the energy terms is to
be evaluated. No arguments means all terms, one argument means all
terms within the group specified by it, and two arguments mean all
terms between the two groups specified.
- energy() returns the energy for the current configuration.
- energyAndGradients() returns the energy and energy gradients
for the current configuration. The gradients are returned as a variable
object.
- energyAndForceConstants() returns the energy and force constants
(second derivatives) for the current configuration. The force constants are
returned as a variable object.
- energyGradientsAndForceConstants() returns the energy, the
energy gradients, and the force constants (second derivatives) for the
current configuration. The gradients and force constants are
returned as a variable object.
- energyTerms() returns the energy for the current configuration
as a dictionary of the individual force field terms.
Operations on universes
Geometrical calculations. Note that these must be defined as methods
on universes to take account of periodic systems correctly.
- distanceVector(o1, o2) returns the vector from the center
of mass of object o1 to the center of mass of object
o2. An optional third argument specifies a configuration
variable; default is the current configuration.
- distance(o1, o2) returns the distance from the center of
mass of object o1 to the center of mass of object
o2. An optional third argument specifies a configuration
variable; default is the current configuration.
- angle(o1, o2, o3) returns the angle at the center of mass
of o2between the directions pointing toward the centers of
mass of o1 and o3. An optional fourth argument
specifies a configuration variable; default is the current
configuration.
- dihedral(o1, o2, o3, o4) returns the dihedral angle
between the planes (o1, o2, o3) and o2, o3, o4 along
the axis o2-o3. An optional fifth argument
specifies a configuration variable; default is the current
configuration.
Configurations and velocities.
- configuration() returns the universe variable
containing the current configuration. To store the current configuration
before it is changed by some operation, it is necessary to make a copy of
the current configuration.
- velocities() returns the universe variable
containing the current velocities. To store the current velocities
before they are changed by some operation, it is necessary to make a copy of
the current velocity variable.
- velocities() returns the universe variable containing the
atomic masses.
- atomNames() returns a list of the full names of all atoms,
sorted like universe variables (configuration, velocities, etc.).
- setConfiguration(configuration) copies the configuration
specified into the current configuration.
- setFromTrajectory(trajectory, step_number) sets the
current configuration and velocities (if availble) to the values
taken from a certain step in a trajectory file.
- renumberAtoms(number_list) changes the atom indices used in
universe variables according to the supplied list of integers.
Table of contents