Module Reference — MMTK User Guide 2.7.7 documentation

### Navigation

- index
- modules |
- previous |
- MMTK User Guide 2.7.7 documentation »

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

  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

  `nextResidue`()

    :returns the next residue in the chain

  `precedingResidue`()

    :returns the preceding residue in the chain

class `MMTK.Biopolymers.` `ResidueChain`(molecule_spec, _memo=None, **properties)

  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`()

    Returns: | a collection containing all residues
    Return type: | `Collection`

  `residuesOfType`(*types)

    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`()

    Returns: | the residue sequence as a list of residue codes
    Return type: | list of str

`MMTK.Biopolymers.` `defineAminoAcidResidue`(full_name, code3, code1=None)

  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)

  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)

  Bases: `object`

  Chemical bond

  A bond links two atoms (attributes a1 and a2)

  `hasAtom`(a)

    Parameters: | a (`Atom`) – an atom
    Returns: | True if a participates in the bond

  `otherAtom`(a)

    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)

  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)

    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)

  Bases: `object`

  Bond angle list

  `dihedralAngles`()

    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)

  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)

  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)

  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)

  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)

  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.3, largest=0.5)

  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)

  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`()

    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.
    Return type: | Scientific.Geometry.Vector

  `position`(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.
    Return type: | Scientific.Geometry.Vector

  `setMass`(mass)

    Changes the mass of the atom.

    Parameters: | mass (float) – the mass

  `setPosition`(position)

    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)

  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)

  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)

  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`()

    Returns: | an iterator over all atoms in the object
    Return type: | iterator

  `atomList`()

    Returns: | a list containing all atoms in the object
    Return type: | list

  `bondedUnits`()

    Returns: | the largest subobjects which can contain bonds. There are no bonds between any of the subobjects in the list.
    Return type: | list

  `degreesOfFreedom`()

    Returns: | the number of degrees of freedom of the object
    Return type: | int

  `distanceConstraintList`()

    Returns: | the distance constraints of the object
    Return type: | list

  `fullName`()

    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)

    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`()

    Returns: | the number of distance constraints of the object
    Return type: | int

  `removeDistanceConstraints`(universe=None)

    Removes all distance constraints.

  `setBondConstraints`(universe=None)

    Sets distance constraints for all bonds.

  `setRigidBodyConstraints`(universe=None)

    Sets distance constraints that make the object fully rigid.

  `topLevelChemicalObject`()

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

  `universe`()

    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)

  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)

  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)

  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)

  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`()

    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)

  Returns: | True if object is a chemical object

## MMTK.Collections

Collections of chemical objects

class `MMTK.Collections.` `Collection`(*objects)

  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)

    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`()

    Returns: | a list containing all atoms of all objects in the collection
    Return type: | list

  `distanceConstraintList`()

    Returns: | the list of distance constraints
    Return type: | list

  `map`(function)

    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`()

    Returns: | the total number of atoms in the objects of the collection
    Return type: | int

  `numberOfDistanceConstraints`()

    Returns: | the number of distance constraints

  `objectList`(type=None)

    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)

    Remove all distance constraints

  `removeObject`(object)

    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)

    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)

    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)

    Set distance constraints for all bonds

  `universe`()

    Returns: | the universe of which all objects in the collection are part. If no such universe exists, the return value is None
    Return type: | `Universe`

class `MMTK.Collections.` `GroupOfAtoms`

  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)

    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)

    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)

    Apply a transformation to the object

    Parameters: | t (Scientific.Geometry.Transformation) – the transformation to be applied

  `atomCollection`()

    Returns: | a collection containing all atoms in the object

  `atomsWithDefinedPositions`(conf=None)

    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`()

    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)

    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)

    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)

    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)

    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`()

    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`()

    Returns: | the number of mechanical degrees of freedom
    Return type: | int

  `dipole`(reference=None)

    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)

    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)

    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)

    Parameters: | velocities (`ParticleVector`) – a set of velocities for all atoms, or None for the current velocities
    Returns: | the kinetic energy
    Return type: | float

  `mass`()

    Returns: | the total mass
    Return type: | float

  `momentum`(velocities=None)

    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)

    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`()

    Translate the center of mass to the coordinate origin

  `normalizingTransformation`(repr=None)

    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`()

    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`()

    Returns: | the number of atoms that are fixed, i.e. that cannot move
    Return type: | int

  `numberOfPoints`()

    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)

    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)

    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)

    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)

    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)

    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)

    Parameters: | velocities (`ParticleVector`) – a set of velocities for all atoms, or None for the current velocities
    Returns: | the temperature
    Return type: | float

  `translateBy`(vector)

    Translate the object by a displacement vector

    Parameters: | vector (Scientific.Geometry.Vector) – the displacement vector

  `translateTo`(position)

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

  `universe`()

    Returns: | the universe of which the object is part. For an object that is not part of a universe, the result is None
    Return type: | `Universe`

  `view`(configuration=None, format='pdb')

    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)

    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)

  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)

  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)

    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`()

    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.
    Return type: | list

`MMTK.Collections.` `isCollection`(object)

  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)

  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)

    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)

  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)

    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)

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

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

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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.7, cutoff=1.2, factor=46402.0, form='exponential')

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

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

  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)

  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`()

    Returns: | the values of the field at the positions of the atoms
    Return type: | `ParticleProperty`

  `view`(scale=1.0, length_scale=1.0, color=None)

    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, length_scale=1.0, color=None)

    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)

  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`()

    Returns: | the gradient of the field
    Return type: | `AtomicVectorField`

  `laplacian`()

    Returns: | the laplacian of the field
    Return type: | `AtomicScalarField`

class `MMTK.Field.` `AtomicVectorField`(system, grid_size, values)

  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`()

    Returns: | the curl of the field
    Return type: | `AtomicVectorField`

  `divergence`()

    Returns: | the divergence of the field
    Return type: | `AtomicScalarField`

  `laplacian`()

    Returns: | the laplacian of the field
    Return type: | `AtomicVectorField`

  `length`()

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

