Module Reference

MMTK

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:

  • Vector from Scientific.Geometry
  • Translation and Rotation from Scientific.Geometry.Transformation
  • copy and deepcopy from copy
  • stdin, stdout, and stderr from sys

MMTK.Biopolymers

Base classes for proteins and nucleic acids

class MMTK.Biopolymers.Residue(group_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.Group

Base class for aminoacid and nucleic acid residues

Parameters:
  • group_spec (str) – a string (not case sensitive) that specifies the group name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the group
  • name (str) – a name given to the group
class MMTK.Biopolymers.ResidueChain(molecule_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.Molecule

Chain of residues

Base class for peptide chains and nucleotide chains

Parameters:
  • molecule_spec (str) – a string (not case sensitive) that specifies the molecule name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the molecule
  • name (str) – a name given to the molecule
  • configuration (str) – 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.
residues()[source]
Returns:a collection containing all residues
Return type:Collection
residuesOfType(*types)[source]
Parameters:
  • types (str) – residue type codes
Returns:

a collection that contains all residues whose type (residue code) is contained in types

Return type:

Collection

sequence()[source]
Returns:the residue sequence as a list of residue codes
Return type:list of str
MMTK.Biopolymers.defineAminoAcidResidue(full_name, code3, code1=None)[source]

Add a non-standard amino acid residue to the internal residue table. Once added to the residue table, the new residue can be used like any of the standard residues in the creation of peptide chains.

Parameters:
  • full_name (str) – the name of the group definition in the chemical database
  • code3 (str) – the three-letter residue code
  • code1 (str) – an optionel one-letter residue code
MMTK.Biopolymers.defineNucleicAcidResidue(full_name, code)[source]

Add a non-standard nucleic acid residue to the internal residue table. Once added to the residue table, the new residue can be used like any of the standard residues in the creation of nucleotide chains.

Parameters:
  • full_name (str) – the name of the group definition in the chemical database
  • code – the residue code

MMTK.Bonds

Bonds, bond lists, bond angle lists, and dihedral angle lists

The classes in this module are normally not used directly from client code. They are used by the classes in ChemicalObjects and ForceField.

class MMTK.Bonds.Bond(blueprint, memo=None)[source]

Bases: object

Chemical bond

A bond links two atoms (attributes a1 and a2)

hasAtom(a)[source]
Parameters:
  • a (Atom) – an atom
Returns:

True if a participates in the bond

otherAtom(a)[source]
Parameters:
  • a (Atom) – an atom involved in the bond
Returns:

the atom at the other end of the bond

Return type:

Atom

Raises ValueError:
 

if a does not belong to the bond

class MMTK.Bonds.BondAngle(b1, b2, ca)[source]

Bases: object

Bond angle

A bond angle is the angle between two bonds that share a common atom. It is defined by two bond objects (attributes b1 and b2) and an atom object (the common atom, attribute ca).

otherBond(bond)[source]
Parameters:
  • bond (Bond) – a bond involved in the angle
Returns:

the other bond involved in the angle

Return type:

Bond

Raises ValueError:
 

if bond does not belong to the angle

class MMTK.Bonds.BondAngleList(angles)[source]

Bases: object

Bond angle list

dihedralAngles()[source]
Returns:a list of all dihedral angles that can be formed from the bond angles in the list
Return type:DihedralAngleList
class MMTK.Bonds.DihedralAngle(ba1, ba2, cb)[source]

Bases: object

Dihedral angle

A dihedral angle is the angle between two planes that are defined by BondAngle objects (attributes ba1 and ba2) and their common bond (attribute cb).

There are proper dihedrals (four atoms linked by three bonds in sequence) and improper dihedrals (a central atom linked to three surrounding atoms by three bonds). The boolean attribute improper indicates whether a dihedral is an improper one.

class MMTK.Bonds.DihedralAngleList(dihedrals)[source]

Bases: object

Dihedral angle list

MMTK.ChargeFit

Fit of point chages to an electrostatic potential surface

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.

The charge fitting method is described in:

K. Hinsen and B. Roux,
An accurate potential for simulating proton transfer in acetylacetone,
J. Comp. Chem. 18, 1997: 368

See also Examples/Miscellaneous/charge_fit.py.

class MMTK.ChargeFit.ChargeFit(system, points, constraints=None)[source]

Bases: object

Fit of point charges to an electrostatic potential surface

A ChargeFit object acts like a dictionary that stores the fitted charge value for each atom in the system.

Parameters:
  • system – any chemical object (usually a molecule)
  • points – 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.
  • constraints – an optional 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.
class MMTK.ChargeFit.EqualityConstraint(atom1, atom2)[source]

Bases: object

Constraint forcing two charges to be equal

To be used with ChargeFit

Any atom may occur in more than one EqualityConstraint object, in order to keep the charges of more than two atoms equal.

Parameters:
  • atom1 (Atom) – the first atom in the equality relation
  • atom2 (Atom) – the second atom in the equality relation
class MMTK.ChargeFit.TotalChargeConstraint(system, charge)[source]

Bases: object

Constraint on the total system charge

To be used with ChargeFit

Parameters:
  • system – any chamical object whose total charge is to be constrained
  • charge (number) – the total charge value
MMTK.ChargeFit.evaluationPoints(system, n, smallest=0.29999999999999999, largest=0.5)[source]

Generate points in space around a molecule that are suitable for potential evaluation in view of a subsequent charge fit. The points are chosen at random and uniformly in a shell around the system.

Parameters:
  • system – the chemical object for which the charges will be fitted
  • n – the number of evaluation points to be generated
  • smallest – the smallest allowed distance of any evaluation point from any non-hydrogen atom
  • largest – the largest allowed value for the distance from an evaluation point to the nearest atom
Returns:

a list of evaluation points

Return type:

list of Scientific.Geometry.Vector

MMTK.ChemicalObjects

Atoms, groups, molecules and similar objects

class MMTK.ChemicalObjects.Atom(atom_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.ChemicalObject

Atom

Parameters:
  • atom_spec (str) – a string (not case sensitive) specifying the chemical element
  • position (Scientific.Geometry.Vector) – the position of the atom
  • name (str) – a name given to the atom
bondedTo()[source]
Returns:a list of all atoms to which a chemical bond exists.
Return type:list
centerOfMass(conf=None)
Returns:the position in configuration conf. If conf is ‘None’, use the current configuration. If the atom has not been assigned a position, the return value is None.
position(conf=None)[source]
Returns:the position in configuration conf. If conf is ‘None’, use the current configuration. If the atom has not been assigned a position, the return value is None.
setMass(mass)[source]

Changes the mass of the atom.

Parameters:
  • mass (float) – the mass
setPosition(position)[source]

Changes the position of the atom.

Parameters:
  • position (Scientific.Geometry.Vector) – the new position
translateTo(position)

Changes the position of the atom.

Parameters:
  • position (Scientific.Geometry.Vector) – the new position
class MMTK.ChemicalObjects.AtomCluster(atoms, **properties)[source]

Bases: MMTK.ChemicalObjects.CompositeChemicalObject, MMTK.ChemicalObjects.ChemicalObject

An agglomeration of atoms

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.

Parameters:
  • atoms (list) – a list of atoms in the cluster
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the cluster
  • name (str) – a name given to the cluster
class MMTK.ChemicalObjects.ChainMolecule(molecule_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.Molecule

ChainMolecule

ChainMolecules are generated by a MoleculeFactory from templates that have a sequence attribute.

Parameters:
  • molecule_spec (str) – a string (not case sensitive) that specifies the molecule name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the molecule
  • name (str) – a name given to the molecule
  • configuration (str) – 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.
class MMTK.ChemicalObjects.ChemicalObject(blueprint, memo)[source]

Bases: MMTK.Collections.GroupOfAtoms, MMTK.Visualization.Viewable

General chemical object

This is an abstract base class that implements methods which are applicable to any chemical object (atom, molecule, etc.).

atomIterator()[source]
Returns:an iterator over all atoms in the object
Return type:iterator
atomList()[source]
Returns:a list containing all atoms in the object
Return type:list
bondedUnits()[source]
Returns:the largest subobjects which can contain bonds. There are no bonds between any of the subobjects in the list.
Return type:list
degreesOfFreedom()[source]
Returns:the number of degrees of freedom of the object
Return type:int
distanceConstraintList()[source]
Returns:the distance constraints of the object
Return type:list
fullName()[source]
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.
Return type:str
getAtomProperty(atom, property)[source]

Retrieve atom properties from the chemical database.

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.

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.

Returns:the value of the specified property for the given atom from the chemical database.
numberOfDistanceConstraints()[source]
Returns:the number of distance constraints of the object
Return type:int
removeDistanceConstraints(universe=None)[source]

Removes all distance constraints.

setBondConstraints(universe=None)[source]

Sets distance constraints for all bonds.

setRigidBodyConstraints(universe=None)[source]

Sets distance constraints that make the object fully rigid.

topLevelChemicalObject()[source]

Returns the highest-level chemical object of which the current object is a part.

universe()[source]
Returns:the universe to which the object belongs, or None if the object does not belong to any universe
Return type:Universe
class MMTK.ChemicalObjects.Complex(complex_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.CompositeChemicalObject, MMTK.ChemicalObjects.ChemicalObject

Complex

A complex is an assembly of molecules that are not connected by chemical bonds.

Parameters:
  • complex_spec (str) – a string (not case sensitive) that specifies the complex name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the complex
  • name (str) – a name given to the complex
  • configuration (str) – the name of a configuration listed in the database definition of the complex, 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.
class MMTK.ChemicalObjects.CompositeChemicalObject(properties)[source]

Bases: object

Chemical object containing subobjects

This is an 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.

class MMTK.ChemicalObjects.Group(group_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.CompositeChemicalObject, MMTK.ChemicalObjects.ChemicalObject

Group of bonded atoms

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.

Groups cannot be created in application programs, but only in database definitions for molecules or through a MoleculeFactory.

Parameters:
  • group_spec (str) – a string (not case sensitive) that specifies the group name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the group
  • name (str) – a name given to the group
class MMTK.ChemicalObjects.Molecule(molecule_spec, _memo=None, **properties)[source]

Bases: MMTK.ChemicalObjects.CompositeChemicalObject, MMTK.ChemicalObjects.ChemicalObject

Molecule

Molecules consist of atoms and groups linked by bonds.

Parameters:
  • molecule_spec (str) – a string (not case sensitive) that specifies the molecule name in the chemical database
  • position (Scientific.Geometry.Vector) – the position of the center of mass of the molecule
  • name (str) – a name given to the molecule
  • configuration (str) – 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.
findHydrogenPositions()[source]

Find reasonable positions for hydrogen atoms that have no position assigned.

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.

MMTK.ChemicalObjects.isChemicalObject(object)[source]
Returns:True if object is a chemical object

MMTK.Collections

Collections of chemical objects

class MMTK.Collections.Collection(*objects)[source]

Bases: MMTK.Collections.GroupOfAtoms, MMTK.Visualization.Viewable

Collection of chemical objects

Collections permit the grouping of arbitrary chemical objects (atoms, molecules, etc.) into one object for the purpose of analysis or manipulation.

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.

Parameters:
  • objects – a chemical object or a sequence of chemical objects that define the initial content of the collection.
addObject(object)[source]

Add objects to the collection.

Parameters:
  • object – the object(s) to be added. If it is another collection or a list, all of its elements are added
atomList()[source]
Returns:a list containing all atoms of all objects in the collection
Return type:list
distanceConstraintList()[source]
Returns:the list of distance constraints
Return type:list
map(function)[source]

Apply a function to all objects in the collection and return the list of the results. If the results are chemical objects, a Collection object is returned instead of a list.

Parameters:
  • function (callable) – the function to be applied
Returns:

the list or collection of the results

numberOfAtoms()[source]
Returns:the total number of atoms in the objects of the collection
Return type:int
numberOfDistanceConstraints()[source]
Returns:the number of distance constraints
objectList(type=None)[source]

Make a list of all objects in the collection that are instances of a specific type or of one of its subtypes.

Parameters:
  • type – the type that serves as a filter. If None, all objects are returned
Returns:

the objects that match the given type

Return type:

list

removeDistanceConstraints(universe=None)[source]

Remove all distance constraints

removeObject(object)[source]

Remove an object or a list or collection of objects from the collection. The object(s) to be removed must be elements of the collection.

Parameters:
  • object – the object to be removed, or a list or collection of objects whose elements are to be removed
Raises ValueError:
 

if the object is not an element of the collection

selectBox(p1, p2)[source]

Select objects in a rectangular volume

Parameters:
  • p1 (Scientific.Geometry.Vector) – one corner of the rectangular volume
  • p2 (Scientific.Geometry.Vector) – the other corner of the rectangular volume
Returns:

a collection of all elements that lie within the rectangular volume

Return type:

Collection

selectShell(point, r1, r2=0.0)[source]

Select objects in a spherical shell around a central point.

Parameters:
  • point (Scientific.Geometry.Vector) – the center of the spherical shell
  • r1 (float) – inner or outer radius of the shell
  • r2 (float) – inner or outer radius of the shell (default: 0.)
Returns:

a collection of all elements whose distance from point is between r1 and r2

Return type:

Collection

setBondConstraints(universe=None)[source]

Set distance constraints for all bonds

universe()[source]
Returns:the universe of which all objects in the collection are part. If no such universe exists, the return value is None
class MMTK.Collections.GroupOfAtoms[source]

Bases: object

Anything that consists of atoms

A mix-in class 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.

angularMomentum(velocities=None, conf=None)[source]
Parameters:
  • velocities (ParticleVector) – a set of velocities for all atoms, or None for the current velocities
  • conf (Configuration) – a configuration object, or None for the current configuration
Returns:

the angluar momentum

Return type:

Scientific.Geometry.Vector

angularVelocity(velocities=None, conf=None)[source]
Parameters:
  • velocities (ParticleVector) – a set of velocities for all atoms, or None for the current velocities
  • conf (Configuration) – a configuration object, or None for the current configuration
Returns:

the angluar velocity

Return type:

Scientific.Geometry.Vector

applyTransformation(t)[source]

Apply a transformation to the object

Parameters:
  • t (Scientific.Geometry.Transformation) – the transformation to be applied
atomCollection()[source]
Returns:a collection containing all atoms in the object
atomsWithDefinedPositions(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

a collection of all atoms that have a position in the given configuration

booleanMask()[source]
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
Return type:ParticleScalar
boundingBox(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
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.

Return type:

tuple of two Scientific.Geometry.Vector

boundingSphere(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

a sphere that contains all atoms in the object. This is B{not} the minimal bounding sphere, just B{some} bounding sphere.

Return type:

Scientific.Geometry.Objects3D.Sphere

centerAndMomentOfInertia(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

the center of mass and the moment of inertia tensor in the given configuration

centerOfMass(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

the center of mass in the given configuration

Return type:

Scientific.Geometry.Vector

charge()[source]
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.
Return type:float
degreesOfFreedom()[source]
Returns:the number of mechanical degrees of freedom
Return type:int
dipole(reference=None)[source]
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.
Return type:Scientific.Geometry.Vector
displacementUnderTransformation(t)[source]
Parameters:
  • t (Scientific.Geometry.Transformation) – the transformation to be applied
Returns:

the displacement vectors for the atoms in the object that correspond to the transformation t.

Return type:

ParticleVector

findTransformation(conf1, conf2=None)[source]
Parameters:
  • conf1 (Configuration) – a configuration object
  • conf2 (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

the linear transformation that, when applied to the object in configuration conf1, minimizes the RMS distance to the conformation in conf2, and the minimal RMS distance. If conf2 is None, returns the transformation from the current configuration to conf1 and the associated RMS distance.

kineticEnergy(velocities=None)[source]
Parameters:
  • velocities (ParticleVector) – a set of velocities for all atoms, or None for the current velocities
Returns:

the kinetic energy

Return type:

float

mass()[source]
Returns:the total mass
Return type:float
momentum(velocities=None)[source]
Parameters:
  • velocities (ParticleVector) – a set of velocities for all atoms, or None for the current velocities
Returns:

the momentum

Return type:

Scientific.Geometry.Vector

normalizeConfiguration(repr=None)[source]

Apply a linear transformation such that the center of mass of the object is translated to the coordinate origin and its principal axes of inertia become parallel to the three coordinate axes.

Parameters:
  • repr – the specific representation for axis alignment: - Ir : x y z <–> b c a - IIr : x y z <–> c a b - IIIr : x y z <–> a b c - Il : x y z <–> c b a - IIl : x y z <–> a c b - IIIl : x y z <–> b a c
normalizePosition()[source]

Translate the center of mass to the coordinate origin

normalizingTransformation(repr=None)[source]

Calculate a linear transformation that shifts the center of mass of the object to the coordinate origin and makes its principal axes of inertia parallel to the three coordinate axes.

Parameters:
  • repr – the specific representation for axis alignment: Ir : x y z <–> b c a IIr : x y z <–> c a b IIIr : x y z <–> a b c Il : x y z <–> c b a IIl : x y z <–> a c b IIIl : x y z <–> b a c
Returns:

the normalizing transformation

Return type:

Scientific.Geometry.Transformation.RigidBodyTransformation

numberOfAtoms()[source]
Returns:the number of atoms
Return type:int
numberOfCartesianCoordinates()
Returns:the number of geometrical points that define the object. It is currently 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.
Return type:int
numberOfFixedAtoms()[source]
Returns:the number of atoms that are fixed, i.e. that cannot move
Return type:int
numberOfPoints()[source]
Returns:the number of geometrical points that define the object. It is currently 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.
Return type:int
position(conf=None)
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

the center of mass in the given configuration

Return type:

Scientific.Geometry.Vector

rmsDifference(conf1, conf2=None)[source]
Parameters:
  • conf1 (Configuration) – a configuration object
  • conf2 (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

the RMS (root-mean-square) difference between the conformations of the object in two universe configurations, conf1 and conf2

Return type:

float

rotateAroundAxis(point1, point2, angle)[source]

Rotate the object arond an axis specified by two points

Parameters:
  • point1 (Scientific.Geometry.Vector) – the first point
  • point2 (Scientific.Geometry.Vector) – the second point
  • angle (float) – the rotation angle (in radians)
rotateAroundCenter(axis_direction, angle)[source]

Rotate the object around an axis that passes through its center of mass.

Parameters:
  • axis_direction (Scientific.Geometry.Vector) – the direction of the axis of rotation
  • angle (float) – the rotation angle (in radians)
rotateAroundOrigin(axis_direction, angle)[source]

Rotate the object around an axis that passes through the coordinate origin.

Parameters:
  • axis_direction (Scientific.Geometry.Vector) – the direction of the axis of rotation
  • angle (float) – the rotation angle (in radians)
rotationalConstants(conf=None)[source]
Parameters:
  • conf (Configuration or NoneType) – a configuration object, or None for the current configuration
Returns:

a sorted array of rotational constants A, B, C in internal units

temperature(velocities=None)[source]
Parameters:
  • velocities (ParticleVector) – a set of velocities for all atoms, or None for the current velocities
Returns:

the temperature

Return type:

float

translateBy(vector)[source]

Translate the object by a displacement vector

Parameters:
  • vector (Scientific.Geometry.Vector) – the displacement vector
translateTo(position)[source]

Translate the object such that its center of mass is at position :param position: the final position :type position: Scientific.Geometry.Vector

universe()[source]
Returns:the universe of which the object is part. For an object that is not part of a universe, the result is None
view(configuration=None, format='pdb')[source]

Start an external viewer for the object in the given configuration.

Parameters:
  • configuration (Configuration) – the configuration to be visualized
  • format – ‘pdb’ (for running $PDBVIEWER) or ‘vrml’ (for running $VRMLVIEWER). An optional subformat specification can be added, see writeToFile for the details.
writeToFile(filename, configuration=None, format=None)[source]

Write a representation of the object in a given configuration to a file.

Parameters:
  • filename (str) – the name of the file
  • configuration (Configuration or NoneType) – a configuration object, or None for the current configuration
  • format (str) – ‘pdb’ or ‘vrml’ (default: guess from filename) A subformat specification can be added, separated by a dot. Subformats of ‘vrml’ are ‘wireframe’ (default), ‘ball_and_stick’, ‘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 whose color indicates the charge on a red-to-green color scale)
class MMTK.Collections.PartitionedAtomCollection(*args)[source]

Bases: MMTK.Collections.PartitionedCollection

Partitioned collection of atoms

PartitionedAtomCollection objects behave like PartitionedCollection atoms, except that they store only atoms. When a composite chemical object is added, its atoms are stored instead.

class MMTK.Collections.PartitionedCollection(partition_size, *objects)[source]

Bases: MMTK.Collections.Collection

Collection with cubic partitions

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.

Parameters:
  • partition_size – the edge length of the cubic cells
  • objects – a chemical object or a sequence of chemical objects that define the initial content of the collection.
pairsWithinCutoff(cutoff)[source]
Parameters:
  • cutoff – a cutoff for pair distances
Returns:

a list containing all pairs of objects in the collection whose center-of-mass distance is less than the cutoff

Return type:

list

partitions()[source]
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.
MMTK.Collections.isCollection(object)[source]
Parameters:
  • object – any Python object
Returns:

True if the object is a Collection

MMTK.ConfigIO

I/O of molecular configurations

Input: Z-Matrix and Cartesian Output: VRML PDB files are handled in PDB.

class MMTK.ConfigIO.Cartesian(data)[source]

Bases: object

Cartesian specification of a molecule conformation

Cartesian objects can be used in chemical database entries to specify molecule conformations by Cartesian coordinates.

Parameters:
  • data – a dictionary mapping atoms to tuples of length three that define its Cartesian coordinates
applyTo(object)[source]

Define the positions of the atoms in a chemical object by the stored coordinates.

Parameters:
  • object – the object to which the coordinates are applied
class MMTK.ConfigIO.ZMatrix(data)[source]

Bases: object

Z-Matrix specification of a molecule conformation

ZMatrix objects can be used in chemical database entries to specify molecule conformations by internal coordinates. With the exception of the three first atoms, each atom is defined relative to three previously atoms by a distance, an angle, and a dihedral angle.

Parameters:
  • data

    a list of atom definitions. Each atom definition (except for the first three ones) is a list containing seven elements:

    • the atom to be defined
    • a previously defined atom and the distance to it
    • another previously defined atom and the angle to it
    • a third previously defined atom and the dihedral angle to it

    The definition of the first atom contains only the first element, the second atom needs the first three elements, and the third atom is defined by the first five elements.

applyTo(object)[source]

Define the positions of the atoms in a chemical object by the internal coordinates of the Z-Matrix.

Parameters:
  • object – the object to which the Z-Matrix is applied

MMTK.DCD

Reading and writing of DCD trajectory files

The DCD format for trajectories is used by CHARMM, X-Plor, and NAMD. It can be read by various visualization programs.

The DCD format is defined as a binary (unformatted) Fortran format and is therefore platform-dependent.

class MMTK.DCD.DCDReader(universe, **options)[source]

Bases: MMTK.Trajectory.TrajectoryGenerator

Reader for DCD trajectories (CHARMM/X-Plor/NAMD)

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.

Reading is started by calling the reader object. The following data categories and variables are available for output:

  • category “time”: time
  • category “configuration”: configuration
Parameters:
  • universe – the universe for which the information from the trajectory file is read
  • options – keyword options
  • dcd_file – the name of the DCD trajecory file to be read
  • actions – a list of actions to be executed periodically (default is none)
MMTK.DCD.writeDCDPDB(conf_list, dcd_file_name, pdb_file_name, delta_t=0.10000000000000001)[source]

Write a sequence of configurations to a DCD file and generate a compatible PDB file.

Parameters:
  • conf_list (sequence of Configuration) – the sequence of configurations
  • dcd_file_name (str) – the name of the DCD file
  • pdb_file_name (str) – the name of the PDB file
  • delta_t (float) – the time step between two configurations
MMTK.DCD.writeVelocityDCDPDB(vel_list, dcd_file_name, pdb_file_name, delta_t=0.10000000000000001)[source]

Write a sequence of velocity particle vectors to a DCD file and generate a compatible PDB file.

Parameters:
  • vel_list (sequence of ParticleVector) – the sequence of velocity particle vectors
  • dcd_file_name (str) – the name of the DCD file
  • pdb_file_name (str) – the name of the PDB file
  • delta_t (float) – the time step between two velocity sets

MMTK.Deformation

Deformation energies in proteins

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 the following articles:

K. Hinsen
Analysis of domain motions by approximate normal mode calculations
Proteins 33 (1998): 417-429
K. Hinsen, A. Thomas, M.J. Field
Analysis of domain motions in large proteins
Proteins 34 (1999): 369-382
class MMTK.Deformation.DeformationEnergyFunction(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Infinite-displacement deformation energy function

The deformation energy is the sum of the deformation values over all atoms of a system.

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.DeformationFunction(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Infinite-displacement deformation function

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.DeformationReducer(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Iterative reduction of the deformation energy

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.FiniteDeformationEnergyFunction(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Finite-displacement deformation energy function

The deformation energy is the sum of the deformation values over all atoms of a system.

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.FiniteDeformationFunction(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Finite-displacement deformation function

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.FiniteDeformationReducer(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEvaluationFunction

Iterative reduction of the finite-displacement deformation energy

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.NormalizedDeformationEnergyFunction(universe, fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0, form='exponential')[source]

Bases: MMTK.Deformation.DeformationEnergyFunction

Normalized infinite-displacement deformation energy function

The normalized deformation energy is the sum of the normalized deformation values over all atoms of a system.

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above. The normalization is defined by equation 10 of reference 1.

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.

Parameters:
  • universe (Universe) – the universe for which the deformation function is defined
  • fc_length (float) – the range parameter r_0 in the pair interaction term
  • cutoff (float) – the cutoff used in the deformation calculation
  • factor (float) – a global scaling factor
  • form (str) – the functional form (‘exponential’ or ‘calpha’)
class MMTK.Deformation.NormalizedDeformationFunction(*args, **kwargs)[source]

Bases: MMTK.Deformation.DeformationFunction

Normalized infinite-displacement deformation function

The default values are appropriate for a Cα model of a protein with the global scaling described in the reference cited above. The normalization is defined by equation 10 of reference 1 (see above).

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.

MMTK.Dynamics

Molecular Dynamics integrators

class MMTK.Dynamics.BarostatReset(first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Barostat reset action

A BarostatReset object is used in the action list of a VelocityVerletIntegrator. It resets the barostat coordinate to zero.

Parameters:
  • first (int) – the number of the first step at which the action is executed
  • last (int) – the number of the first step at which the action is no longer executed. A value of None indicates that the action should be executed indefinitely.
  • skip (int) – the number of steps to skip between two applications of the action
class MMTK.Dynamics.Heater(temp1, temp2, gradient, first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Periodic heating action

A Heater object us used in the action list of a VelocityVerletIntegrator. It scales the velocities to a temperature that increases over time.

Parameters:
  • temp1 (float) – the temperature value to which the velocities should be scaled initially
  • temp2 (float) – the final temperature value to which the velocities should be scaled
  • gradient (float) – the temperature gradient (in K/ps)
  • first (int) – the number of the first step at which the action is executed
  • last (int) – the number of the first step at which the action is no longer executed. A value of None indicates that the action should be executed indefinitely.
  • skip (int) – the number of steps to skip between two applications of the action
class MMTK.Dynamics.RotationRemover(first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Action that eliminates global rotation

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.

Parameters:
  • first (int) – the number of the first step at which the action is executed
  • last (int) – the number of the first step at which the action is no longer executed. A value of None indicates that the action should be executed indefinitely.
  • skip (int) – the number of steps to skip between two applications of the action
class MMTK.Dynamics.TranslationRemover(first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Action that eliminates global translation

A TranslationRemover object is used in the action list of a VelocityVerletIntegrator. It subtracts the total velocity of the system from each atomic velocity.

Parameters:
  • first (int) – the number of the first step at which the action is executed
  • last (int) – the number of the first step at which the action is no longer executed. A value of None indicates that the action should be executed indefinitely.
  • skip (int) – the number of steps to skip between two applications of the action
class MMTK.Dynamics.VelocityScaler(temperature, window=0.0, first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Periodic velocity scaling action

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.

Parameters:
  • temperature (float) – the temperature value to which the velocities should be scaled
  • window (float) – the deviation from the ideal temperature that is tolerated in either direction before rescaling takes place
  • first (int) – the number of the first step at which the action is executed
  • last (int) – the number of the first step at which the action is no longer executed. A value of None indicates that the action should be executed indefinitely.
  • skip (int) – the number of steps to skip between two applications of the action
class MMTK.Dynamics.VelocityVerletIntegrator(universe, **options)[source]

Bases: MMTK.Dynamics.Integrator

Velocity-Verlet molecular dynamics integrator

The integrator can handle fixed atoms, distance constraints, a thermostat, and a barostat, as well as any combination. It is fully thread-safe.

The integration is started by calling the integrator object. All the keyword options (see documnentation of __init__) can be specified either when creating the integrator or when calling it.

The following data categories and variables are available for output:

  • category “time”: time
  • category “configuration”: configuration and box size (for periodic universes)
  • category “velocities”: atomic velocities
  • category “gradients”: energy gradients for each atom
  • category “energy”: potential and kinetic energy, plus extended-system energy terms if a thermostat and/or barostat are used
  • category “thermodynamic”: temperature, volume (if a barostat is used) and pressure
  • category “auxiliary”: extended-system coordinates if a thermostat and/or barostat are used
Parameters:
  • universe (Universe) – the universe on which the integrator acts
  • steps (int) – the number of integration steps (default is 100)
  • delta_t (float) – the time step (default is 1 fs)
  • actions (list) – a list of actions to be executed periodically (default is none)
  • threads (int) – the number of threads to use in energy evaluation (default set by MMTK_ENERGY_THREADS)
  • background (bool) – if True, the integration is executed as a separate thread (default: False)
  • mpi_communicator (Scientific.MPI.MPICommunicator) – an MPI communicator object, or None, meaning no parallelization (default: None)

MMTK.Environment

Environment objects

Environment objects are objects that define a simulation system without being composed of atoms. Examples are thermostats, barostats, external fields, etc.

class MMTK.Environment.AndersenBarostat(pressure, relaxation_time=1.5)[source]

Bases: MMTK.Environment.EnvironmentObject

Andersen barostat for Molecular Dynamics

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.

Parameters:
  • pressure (float) – the pressure set by the barostat
  • relaxation_time (float) – the relaxation time of the barostat coordinate
class MMTK.Environment.NoseThermostat(temperature, relaxation_time=0.20000000000000001)[source]

Bases: MMTK.Environment.EnvironmentObject

Nose thermostat for Molecular Dynamics

A thermostat object can be added to a universe and will then modify the integration algorithm to a simulation of an NVT ensemble.

Parameters:
  • temperature (float) – the temperature set by the thermostat
  • relaxation_time (float) – the relaxation time of the thermostat coordinate

MMTK.Field

Scalar and vector fields in molecular systems

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.

class MMTK.Field.AtomicField(system, grid_size, values)[source]

Bases: object

A field whose values are determined by atomic quantities

This is an abstract base class. To create field objects, use one of its subclasses.

particleValues()[source]
Returns:the values of the field at the positions of the atoms
Return type:ParticleProperty
view(scale=1.0, color=None)[source]

Shows a graphical representation of the field using a VRML viewer.

Parameters:
  • scale (float) – scale factor applied to all field values
  • color (Scientific.Visualization.Color) – the color for all graphics objects
writeToFile(filename, scale=1.0, color=None)[source]

Writes a graphical representation of the field to a VRML file.

Parameters:
  • filename (str) – the name of the destination file
  • scale (float) – scale factor applied to all field values
  • color (Scientific.Visualization.Color) – the color for all graphics objects
class MMTK.Field.AtomicScalarField(system, grid_size, values)[source]

Bases: MMTK.Field.AtomicField, MMTK.Visualization.Viewable

Scalar field defined by atomic quantities

For visualization, scalar fields are represented by a small cube on 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 exist for graphics object generation:
  • scale=factor, to multiply all field values by a factor
  • range=(min, max), to eliminate graphics objects for values that are smaller than min or larger than max
Parameters:
  • system – any subset of a molecular system
  • grid_size (float) – the spacing of a cubic grid on which the field values are defined. The value for a point is obtained by averaging the atomic quantities over all atoms in a cube centered on the point.
  • values (ParticleScalar) – the atomic values that define the field
gradient()[source]
Returns:the gradient of the field
Return type:AtomicVectorField
laplacian()[source]
Returns:the laplacian of the field
Return type:AtomicScalarField
class MMTK.Field.AtomicVectorField(system, grid_size, values)[source]

Bases: MMTK.Field.AtomicField, MMTK.Visualization.Viewable

Vector field defined by atomic quantities

For visualization, scalar fields are represented by a small arrow on each grid point. The arrow starts at the grid point and represents the vector value at that point.

Additional keyword options exist for graphics object generation:
  • scale=factor, to multiply all field values by a factor
  • diameter=number, to define the diameter of the arrow objects (default: 1.)
  • range=(min, max), to eliminate graphics objects for values that are smaller than min or larger than max
  • color=string, to define the color of the arrows by a color name
Parameters:
  • system – any subset of a molecular system
  • grid_size (float) – the spacing of a cubic grid on which the field values are defined. The value for a point is obtained by averaging the atomic quantities over all atoms in a cube centered on the point.
  • values (ParticleVector) – the atomic values that define the field
curl()[source]
Returns:the curl of the field
Return type:AtomicVectorField
divergence()[source]
Returns:the divergence of the field
Return type:AtomicScalarField
laplacian()[source]
Returns:the laplacian of the field
Return type:AtomicVectorField
length()[source]
Returns:a field of the length of the field vectors
Return type:AtomicScalarField

MMTK.ForceFields

MMTK.ForceFields.AmberForceField

Amber force field implementation

General comments about parameters for Lennard-Jones and electrostatic interactions:

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.

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 (see Wolf et al., J. Chem. Phys. 17, 8254 (1999)).

For Ewald summation, there are some additional parameters that can be specified by dictionary entries:

  • “beta” specifies the Ewald screening parameter

  • “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.

  • “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.

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.

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 (see article cited above). It requires the specification of the dictionary entries “cutoff” and “beta”.

The fast-multipole method uses the DPMTA library. 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.

MMTK.ForceFields.Amber94ForceField

class MMTK.ForceFields.Amber.Amber94ForceField(lj_options=None, es_options=None, bonded_scale_factor=1.0, **kwargs)

Bases: MMTK.ForceFields.MMForceField.MMForceField

Amber 94 force field

Parameters:
  • lj_options

    parameters for Lennard-Jones interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (no cutoff; inclusion of all pairs, using the minimum-image conventions for periodic universes)
    • 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”.
  • es_options

    parameters for electrostatic interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (all pairs without cutoff for non-periodic system, Ewald summation for periodic systems)
    • 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” or “multipole” (fast-multipole method).
  • mod_files – a list of parameter modification files. The file format is the one defined by AMBER. Each item in the list can be either a file object or a filename, filenames are looked up first relative to the current directory and then relative to the directory containing MMTK’s AMBER parameter files.

MMTK.ForceFields.Amber99ForceField

class MMTK.ForceFields.Amber.Amber99ForceField(lj_options=None, es_options=None, bonded_scale_factor=1.0, **kwargs)

Bases: MMTK.ForceFields.MMForceField.MMForceField

Amber 99 force field

Parameters:
  • lj_options

    parameters for Lennard-Jones interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (no cutoff; inclusion of all pairs, using the minimum-image conventions for periodic universes)
    • 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”.
  • es_options

    parameters for electrostatic interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (all pairs without cutoff for non-periodic system, Ewald summation for periodic systems)
    • 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” or “multipole” (fast-multipole method).
  • mod_files – a list of parameter modification files. The file format is the one defined by AMBER. Each item in the list can be either a file object or a filename, filenames are looked up first relative to the current directory and then relative to the directory containing MMTK’s AMBER parameter files.

MMTK.ForceFields.OPLSForceField

class MMTK.ForceFields.Amber.OPLSForceField(lj_options=None, es_options=None, bonded_scale_factor=1.0, **kwargs)

Bases: MMTK.ForceFields.MMForceField.MMForceField

MMTK.ForceFields.AnisotropicNetworkForceField

class MMTK.ForceFields.ANMFF.AnisotropicNetworkForceField(cutoff=None, scale_factor=1.0)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Effective harmonic force field for an ANM protein model

Parameters:
  • cutoff (float) – the cutoff for pair interactions. 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.
  • scale_factor (float) – a global scaling factor

MMTK.ForceFields.CalphaForceField

class MMTK.ForceFields.CalphaFF.CalphaForceField(cutoff=None, scale_factor=1.0, version=1)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Effective harmonic force field for a C-alpha protein model

Parameters:
  • cutoff (float) – the cutoff for pair interactions, should be at least 2.5 nm. 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.
  • scale_factor (float) – a global scaling factor

MMTK.ForceFields.DeformationForceField

class MMTK.ForceFields.DeformationFF.DeformationForceField(fc_length=0.69999999999999996, cutoff=1.2, factor=46402.0)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Deformation force field for protein normal mode calculations

The pair interaction force constant has the form k(r)=factor*exp(-(r**2-0.01)/range**2). The default value for range is appropriate for a C-alpha model of a protein. The offset of 0.01 is a convenience for defining factor; with this definition, factor is the force constant for a distance of 0.1nm.

Parameters:
  • fc_length (float) – a range parameter
  • cutoff (float) – the cutoff for pair interactions, should be at least 2.5 nm. 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.
  • factor (float) – a global scaling factor

MMTK.ForceFields.HarmonicForceField

class MMTK.ForceFields.BondFF.HarmonicForceField(fc_length=0.45000000000000001, cutoff=0.59999999999999998, factor=400.0)[source]

Bases: MMTK.ForceFields.MMForceField.MMAtomParameters, MMTK.ForceFields.ForceField.CompoundForceField

Simplified harmonic force field for normal mode calculations

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.

For a description of this force field, see:
Hinsen & Kneller, J. Chem. Phys. 24, 10766 (1999)
For an application to DNA, see:
Viduna, Hinsen & Kneller, Phys. Rev. E 3, 3986 (2000)

MMTK.ForceFields.LennardJonesForceField

class MMTK.ForceFields.LennardJonesFF.LennardJonesForceField(cutoff=None)[source]

Bases: MMTK.ForceFields.NonBondedInteractions.LJForceField

Lennard-Jones force field

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).

Parameters:
  • cutoff (float) – a cutoff value or None, meaning no cutoff. 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.

MMTK.ForceFields.SPCEForceField

class MMTK.ForceFields.SPCEFF.SPCEForceField(lj_options=None, es_options=None)[source]

Bases: MMTK.ForceFields.MMForceField.MMForceField

Force field for water simulations with the SPC/E model

Parameters:
  • lj_options

    parameters for Lennard-Jones interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (no cutoff; inclusion of all pairs, using the minimum-image conventions for periodic universes)
    • 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”.
  • es_options

    parameters for electrostatic interactions; one of:

    • a number, specifying the cutoff
    • None, meaning the default method (all pairs without cutoff for non-periodic system, Ewald summation for periodic systems)
    • 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” or “multipole” (fast-multipole method).

MMTK.ForceFields.ForceFieldTest

Force field consistency tests

MMTK.ForceFields.ForceFieldTest.forceConstantTest(universe, atoms=None, delta=0.0001)[source]

Test force constants by comparing to the numerical derivatives of the gradients.

Parameters:
  • universe (Universe) – the universe on which the test is performed
  • atoms (list) – the atoms of the universe for which the gradient is tested (default: all atoms)
  • delta (float) – the step size used in calculating the numerical derivatives
MMTK.ForceFields.ForceFieldTest.gradientTest(universe, atoms=None, delta=0.0001)[source]

Test gradients by comparing to numerical derivatives of the energy.

Parameters:
  • universe (Universe) – the universe on which the test is performed
  • atoms (list) – the atoms of the universe for which the gradient is tested (default: all atoms)
  • delta (float) – the step size used in calculating the numerical derivatives
MMTK.ForceFields.ForceFieldTest.virialTest(universe)[source]

Test the virial by comparing to an explicit computation from positions and gradients.

Parameters:
  • universe (Universe) – the universe on which the test is performed

MMTK.ForceFields.Restraints

Harmonic restraint terms that can be added to any force field

Example:

from MMTK import *
from MMTK.ForceFields import Amber99ForceField
from MMTK.ForceFields.Restraints import HarmonicDistanceRestraint

universe = InfiniteUniverse()
universe.protein = Protein('bala1')
force_field = Amber99ForceField() +                HarmonicDistanceRestraint(universe.protein[0][1].peptide.N,
                                        universe.protein[0][1].peptide.O,
                                        0.5, 10.)
universe.setForceField(force_field)
class MMTK.ForceFields.Restraints.HarmonicAngleRestraint(atom1, atom2, atom3, angle, force_constant)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Harmonic angle restraint between three atoms

Parameters:
  • atom1 (Atom) – first atom
  • atom2 (Atom) – second (central) atom
  • atom3 (Atom) – third atom
  • angle (float) – the angle at which the restraint is zero
  • force_constant – the force constant of the restraint term. The functional form of the restraint is force_constant*(phi-angle)**2, where phi is the angle atom1-atom2-atom3.
class MMTK.ForceFields.Restraints.HarmonicDihedralRestraint(atom1, atom2, atom3, atom4, dihedral, force_constant)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Harmonic dihedral angle restraint between four atoms

Parameters:
  • atom1 (Atom) – first atom
  • atom2 (Atom) – second (axis) atom
  • atom3 (Atom) – third (axis)atom
  • atom4 (Atom) – fourth atom
  • dihedral (float) – the dihedral angle at which the restraint is zero
  • force_constant – the force constant of the restraint term. The functional form of the restraint is force_constant*(phi-abs(dihedral))**2, where phi is the dihedral angle atom1-atom2-atom3-atom4.
class MMTK.ForceFields.Restraints.HarmonicDistanceRestraint(atom1, atom2, distance, force_constant)[source]

Bases: MMTK.ForceFields.ForceField.ForceField

Harmonic distance restraint between two atoms

Parameters:
  • atom1 (Atom) – first atom
  • atom2 (Atom) – second atom
  • distance (float) – the distance at which the restraint is zero
  • force_constant – the force constant of the restraint term. 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.

MMTK.FourierBasis

Fourier basis for low-frequency normal mode calculations

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

K. Hinsen
Analysis of domain motions by approximate normal mode calculations
Proteins 33 (1998): 417-429
class MMTK.FourierBasis.FourierBasis(universe, cutoff)[source]

Bases: object

Collective-motion basis for low-frequency normal mode calculations

A FourierBasis behaves like a sequence of ParticleVector objects. The vectors are B{not} orthonormal, because orthonormalization is handled automatically by the normal mode class.

Parameters:
  • universe (Universe) – the universe for which the basis will be used
  • cutoff (float) – the wavelength cutoff. A smaller value yields a larger basis.
MMTK.FourierBasis.countBasisVectors(universe, cutoff)[source]

Estimate the number of basis vectors for a given universe and cutoff

Parameters:
  • universe (Universe) – the universe
  • cutoff (float) – the wavelength cutoff. A smaller value yields a larger basis.
Returns:

the number of basis vectors in a FourierBasis

Return type:

int

MMTK.FourierBasis.estimateCutoff(universe, nmodes)[source]

Estimate the cutoff that yields a given number of basis vectors for a given universe.

Parameters:
  • universe (Universe) – the universe
  • nmodes (int) – the number of basis vectors in a FourierBasis
Returns:

the wavelength cutoff and the precise number of basis vectors

Return type:

tuple (float, int)

MMTK.Geometry

Elementary geometrical objects

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.

class MMTK.Geometry.BCCLattice(cellsize, cells, function=None, base=None)[source]

Bases: MMTK.Geometry.RhombicLattice

Body-Centered Cubic lattice

A Body-Centered Cubic lattice has two points per elementary cell.

Parameters:
  • cellsize (float) – the edge length of the elementary cell
  • cells – a list of integers, whose length must equal the number of dimensions. Each entry specifies how often a cell is repeated along this dimension.
  • function – 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 ‘None’, the vector is directly stored in the lattice object.
class MMTK.Geometry.Box(corner1, corner2)[source]

Bases: MMTK.Geometry.GeometricalObject3D

Rectangular box aligned with the coordinate axes

Parameters:
  • corner1 (Scientific.Geometry.Vector) – one corner of the box
  • corner2 (Scientific.Geometry.Vector) – the diagonally opposite corner
class MMTK.Geometry.BravaisLattice(lattice_vectors, cells, function=None, base=None)[source]

Bases: MMTK.Geometry.RhombicLattice

Bravais lattice

A Bravais lattice is a special case of a general rhombic lattice in which the elementary cell contains only one point.

Parameters:
  • lattice_vectors – 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.
  • cells – a list of integers, whose length must equal the number of dimensions. Each entry specifies how often a cell is repeated along this dimension.
  • function – 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 ‘None’, the vector is directly stored in the lattice object.
class MMTK.Geometry.Circle(center, normal, radius)[source]

Bases: MMTK.Geometry.GeometricalObject3D

2D circle in 3D space

Parameters:
  • center (Scientific.Geometry.Vector) – the center of the circle
  • normal (Scientific.Geometry.Vector) – the normal vector of the circle’s plane
  • radius (float) – the radius of the circle
class MMTK.Geometry.Cone(center, axis, angle)[source]

Bases: MMTK.Geometry.GeometricalObject3D

Cone

Parameters:
  • center (Scientific.Geometry.Vector) – the center (tip) of the cone
  • axis (Scientific.Geometry.Vector) – the direction of the axis of rotational symmetry
  • angle (float) – the angle between any straight line on the cone surface and the axis of symmetry
class MMTK.Geometry.Cylinder(center1, center2, radius)[source]

Bases: MMTK.Geometry.GeometricalObject3D

Cylinder

Parameters:
  • center1 (Scientific.Geometry.Vector) – the center of the bottom circle
  • center2 (Scientific.Geometry.Vector) – the center of the top circle
  • radius (float) – the radius of the cylinder
class MMTK.Geometry.FCCLattice(cellsize, cells, function=None, base=None)[source]

Bases: MMTK.Geometry.RhombicLattice

Face-Centered Cubic lattice

A Face-Centered Cubic lattice has four points per elementary cell.

Parameters:
  • cellsize (float) – the edge length of the elementary cell
  • cells – a list of integers, whose length must equal the number of dimensions. Each entry specifies how often a cell is repeated along this dimension.
  • function – 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 ‘None’, the vector is directly stored in the lattice object.
class MMTK.Geometry.GeometricalObject3D[source]

Bases: object

3D shape object

This is an abstract base class. To create 3D objects, use one of its subclasses.

enclosesPoint(point)[source]
Parameters:
  • point (Scientific.Geometry.Vector) – a point in 3D space
Returns:

True of the point is inside the volume of the object

Return type:

bool

hasPoint(point)[source]
Parameters:
  • point (Scientific.Geometry.Vector) – a point in 3D space
Returns:

True of the point lies on the surface of the object

Return type:

bool

intersectWith(other)[source]
Parameters:
  • other – another 3D object
Returns:

a 3D object that represents the intersection with other

volume()[source]
Returns:the volume of the object
Return type:float
class MMTK.Geometry.Lattice(function)[source]

Bases: object

General lattice

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. Note that the lattices represented by these objects are finite, they have a finite (and fixed) number of repetitions along each lattice vector.

This is an abstract base class. To create lattice objects, use one of its subclasses.

class MMTK.Geometry.Line(point, direction)[source]

Bases: MMTK.Geometry.GeometricalObject3D

Line

Parameters:
  • point (Scientific.Geometry.Vector) – any point on the line
  • direction (Scientific.Geometry.Vector) – the direction of the line
distanceFrom(point)[source]
Parameters:
  • point (Scientific.Geometry.Vector) – a point in space
Returns:

the smallest distance of the point from the line

Return type:

float

perpendicularVector(plane)[source]
Parameters:
  • plane (Plane) – a plane
Returns:

a vector in the plane perpendicular to the line

Return type:

Scientific.Geometry.Vector

projectionOf(point)[source]
Parameters:
  • point (Scientific.Geometry.Vector) – a point in space
Returns:

the orthogonal projection of the point onto the line

Return type:

Scientific.Geometry.Vector

class MMTK.Geometry.Plane(*args)[source]

Bases: MMTK.Geometry.GeometricalObject3D

2D plane in 3D space

Parameters:
  • args – three points (of type Scientific.Geometry.Vector) that are not collinear, or a point in the plane and the normal vector of the plane
class MMTK.Geometry.RhombicLattice(elementary_cell, lattice_vectors, cells, function=None, base=None)[source]

Bases: MMTK.Geometry.Lattice

Rhombic lattice

Parameters:
  • elementary_cell – a list of points in the elementary cell
  • lattice_vectors – 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.
  • cells – a list of integers, whose length must equal the number of dimensions. Each entry specifies how often a cell is repeated along this dimension.
  • function – 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 ‘None’, the vector is directly stored in the lattice object.
class MMTK.Geometry.SCLattice(cellsize, cells, function=None, base=None)[source]

Bases: MMTK.Geometry.BravaisLattice

Simple Cubic lattice

A Simple Cubic lattice is a special case of a Bravais lattice in which the elementary cell is a cube.

Parameters:
  • cellsize (float) – the edge length of the elementary cell
  • cells – a list of integers, whose length must equal the number of dimensions. Each entry specifies how often a cell is repeated along this dimension.
  • function – 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 ‘None’, the vector is directly stored in the lattice object.
class MMTK.Geometry.Sphere(center, radius)[source]

Bases: MMTK.Geometry.GeometricalObject3D

Sphere

Parameters:
  • center (Scientific.Geometry.Vector) – the center of the sphere
  • radius (float) – the radius of the sphere

MMTK.InternalCoordinates

Manipulation of molecular configurations in terms of internal coordinates

class MMTK.InternalCoordinates.BondAngle(atom1, atom2, atom3)[source]

Bases: MMTK.InternalCoordinates.InternalCoordinate

Bond angle

A BondAngle object permits calculating and modifying the angle between two bonds in a molecule, under the condition that the bonds are not part of a circular bond structure (but it is not a problem to have a circular bond structure elsewhere in the molecule). Modifying the bond angle rotates the parts of the molecule on both sides of the central atom around an axis passing through the central atom and perpendicular to the plane defined by the two bonds in such a way that there is no overall rotation of the molecule. The central atom and any other atoms bonded to it do not move.

The initial construction of the BondAngle object can be expensive (the bond structure of the molecule must be analyzed). It is therefore advisable to keep the object rather than recreate it frequently. Note that if you only want to calculate bond angles (no modification), the method Universe.angle is simpler and faster.

Parameters:
  • atom1 (Atom) – the first atom that defines the angle
  • atom2 (Atom) – the second and central atom that defines the bond
  • atom3 (Atom) – the third atom that defines the bond
getValue(conf=None)[source]
Parameters:
  • conf (Configuration) – a configuration (defaults to the current configuration)
Returns:

the size of the angle in the configuration conf

Return type:

float

setValue(value)[source]

Sets the size of the angle :param value: the desired angle :type value: float

class MMTK.InternalCoordinates.BondLength(atom1, atom2)[source]

Bases: MMTK.InternalCoordinates.InternalCoordinate

Bond length coordinate

A BondLength object permits calculating and modifying the length of a bond in a molecule, under the condition that the bond is not part of a circular bond structure (but it is not a problem to have a circular bond structure elsewhere in the molecule). Modifying the bond length moves the parts of the molecule on both sides of the bond along the bond direction in such a way that the center of mass of the molecule does not change.

The initial construction of the BondLength object can be expensive (the bond structure of the molecule must be analyzed). It is therefore advisable to keep the object rather than recreate it frequently. Note that if you only want to calculate bond lengths (no modification), the method Universe.distance is simpler and faster.

Parameters:
  • atom1 (Atom) – the first atom that defines the bond
  • atom2 (Atom) – the second atom that defines the bond
getValue(conf=None)[source]
Parameters:
  • conf (Configuration) – a configuration (defaults to the current configuration)
Returns:

the length of the bond in the configuration conf

Return type:

float

setValue(value)[source]

Sets the length of the bond :param value: the desired length of the bond :type value: float

class MMTK.InternalCoordinates.DihedralAngle(atom1, atom2, atom3, atom4)[source]

Bases: MMTK.InternalCoordinates.InternalCoordinate

Dihedral angle

A DihedralAngle object permits calculating and modifying the dihedral angle defined by three consecutive bonds in a molecule, under the condition that the central bond is not part of a circular bond structure (but it is not a problem to have a circular bond structure elsewhere in the molecule). Modifying the dihedral angle rotates the parts of the molecule on both sides of the central bond around this central bond in such a way that there is no overall rotation of the molecule.

The initial construction of the DihedralAngle object can be expensive (the bond structure of the molecule must be analyzed). It is therefore advisable to keep the object rather than recreate it frequently. Note that if you only want to calculate bond angles (no modification), the method Universe.dihedral is simpler and faster.

Parameters:
  • atom1 (Atom) – the first atom that defines the dihedral
  • atom2 (Atom) – the second atom that defines the dihedral, must be on the central bond
  • atom3 (Atom) – the third atom that defines the dihedral, must be on the central bond
  • atom4 (Atom) – the fourth atom that defines the dihedral
getValue(conf=None)[source]
Parameters:
  • conf (Configuration) – a configuration (defaults to the current configuration)
Returns:

the size of the dihedral angle in the configuration conf

Return type:

float

setValue(value)[source]

Sets the size of the dihedral :param value: the desired dihedral angle :type value: float

MMTK.Minimization

Energy minimizers

class MMTK.Minimization.ConjugateGradientMinimizer(universe, **options)[source]

Bases: MMTK.Minimization.Minimizer

Conjugate gradient minimizer

The minimizer can handle fixed atoms, but no distance constraints. It is fully thread-safe.

The minimization is started by calling the minimizer object. All the keyword options can be specified either when creating the minimizer or when calling it.

The following data categories and variables are available for output:

  • category “configuration”: configuration and box size (for periodic universes)

  • category “gradients”: energy gradients for each atom

  • category “energy”: potential energy and

    norm of the potential energy gradient

Parameters:
  • universe (Universe) – the universe on which the integrator acts
  • steps (int) – the number of minimization steps (default is 100)
  • step_size (float) – the initial size of a minimization step (default is 0.002 nm)
  • convergence (float) – the root-mean-square gradient length at which minimization stops (default is 0.01 kJ/mol/nm)
  • actions (list) – a list of actions to be executed periodically (default is none)
  • threads (int) – the number of threads to use in energy evaluation (default set by MMTK_ENERGY_THREADS)
  • background (bool) – if True, the integration is executed as a separate thread (default: False)
class MMTK.Minimization.SteepestDescentMinimizer(universe, **options)[source]

Bases: MMTK.Minimization.Minimizer

Steepest-descent minimizer

The minimizer can handle fixed atoms, but no distance constraints. It is fully thread-safe.

The minimization is started by calling the minimizer object. All the keyword options (see documnentation of __init__) can be specified either when creating the minimizer or when calling it.

The following data categories and variables are available for output:

  • category “configuration”: configuration and box size (for periodic universes)

  • category “gradients”: energy gradients for each atom

  • category “energy”: potential energy and

    norm of the potential energy gradient

Parameters:
  • universe (Universe) – the universe on which the integrator acts
  • steps (int) – the number of minimization steps (default is 100)
  • step_size (float) – the initial size of a minimization step (default is 0.002 nm)
  • convergence (float) – the root-mean-square gradient length at which minimization stops (default is 0.01 kJ/mol/nm)
  • actions (list) – a list of actions to be executed periodically (default is none)
  • threads (int) – the number of threads to use in energy evaluation (default set by MMTK_ENERGY_THREADS)
  • background (bool) – if True, the integration is executed as a separate thread (default: False)
  • mpi_communicator (Scientific.MPI.MPICommunicator) – an MPI communicator object, or None, meaning no parallelization (default: None)

MMTK.MolecularSurface

Molecular surfaces and volumes.

MMTK.MolecularSurface.findContacts(object1, object2, contact_factor=1.0, cutoff=0.0)[source]

Identifies contacts between two molecules. 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.

Parameters:
  • object1 (GroupOfAtoms) – a chemical object
  • object2 (GroupOfAtoms) – a chemical object
  • contact_factor (float) – a scale factor in the contact distance criterion
  • cutoff (float) – a constant in the contact distance criterion
Returns:

a list of Contact objects that describe atomic contacts between object1 and object2.

Return type:

list

MMTK.MolecularSurface.surfaceAndVolume(object, probe_radius=0.0)[source]
Parameters:
  • object (GroupOfAtoms) – a chemical object
  • probe_radius (float) – the distance from the vdW-radii of the atoms at which the surface is computed
Returns:

the molecular surface and volume of object

Return type:

tuple

MMTK.MolecularSurface.surfaceAtoms(object, probe_radius=0.0)[source]
Parameters:
  • object (GroupOfAtoms) – a chemical object
  • probe_radius (float) – the distance from the vdW-radii of the atoms at which the surface is computed
Returns:

a dictionary that maps the surface atoms to their exposed surface areas

Return type:

dict

MMTK.MolecularSurface.surfacePointsAndGradients(object, probe_radius=0.0, point_density=258)[source]
Parameters:
  • object (GroupOfAtoms) – a chemical object
  • probe_radius (float) – the distance from the vdW-radii of the atoms at which the surface is computed
  • point_density (int) – the density of points that describe the surface
Returns:

a dictionary that maps the surface atoms to a tuple containing three surface-related quantities: the exposed surface area, a list of points in the exposed surface, and a gradient vector pointing outward from the surface.

Return type:

dict

MMTK.MoleculeFactory

Molecule factory for creating chemical objects

class MMTK.MoleculeFactory.MoleculeFactory[source]

Bases: object

MoleculeFactory

A MoleculeFactory serves to create molecules without reference to database definitions. Molecules and groups are defined in terms of atoms, groups, and bonds. Each MoleculeFactory constitutes an independent set of definitions. Definitions within a MoleculeFactory can refer to each other.

Each MoleculeFactory stores a set of Group objects which are referred to by names. The typical operation sequence is to create a new group and then add atoms, bonds, and subgroups. It is also possible to define coordinates and arbitrary attributes (in particular for force fields). In the end, a finished object can be retrieved as a Molecule object.

addAtom(group, atom_name, element)[source]

Add an atom to a group

Parameters:
  • group (str) – the name of the group
  • atom_name (str) – the name of the atom
  • element (str) – the chemical element symbol
addBond(group, atom1, atom2)[source]

Add a bond to a group

Parameters:
  • group (str) – the name of the group
  • atom1 (str) – the name of the first atom
  • atom2 (str) – the name of the second atom
addSubgroup(group, subgroup_name, subgroup)[source]

Add a subgroup to a group

Parameters:
  • group (str) – the name of the group
  • subgroup_name (str) – the name of the subgroup within the group
  • subgroup (str) – the subgroup type
createGroup(name)[source]

Create a new (initially empty) group object.

retrieveMolecule(group)[source]
Parameters:
  • group (str) – the name of the group to be used as a template
Returns:

a molecule defined by the contents of the group

Return type:

Molecule

MMTK.NormalModes

Normal modes

MMTK.NormalModes.BrownianModes

Brownian normal modes

class MMTK.NormalModes.BrownianModes.BrownianMode(universe, n, inv_relaxation_time, mode)[source]

Bases: MMTK.NormalModes.Core.Mode

Single Brownian normal mode

Mode objects are created by indexing a BrownianModes object. They contain the atomic displacements corresponding to a single mode. In addition, the inverse of the relaxation time corresponding to the mode is stored in the attribute “inv_relaxation_time”.

Note: the Brownian mode vectors are not friction weighted and therefore not orthogonal to each other.

class MMTK.NormalModes.BrownianModes.BrownianModes(universe=None, friction=None, temperature=300.0, subspace=None, delta=None, sparse=False)[source]

Bases: MMTK.NormalModes.Core.NormalModes

Brownian modes describe the independent relaxation motions of a harmonic system with friction. They are obtained by diagonalizing the friction-weighted force constant matrix.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

Individual modes (see BrownianMode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

Brownian modes describe the independent relaxation motions of a harmonic system with friction. They are obtained by diagonalizing the friction-weighted force constant matrix.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A BrownianModes object behaves like a sequence of modes. Individual modes (see BrownianMode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

Parameters:
  • universe (Universe) – the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy
  • friction (ParticleScalar) – the friction coefficient for each particle. Note: The friction coefficients are not mass-weighted, i.e. they have the dimension of an inverse time.
  • temperature (float) – the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of None can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.
  • subspace – 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 second set of vectors projected on the complement of the space spanned by the first set of vectors. The first set thus defines directions that are excluded from the subspace. The default value of None indicates a standard normal mode calculation in the 3N-dimensional configuration space.
  • delta (float) – the rms step length for numerical differentiation. The default value of None indicates analytical differentiation. Numerical differentiation is available only when a subspace basis is used as well. Instead of calculating the full force constant matrix and then multiplying with the subspace basis, the subspace force constant matrix is obtained by numerical differentiation of the energy gradients along the basis vectors of the subspace. If the basis is much smaller than the full configuration space, this approach needs much less memory.
  • sparse (bool) – a flag that indicates if a sparse representation of the force constant matrix is to be used. This is of interest when there are no long-range interactions and a subspace of smaller size then 3N is specified. In that case, the calculation will use much less memory with a sparse representation.
EISF(q_range=(0.0, 15.0), subset=None, weights=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q_range (tuple) – the range of angular wavenumber values
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: incoherent scattering lengths)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Elastic Incoherent Structure Factor (EISF) as a function of angular wavenumber

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

coherentScatteringFunction(q, time_range=(0.0, None, None), subset=None, weights=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q (float) – the angular wavenumber
  • time_range (tuple) – the time values at which the mean-square displacement is evaluated, specified as a range tuple (first, last, step). The defaults are first=0, last= 20 times the longest vibration perdiod, and step defined such that 300 points are used in total.
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: coherent scattering lengths)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Coherent Scattering Function as a function of time

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

incoherentScatteringFunction(q, time_range=(0.0, None, None), subset=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q (float) – the angular wavenumber
  • time_range (tuple) – the time values at which the mean-square displacement is evaluated, specified as a range tuple (first, last, step). The defaults are first=0, last= 20 times the longest vibration perdiod, and step defined such that 300 points are used in total.
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Incoherent Scattering Function as a function of time

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

meanSquareDisplacement(subset=None, weights=None, time_range=(0.0, None, None), first_mode=6)[source]
Parameters:
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: atomic masses)
  • time_range (tuple) – the time values at which the mean-square displacement is evaluated, specified as a range tuple (first, last, step). The defaults are first=0, last= 20 times the longest vibration perdiod, and step defined such that 300 points are used in total.
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the averaged mean-square displacement of the atoms in subset as a function of time

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

rawMode(item)[source]
Parameters:
  • item (int) – the index of a normal mode
Returns:

the unscaled mode vector

Return type:

BrownianMode

staticStructureFactor(q_range=(1.0, 15.0), subset=None, weights=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q_range (tuple) – the range of angular wavenumber values
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: coherent scattering lengths)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Static Structure Factor as a function of angular wavenumber

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

MMTK.NormalModes.EnergeticModes

Energetic normal modes

class MMTK.NormalModes.EnergeticModes.EnergeticMode(universe, n, force_constant, mode)[source]

Bases: MMTK.NormalModes.Core.Mode

Single energetic normal mode

Mode objects are created by indexing a MMTK.NormalModes.EnergeticModes.EnergeticModes object. They contain the atomic displacements corresponding to a single mode. In addition, the force constant corresponding to the mode is stored in the attribute “force_constant”.

class MMTK.NormalModes.EnergeticModes.EnergeticModes(universe=None, temperature=300, subspace=None, delta=None, sparse=False)[source]

Bases: MMTK.NormalModes.Core.NormalModes

Energetic modes describe the principal axes of an harmonic approximation to the potential energy surface of a system. They are obtained by diagonalizing the force constant matrix without prior mass-weighting.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

Individual modes (see class EnergeticMode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

Parameters:
  • universe (Universe) – the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy
  • temperature (float) – the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of None can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.
  • subspace – 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 second set of vectors projected on the complement of the space spanned by the first set of vectors. The first set thus defines directions that are excluded from the subspace. The default value of None indicates a standard normal mode calculation in the 3N-dimensional configuration space.
  • delta (float) – the rms step length for numerical differentiation. The default value of None indicates analytical differentiation. Numerical differentiation is available only when a subspace basis is used as well. Instead of calculating the full force constant matrix and then multiplying with the subspace basis, the subspace force constant matrix is obtained by numerical differentiation of the energy gradients along the basis vectors of the subspace. If the basis is much smaller than the full configuration space, this approach needs much less memory.
  • sparse (bool) – a flag that indicates if a sparse representation of the force constant matrix is to be used. This is of interest when there are no long-range interactions and a subspace of smaller size then 3N is specified. In that case, the calculation will use much less memory with a sparse representation.
rawMode(item)[source]
Parameters:
  • item (int) – the index of a normal mode
Returns:

the unscaled mode vector

Return type:

EnergeticMode

MMTK.NormalModes.VibrationalModes

Vibrational normal modes

class MMTK.NormalModes.VibrationalModes.VibrationalMode(universe, n, frequency, mode)[source]

Bases: MMTK.NormalModes.Core.Mode

Single vibrational normal mode

Mode objects are created by indexing a VibrationalModes object. They contain the atomic displacements corresponding to a single mode. In addition, the frequency corresponding to the mode is stored in the attribute “frequency”.

Note: the normal mode vectors are not mass weighted, and therefore not orthogonal to each other.

class MMTK.NormalModes.VibrationalModes.VibrationalModes(universe=None, temperature=300.0, subspace=None, delta=None, sparse=False)[source]

Bases: MMTK.NormalModes.Core.NormalModes

Vibrational modes describe the independent vibrational motions of a harmonic system. They are obtained by diagonalizing the mass-weighted force constant matrix.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

Individual modes (see VibrationalMode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

Parameters:
  • universe (Universe) – the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy
  • temperature (float) – the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of None can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.
  • subspace – 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 second set of vectors projected on the complement of the space spanned by the first set of vectors. The first set thus defines directions that are excluded from the subspace. The default value of None indicates a standard normal mode calculation in the 3N-dimensional configuration space.
  • delta (float) – the rms step length for numerical differentiation. The default value of None indicates analytical differentiation. Numerical differentiation is available only when a subspace basis is used as well. Instead of calculating the full force constant matrix and then multiplying with the subspace basis, the subspace force constant matrix is obtained by numerical differentiation of the energy gradients along the basis vectors of the subspace. If the basis is much smaller than the full configuration space, this approach needs much less memory.
  • sparse (bool) – a flag that indicates if a sparse representation of the force constant matrix is to be used. This is of interest when there are no long-range interactions and a subspace of smaller size then 3N is specified. In that case, the calculation will use much less memory with a sparse representation.
EISF(q_range=(0.0, 15.0), subset=None, weights=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q_range (tuple) – the range of angular wavenumber values
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: incoherent scattering lengths)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Elastic Incoherent Structure Factor (EISF) as a function of angular wavenumber

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

incoherentScatteringFunction(q, time_range=(0.0, None, None), subset=None, weights=None, tau=None, random_vectors=15, first_mode=6)[source]
Parameters:
  • q (float) – the angular wavenumber
  • time_range (tuple) – the time values at which the mean-square displacement is evaluated, specified as a range tuple (first, last, step). The defaults are first=0, last= 20 times the longest vibration perdiod, and step defined such that 300 points are used in total.
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: incoherent scattering lengths)
  • tau (float) – the relaxation time of an exponential damping factor (default: no damping)
  • random_vectors (int) – the number of random direction vectors used in the orientational average
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the Incoherent Scattering Function as a function of time

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

meanSquareDisplacement(subset=None, weights=None, time_range=(0.0, None, None), tau=None, first_mode=6)[source]
Parameters:
  • subset (GroupOfAtoms) – the subset of the universe used in the calculation (default: the whole universe)
  • weights (ParticleScalar) – the weight to be given to each atom in the average (default: atomic masses)
  • time_range (tuple) – the time values at which the mean-square displacement is evaluated, specified as a range tuple (first, last, step). The defaults are first=0, last= 20 times the longest vibration perdiod, and step defined such that 300 points are used in total.
  • tau (float) – the relaxation time of an exponential damping factor (default: no damping)
  • first_mode (int) – the first mode to be taken into account for the fluctuation calculation. The default value of 6 is right for molecules in vacuum.
Returns:

the averaged mean-square displacement of the atoms in subset as a function of time

Return type:

Scientific.Functions.Interpolation.InterpolatingFunction

rawMode(item)[source]
Parameters:
  • item (int) – the index of a normal mode
Returns:

the unscaled mode vector

Return type:

VibrationalMode

MMTK.NucleicAcids

Nucleic acid chains

class MMTK.NucleicAcids.Nucleotide(name=None, model='all')[source]

Bases: MMTK.Biopolymers.Residue

Nucleic acid residue

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 (‘sugar’ and ‘base’, plus ‘phosphate’ 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).

Parameters:
  • name (str) – 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.
  • model (str) – 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”.
backbone()[source]
Returns:the sugar and phosphate groups
Return type:Group
bases()[source]
Returns:the base group
Return type:Group
class MMTK.NucleicAcids.NucleotideChain(sequence, **properties)[source]

Bases: MMTK.Biopolymers.ResidueChain

Nucleotide chain

Nucleotide chains consist of nucleotides that are linked together. They are a special kind of molecule, i.e. all molecule operations are available.

Nucleotide chains act as sequences of residues. If n is a NucleotideChain object, then

  • len(n) yields the number of nucleotides

  • n[i] yields nucleotide number i

  • n[i:j] yields the subchain from nucleotide number i up to but

    excluding nucleotide number j

Parameters:
  • sequence – the nucleotide sequence. This can be a string containing the one-letter codes, or 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.
  • model (str) – 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). Default is “all”. Currently the database contains definitions only for “all”.
  • terminus_5 (bool) – if True, the first residue is constructed using the 5’-terminal variant, if False the non-terminal version is used. Default is True.
  • terminus_3 (bool) – if True, the last residue is constructed using the 3’-terminal variant, if False the non-terminal version is used. Default is True.
  • circular (bool) – if True, a bond is constructed between the first and the last residue. Default is False.
  • name (str) – a name for the chain (a string)
backbone()[source]
Returns:the sugar and phosphate groups of all nucleotides
Return type:Collection
bases()[source]
Returns:the base groups of all nucleotides
Return type:Collection
class MMTK.NucleicAcids.NucleotideSubChain(chain, groups, name='')[source]

Bases: MMTK.NucleicAcids.NucleotideChain

A contiguous part of a nucleotide chain

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.

MMTK.NucleicAcids.isNucleotideChain(x)[source]

Returns True if x is a NucleotideChain.

MMTK.PDB

PDB files

This module provides classes that represent molecules in a 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.

class MMTK.PDB.PDBConfiguration(file_or_filename, model=0, alternate_code='A')[source]

Bases: Scientific.IO.PDB.Structure

Everything in a PDB file

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.

Parameters:
  • file_or_filename – the name of a PDB file, or a file object
  • model (int) – the number of the model to be used from a multiple model file
  • alternate_code (str) – the alternate code to be used for atoms that have multiple positions
applyTo(object, atom_map=None)[source]

Sets the configuration of object 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. :param object: a chemical object or collection of chemical objects

asuToUnitCell(asu_contents, compact=True)[source]
Parameters:
  • asu_contents – the molecules in the asymmetric unit, usually obtained from createAll().
  • compact (bool) – if True, all molecules images are shifted such that their centers of mass lie inside the unit cell.
Returns:

a collection containing all molecules in the unit cell, obtained by copying and moving the molecules from the asymmetric unit according to the crystallographic symmetry operations.

Return type:

Collection

createAll(molecule_names=None, permit_undefined=True)[source]
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().
createMolecules(names=None, permit_undefined=True)[source]
Parameters:
  • names (list) – If 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 a dictionary, it is used to map PDB residue names to molecule names. With the default (None), only water molecules are built.
  • permit_undefined – If False, an exception is raised when a PDB residue is encountered for which no molecule name is supplied in names. If True, an AtomCluster object is constructed for each unknown molecule.
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.

Return type:

Collection

createNucleotideChains(model='all')[source]
Returns:a list of NucleotideChain objects, one for each nucleotide chain in the PDB file. The parameter model has the same meaning as for the NucleotideChain constructor.
createPeptideChains(model='all')[source]
Returns:a list of PeptideChain objects, one for each peptide chain in the PDB file. The parameter model has the same meaning as for the PeptideChain constructor.
createUnitCellUniverse()[source]

Constructs an empty universe (OrthrhombicPeriodicUniverse or ParallelepipedicPeriodicUniverse) representing the unit cell of the crystal. If the PDB file does not define a unit cell at all, an InfiniteUniverse is returned.

Returns:a universe
Return type:Universe
molecule_constructor

alias of PDBMolecule

nucleotide_chain_constructor

alias of PDBNucleotideChain

peptide_chain_constructor

alias of PDBPeptideChain

MMTK.PDB.PDBFile

alias of PDBConfiguration

class MMTK.PDB.PDBMolecule(name, atoms=None, number=None)[source]

Bases: Scientific.IO.PDB.Molecule

Molecule in a PDB file

See the description of Scientific.IO.PDB.Molecule 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.

@param name: the name of the group @type name: C{str} @param atoms: a list of atoms (or C{None} for no atoms) @type atoms: C{list} or C{NoneType} @param number: the PDB residue number (or C{None}) @type number: C{int} or C{NoneType}

createMolecule(name=None)[source]
Returns:a Molecule object corresponding to the molecule in the PDB file. The parameter name specifies the molecule name as defined in the chemical database. It can be left out for known molecules (currently only water).
Return type:Molecule
class MMTK.PDB.PDBNucleotideChain(residues=None, chain_id=None, segment_id=None)[source]

Bases: Scientific.IO.PDB.NucleotideChain, MMTK.PDB.PDBChain

Nucleotide chain in a PDB file

See the description of Scientific.IO.PDB.NucleotideChain 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).

@param residues: a list of residue objects, or C{None} meaning
that the chain is initially empty

@type residues: C{list} or C{NoneType} @param chain_id: a one-letter chain identifier or C{None} @type chain_id: C{str} or C{NoneType} @param segment_id: a multi-character segment identifier or C{None} @type segment_id: C{str} or C{NoneType}

createNucleotideChain(model='all')[source]
Returns:a NucleotideChain object corresponding to the nucleotide chain in the PDB file. The parameter model has the same meaning as for the NucleotideChain constructor.
Return type:NucleotideChain
class MMTK.PDB.PDBOutputFile(filename, subformat=None)[source]

Bases: object

PDB file for output

Parameters:
  • filename (str) – the name of the PDB file that is created
  • subformat (str) – a variant of the PDB format; these subformats are defined in module Scientific.IO.PDB. The default is the standard PDB format.
close()[source]

Closes the file. Must be called in order to prevent data loss.

nextModel()[source]

Start a new model

write(object, configuration=None, tag=None)[source]

Write an object to the file

Parameters:
  • object (GroupOfAtoms) – the object to be written
  • configuration (Configuration) – the configuration from which the coordinates are taken (default: current configuration)
class MMTK.PDB.PDBPeptideChain(residues=None, chain_id=None, segment_id=None)[source]

Bases: Scientific.IO.PDB.PeptideChain, MMTK.PDB.PDBChain

Peptide chain in a PDB file

See the description of Scientific.IO.PDB.PeptideChain 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).

@param residues: a list of residue objects, or C{None} meaning
that the chain is initially empty

@type residues: C{list} or C{NoneType} @param chain_id: a one-letter chain identifier or C{None} @type chain_id: C{str} or C{NoneType} @param segment_id: a multi-character segment identifier or C{None} @type segment_id: C{str} or C{NoneType}

createPeptideChain(model='all', n_terminus=None, c_terminus=None)[source]
Returns:a PeptideChain object corresponding to the peptide chain in the PDB file. The parameter model has the same meaning as for the PeptideChain constructor.
Return type:PeptideChain

MMTK.PDBMoleculeFactory

Molecule factory defined by a PDB file

This module permits the construction of molecular objects that correspond exactly to the contents of a PDB file. It is used for working with experimental data. Note that most force fields cannot be applied to the systems generated in this way because the molecule factory does not know any force field parameters.

class MMTK.PDBMoleculeFactory.PDBMoleculeFactory(pdb_conf, residue_filter=None, atom_filter=None)[source]

Bases: MMTK.MoleculeFactory.MoleculeFactory

A PDBMoleculeFactory generates molecules and universes from the contents of a PDBConfiguration. Nothing is added or left out (except as defined by the optional residue and atom filters), and the atom and residue names are exactly those of the original PDB file.

Parameters:
  • pdb_conf (PDBConfiguration) – a PDBConfiguration
  • residue_filter (callable) – a function taking a residue object (as defined in Scientific.IO.PDB) and returning True if that residue is to be kept in the molecule factory
  • atom_filter (callable) – a function taking a residue object and an atom object (as defined in Scientific.IO.PDB) and returning True if that atom is to be kept in the molecule factory
retrieveAsymmetricUnit()[source]

Constructs a universe (OrthrhombicPeriodicUniverse or ParallelepipedicPeriodicUniverse) representing the unit cell of the crystal and adds the molecules representing the asymmetric unit.

Returns:a universe
Return type:Universe
retrieveMolecules()[source]

Constructs Molecule objects corresponding to the contents of the PDBConfiguration. Each peptide or nucleotide chain becomes one molecule. For residues that are neither amino acids nor nucleic acids, each residue becomes one molecule.

Chain molecules (peptide and nucleotide chains) can be iterated over to retrieve the individual residues. The residues can also be accessed as attributes whose names are the three-letter residue name (upper case) followed by an underscore and the residue number from the PDB file (e.g. ‘GLY_34’).

Each object that corresponds to a PDB residue (i.e. each residue in a chain and each non-chain molecule) has the attributes ‘residue_name’ and ‘residue_number’. Each atom has the attributes ‘serial_number’, ‘occupancy’ and ‘temperature_factor’. Atoms for which a ANISOU record exists also have an attribute ‘u’ whose value is a tensor object.

Returns:a list of Molecule objects
Return type:list
retrieveUnitCell(compact=True)[source]

Constructs a universe (OrthrhombicPeriodicUniverse or ParallelepipedicPeriodicUniverse) representing the unit cell of the crystal and adds all the molecules it contains, i.e. the molecules of the asymmetric unit and its images obtained by applying the crystallographic symmetry operations.

Parameters:
  • compact (bool) – if True, the images are shifted such that their centers of mass lie inside the unit cell.
Returns:

a universe

Return type:

Universe

retrieveUniverse()[source]

Constructs an empty universe (OrthrhombicPeriodicUniverse or ParallelepipedicPeriodicUniverse) representing the unit cell of the crystal. If the PDB file does not define a unit cell at all, an InfiniteUniverse is returned.

Returns:a universe
Return type:Universe

MMTK.ParticleProperties

Quantities defined for each particle in a universe

class MMTK.ParticleProperties.Configuration(universe, data_array=None, cell=None)[source]

Bases: MMTK.ParticleProperties.ParticleVector

Configuration of a universe

Configuration 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.

Parameters:
  • universe (Universe) – the universe for which the values are defined
  • data_array (Scientific.N.array_type) – the data array containing the values for each particle. If None, a new array containing zeros is created and used. Otherwise, the array myst be of shape (N,3), where N is the number of particles in the universe.
  • cell – the cell parameters of the universe, i.e. the return value of universe.cellParameters()
class MMTK.ParticleProperties.ParticleProperty(universe, data_rank, value_rank)[source]

Bases: object

Property defined for each particle

This is an abstract base class; for creating instances, use one of its subclasses.

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.

assign(other)[source]

Copy all values from another compatible ParticleProperty object.

Parameters:
  • other – the data source
return_class

alias of ParticleProperty

scaleBy(factor)[source]

Multiply all values by a factor

Parameters:
  • factor (float) – the scale factor
selectAtoms(condition)[source]

Return a collection containing all atoms a for which condition(property[a]) is True.

Parameters:
  • condition (callable) – a test function
sumOverParticles()[source]
Returns:the sum of the values for all particles.
zero()[source]
Returns:an object of the element type (scalar, vector, etc.) with the value 0.
class MMTK.ParticleProperties.ParticleScalar(universe, data_array=None)[source]

Bases: MMTK.ParticleProperties.ParticleProperty

Scalar property defined for each particle

ParticleScalar objects can be added to each other and multiplied with scalars.

Parameters:
  • universe (Universe) – the universe for which the values are defined
  • data_array (Scientific.N.array_type) – the data array containing the values for each particle. If None, a new array containing zeros is created and used. Otherwise, the array myst be of shape (N,), where N is the number of particles in the universe.
applyFunction(function)[source]
Parameters:
  • function – a function that is applied to each data value
Returns:

a new ParticleScalar object containing the function results

maximum()[source]
Returns:the highest value in the data array particle
Return type:float
minimum()[source]
Returns:the smallest value in the data array particle
Return type:float
return_class

alias of ParticleScalar

class MMTK.ParticleProperties.ParticleTensor(universe, data_array=None)[source]

Bases: MMTK.ParticleProperties.ParticleProperty

Rank-2 tensor property defined for each particle

ParticleTensor objects can be added to each other and multiplied with scalars or ParticleScalar objects; all of these operations result in another ParticleTensor object.

Parameters:
  • universe (Universe) – the universe for which the values are defined
  • data_array (Scientific.N.array_type) – the data array containing the values for each particle. If None, a new array containing zeros is created and used. Otherwise, the array myst be of shape (N,3,3), where N is the number of particles in the universe.
return_class

alias of ParticleTensor

class MMTK.ParticleProperties.ParticleVector(universe, data_array=None)[source]

Bases: MMTK.ParticleProperties.ParticleProperty

Vector property defined for each particle

ParticleVector objects can be added to each other and multiplied with scalars or ParticleScalar objects; all of these operations result in another ParticleVector object. Multiplication with a vector or another ParticleVector object yields a ParticleScalar object containing the dot products for each particle. Multiplications that treat ParticleVectors as vectors in a 3N-dimensional space are implemented as methods.

Parameters:
  • universe (Universe) – the universe for which the values are defined
  • data_array (Scientific.N.array_type) – the data array containing the values for each particle. If None, a new array containing zeros is created and used. Otherwise, the array myst be of shape (N,3), where N is the number of particles in the universe.
dotProduct(other)[source]
Parameters:
Returns:

the dot product with other, treating both operands as 3N-dimensional vectors.

dyadicProduct(other)[source]
Parameters:
Returns:

the dyadic product with other

Return type:

ParticleTensor

length()[source]
Returns:the length (norm) of the vector for each particle
Return type:ParticleScalar
massWeightedDotProduct(other)[source]
Parameters:
Returns:

the mass-weighted dot product with other treating both operands as 3N-dimensional vectors

Return type:

float

massWeightedNorm()[source]
Returns:the mass-weighted norm of the ParticleVector seen as a 3N-dimensional vector
Return type:float
norm()[source]
Returns:the norm of the ParticleVector seen as a 3N-dimensional vector
Return type:float
return_class

alias of ParticleVector

totalNorm()
Returns:the norm of the ParticleVector seen as a 3N-dimensional vector
Return type:float
MMTK.ParticleProperties.isConfiguration(object)[source]
Parameters:
  • object – any object
Returns:

True if object is a Configuration

Return type:

bool

MMTK.ParticleProperties.isParticleProperty(object)[source]
Parameters:
  • object – any object
Returns:

True if object is a ParticleProperty

Return type:

bool

MMTK.ProteinFriction

A friction constant model for Cα models of proteins

MMTK.ProteinFriction.calphaFrictionConstants(protein, set=2)[source]
Parameters:
  • protein (Protein) – a Cα model protein
  • set – the number of a friction constant set (1, 2, 3, or 4)
Returns:

the estimated friction constants for the atoms in the protein

Return type:

ParticleScalar

MMTK.Proteins

Peptide chains and proteins

class MMTK.Proteins.ConnectedChains(chains=None)[source]

Bases: MMTK.Proteins.PeptideChain

Peptide chains connected by disulfide bridges

A group of peptide chains connected by disulfide bridges must be considered a single molecule due to the presence of chemical bonds. Such a molecule is represented by a ConnectedChains object. These objects are created automatically when a Protein object is assembled. They are normally not used directly by application programs. When a chain with disulfide bridges to other chains is extracted from a Protein object, the return value is a SubChain object that indirectly refers to a ConnectedChains object.

class MMTK.Proteins.PeptideChain(sequence, **properties)[source]

Bases: MMTK.Biopolymers.ResidueChain

Peptide chain

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.

Peptide chains act as sequences of residues. If p is a PeptideChain object, then

  • len(p) yields the number of residues

  • p[i] yields residue number i

  • p[i:j] yields the subchain from residue number i up to

    but excluding residue number j

Parameters:
  • sequence – 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.
  • model (str) – 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α atom of each residue). Default is “all”.
  • n_terminus (bool) – if True, the first residue is constructed using the N-terminal variant, if False the non-terminal version is used. Default is True.
  • c_terminus (bool) – if True, the last residue is constructed using the C-terminal variant, if False the non-terminal version is used. Default is True.
  • circular (bool) – if True, a peptide bond is constructed between the first and the last residues. Default is False.
  • name (str) – a name for the chain (a string)
backbone()[source]
Returns:the peptide groups of all residues
Return type:Collection
phiPsi(conf=None)[source]
Returns:a list of the (phi, psi) backbone angles for each residue
Return type:list of tuple of float
replaceResidue(r_old, r_new)[source]
Parameters:
  • r_old (Residue) – the residue to be replaced (must be part of the chain)
  • r_new (Residue) – the residue that replaces r_old
sequence()[source]
Returns:the primary sequence as a list of three-letter residue codes.
Return type:list
sidechains()[source]
Returns:the sidechain groups of all residues
Return type:Collection
class MMTK.Proteins.Protein(*items, **properties)[source]

Bases: MMTK.ChemicalObjects.Complex

Protein

A Protein object is a special kind of Complex object which is made up of peptide chains and possibly ligands.

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.

Proteins act as sequences of chains. If p is a Protein object, then

  • len(p) yields the number of chains
  • p[i] yields chain number i
Parameters:
  • items – either a sequence of peptide chain objects, or 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.
  • model (str) – 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α atom of each residue). Default is “all”.
  • position (Scientific.Geometry.Vector) – the center-of-mass position of the protein
  • name (str) – a name for the protein
backbone()[source]
Returns:the peptide groups of all residues in all chains
Return type:Collection
phiPsi(conf=None)[source]
Returns:a list of the (phi, psi) backbone angles for all residue in all chains
Return type:list of list of tuple of float
residues()[source]
Returns:all residues in all chains
Return type:Collection
residuesOfType(*types)[source]
Parameters:
  • types (sequence of str) – a sequence of residue codes (one- or three-letter)
Returns:

all residues whose type (one- or three-letter code) is contained in types

Return type:

Collection

sidechains()[source]
Returns:the sidechain groups of all residues in all chains
Return type:Collection
class MMTK.Proteins.Residue(name=None, model='all')[source]

Bases: MMTK.Biopolymers.Residue

Amino acid residue

Amino acid residues are a special kind of group. They are defined in the chemical database. Each residue has two subgroups (‘peptide’ and ‘sidechain’) 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α).

Parameters:
  • name (str) – 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.
  • model (str) – 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α atom).
backbone()[source]
Returns:the peptide group
Return type:Group
chiAngle()[source]
Returns:an object representing the chi angle and allowing to modify it
Return type:MMTK.InternalCoordinates.DihedralAngle
phiAngle()[source]
Returns:an object representing the phi angle and allowing to modify it
Return type:MMTK.InternalCoordinates.DihedralAngle
phiPsi(conf=None)[source]
Returns:the values of the backbone dihedral angles phi and psi.
Return type:tuple (float, float)
psiAngle()[source]
Returns:an object representing the psi angle and allowing to modify it
Return type:MMTK.InternalCoordinates.DihedralAngle
sidechains()[source]
Returns:the sidechain group
Return type:Group
class MMTK.Proteins.SubChain(chain=None, groups=None, name='')[source]

Bases: MMTK.Proteins.PeptideChain

A contiguous part of a peptide chain

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.

MMTK.Proteins.isPeptideChain(x)[source]
Parameters:
  • x – any object
Returns:

True if x is a peptide chain

Return type:

bool

MMTK.Proteins.isProtein(x)[source]
Parameters:
  • x – any object
Returns:

True if x is a protein

Return type:

bool

MMTK.Random

Random quantities for use in molecular simulations

MMTK.Random.randomDirection()[source]
Returns:a vector drawn from a uniform distribution on the surface of a unit sphere.
Return type:Scientific.Geometry.Vector
MMTK.Random.randomDirections(n)[source]
Parameters:
  • n – the number of direction vectors
Returns:

a list of n vectors drawn from a uniform distribution on the surface of a unit sphere. If n is negative, returns a deterministic list of not more than -n vectors of unit length (useful for testing purposes).

Return type:

list

MMTK.Random.randomParticleVector(universe, width)[source]
Parameters:
  • universe (Universe) – a universe
  • width (float) – the width (standard deviation) of a Gaussian distribution
Returns:

a set of vectors drawn from a Gaussian distribution with a given width centered around zero.

Return type:

ParticleVector

MMTK.Random.randomPointInBox(a, b=None, c=None)[source]
Parameters:
  • a (float) – the edge length of a box along the x axis
  • b (float) – the edge length of a box along the y axis (default: a)
  • c (float) – the edge length of a box along the z axis (default: a)
Returns:

a vector drawn from a uniform distribution within a rectangular box with edge lengths a, b, c.

Return type:

Scientific.Geometry.Vector

MMTK.Random.randomPointInSphere(r)[source]
Parameters:
  • r (float) – the radius of a sphere
Returns:

a vector drawn from a uniform distribution within a sphere of radius r.

Return type:

Scientific.Geometry.Vector

MMTK.Random.randomRotation(max_angle=3.1415926535897931)[source]
Parameters:
  • max_angle (float) – the upper limit for the rotation angle
Returns:

a random rotation with a uniform axis distribution and angles drawn from a uniform distribution between -max_angle and max_angle.

Return type:

Scientific.Geometry.Transformations.Rotation

MMTK.Random.randomVelocity(temperature, mass)[source]
Parameters:
  • temperature (float) – the temperature defining a Maxwell distribution
  • mass (float) – the mass of a particle
Returns:

a random velocity vector for a particle of a given mass at a given temperature

Return type:

Scientific.Geometry.Vector

MMTK.Solvation

Solvation of solute molecules

MMTK.Solvation.addSolvent(universe, solvent, density, scale_factor=4.0)[source]

Scales up the universe and adds as many solvent molecules as are necessary to obtain the specified solvent density, 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.

Parameters:
  • universe (Universe) – a finite universe
  • solvent (Molecule or str) – a molecule, or the name of a molecule in the database
  • density (float) – the density of the solvent (amu/nm**3)
  • scale_factor (float) – the factor by which the initial universe is expanded before adding the solvent molecules
MMTK.Solvation.numberOfSolventMolecules(universe, solvent, density)[source]
Parameters:
  • universe (Universe) – a finite universe
  • solvent (Molecule or str) – a molecule, or the name of a molecule in the database
  • density (float) – the density of the solvent (amu/nm**3)
Returns:

the number of solvent molecules that must be added to the universe, in addition to whatever it already contains, to obtain the given solvent density.

Return type:

int

MMTK.Solvation.shrinkUniverse(universe, temperature=300.0, trajectory=None, scale_factor=0.94999999999999996)[source]

Shrinks the universe, which must have been scaled up by 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 temperature, and an optional trajectory can be specified in which intermediate configurations are stored.

Parameters:
  • universe (Universe) – a finite universe
  • temperature (float) – the temperature at which the Molecular Dynamics steps are run
  • trajectory (Trajectory or str) – the trajectory in which the progress of the shrinking procedure is stored, or a filename
  • scale_factor (float) – the factor by which the universe is scaled at each reduction step

MMTK.Subspace

Linear subspaces for infinitesimal motions

This module implements subspaces for infinitesimal (or finite small-amplitude) atomic motions. They can be used in normal mode calculations or for analyzing complex motions. For an explanation, see:

K. Hinsen and G.R. Kneller
Projection methods for the analysis of complex motions in macromolecules
Mol. Sim. 23:275-292 (2000)
class MMTK.Subspace.LinkedRigidBodyMotionSubspace(universe, rigid_bodies)[source]

Bases: MMTK.Subspace.Subspace

Subspace for the motion of linked rigid bodies

This class describes the same subspace as RigidBodyMotionSubspace, and is used by the latter. For collections of several chains of linked rigid bodies, RigidBodyMotionSubspace is more efficient.

Parameters:
  • universe (Universe) – the universe for which the subspace is created
  • rigid_bodies – a list or set of rigid bodies with some common atoms
class MMTK.Subspace.PairDistanceSubspace(universe, atom_pairs)[source]

Bases: MMTK.Subspace.Subspace

Subspace of pair-distance motions

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.

Parameters:
  • universe (Universe) – the universe for which the subspace is created
  • atom_pairs – a sequence of atom pairs whose distance-vector motion is included in the subspace
class MMTK.Subspace.RigidMotionSubspace(universe, objects)[source]

Bases: MMTK.Subspace.Subspace

Subspace of rigid-body motions

A rigid-body motion subspace is the subspace which contains the rigid-body motions of any number of chemical objects.

Parameters:
  • universe (Universe) – the universe for which the subspace is created
  • objects – a sequence of objects whose rigid-body motion is included in the subspace
class MMTK.Subspace.Subspace(universe, vectors)[source]

Bases: object

Subspace of infinitesimal atomic motions

Parameters:
  • universe (Universe) – the universe for which the subspace is created
  • vectors (list) – a list of ParticleVector objects that define the subspace. They need not be orthogonal or linearly independent.
complement()[source]
Returns:the orthogonal complement subspace
Return type:Subspace
getBasis()[source]

Construct a basis for the subspace by orthonormalization of the input vectors using Singular Value Decomposition. The basis consists of a sequence of ParticleVector objects that are orthonormal in configuration space. :returns: the basis

projectionComplementOf(vector)[source]
Parameters:
Returns:

the projection of the vector onto the orthogonal complement of the subspace.

projectionOf(vector)[source]
Parameters:
Returns:

the projection of the vector onto the subspace.

MMTK.Trajectory

Trajectory files and their contents

class MMTK.Trajectory.LogOutput(file, data=None, first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryOutput

Protocol file output action

A LogOutput object can be used in the action list of any trajectory-generating operation. It writes any of the available data to a text file.

Parameters:
  • file – a file object or a string, which is interpreted as the name of a file that is opened in write mode
  • data – 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 (data = None) the categories “configuration”, “energy”, “thermodynamic”, and “time” are written.
  • first (int) – the number of the first step at which the action is run
  • last (int) – the number of the step at which the action is suspended. A value of None indicates that the action should be applied indefinitely.
  • skip (int) – the number of steps to skip between two action runs
class MMTK.Trajectory.ParticleTrajectory(trajectory, atom, first=0, last=None, skip=1, variable='configuration')[source]

Bases: object

Trajectory data for a single particle

A ParticleTrajectory object is created by calling the method readParticleTrajectory() on a Trajectory object.

If pt is a ParticleTrajectory object, then

  • len(pt) is the number of steps stored in it
  • pt[i] is the value at step i (a vector)
translateBy(vector)[source]

Adds a vector to the values at all steps. This does B{not} change the data in the trajectory file.

Parameters:
  • vector (Scientific.Geometry.Vector) – the vector to be added
class MMTK.Trajectory.RestartTrajectoryOutput(trajectory, skip=100, length=3)[source]

Bases: MMTK.Trajectory.TrajectoryOutput

Restart trajectory output action

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.

Parameters:
  • trajectory – 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 length and double-precision variables
  • skip (int) – the number of steps between two write operations to the restart trajectory
  • length – the number of steps stored in the restart trajectory; used only if trajectory is a string
class MMTK.Trajectory.RigidBodyTrajectory(trajectory, object, first=0, last=None, skip=1, reference=None)[source]

Bases: object

Rigid-body trajectory data

A RigidBodyTrajectory object is created by calling the method readRigidBodyTrajectory() on a Trajectory object.

If rbt is a RigidBodyTrajectory object, then

  • len(rbt) is the number of steps stored in it
  • rbt[i] is the value at step i (a vector for the center of mass and a quaternion for the orientation)
class MMTK.Trajectory.SnapshotGenerator(universe, **options)[source]

Bases: MMTK.Trajectory.TrajectoryGenerator

Trajectory generator for single steps

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.

Each call to the SnapshotGenerator object produces one step. All the keyword options can be specified either when creating the generator or when calling it.

Parameters:
  • universe – the universe on which the generator acts
  • data – a dictionary that supplies values for variables that are not part of the universe state (e.g. potential energy)
  • actions – a list of actions to be executed periodically (default is none)
class MMTK.Trajectory.StandardLogOutput(skip=50)[source]

Bases: MMTK.Trajectory.LogOutput

Standard protocol output action

A StandardLogOutput object can be 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.

Parameters:
  • skip (int) – the number of steps to skip between two action runs
class MMTK.Trajectory.SubTrajectory(trajectory, indices)[source]

Bases: object

Reference to a subset of a trajectory

A SubTrajectory object is created by slicing a Trajectory object or another SubTrajectory object. It provides all the operations defined on Trajectory objects.

class MMTK.Trajectory.SubVariable(variable, indices)[source]

Bases: MMTK.Trajectory.TrajectoryVariable

Reference to a subset of a TrajectoryVariable

A SubVariable object is created by slicing a TrajectoryVariable object or another SubVariable object. It provides all the operations defined on TrajectoryVariable objects.

class MMTK.Trajectory.Trajectory(object, filename, mode='r', comment=None, double_precision=False, cycle=0, block_size=1)[source]

Bases: object

Trajectory file

The data in a trajectory file can be accessed by step or by variable. If t is a Trajectory object, then:

  • len(t) is the number of steps
  • t[i] is the data for step i, in the form of a dictionary that maps variable names to data
  • t[i:j] and t[i:j:n] return a SubTrajectory object that refers to a subset of the total number of steps (no data is copied)
  • t.variable 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.

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”.

Parameters:
  • object (ChemicalObject) – the object whose data is stored in the trajectory file. This can be ‘None’ 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 ‘universe’ of the trajectory object.
  • filename (str) – the name of the trajectory file
  • mode (str) – 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)
  • comment (str) – optional comment that is stored in the file; allowed only with mode=”r”
  • double_precision (bool) – if True, 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.
  • cycle (int) – if non-zero, a trajectory is created for a fixed number of steps equal to the value of cycle, and these steps are used cyclically. This is meant for restart trajectories.
  • block_size (int) – 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.
close()[source]

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.

flush()[source]

Make sure that all data that has been written to the trajectory is also written to the file.

readParticleTrajectory(atom, first=0, last=None, skip=1, variable='configuration')[source]

Read trajectory information for a single atom but for multiple time steps.

Parameters:
  • atom (Atom) – the atom whose trajectory is requested
  • first (int) – the number of the first step to be read
  • last (int) – the number of the first step not to be read. A value of None indicates that the whole trajectory should be read.
  • skip (int) – the number of steps to skip between two steps read
  • variable (str) – the name of the trajectory variable to be read. 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.
Returns:

the trajectory for a single atom

Return type:

ParticleTrajectory

readRigidBodyTrajectory(object, first=0, last=None, skip=1, reference=None)[source]

Read the positions for an object at multiple time steps and extract the rigid-body motion (center-of-mass position plus orientation as a quaternion) by an optimal-transformation fit.

Parameters:
  • object (GroupOfAtoms) – the object whose rigid-body trajectory is requested
  • first (int) – the number of the first step to be read
  • last (int) – the number of the first step not to be read. A value of None indicates that the whole trajectory should be read.
  • skip (int) – the number of steps to skip between two steps read
  • reference (Configuration) – the reference configuration for the fit
Returns:

the trajectory for a single rigid body

Return type:

RigidBodyTrajectory

variables()[source]
Returns:a list of the names of all variables that are stored in the trajectory
Return type:list of str
view(first=0, last=None, skip=1, object=None)[source]

Show an animation of the trajectory using an external visualization program.

Parameters:
  • first (int) – the number of the first step in the animation
  • last (int) – the number of the first step not to include in the animation. A value of None indicates that the whole trajectory should be used.
  • skip (int) – the number of steps to skip between two steps read
  • object (GroupOfAtoms) – the object to be animated, which must be in the universe stored in the trajectory. None stands for the whole universe.
class MMTK.Trajectory.TrajectoryAction(first, last, skip)[source]

Bases: object

Trajectory action base class

Subclasses of this base class implement the actions that can be inserted into trajectory generation at regular intervals.

class MMTK.Trajectory.TrajectoryGenerator(universe, options)[source]

Bases: object

Trajectory generator base class

This base class implements the common aspects of everything that generates trajectories: integrators, minimizers, etc.

class MMTK.Trajectory.TrajectoryOutput(trajectory, data=None, first=0, last=None, skip=1)[source]

Bases: MMTK.Trajectory.TrajectoryAction

Trajectory output action

A TrajectoryOutput object can be 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.

Parameters:
  • trajectory – a trajectory object or a string, which is interpreted as the name of a file that is opened as a trajectory in append mode
  • data – 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 (data = None) the categories “configuration”, “energy”, “thermodynamic”, and “time” are written.
  • first (int) – the number of the first step at which the action is run
  • last (int) – the number of the step at which the action is suspended. A value of None indicates that the action should be applied indefinitely.
  • skip (int) – the number of steps to skip between two action runs
class MMTK.Trajectory.TrajectorySet(object, filenames)[source]

Bases: object

Trajectory file set

A TrajectorySet permits to treat a sequence of trajectory files like a single trajectory for reading data. It behaves exactly like a Trajectory object. 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.

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.

Parameters:
  • object – the object whose data is stored in the trajectory files. This can be (and usually is) None; 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 universe of the trajectory set object.
  • filenames – a list of trajectory file names or (filename, first_step, last_step, increment) tuples.
class MMTK.Trajectory.TrajectorySetVariable(universe, trajectory_set, name)[source]

Bases: MMTK.Trajectory.TrajectoryVariable

Variable in a trajectory set

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.

class MMTK.Trajectory.TrajectoryVariable(universe, trajectory, name)[source]

Bases: object

Variable in a trajectory

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.

If t is a TrajectoryVariable object, then:

  • len(t) is the number of steps
  • t[i] is the data for step i, in the form of a ParticleScalar, a ParticleVector, or a Configuration object, depending on the variable
  • t[i:j] and t[i:j:n] return a SubVariable object that refers to a subset of the total number of steps
MMTK.Trajectory.isTrajectory(object)[source]
Parameters:
  • object – any Python object
Returns:

True if object is a trajectory

MMTK.Trajectory.trajectoryInfo(filename)[source]
Parameters:
  • filename (str) – the name of a trajectory file
Returns:

a string with summarial information about the trajectory

MMTK.Units

Units and physical constants

This module defines constants and prefactors that convert from various units to MMTK’s internal unit system. There are also some common physical constants.

MMTK’s unit system is defined by:

  • nm for length
  • ps for time
  • amu (g/mol) for mass
  • the charge of a proton for charge
  • rad for angles

All formulas that do not contain electrical quantities (charge, electric/magnetic field, ...) have the same form in this unit system as in the SI system. The energy unit that results from the choices given above is kJ/mol.

The constants defined in this module are:

  • SI Prefixes: ato, femto, pico, nano, micro, milli, centi, deci,

    deca, hecto, kilo, mega, giga, tera, peta

  • Length units: m, cm, mm, nm, pm, fm, Ang, Bohr

  • Angle units: rad, deg

  • Volume units: l

  • Time units: s, ns, ps, fs

  • Frequency units: Hz, invcm (wavenumbers)

  • Mass units: amu, g, kg

  • Quantity-of-matter units: mol

  • Energy units: J, kJ, cal (thermochemical), kcal, Hartree, Bohr

  • Temperature units: K

  • Force units: N, dyn

  • Pressure units: Pa, MPa, GPa, bar, kbar, atm

  • Electrostatic units: C, A, V, D, eV, e

  • 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)
  • Other:

    • akma_time (the time unit in the DCD trajectory format)
    • electrostatic_energy (the prefactor in Coulomb’s law)

MMTK.Universe

Universes

class MMTK.Universe.CubicPeriodicUniverse(size=None, forcefield=None, **properties)[source]

Bases: MMTK.Universe.OrthorhombicPeriodicUniverse

Periodic universe with cubic elementary cell.

Parameters:
  • size – a sequence of length three specifying the edge lengths along the x, y, and z directions
  • forcefield (ForceField) – a force field, or None for no force field
setSize(size)[source]

Set the edge length to a given value.

Parameters:
  • size (float) – the new size
class MMTK.Universe.InfiniteUniverse(forcefield=None, **properties)[source]

Bases: MMTK.Universe.Universe

Infinite (unbounded and nonperiodic) universe.

Parameters:
  • forcefield (ForceField) – a force field, or None for no force field
class MMTK.Universe.OrthorhombicPeriodicUniverse(size=None, forcefield=None, **properties)[source]

Bases: MMTK.Universe.Periodic3DUniverse

Periodic universe with orthorhombic elementary cell.

Parameters:
  • size – a sequence of length three specifying the edge lengths along the x, y, and z directions
  • forcefield (ForceField) – a force field, or None for no force field
scaleSize(factor)[source]

Multiplies all edge lengths by a factor.

Parameters:
  • factor (float) – the scale factor
class MMTK.Universe.ParallelepipedicPeriodicUniverse(shape=None, forcefield=None, **properties)[source]

Bases: MMTK.Universe.Periodic3DUniverse

Periodic universe with parallelepipedic elementary cell.

Parameters:
  • shape (sequence of Scientific.Geometry.Vector) – the basis vectors
  • forcefield (ForceField) – a force field, or None for no force field
scaleSize(factor)[source]

Multiplies all edge lengths by a factor.

Parameters:
  • factor (float) – the scale factor
class MMTK.Universe.Universe(forcefield, properties)[source]

Bases: MMTK.Collections.GroupOfAtoms, MMTK.Visualization.Viewable

Universe

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.

The class Universe is an abstract base class that defines properties common to all kinds of universes. To create universe objects, use one of its subclasses.

In addition to the methods listed below, universe objects support the following operations (u is any universe object, o is any chemical object):

  • len(u) yields the number of chemical objects in the universe
  • u[i] returns object number i
  • u.name = o adds o to the universe and also makes it accessible as an attribute
  • del u.name removes the object that was assigned to u.name from the universe
acquireConfigurationChangeLock(waitflag=True)[source]

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.

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.

Parameters:
  • waitflag (bool) – if true, the method waits until the lock becomes available; this is the most common mode. If false, the method returns immediately even if another thread holds the lock.
Returns:

a flag indicating if the lock was successfully acquired (1) or not (0).

Return type:

int

acquireReadStateLock()[source]

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.

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.

acquireWriteStateLock()[source]

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.

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.

addObject(object, steal=False)[source]

Adds object to the universe. If object is a Collection, all elements of the Collection are added to the universe.

Parameters:
  • object – the object (chemical or environment) to be added
  • steal (bool) – if True, permit stealing the object from another universe, otherwise the object must not yet be attached to any universe.
addToConfiguration(displacement, block=True)[source]

Update the current configuration of the universe by adding the given displacement vector.

Parameters:
  • displacement (ParticleVector) – the displacement vector for each atom
  • block (bool) – if True, the operation blocks other threads from accessing the configuration before the update is completed. If False, it is assumed that the caller takes care of locking.
adjustVelocitiesToConstraints(velocities=None, block=True)[source]

Modifies the velocities to be compatible with the distance constraints, i.e. projects out the velocity components along the constrained distances.

Parameters:
  • velocities (ParticleVector) – the velocities in which the constraints are enforced (None for current velocities)
  • block (bool) – if True, the operation blocks other threads from accessing the configuration before the update is completed. If False, it is assumed that the caller takes care of locking.
angle(p1, p2, p3, conf=None)[source]
Parameters:
  • p1 – a vector or a chemical object whose position is taken
  • p2 – a vector or a chemical object whose position is taken
  • p3 – a vector or a chemical object whose position is taken
  • conf – a configuration (None for the current configuration)
Returns:

the angle between the distance vectors p1-p2 and p3-p2

Return type:

float

atomList()[source]
Returns:a list of all atoms in the universe
Return type:list
basisVectors()[source]
Returns:the basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe
boxToRealCoordinates(vector)[source]
Parameters:
  • vector – a point in the universe expressed in box coordinates
Returns:

the real-space equivalent of vector

Return type:

Scientific.Geometry.Vector

cartesianToFractional(vector)[source]

Fractional coordinates are defined only for periodic universes; their components have values between 0. and 1.

Parameters:
  • vector (Scientific.Geometry.Vector) – a point in the universe
Returns:

the fractional coordinate equivalent of vector

Return type:

Scientific.N.array_type

cellVolume()[source]
Returns:the volume of the elementary cell of a periodic universe, None for a non-periodic universe
charges()[source]

Return the atomic charges defined by the universe’s force field.

Returns:the charges of all atoms in the universe
Return type:ParticleScalar
configuration()[source]
Returns:the configuration object describing the current configuration of the universe. Note that this is not a copy of the current state, but a reference: the positions in the configuration object will change when coordinate changes are applied to the universe in whatever way.
Return type:Configuration
configurationDifference(conf1, conf2)[source]
Parameters:
Returns:

the difference vector between the two configurations for each atom, taking into account the universe topology (e.g. minimum-image convention).

Return type:

ParticleVector

contiguousObjectConfiguration(objects=None, conf=None)[source]
Parameters:
  • objects (list) – a list of chemical objects, or None for all objects in the universe
  • conf – a configuration (None for the current configuration)
Returns:

configuration conf (default: current configuration) corrected by the contiguous object offsets for that configuration.

Return type:

Configuration

contiguousObjectOffset(objects=None, conf=None, box_coordinates=False)[source]
Parameters:
  • objects (list) – a list of chemical objects, or None for all objects in the universe
  • conf – a configuration (None for the current configuration)
  • box_coordinates (bool) – use box coordinates rather than real ones
Returns:

a set of displacement vectors relative to the conf which, when added to the configuration, create a configuration in which none of the objects is split across the edge of the elementary cell. For nonperiodic universes the return value is None.

Return type:

ParticleVector

copyConfiguration()[source]

This operation is thread-safe; it won’t return inconsistent data even when another thread is modifying the configuration.

Returns:a copy of the current configuration
Return type:Configuration
dihedral(p1, p2, p3, p4, conf=None)[source]
Parameters:
  • p1 – a vector or a chemical object whose position is taken
  • p2 – a vector or a chemical object whose position is taken
  • p3 – a vector or a chemical object whose position is taken
  • p4 – a vector or a chemical object whose position is taken
  • conf – a configuration (None for the current configuration)
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

Return type:

float

distance(p1, p2, conf=None)[source]
Parameters:
  • p1 – a vector or a chemical object whose position is taken
  • p2 – a vector or a chemical object whose position is taken
  • conf – a configuration (None for the current configuration)
Returns:

the distance between p1 and p2, i.e. the length of the distance vector

Return type:

float

distanceConstraintList()[source]
Returns:the list of distance constraints
Return type:list
distanceVector(p1, p2, conf=None)[source]
Parameters:
  • p1 – a vector or a chemical object whose position is taken
  • p2 – a vector or a chemical object whose position is taken
  • conf – a configuration (None for the current configuration)
Returns:

the distance vector between p1 and p2 (i.e. the vector from p1 to p2) in the configuration conf, taking into account the universe’s topology.

energy(subset1=None, subset2=None, small_change=False)[source]
Parameters:
  • subset1 (ChemicalObject) – a subset of a universe, or None
  • subset2 (ChemicalObject) – a subset of a universe, or None
  • small_change (bool) – if True, algorithms optimized for small configurational changes relative to the last evaluation may be used.
Returns:

the potential energy of interaction between the atoms in subset1 and the atoms in subset2. If subset2 is None, the interactions within subset1 are calculated. It both subsets are None, the potential energy of the whole universe is returned.

Return type:

float

energyAndForceConstants(subset1=None, subset2=None, small_change=False)[source]
Returns:the energy and the force constants
Return type:(float, SymmetricPairTensor)
energyAndGradients(subset1=None, subset2=None, small_change=False)[source]
Returns:the energy and the energy gradients
Return type:(float, ParticleVector)
energyGradientsAndForceConstants(subset1=None, subset2=None, small_change=False)[source]
Returns:the energy, its gradients, and the force constants
Return type:(float, ParticleVector, SymmetricPairTensor)
energyTerms(subset1=None, subset2=None, small_change=False)[source]
Returns:a dictionary containing the energy values for each energy term separately. The energy terms are defined by the force field.
Return type:dict
enforceConstraints(configuration=None, velocities=None)[source]

Enforces the previously defined distance constraints by modifying the configuration and velocities.

Parameters:
  • configuration (Configuration) – the configuration in which the constraints are enforced (None for current configuration)
  • velocities (ParticleVector) – the velocities in which the constraints are enforced (None for current velocities)
environmentObjectList(klass=None)[source]
Parameters:
  • klass (class) – an optional class argument
Returns:

a list of all environment objects in the universe. If klass is given, only objects that are instances of klass are returned.

Return type:

list

forcefield()[source]
Returns:the force field
Return type:ForceField
fractionalToCartesian(array)[source]

Fractional coordinates are defined only for periodic universes; their components have values between 0. and 1.

Parameters:
  • array (Scientific.N.array_type) – an array of fractional coordinates
Returns:

the real-space equivalent of vector

Return type:

Scientific.Geometry.Vector

getAtomBooleanArray(name)
Parameters:
  • name (str) – the name of an atom attribute
Returns:

the values of the boolean attribute ‘name’ for each atom in the universe, or False for atoms that do not have the attribute.

Return type:

ParticleScalar

getAtomScalarArray(name, datatype='d')
Parameters:
  • name (str) – the name of an atom attribute
  • datatype – the datatype of the array allocated to hold the data
Returns:

the values of the attribute ‘name’ for each atom in the universe.

Return type:

ParticleScalar

getParticleBoolean(name)[source]
Parameters:
  • name (str) – the name of an atom attribute
Returns:

the values of the boolean attribute ‘name’ for each atom in the universe, or False for atoms that do not have the attribute.

Return type:

ParticleScalar

getParticleScalar(name, datatype='d')[source]
Parameters:
  • name (str) – the name of an atom attribute
  • datatype – the datatype of the array allocated to hold the data
Returns:

the values of the attribute ‘name’ for each atom in the universe.

Return type:

ParticleScalar

initializeVelocitiesToTemperature(temperature)[source]

Generate random velocities for all atoms from a Boltzmann distribution.

Parameters:
  • temperature (float) – the reference temperature for the Boltzmann distribution
largestDistance()[source]
Returns:the largest possible distance between any two points that can be represented independent of orientation, i.e. the radius of the largest sphere that fits into the simulation cell. Returns None if no such upper limit exists.
map(function)[source]

Apply a function to all objects in the universe and return the list of the results. If the results are chemical objects, a Collection object is returned instead of a list.

Parameters:
  • function (callable) – the function to be applied
Returns:

the list or collection of the results

masses()[source]
Returns:the masses of all atoms in the universe
Return type:ParticleScalar
numberOfDistanceConstraints()[source]
Returns:the number of distance constraints
Return type:int
objectList(klass=None)[source]
Parameters:
  • klass (class) – an optional class argument
Returns:

a list of all chemical objects in the universe. If klass is given, only objects that are instances of klass are returned.

Return type:

list

randomPoint()[source]
Returns:a random point from a uniform distribution within the universe. This operation is defined only for finite-volume universes, e.g. periodic universes.
Return type:Scientific.Geometry.Vector
realToBoxCoordinates(vector)[source]

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.

Parameters:
  • vector – a point in the universe
Returns:

the box coordinate equivalent of vector, or the original vector if no box coordinate system exists

Return type:

Scientific.Geometry.Vector

reciprocalBasisVectors()[source]
Returns:the reciprocal basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe
releaseConfigurationChangeLock()[source]

Releases the configuration change lock.

releaseReadStateLock(write=False)[source]

Release the universe read state lock.

releaseWriteStateLock(write=False)[source]

Release the universe write state lock.

removeDistanceConstraints()[source]

Removes all distance constraints.

removeObject(object)[source]

Removes object from the universe. If object is a Collection, each of its elements is removed. The object to be removed must be in the universe.

Parameters:
  • object – the object (chemical or environment) to be removed
scaleVelocitiesToTemperature(temperature, block=True)[source]

Scale all velocities by a common factor in order to obtain the specified temperature.

Parameters:
  • temperature (float) – the reference temperature
  • block (bool) – if True, the operation blocks other threads from accessing the configuration before the update is completed. If False, it is assumed that the caller takes care of locking.
selectBox(p1, p2)[source]
Parameters:
  • p1 (Scientific.Geometry.Vector) – one corner of a box in space
  • p2 (Scientific.Geometry.Vector) – the other corner of a box in space
Returns:

a Collection of all objects in the universe that lie within the box whose diagonally opposite corners are given by p1 and p2.

selectShell(point, r1, r2=0.0)[source]
Parameters:
  • point (Scientific.Geometry.Vector) – a point in space
  • r1 (float) – one of the radii of a spherical shell
  • r2 (float) – the other of the two radii of a spherical shell
Returns:

a Collection of all objects in the universe whose distance from point lies between r1 and r2.

setBondConstraints()[source]

Sets distance constraints for all bonds.

setConfiguration(configuration, block=True)[source]

Update the current configuration of the universe by copying the given input configuration.

Parameters:
  • configuration (Configuration) – the new configuration
  • block (bool) – if True, the operation blocks other threads from accessing the configuration before the update is completed. If False, it is assumed that the caller takes care of locking.
setForceField(forcefield)[source]
Parameters:
  • forcefield (ForceField) – the new forcefield for this universe
setFromTrajectory(trajectory, step=None)[source]

Set the state of the universe to the one stored in a trajectory. This operation is thread-safe; it blocks other threads that want to access the configuration or velocities while the data is being updated.

Parameters:
  • trajectory (Trajectory) – a trajectory object for this universe
  • step (int) – a step number, or None for the default step (0 for a standard trajectory, the last written step for a restart trajectory)
setVelocities(velocities, block=True)[source]

Update the current velocities of the universe by copying the given input velocities.

Parameters:
  • velocities (ParticleVector) – the new velocities, or None to remove the velocity definition from the universe
  • block (bool) – if True, the operation blocks other threads from accessing the configuration before the update is completed. If False, it is assumed that the caller takes care of locking.
universe()[source]
Returns:the universe itself
velocities()[source]
Returns:the current velocities of all atoms, or None if no velocities are defined. Note that this is not a copy of the current state but a reference to it; its data will change whenever any changes are made to the current velocities.
Return type:ParticleVector
MMTK.Universe.isUniverse(object)[source]
Parameters:
  • object – any Python object
Returns:

True if object is a universe.

MMTK.Visualization

Visualization of chemical objects, including animation

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.

A viewer for PDB files can be defined by the environment variable ‘PDBVIEWER’. 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.

A viewer for VRML files can be defined by the environment variable ‘VRMLVIEWER’. 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.

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 ‘PDBVIEWER’. This value must be the file name of the executable, and must give “vmd” or “xmol” after stripping off an optional directory specification.

class MMTK.Visualization.Viewable[source]

Bases: object

Any viewable chemical object

This is a mix-in class that defines a general visualization method for all viewable objects, i.e. chemical objects (atoms, molecules, etc.), collections, and universes.

graphicsObjects(**options)[source]
Parameters:
  • configuration (Configuration) – the configuration in which the objects are drawn (default: the current configuration)
  • model (str) – the graphical representation to be used (one of “wireframe”, “tube”, “ball_and_stick”, “vdw” and “vdw_and_stick”). The vdw models use balls with the radii taken from the atom objects. Default is “wireframe”.
  • ball_radius (float) – the radius of the balls representing the atoms in a ball_and_stick model, default: 0.03 This is also used in vdw and vdw_and_stick when an atom does not supply a radius.
  • stick_radius (float) – the radius of the sticks representing the bonds in a ball_and_stick, vdw_and_stick or tube model. Default: 0.02 for the tube model, 0.01 for the ball_and_stick and vdw_and_stick models
  • graphics_module (module) – the module in which the elementary graphics objects are defined (default: Scientific.Visualization.VRML)
  • color_values (ParticleScalar) – a color value for each atom which defines the color via the color scale object specified by the option color_scale. If no value is given, the atoms’ colors are taken from the attribute ‘color’ of each atom object (default values for each chemical element are provided in the chemical database).
  • color_scale (callable) – 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 color_values is specified as well. The default is a blue-to-red color scale that covers the range of the values given in color_values.
  • color – a color name predefined in the module Scientific.Visualization.Color. The corresponding color is applied to all graphics objects that are returned.
Returns:

a list of graphics objects that represent the object for which the method is called.

Return type:

list

MMTK.Visualization.definePDBViewer(progname, exec_path)[source]

Define the program used to view PDB files.

Parameters:
  • progname (str) – the canonical name of the PDB viewer. If it is a known one (one of “vmd”, “xmol”, “imol”), special features such as animation may be available.
  • exec_path (str) – the path to the executable program
MMTK.Visualization.defineVRMLiewer(progname, exec_path)[source]

Define the program used to view VRML files.

Parameters:
  • progname (str) – the canonical name of the VRML viewer
  • exec_path (str) – the path to the executable program
MMTK.Visualization.view(object, *parameters)[source]

Equivalent to object.view(parameters).

MMTK.Visualization.viewSequence(object, conf_list, periodic=False, label=None)[source]

Launches an animation using an external viewer.

Parameters:
  • object (GroupOfAtoms) – the object for which the animation is displayed.
  • conf_list (sequence) – a sequence of configurations that define the animation
  • periodic – if True, turn animation into a loop
  • label (str) – an optional text string that some interfaces use to pass a description of the object to the visualization system.
MMTK.Visualization.viewTrajectory(trajectory, first=0, last=None, skip=1, subset=None, label=None)[source]

Launches an animation based on a trajectory using an external viewer.

Parameters:
  • trajectory (Trajectory) – the trajectory
  • first (int) – the first trajectory step to be used
  • last (int) – the first trajectory step NOT to be used
  • skip (int) – the distance between two consecutive steps shown
  • subset (GroupOfAtoms) – the subset of the universe that is shown (default: the whole universe)
  • label (str) – an optional text string that some interfaces use to pass a description of the object to the visualization system.

MMTK.XML

XML format for describing molecular systems

Note: this format is not used by any other program at the moment. It should be considered experimental and subject to change.

class MMTK.XML.XMLMoleculeFactory(file)[source]

Bases: MMTK.MoleculeFactory.MoleculeFactory

XML molecule factory

An XML molecule factory reads an XML specification of a molecular system and builds the molecule objects and universe described therein. The universe can be obtained through the attribute universe.

Parameters:
  • file – the name of an XML file, or a file object