Source code for MMTK.Universe

# This module implements the various types of universes
# (infinite, periodic etc.). A universe defines the
# geometry of space, the force field, and external interactions
# (boundary conditions, external fields, etc.)
#
# Written by Konrad Hinsen
#

"""
Universes
"""

__docformat__ = 'restructuredtext'

from MMTK import Bonds, ChemicalObjects, Collections, Environment, \
                 Random, Utility, ParticleProperties, Visualization
from Scientific.Geometry import Transformation
from Scientific.Geometry import Vector, isVector
from Scientific import N
import copy

try:
    import threading
    if not hasattr(threading, 'Thread'):
        threading = None
except ImportError:
    threading = None

#
# The base class for all universes.
#
[docs]class Universe(Collections.GroupOfAtoms, 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 """ def __init__(self, forcefield, properties): self._forcefield = forcefield self._evaluator = {} self.name = '' if properties.has_key('name'): self.name = properties['name'] del properties['name'] self._objects = Collections.Collection() self._environment = [] self._configuration = None self._masses = None self._atom_properties = {} self._atoms = None self._bond_database = None self._bond_pairs = None self._version = 0 self._np = None is_universe = True is_periodic = False is_orthogonal = False def __getstate__(self): state = copy.copy(self.__dict__) state['_evaluator'] = {} state['_configuration'] = None del state['_masses'] del state['_bond_database'] del state['_bond_pairs'] del state['_np'] del state['_spec'] return state def __setstate__(self, state): state['_np'] = None state['_atoms'] = None state['_bond_database'] = None state['_bond_pairs'] = None self.__dict__['_environment'] = [] if state.has_key('atom_properties'): self.__dict__['_atom_properties'] = state['atom_properties'] del state['atom_properties'] for attr, value in state.items(): self.__dict__[attr] = value self._evaluator = {} self._masses = None self._createSpec() def __len__(self): return len(self._objects) def __getitem__(self, item): return self._objects[item] def __setattr__(self, attr, value): if attr[0] != '_' and self.__dict__.has_key(attr): try: self.removeObject(self.__dict__[attr]) except ValueError: pass self.__dict__[attr] = value if attr[0] != '_' and (ChemicalObjects.isChemicalObject(value) or Environment.isEnvironmentObject(value)): self.addObject(value) def __delattr__(self, attr): try: self.removeObject(self.__dict__[attr]) except ValueError: pass del self.__dict__[attr] def __repr__(self): return self.__class__.__name__ + ' ' + self.name + ' containing ' + \ `len(self._objects)` + ' objects.' __str__ = __repr__ def __copy__(self): return copy.deepcopy(self)
[docs] def objectList(self, klass = None): """ :param klass: an optional class argument :type klass: class :returns: a list of all chemical objects in the universe. If klass is given, only objects that are instances of klass are returned. :rtype: list """ return self._objects.objectList(klass)
[docs] def environmentObjectList(self, klass = None): """ :param klass: an optional class argument :type klass: class :returns: a list of all environment objects in the universe. If klass is given, only objects that are instances of klass are returned. :rtype: list """ if klass is None: return self._environment else: return filter(lambda o, k=klass: o.__class__ is k, self._environment)
[docs] def atomList(self): """ :returns: a list of all atoms in the universe :rtype: list """ if self._atoms is None: self._atoms = self._objects.atomList() return self._atoms
def atomIterator(self): return self._objects.atomIterator() def bondedUnits(self): return self._objects.bondedUnits()
[docs] def universe(self): """ :returns: the universe itself """ return self
[docs] def addObject(self, object, steal = False): """ Adds object to the universe. If object is a Collection, all elements of the Collection are added to the universe. :param object: the object (chemical or environment) to be added :param steal: if True, permit stealing the object from another universe, otherwise the object must not yet be attached to any universe. :type steal: bool """ if ChemicalObjects.isChemicalObject(object): if (not steal) and object.parent is not None: if isUniverse(object.parent): raise ValueError(`object` + ' is already in another universe') else: raise ValueError(`object` + ' is part of another object') object.parent = self self._objects.addObject(object) self._changed(True) elif Environment.isEnvironmentObject(object): for o in self._environment: o.checkCompatibilityWith(object) self._environment.append(object) self._changed(False) elif Collections.isCollection(object) \ or Utility.isSequenceObject(object): for o in object: self.addObject(o, steal) else: raise TypeError(repr(object) + ' cannot be added to a universe')
[docs] def removeObject(self, 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. :param object: the object (chemical or environment) to be removed """ if ChemicalObjects.isChemicalObject(object): if object.parent != self: raise ValueError(`object` + ' is not in this universe.') object.parent = None self._objects.removeObject(object) self._changed(True) elif Collections.isCollection(object) \ or Utility.isSequenceObject(object): for o in object: self.removeObject(o) elif Environment.isEnvironmentObject(object): self._environment.remove(object) self._changed(False) else: raise ValueError(`object` + ' is not in this universe.')
[docs] def selectShell(self, point, r1, r2=0.): """ :param point: a point in space :type point: Scientific.Geometry.Vector :param r1: one of the radii of a spherical shell :type r1: float :param r2: the other of the two radii of a spherical shell :type r2: float :returns: a Collection of all objects in the universe whose distance from point lies between r1 and r2. """ return self._objects.selectShell(point, r1, r2)
[docs] def selectBox(self, p1, p2): """ :param p1: one corner of a box in space :type p1: Scientific.Geometry.Vector :param p2: the other corner of a box in space :type p2: Scientific.Geometry.Vector :returns: a Collection of all objects in the universe that lie within the box whose diagonally opposite corners are given by p1 and p2. """ return self._objects.selectBox(p1, p2)
def _changed(self, system_size_changed): self._evaluator = {} self._bond_database = None self._version += 1 if system_size_changed: for a in self.atomList(): a.unsetArray() self._configuration = None self._masses = None self._atom_properties = {} self._atoms = None self._np = None self._bond_pairs = None else: if self._configuration is not None: self._configuration.version = self._version if self._masses is not None: self._masses.version = self._version
[docs] def acquireReadStateLock(self): """ 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. """ return self._spec.stateLock(1)
[docs] def acquireWriteStateLock(self): """ 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. """ return self._spec.stateLock(-1)
[docs] def releaseReadStateLock(self, write=False): """ Release the universe read state lock. """ return self._spec.stateLock(2)
[docs] def releaseWriteStateLock(self, write=False): """ Release the universe write state lock. """ return self._spec.stateLock(-2)
[docs] def acquireConfigurationChangeLock(self, 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. :param waitflag: 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. :type waitflag: bool :returns: a flag indicating if the lock was successfully acquired (1) or not (0). :rtype: int """ if waitflag: return self._spec.configurationChangeLock(1) else: return self._spec.configurationChangeLock(0)
[docs] def releaseConfigurationChangeLock(self): """ Releases the configuration change lock. """ self._spec.configurationChangeLock(2)
[docs] def setForceField(self, forcefield): """ :param forcefield: the new forcefield for this universe :type forcefield: :class:`~MMTK.ForceFields.ForceField.ForceField` """ self._forcefield = forcefield self._evaluator = {} self._bond_database = None
def position(self, object, conf): if ChemicalObjects.isChemicalObject(object): return object.position(conf) elif isVector(object): return object else: return Vector(object) def numberOfAtoms(self): return self._objects.numberOfAtoms() def numberOfPoints(self): if self._np is None: self._np = Collections.GroupOfAtoms.numberOfPoints(self) return self._np numberOfCartesianCoordinates = numberOfPoints
[docs] def configuration(self): """ :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. :rtype: :class:`~MMTK.ParticleProperties.Configuration` """ if self._configuration is None: np = self.numberOfAtoms() coordinates = N.zeros((np, 3), N.Float) index_map = {} redef = [] for a in self.atomList(): if a.index is None or a.index >= np: redef.append(a) else: if index_map.get(a.index, None) is None: index_map[a.index] = a else: redef.append(a) free_indices = [i for i in xrange(np) if index_map.get(i, None) is None] assert len(free_indices) == len(redef) for a, i in zip(redef, free_indices): a.index = i # At this point a.index runs from 0 to np-1 in the universe. for a in self.atomList(): if a.array is None: try: coordinates[a.index, :] = a.pos.array del a.pos except AttributeError: coordinates[a.index, :] = Utility.undefined else: coordinates[a.index, :] = a.array[a.index, :] a.array = coordinates # Define configuration object. self._configuration = 1 # a hack to prevent endless recursion self._configuration = \ ParticleProperties.Configuration(self, coordinates) return self._configuration
[docs] def copyConfiguration(self): """ 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 :rtype: :class:`~MMTK.ParticleProperties.Configuration` """ self.acquireReadStateLock() try: conf = copy.copy(self.configuration()) finally: self.releaseReadStateLock() return conf
def atomNames(self): self.configuration() names = self.numberOfAtoms()*[None] for a in self.atomList(): names[a.index] = a.fullName() return names
[docs] def setConfiguration(self, configuration, block=True): """ Update the current configuration of the universe by copying the given input configuration. :param configuration: the new configuration :type configuration: :class:`~MMTK.ParticleProperties.Configuration` :param block: 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. :type block: bool """ if not ParticleProperties.isConfiguration(configuration): raise TypeError('not a universe configuration') conf = self.configuration() if block: self.acquireWriteStateLock() try: conf.assign(configuration) self.setCellParameters(configuration.cell_parameters) finally: if block: self.releaseWriteStateLock()
[docs] def addToConfiguration(self, displacement, block=True): """ Update the current configuration of the universe by adding the given displacement vector. :param displacement: the displacement vector for each atom :type displacement: :class:`~MMTK.ParticleProperties.ParticleVector` :param block: 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. :type block: bool """ conf = self.configuration() if block: self.acquireWriteStateLock() try: conf.assign(conf+displacement) finally: if block: self.releaseWriteStateLock()
[docs] def getParticleScalar(self, name, datatype = N.Float): """ :param name: the name of an atom attribute :type name: str :param datatype: the datatype of the array allocated to hold the data :returns: the values of the attribute 'name' for each atom in the universe. :rtype: :class:`~MMTK.ParticleProperties.ParticleScalar` """ conf = self.configuration() array = N.zeros((len(conf),), datatype) for a in self.atomList(): array[a.index] = getattr(a, name) return ParticleProperties.ParticleScalar(self, array)
getAtomScalarArray = getParticleScalar
[docs] def getParticleBoolean(self, name): """ :param name: the name of an atom attribute :type name: str :returns: the values of the boolean attribute 'name' for each atom in the universe, or False for atoms that do not have the attribute. :rtype: :class:`~MMTK.ParticleProperties.ParticleScalar` """ conf = self.configuration() array = N.zeros((len(conf),), N.Int) for a in self.atomList(): try: array[a.index] = getattr(a, name) except AttributeError: pass return ParticleProperties.ParticleScalar(self, array)
getAtomBooleanArray = getParticleBoolean
[docs] def masses(self): """ :returns: the masses of all atoms in the universe :rtype: :class:`~MMTK.ParticleProperties.ParticleScalar` """ if self._masses is None: self._masses = self.getParticleScalar('_mass') return self._masses
[docs] def charges(self): """ Return the atomic charges defined by the universe's force field. :returns: the charges of all atoms in the universe :rtype: :class:`~MMTK.ParticleProperties.ParticleScalar` """ ff = self._forcefield if ff is None: raise ValueError("no force field defined") return ff.charges(self)
[docs] def velocities(self): """ :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. :rtype: :class:`~MMTK.ParticleProperties.ParticleVector` """ try: return self._atom_properties['velocity'] except KeyError: return None
[docs] def setVelocities(self, velocities, block=True): """ Update the current velocities of the universe by copying the given input velocities. :param velocities: the new velocities, or None to remove the velocity definition from the universe :type velocities: :class:`~MMTK.ParticleProperties.ParticleVector` :param block: 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. :type block: bool """ if velocities is None: try: del self._atom_properties['velocity'] except KeyError: pass else: try: v = self._atom_properties['velocity'] except KeyError: v = ParticleProperties.ParticleVector(self) self._atom_properties['velocity'] = v if block: self.acquireWriteStateLock() try: v.assign(velocities) finally: if block: self.releaseWriteStateLock()
[docs] def initializeVelocitiesToTemperature(self, temperature): """ Generate random velocities for all atoms from a Boltzmann distribution. :param temperature: the reference temperature for the Boltzmann distribution :type temperature: float """ self.configuration() masses = self.masses() if self._atom_properties.has_key('velocity'): del self._atom_properties['velocity'] fixed = self.getParticleBoolean('fixed') np = self.numberOfPoints() velocities = N.zeros((np, 3), N.Float) for i in xrange(np): m = masses[i] if m > 0. and not fixed[i]: velocities[i] = Random.randomVelocity(temperature, m).array self._atom_properties['velocity'] = \ ParticleProperties.ParticleVector(self, velocities) self.adjustVelocitiesToConstraints()
[docs] def scaleVelocitiesToTemperature(self, temperature, block=True): """ Scale all velocities by a common factor in order to obtain the specified temperature. :param temperature: the reference temperature :type temperature: float :param block: 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. :type block: bool """ velocities = self.velocities() factor = N.sqrt(temperature/self.temperature()) if block: self.acquireWriteStateLock() try: velocities.scaleBy(factor) finally: if block: self.releaseWriteStateLock()
def degreesOfFreedom(self): return GroupOfAtoms.degreesOfFreedom(self) \ - self.numberOfDistanceConstraints()
[docs] def distanceConstraintList(self): """ :returns: the list of distance constraints :rtype: list """ return self._objects.distanceConstraintList()
[docs] def numberOfDistanceConstraints(self): """ :returns: the number of distance constraints :rtype: int """ return self._objects.numberOfDistanceConstraints()
[docs] def setBondConstraints(self): """ Sets distance constraints for all bonds. """ self.configuration() self._objects.setBondConstraints(self) self.enforceConstraints()
[docs] def removeDistanceConstraints(self): """ Removes all distance constraints. """ self._objects.removeDistanceConstraints(self)
[docs] def enforceConstraints(self, configuration=None, velocities=None): """ Enforces the previously defined distance constraints by modifying the configuration and velocities. :param configuration: the configuration in which the constraints are enforced (None for current configuration) :type configuration: :class:`~MMTK.ParticleProperties.Configuration` :param velocities: the velocities in which the constraints are enforced (None for current velocities) :type velocities: :class:`~MMTK.ParticleProperties.ParticleVector` """ from MMTK import Dynamics Dynamics.enforceConstraints(self, configuration) self.adjustVelocitiesToConstraints(velocities)
[docs] def adjustVelocitiesToConstraints(self, 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. :param velocities: the velocities in which the constraints are enforced (None for current velocities) :type velocities: :class:`~MMTK.ParticleProperties.ParticleVector` :param block: 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. :type block: bool """ from MMTK import Dynamics if velocities is None: velocities = self.velocities() if velocities is not None: if block: self.acquireWriteStateLock() try: Dynamics.projectVelocities(self, velocities) finally: if block: self.releaseWriteStateLock()
def bondLengthDatabase(self): if self._bond_database is None: self._bond_database = None if self._bond_database is None: ff = self._forcefield try: self._bond_database = ff.bondLengthDatabase(self) except AttributeError: pass if self._bond_database is None: self._bond_database = Bonds.DummyBondLengthDatabase(self) return self._bond_database
[docs] def forcefield(self): """ :returns: the force field :rtype: :class:`~MMTK.ForceFields.ForceField.ForceField` """ return self._forcefield
def energyEvaluatorParameters(self, subset1 = None, subset2 = None): self.configuration() from MMTK.ForceFields import ForceField ffdata = ForceField.ForceFieldData() return self._forcefield.evaluatorParameters(self, subset1, subset2, ffdata) def energyEvaluator(self, subset1 = None, subset2 = None, threads=None, mpi_communicator=None): if self._forcefield is None: raise ValueError("no force field defined") try: eval = self._evaluator[(subset1, subset2, threads)] except KeyError: from MMTK.ForceFields import ForceField eval = ForceField.EnergyEvaluator(self, self._forcefield, subset1, subset2, threads, mpi_communicator) self._evaluator[(subset1, subset2, threads)] = eval return eval
[docs] def energy(self, subset1 = None, subset2 = None, small_change=False): """ :param subset1: a subset of a universe, or None :type subset1: :class:`~MMTK.ChemicalObjects.ChemicalObject` :param subset2: a subset of a universe, or None :type subset2: :class:`~MMTK.ChemicalObjects.ChemicalObject` :param small_change: if True, algorithms optimized for small configurational changes relative to the last evaluation may be used. :type small_change: bool :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. :rtype: float """ eval = self.energyEvaluator(subset1, subset2) return eval(0, 0, small_change)
[docs] def energyAndGradients(self, subset1 = None, subset2 = None, small_change=False): """ :returns: the energy and the energy gradients :rtype: (float, :class:`~MMTK.ParticleProperties.ParticleVector`) """ eval = self.energyEvaluator(subset1, subset2) return eval(1, 0, small_change)
[docs] def energyAndForceConstants(self, subset1 = None, subset2 = None, small_change=False): """ :returns: the energy and the force constants :rtype: (float, :class:`~MMTK.ParticleProperties.SymmetricPairTensor`) """ eval = self.energyEvaluator(subset1, subset2) e, g, fc = eval(0, 1, small_change) return e, fc
[docs] def energyGradientsAndForceConstants(self, subset1 = None, subset2 = None, small_change=False): """ :returns: the energy, its gradients, and the force constants :rtype: (float, :class:`~MMTK.ParticleProperties.ParticleVector`, :class:`~MMTK.ParticleProperties.SymmetricPairTensor`) """ eval = self.energyEvaluator(subset1, subset2) return eval(1, 1, small_change)
[docs] def energyTerms(self, 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. :rtype: dict """ eval = self.energyEvaluator(subset1, subset2) eval(0, 0, small_change) return eval.lastEnergyTerms()
[docs] def configurationDifference(self, conf1, conf2): """ :param conf1: a configuration :type conf1: :class:`~MMTK.ParticleProperties.Configuration` :param conf2: a configuration :type conf2: :class:`~MMTK.ParticleProperties.Configuration` :returns: the difference vector between the two configurations for each atom, taking into account the universe topology (e.g. minimum-image convention). :rtype: :class:`~MMTK.ParticleProperties.ParticleVector` """ d = conf2-conf1 cell = conf1.cell_parameters if cell is not None: self._spec.foldCoordinatesIntoBox(d.array) return d
[docs] def distanceVector(self, p1, p2, conf=None): """ :param p1: a vector or a chemical object whose position is taken :param p2: a vector or a chemical object whose position is taken :param 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. """ p1 = self.position(p1, conf) p2 = self.position(p2, conf) if conf is None: return Vector(self._spec.distanceVector(p1.array, p2.array)) else: cell = self._fixCellParameters(conf.cell_parameters) if cell is None: return Vector(self._spec.distanceVector(p1.array, p2.array)) else: return Vector(self._spec.distanceVector(p1.array, p2.array, cell))
[docs] def distance(self, p1, p2, conf = None): """ :param p1: a vector or a chemical object whose position is taken :param p2: a vector or a chemical object whose position is taken :param conf: a configuration (None for the current configuration) :returns: the distance between p1 and p2, i.e. the length of the distance vector :rtype: float """ return self.distanceVector(p1, p2, conf).length()
[docs] def angle(self, p1, p2, p3, conf = None): """ :param p1: a vector or a chemical object whose position is taken :param p2: a vector or a chemical object whose position is taken :param p3: a vector or a chemical object whose position is taken :param conf: a configuration (None for the current configuration) :returns: the angle between the distance vectors p1-p2 and p3-p2 :rtype: float """ v1 = self.distanceVector(p2, p1, conf) v2 = self.distanceVector(p2, p3, conf) return v1.angle(v2)
[docs] def dihedral(self, p1, p2, p3, p4, conf = None): """ :param p1: a vector or a chemical object whose position is taken :param p2: a vector or a chemical object whose position is taken :param p3: a vector or a chemical object whose position is taken :param p4: a vector or a chemical object whose position is taken :param 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 :rtype: float """ v1 = self.distanceVector(p2, p1, conf) v2 = self.distanceVector(p3, p2, conf) v3 = self.distanceVector(p3, p4, conf) a = v1.cross(v2).normal() b = v3.cross(v2).normal() cos = a*b sin = b.cross(a)*v2/v2.length() return Transformation.angleFromSineAndCosine(sin, cos)
def _deleteAtom(self, atom): pass
[docs] def basisVectors(self): """ :returns: the basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe """ return None
[docs] def reciprocalBasisVectors(self): """ :returns: the reciprocal basis vectors of the elementary cell of a periodic universe, or None for a non-periodic universe """ return None
def cellParameters(self): return None def setCellParameters(self, parameters): if parameters is not None: raise ValueError('incompatible cell parameters') def _fixCellParameters(self, cell_parameters): return cell_parameters
[docs] def cellVolume(self): """ :returns: the volume of the elementary cell of a periodic universe, None for a non-periodic universe """ return None
[docs] def largestDistance(self): """ :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 None
[docs] def contiguousObjectOffset(self, objects = None, conf = None, box_coordinates = False): """ :param objects: a list of chemical objects, or None for all objects in the universe :type objects: list :param conf: a configuration (None for the current configuration) :param box_coordinates: use box coordinates rather than real ones :type box_coordinates: bool :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. :rtype: :class:`~MMTK.ParticleProperties.ParticleVector` """ return None
[docs] def contiguousObjectConfiguration(self, objects = None, conf = None): """ :param objects: a list of chemical objects, or None for all objects in the universe :type objects: list :param conf: a configuration (None for the current configuration) :returns: configuration conf (default: current configuration) corrected by the contiguous object offsets for that configuration. :rtype: :class:`~MMTK.ParticleProperties.Configuration` """ if conf is None: conf = self.configuration() offset = self.contiguousObjectOffset(objects, conf) if offset is not None: return conf + offset else: return copy.copy(conf)
[docs] def realToBoxCoordinates(self, 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. :param vector: a point in the universe :returns: the box coordinate equivalent of vector, or the original vector if no box coordinate system exists :rtype: Scientific.Geometry.Vector """ return vector
[docs] def boxToRealCoordinates(self, vector): """ :param vector: a point in the universe expressed in box coordinates :returns: the real-space equivalent of vector :rtype: Scientific.Geometry.Vector """ return vector
def _realToBoxPointArray(self, array, parameters=None): return array def _boxToRealPointArray(self, array, parameters=None): return array
[docs] def cartesianToFractional(self, vector): """ Fractional coordinates are defined only for periodic universes; their components have values between 0. and 1. :param vector: a point in the universe :type vector: Scientific.Geometry.Vector :returns: the fractional coordinate equivalent of vector :rtype: Scientific.N.array_type """ raise ValueError("Universe is not periodic")
def cartesianToFractionalMatrix(self): raise ValueError("Universe is not periodic")
[docs] def fractionalToCartesian(self, array): """ Fractional coordinates are defined only for periodic universes; their components have values between 0. and 1. :param array: an array of fractional coordinates :type array: Scientific.N.array_type :returns: the real-space equivalent of vector :rtype: Scientific.Geometry.Vector """ raise ValueError("Universe is not periodic")
def fractionalToCartesianMatrix(self): raise ValueError("Universe is not periodic") def foldCoordinatesIntoBox(self): return
[docs] def randomPoint(self): """ :returns: a random point from a uniform distribution within the universe. This operation is defined only for finite-volume universes, e.g. periodic universes. :rtype: Scientific.Geometry.Vector """ raise TypeError("undefined operation")
[docs] def map(self, 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. :param function: the function to be applied :type function: callable :returns: the list or collection of the results """ return self._objects.map(function)
def description(self, objects = None, index_map = None): if objects is None: objects = self attributes = {} for attr in dir(self): if attr[0] != '_': object = getattr(self, attr) if ChemicalObjects.isChemicalObject(object) \ or Environment.isEnvironmentObject(object): attributes[object] = attr items = [] for o in objects.objectList(): attr = attributes.get(o, None) if attr is not None: items.append(repr(attr)) items.append(o.description(index_map)) for o in self._environment: attr = attributes.get(o, None) if attr is not None: items.append(repr(attr)) items.append(o.description()) try: classname = self.classname_for_trajectories except AttributeError: classname = self.__class__.__name__ s = 'c(%s,[%s])' % \ (`classname + self._descriptionArguments()`, ','.join(items)) return s def _graphics(self, conf, distance_fn, model, module, options): return self._objects._graphics(conf, distance_fn, model, module, options)
[docs] def setFromTrajectory(self, 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. :param trajectory: a trajectory object for this universe :type trajectory: :class:`~MMTK.Trajectory.Trajectory` :param step: a step number, or None for the default step (0 for a standard trajectory, the last written step for a restart trajectory) :type step: int """ if step is None: step = trajectory.defaultStep() self.acquireWriteStateLock() try: self.setConfiguration(trajectory.configuration[step], False) vel = self.velocities() try: vel_tr = trajectory.velocities[step] except AttributeError: if vel is not None: Utility.warning("velocities were not modified because " + "the trajectory does not contain " + "velocity data.") return if vel is None: self._atom_properties['velocity'] = vel_tr else: vel.assign(vel_tr) finally: self.releaseWriteStateLock() # # More efficient reimplementations of methods in Collections.GroupOfAtoms #
def numberOfFixedAtoms(self): return self.getParticleBoolean('fixed').sumOverParticles() def degreesOfFreedom(self): return 3*(self.numberOfAtoms()-self.numberOfFixedAtoms()) \ - self.numberOfDistanceConstraints() def mass(self): return self.masses().sumOverParticles() def centerOfMass(self, conf = None): m = self.masses() if conf is None: conf = self.configuration() return (m*conf).sumOverParticles()/m.sumOverParticles() def kineticEnergy(self, velocities = None): if velocities is None: velocities = self.velocities() return 0.5*velocities.massWeightedDotProduct(velocities) def momentum(self, velocities = None): if velocities is None: velocities = self.velocities() return (self.masses()*velocities).sumOverParticles() def translateBy(self, vector): conf = self.configuration().array N.add(conf, vector.array[N.NewAxis, :], conf) def applyTransformation(self, t): conf = self.configuration().array rot = t.rotation().tensor.array conf[:] = N.dot(conf, N.transpose(rot)) N.add(conf, t.translation().vector.array[N.NewAxis, :], conf) def writeXML(self, file): file.write('<?xml version="1.0" encoding="ISO-8859-1" ' + 'standalone="yes"?>\n\n') file.write('<molecularsystem>\n\n') file.write('<templates>\n\n') memo = {'counter': 1} instances = [] atoms = [] for object in self._objects.objectList(): instances = instances + object.writeXML(file, memo, 1) atoms = atoms + object.getXMLAtomOrder() file.write('\n</templates>\n\n') file.write('<universe %s>\n' % self.XMLSpec()) for instance in instances: file.write(' ') file.write(instance) file.write('\n') conf = self.configuration() if conf.hasValidPositions(): file.write(' <configuration>\n') file.write(' <atomArray units="units:nm"\n') file.write(' x3="') for atom in atoms: file.write(str(conf[atom][0])) file.write(' ') file.write('"\n') file.write(' y3="') for atom in atoms: file.write(str(conf[atom][1])) file.write(' ') file.write('"\n') file.write(' z3="') for atom in atoms: file.write(str(conf[atom][2])) file.write(' ') file.write('"\n') file.write(' />\n') file.write(' </configuration>\n') file.write('</universe>\n\n') file.write('</molecularsystem>\n') # # Infinite universes #
[docs]class InfiniteUniverse(Universe): """ Infinite (unbounded and nonperiodic) universe. """ def __init__(self, forcefield=None, **properties): """ :param forcefield: a force field, or None for no force field :type forcefield: :class:`~MMTK.ForceFields.ForceField.ForceField` """ Universe.__init__(self, forcefield, properties) self._createSpec() def CdistanceFunction(self): from MMTK_universe import infinite_universe_distance_function return infinite_universe_distance_function, N.array([0.]) def CcorrectionFunction(self): from MMTK_universe import infinite_universe_correction_function return infinite_universe_correction_function, N.array([0.]) def CvolumeFunction(self): from MMTK_universe import infinite_universe_volume_function return infinite_universe_volume_function, N.array([0.]) def CboxTransformationFunction(self): return None, N.array([0.]) def _createSpec(self): from MMTK_universe import InfiniteUniverseSpec self._spec = InfiniteUniverseSpec() def _descriptionArguments(self): if self._forcefield is None: return '()' else: return '(%s)' % self._forcefield.description() def XMLSpec(self): return 'topology="infinite"' # # 3D periodic universe base class #
class Periodic3DUniverse(Universe): is_periodic = True def setVolume(self, volume): """ Multiplies all edge lengths by the same factor such that the cell volume becomes equal to the specified value. :param volume: the desired volume :type volume: float """ factor = (volume/self.cellVolume())**(1./3.) self.scaleSize(factor) def foldCoordinatesIntoBox(self): self._spec.foldCoordinatesIntoBox(self.configuration().array) def basisVectors(self): return [self.boxToRealCoordinates(Vector(1., 0., 0.)), self.boxToRealCoordinates(Vector(0., 1., 0.)), self.boxToRealCoordinates(Vector(0., 0., 1.))] def cartesianToFractional(self, vector): r1, r2, r3 = self.reciprocalBasisVectors() return N.array([r1*vector, r2*vector, r3*vector]) def cartesianToFractionalMatrix(self): return N.array(self.reciprocalBasisVectors()) def fractionalToCartesian(self, array): e1, e2, e3 = self.basisVectors() return array[0]*e1 + array[1]*e2 + array[2]*e3 def fractionalToCartesianMatrix(self): return N.transpose(self.basisVectors()) def randomPoint(self): return self.boxToRealCoordinates(Random.randomPointInBox(1., 1., 1.)) def contiguousObjectOffset(self, objects = None, conf = None, box_coordinates = 0): from MMTK_universe import contiguous_object_offset if objects is None or objects == self or objects == [self]: default = True objects = self._objects.objectList() pairs = self._bond_pairs else: default = False pairs = None if conf is None: conf = self.configuration() cell = self._fixCellParameters(conf.cell_parameters) offset = ParticleProperties.ParticleVector(self) if pairs is None: pairs = [] for o in objects: new_object = True if ChemicalObjects.isChemicalObject(o): units = o.bondedUnits() elif Collections.isCollection(o) or isUniverse(o): units = set([u for element in o for u in element.topLevelChemicalObject() .bondedUnits()]) else: raise ValueError(str(o) + " not a chemical object") for bu in units: atoms = [a.index for a in bu.atomsWithDefinedPositions()] mpairs = bu.traverseBondTree(lambda a: a.index) mpairs = [(a1, a2) for (a1, a2) in mpairs if a1 in atoms and a2 in atoms] if len(mpairs) == 0: mpairs = Utility.pairs(atoms) new_object = False pairs.extend(mpairs) pairs = N.array(pairs) if default: self._bond_pairs = pairs if cell is None: contiguous_object_offset(self._spec, pairs, conf.array, offset.array, box_coordinates) else: contiguous_object_offset(self._spec, pairs, conf.array, offset.array, box_coordinates, cell) return offset def _graphics(self, conf, distance_fn, model, module, options): objects = self._objects._graphics(conf, distance_fn, model, module, options) v1, v2, v3 = self.basisVectors() p = -0.5*(v1+v2+v3) color = options.get('color', 'white') material = module.EmissiveMaterial(color) objects.append(module.Line(p, p+v1, material=material)) objects.append(module.Line(p, p+v2, material=material)) objects.append(module.Line(p+v1, p+v1+v2, material=material)) objects.append(module.Line(p+v2, p+v1+v2, material=material)) objects.append(module.Line(p, p+v3, material=material)) objects.append(module.Line(p+v1, p+v1+v3, material=material)) objects.append(module.Line(p+v2, p+v2+v3, material=material)) objects.append(module.Line(p+v1+v2, p+v1+v2+v3, material=material)) objects.append(module.Line(p+v3, p+v1+v3, material=material)) objects.append(module.Line(p+v3, p+v2+v3, material=material)) objects.append(module.Line(p+v1+v3, p+v1+v2+v3, material=material)) objects.append(module.Line(p+v2+v3, p+v1+v2+v3, material=material)) return objects # # Orthorhombic universe with periodic boundary conditions #
[docs]class OrthorhombicPeriodicUniverse(Periodic3DUniverse): """ Periodic universe with orthorhombic elementary cell. """ def __init__(self, size = None, forcefield = None, **properties): """ :param size: a sequence of length three specifying the edge lengths along the x, y, and z directions :param forcefield: a force field, or None for no force field :type forcefield: :class:`~MMTK.ForceFields.ForceField.ForceField` """ Universe.__init__(self, forcefield, properties) self.data = N.zeros((3,), N.Float) if size is not None: self.setSize(size) self._createSpec() is_orthogonal = True def __setstate__(self, state): Universe.__setstate__(self, state) if len(self.data.shape) == 2: self.data = self.data[0] def setSize(self, size): self.data[:] = size
[docs] def scaleSize(self, factor): """ Multiplies all edge lengths by a factor. :param factor: the scale factor :type factor: float """ self.data[:] = factor*self.data self._spec.foldCoordinatesIntoBox(self.configuration().array)
def setCellParameters(self, parameters): if parameters is not None: self.data[:] = parameters def realToBoxCoordinates(self, vector): x, y, z = vector return Vector(x/self.data[0], y/self.data[1], z/self.data[2]) def boxToRealCoordinates(self, vector): x, y, z = vector return Vector(x*self.data[0], y*self.data[1], z*self.data[2]) def _realToBoxPointArray(self, array, parameters=None): if parameters is None: parameters = self.data if parameters.shape == (3,): parameters = parameters[N.NewAxis, :] return array/parameters def _boxToRealPointArray(self, array, parameters=None): if parameters is None: parameters = self.data if parameters.shape == (3,): parameters = parameters[N.NewAxis, :] return array*parameters def CdistanceFunction(self): from MMTK_universe import orthorhombic_universe_distance_function return orthorhombic_universe_distance_function, self.data def CcorrectionFunction(self): from MMTK_universe import orthorhombic_universe_correction_function return orthorhombic_universe_correction_function, self.data def CvolumeFunction(self): from MMTK_universe import orthorhombic_universe_volume_function return orthorhombic_universe_volume_function, self.data def CboxTransformationFunction(self): from MMTK_universe import orthorhombic_universe_box_transformation return orthorhombic_universe_box_transformation, self.data def cellParameters(self): return self.data def reciprocalBasisVectors(self): return [Vector(1., 0., 0.)/self.data[0], Vector(0., 1., 0.)/self.data[1], Vector(0., 0., 1.)/self.data[2]] def cellVolume(self): return N.multiply.reduce(self.data) def largestDistance(self): return 0.5*N.minimum.reduce(self.data) def _createSpec(self): from MMTK_universe import OrthorhombicPeriodicUniverseSpec self._spec = OrthorhombicPeriodicUniverseSpec(self.data) def _descriptionArguments(self): if self._forcefield is None: return '((0.,0.,0.),)' else: return '((0.,0.,0.),%s)' % self._forcefield.description() def XMLSpec(self): return 'topology="periodic3d" ' + \ 'cellshape="orthorhombic" ' + \ ('cellsize="%f %f %f" ' % tuple(self.data)) + \ 'units="units:nm"' # # Cubic universe with periodic boundary conditions #
[docs]class CubicPeriodicUniverse(OrthorhombicPeriodicUniverse): """ Periodic universe with cubic elementary cell. """
[docs] def setSize(self, size): """ Set the edge length to a given value. :param size: the new size :type size: float """ OrthorhombicPeriodicUniverse.setSize(self, 3*(size,))
def _descriptionArguments(self): if self._forcefield is None: return '(0.)' else: return '(0.,%s)' % self._forcefield.description() # # Parallelepipedic universe with periodic boundary conditions #
[docs]class ParallelepipedicPeriodicUniverse(Periodic3DUniverse): """ Periodic universe with parallelepipedic elementary cell. """ def __init__(self, shape = None, forcefield = None, **properties): """ :param shape: the basis vectors :type shape: sequence of Scientific.Geometry.Vector :param forcefield: a force field, or None for no force field :type forcefield: :class:`~MMTK.ForceFields.ForceField.ForceField` """ Universe.__init__(self, forcefield, properties) self.data = N.zeros((19,), N.Float) if shape is not None: self.setShape(shape) self._createSpec() is_periodic = True def setShape(self, shape): self.data[:9] = N.ravel(N.transpose([list(s) for s in shape])) from MMTK_universe import parallelepiped_invert parallelepiped_invert(self.data)
[docs] def scaleSize(self, factor): """ Multiplies all edge lengths by a factor. :param factor: the scale factor :type factor: float """ self.data[:9] = factor*self.data[:9] from MMTK_universe import parallelepiped_invert parallelepiped_invert(self.data) self._spec.foldCoordinatesIntoBox(self.configuration().array)
def setCellParameters(self, parameters): if parameters is not None: self.data[:9] = parameters from MMTK_universe import parallelepiped_invert parallelepiped_invert(self.data) def _fixCellParameters(self, cell_parameters): full_parameters = 0.*self.data full_parameters[:9] = cell_parameters from MMTK_universe import parallelepiped_invert parallelepiped_invert(full_parameters) return full_parameters def realToBoxCoordinates(self, vector): x, y, z = vector return Vector(self.data[0+9]*x + self.data[1+9]*y + self.data[2+9]*z, self.data[3+9]*x + self.data[4+9]*y + self.data[5+9]*z, self.data[6+9]*x + self.data[7+9]*y + self.data[8+9]*z) def boxToRealCoordinates(self, vector): x, y, z = vector return Vector(self.data[0]*x + self.data[1]*y + self.data[2]*z, self.data[3]*x + self.data[4]*y + self.data[5]*z, self.data[6]*x + self.data[7]*y + self.data[8]*z) def _realToBoxPointArray(self, array, parameters=None): if parameters is None: matrix = N.reshape(self.data[9:18], (1, 3, 3)) else: parameters = N.concatenate([parameters, N.zeros((10,), N.Float)]) from MMTK_universe import parallelepiped_invert parallelepiped_invert(parameters) matrix = N.reshape(parameters[9:18], (1, 3, 3)) return N.add.reduce(matrix*array[:, N.NewAxis, :], axis=-1) def _boxToRealPointArray(self, array, parameters=None): if parameters is None: parameters = self.data[:9] matrix = N.reshape(parameters, (1, 3, 3)) return N.add.reduce(matrix*array[:, N.NewAxis, :], axis=-1) def CdistanceFunction(self): from MMTK_universe import parallelepipedic_universe_distance_function return parallelepipedic_universe_distance_function, self.data def CcorrectionFunction(self): from MMTK_universe import parallelepipedic_universe_correction_function return parallelepipedic_universe_correction_function, self.data def CvolumeFunction(self): from MMTK_universe import parallelepipedic_universe_volume_function return parallelepipedic_universe_volume_function, self.data def CboxTransformationFunction(self): from MMTK_universe import parallelepipedic_universe_box_transformation return parallelepipedic_universe_box_transformation, self.data def cellParameters(self): return self.data[:9] def reciprocalBasisVectors(self): return [Vector(self.data[9:12]), Vector(self.data[12:15]), Vector(self.data[15:18])] def cellVolume(self): return abs(self.data[18]) def largestDistance(self): return min([0.5/v.length() for v in self.reciprocalBasisVectors()]) def _createSpec(self): from MMTK_universe import ParallelepipedicPeriodicUniverseSpec self._spec = ParallelepipedicPeriodicUniverseSpec(self.data) def _descriptionArguments(self): if self._forcefield is None: return '((Vector(0.,0.,0.),Vector(0.,0.,0.),Vector(0.,0.,0.)))' else: return '((Vector(0.,0.,0.),Vector(0.,0.,0.),Vector(0.,0.,0.)),%s)'\ % self._forcefield.description() def XMLSpec(self): return 'topology="periodic3d" ' + \ 'cellshape="parallelepipedic" ' + \ ('cellshape="%f %f %f %f %f %f %f %f %f" ' % tuple(self.data[:9])) + \ 'units="units:nm"' # # Recognition functions #
[docs]def isUniverse(object): """ :param object: any Python object :returns: True if object is a universe. """ return isinstance(object, Universe)