#### 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), or “screened”. 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), or “screened”. 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)

  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)

  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.7, cutoff=1.2, factor=46402.0)

  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.45, cutoff=0.6, factor=400.0)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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`(obj1, obj2, distance, force_constant, nb_exclusion=False)

  Bases: `MMTK.ForceFields.ForceField.ForceField`

  Harmonic distance restraint between two atoms

  Parameters: | obj1 (`GroupOfAtoms`) – the object defining center-of-mass 1 obj2 (`GroupOfAtoms`) – the object defining center-of-mass 2 distance (float) – the distance between cm 1 and cm2 at which the restraint is zero force_constant (float) – the force constant of the restraint term. The functional form of the restraint is force_constant*((cm1-cm2).length()-distance)**2, where cm1 and cm2 are the centrer-of-mass positions of the two objects. nb_exclussion (bool) – if True, non-bonded interactions between the restrained atoms are suppressed, as for a chemical bond

class `MMTK.ForceFields.Restraints.` `HarmonicTrapForceField`(obj, center, force_constant)

  Bases: `MMTK.ForceFields.ForceField.ForceField`

  Harmonic potential with respect to a fixed point in space

  Parameters: | obj (`GroupOfAtoms`) – the object on whose center of mass the force field acts center (Scientific.Geometry.Vector) – the point to which the atom is attached by the harmonic potential force_constant (float) – the force constant of the harmonic potential

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

  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)

  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)

  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 and operations

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)

  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)

  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)

  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)

  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)

  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)

  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)

  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`

  Bases: `object`

  3D shape object

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

  `enclosesPoint`(point)

    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)

    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)

    Parameters: | other – another 3D object
    Returns: | a 3D object that represents the intersection with other

  `volume`()

    Returns: | the volume of the object
    Return type: | float

class `MMTK.Geometry.` `Lattice`(function)

  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)

  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)

    Parameters: | point (Scientific.Geometry.Vector) – a point in space
    Returns: | the smallest distance of the point from the line
    Return type: | float

  `perpendicularVector`(plane)

    Parameters: | plane (Plane) – a plane
    Returns: | a vector in the plane perpendicular to the line
    Return type: | Scientific.Geometry.Vector

  `projectionOf`(point)

    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)

  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)

  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)

  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)

  Bases: `MMTK.Geometry.GeometricalObject3D`

  Sphere

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

`MMTK.Geometry.` `superpositionFit`(confs)

  Parameters: | confs (sequence of (float, Vector, Vector)) – the weight, reference position, and alternate position for each atom
  Returns: | the quaternion representing the rotation, the center of mass in the alternate configuraton, the center of mass in the reference configuration, and the RMS distance after the optimal superposition

## MMTK.InternalCoordinates

Manipulation of molecular configurations in terms of internal coordinates

class `MMTK.InternalCoordinates.` `BondAngle`(atom1, atom2, atom3)

  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)

    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)

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

class `MMTK.InternalCoordinates.` `BondLength`(atom1, atom2)

  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)

    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)

    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)

  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)

    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)

    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)

  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)

  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)

  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)

  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)

  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)

  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`

  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)

    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)

    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)

    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)

    Create a new (initially empty) group object.

  `retrieveMolecule`(group)

    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)

  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)

  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)

    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)

    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)

    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)

    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)

    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)

    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)

  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)

  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)

    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)

  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)

  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)

    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)

    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)

    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)

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

  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`()

    Returns: | the sugar and phosphate groups
    Return type: | `Group`

  `bases`()

    Returns: | the base group
    Return type: | `Group`

class `MMTK.NucleicAcids.` `NucleotideChain`(sequence, **properties)

  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`()

    Returns: | the sugar and phosphate groups of all nucleotides
    Return type: | `Collection`

  `bases`()

    Returns: | the base groups of all nucleotides
    Return type: | `Collection`

class `MMTK.NucleicAcids.` `NucleotideSubChain`(chain, groups, name='')

  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)

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

  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)

    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)

    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)

    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()`.
    Return type: | `Collection`

  `createMolecules`(names=None, permit_undefined=True)

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

    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.
    Return type: | list

  `createPeptideChains`(model='all')

    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.
    Return type: | list

  `createUnitCellUniverse`()

    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)

  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)

    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)

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

    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)

  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`()

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

  `nextModel`()

    Start a new model

  `write`(object, configuration=None, tag=None)

    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)

  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)

    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)

  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`()

    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`()

    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)

    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`()

    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)

  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)

  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)

    Copy all values from another compatible ParticleProperty object.

    Parameters: | other – the data source

  `return_class`

    alias of `ParticleProperty`

  `scaleBy`(factor)

    Multiply all values by a factor

    Parameters: | factor (float) – the scale factor

  `selectAtoms`(condition)

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

    Parameters: | condition (callable) – a test function

  `sumOverParticles`()

    Returns: | the sum of the values for all particles.
    Return type: | element type

  `zero`()

    Returns: | an object of the element type (scalar, vector, etc.) with the value 0.
    Return type: | element type

class `MMTK.ParticleProperties.` `ParticleScalar`(universe, data_array=None)

  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)

    Parameters: | function – a function that is applied to each data value
    Returns: | a new ParticleScalar object containing the function results

  `maximum`()

    Returns: | the highest value in the data array particle
    Return type: | float

  `minimum`()

    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)

  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)

  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)

    Parameters: | other (`ParticleVector`) – another ParticleVector
    Returns: | the dot product with other, treating both operands as 3N-dimensional vectors.

  `dyadicProduct`(other)

    Parameters: | other (`ParticleVector`) – another ParticleVector
    Returns: | the dyadic product with other
    Return type: | `ParticleTensor`

  `length`()

    Returns: | the length (norm) of the vector for each particle
    Return type: | `ParticleScalar`

  `massWeightedDotProduct`(other)

    Parameters: | other (`ParticleVector`) – another ParticleVector
    Returns: | the mass-weighted dot product with other treating both operands as 3N-dimensional vectors
    Return type: | float

  `massWeightedNorm`()

    Returns: | the mass-weighted norm of the ParticleVector seen as a 3N-dimensional vector
    Return type: | float

  `norm`()

    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)

  Parameters: | object – any object
  Returns: | True if object is a `Configuration`
  Return type: | bool

`MMTK.ParticleProperties.` `isParticleProperty`(object)

  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)

  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)

  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)

  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`()

    Returns: | the peptide groups of all residues
    Return type: | `Collection`

  `phiPsi`(conf=None)

    Returns: | a list of the (phi, psi) backbone angles for each residue
    Return type: | list of tuple of float

  `replaceResidue`(r_old, r_new)

    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`()

    Returns: | the primary sequence as a list of three-letter residue codes.
    Return type: | list

  `sidechains`()

    Returns: | the sidechain groups of all residues
    Return type: | `Collection`

class `MMTK.Proteins.` `Protein`(*items, **properties)

  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`()

    Returns: | the peptide groups of all residues in all chains
    Return type: | `Collection`

  `phiPsi`(conf=None)

    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`()

    Returns: | all residues in all chains
    Return type: | `Collection`

  `residuesOfType`(*types)

    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`()

    Returns: | the sidechain groups of all residues in all chains
    Return type: | `Collection`

class `MMTK.Proteins.` `Residue`(name=None, model='all')

  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`()

    Returns: | the peptide group
    Return type: | `Group`

  `chiAngle`()

    Returns: | an object representing the chi angle and allowing to modify it
    Return type: | MMTK.InternalCoordinates.DihedralAngle

  `phiAngle`()

    Returns: | an object representing the phi angle and allowing to modify it
    Return type: | MMTK.InternalCoordinates.DihedralAngle

  `phiPsi`(conf=None)

    Returns: | the values of the backbone dihedral angles phi and psi.
    Return type: | tuple (float, float)

  `psiAngle`()

    Returns: | an object representing the psi angle and allowing to modify it
    Return type: | MMTK.InternalCoordinates.DihedralAngle

  `sidechains`()

    Returns: | the sidechain group
    Return type: | `Group`

class `MMTK.Proteins.` `SubChain`(chain=None, groups=None, name='')

  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)

  Parameters: | x – any object
  Returns: | True if x is a peptide chain
  Return type: | bool

`MMTK.Proteins.` `isProtein`(x)

  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`()

  Returns: | a vector drawn from a uniform distribution on the surface of a unit sphere.
  Return type: | Scientific.Geometry.Vector

`MMTK.Random.` `randomDirections`(n)

  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)

  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)

  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)

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

  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)

  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)

  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)

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

  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)

  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)

  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)

  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)

  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`()

    Returns: | the orthogonal complement subspace
    Return type: | `Subspace`

  `getBasis`()

    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)

    Parameters: | vector (`ParticleVector`) – a particle vector
    Returns: | the projection of the vector onto the orthogonal complement of the subspace.

  `projectionOf`(vector)

    Parameters: | vector (`ParticleVector`) – a particle vector
    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)

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

  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)

    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)

  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)

  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)

  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)

  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)

  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)

  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)

  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`()

    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`()

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

    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)

    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`()

    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)

    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)

  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)

  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)

  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)

  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)

  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)

  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)

  Parameters: | object – any Python object
  Returns: | True if object is a trajectory

`MMTK.Trajectory.` `trajectoryInfo`(filename)

  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)

  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)

    Set the edge length to a given value.

    Parameters: | size (float) – the new size

class `MMTK.Universe.` `InfiniteUniverse`(forcefield=None, **properties)

  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)

  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)

    Multiplies all edge lengths by a factor.

    Parameters: | factor (float) – the scale factor

class `MMTK.Universe.` `ParallelepipedicPeriodicUniverse`(shape=None, forcefield=None, **properties)

  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)

    Multiplies all edge lengths by a factor.

    Parameters: | factor (float) – the scale factor

class `MMTK.Universe.` `Universe`(forcefield, properties)

  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)

    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`()

    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`()

    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)

    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)

    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)

    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)

    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`()

    Returns: | a list of all atoms in the universe
    Return type: | list

  `basisVectors`()

    Returns: | the basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe
    Return type: | NoneType or list

  `boxToRealCoordinates`(vector)

    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)

    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`()

    Returns: | the volume of the elementary cell of a periodic universe, None for a non-periodic universe
    Return type: | NoneType or float

  `charges`()

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

    Returns: | the charges of all atoms in the universe
    Return type: | `ParticleScalar`

  `configuration`()

    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)

    Parameters: | conf1 (`Configuration`) – a configuration conf2 (`Configuration`) – a configuration
    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)

    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)

    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`()

    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)

    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)

    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`()

    Returns: | the list of distance constraints
    Return type: | list

  `distanceVector`(p1, p2, conf=None)

    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)

    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)

    Returns: | the energy and the force constants
    Return type: | (float, `SymmetricPairTensor`)

  `energyAndGradients`(subset1=None, subset2=None, small_change=False)

    Returns: | the energy and the energy gradients
    Return type: | (float, `ParticleVector`)

  `energyGradientsAndForceConstants`(subset1=None, subset2=None, small_change=False)

    Returns: | the energy, its gradients, and the force constants
    Return type: | (float, `ParticleVector`, `SymmetricPairTensor`)

  `energyTerms`(subset1=None, subset2=None, small_change=False)

    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)

    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)

    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`()

    Returns: | the force field
    Return type: | `ForceField`

  `fractionalToCartesian`(array)

    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)

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

    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)

    Generate random velocities for all atoms from a Boltzmann distribution.

    Parameters: | temperature (float) – the reference temperature for the Boltzmann distribution

  `largestDistance`()

    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.
    Return type: | NoneType or float

  `map`(function)

    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`()

    Returns: | the masses of all atoms in the universe
    Return type: | `ParticleScalar`

  `numberOfDistanceConstraints`()

    Returns: | the number of distance constraints
    Return type: | int

  `objectList`(klass=None)

    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`()

    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)

    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`()

    Returns: | the reciprocal basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe
    Return type: | NoneType or list

  `releaseConfigurationChangeLock`()

    Releases the configuration change lock.

  `releaseReadStateLock`(write=False)

    Release the universe read state lock.

  `releaseWriteStateLock`(write=False)

    Release the universe write state lock.

  `removeDistanceConstraints`()

    Removes all distance constraints.

  `removeObject`(object)

    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)

    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)

    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)

    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`()

    Sets distance constraints for all bonds.

  `setConfiguration`(configuration, block=True)

    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)

    Parameters: | forcefield (`ForceField`) – the new forcefield for this universe

  `setFromTrajectory`(trajectory, step=None)

    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)

    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`()

    Returns: | the universe itself

  `velocities`()

    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)

  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`

  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)

    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)

  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)

  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)

  Equivalent to object.view(parameters).

`MMTK.Visualization.` `viewSequence`(object, conf_list, periodic=False, label=None)

  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)

  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)

  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

### Navigation

- index
- modules |
- previous |
- MMTK User Guide 2.7.7 documentation »