# Module MMTK.Universe

## Functions

- isUniverse()

  Returns 1 if object is a Universe.

## Class Universe: Complete model of chemical system

A subclass of MMTK.Collection.GroupOfAtoms and MMTK.Visualization.Viewable.

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 Glossary: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

Methods:

- objectList(klass=`None`)

  Returns a list of all chemical objects in the universe. If klass is not None, only objects whose class is equal to klass are returned.

- environmentObjectList(klass=`None`)

  Returns a list of all environment objects in the universe. If klass is not None, only objects whose class is equal to klass are returned.

- atomList()

  Returns a list of all atoms in the universe. This includes atoms that make up the compound chemical objects (molecules etc.).

- universe()

  Returns the universe itself.

- addObject(object)

  Adds object to the universe. If object is a Collection, all elements of the Collection are added to the universe. An object can only be added to a universe if it is not already part of another universe.

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

- selectShell(point, r1, r2=`0.0`)

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

- selectBox(p1, p2)

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

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

- releaseReadStateLock(write=`0`)

  Release the universe read state lock.

- releaseWriteStateLock(write=`0`)

  Release the universe write state lock.

- acquireConfigurationChangeLock(waitflag=`1`)

  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.

  If waitflag is true, the method waits until the lock becomes available; this is the most common operation. If waitflag is false, the method returns immediately even if another thread holds the lock. The return value indicates if the lock could be acquired (1) or not (0).

- releaseConfigurationChangeLock()

  Releases the configuration change lock.

- setForceField(forcefield)

  Assign a new forcefield to the universe.

- configuration()

  Return the configuration object describing the current configuration of the universe. Note that this is not a copy of the current state; the positions in the configuration object will change when coordinate changes are applied to the universe in whatever way.

- copyConfiguration()

  Returns a copy of the current configuration.

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

- setConfiguration(configuration, block=`1`)

  Copy all positions are from configuration (which must be a Configuration object) to the current universe configuration.

  This operation is thread-safe; it blocks other threads that want to access the configuration while the data is being updated. If this is not desired (e.g. when calling from a routine that handles locking itself), the optional parameter block should be set to 0.

- addToConfiguration(displacement, block=`1`)

  Add displacement (a ParticleVector object) to the current configuration of the universe.

  This operation is thread-safe; it blocks other threads that want to access the configuration while the data is being updated. If this is not desired (e.g. when calling from a routine that handles locking itself), the optional parameter block should be set to 0.

- getParticleScalar(name, datatype=`'d'`)

  Return a ParticleScalar object containing the values of the attribute name for each atom in the universe.

- getParticleBoolean(name)

  Return a ParticleScalar object containing the boolean values (0 or 1) of the attribute name for each atom in the universe. An atom that does not have the attribute name is assigned a value of zero.

- masses()

  Return a ParticleScalar object containing the atom masses.

- charges()

  Return a ParticleScalar object containing the atom charges. Since charges are parameters defined by a force field, this method will raise an exception if no force field is defined or if the current force field defines no charges.

- velocities()

  Returns ParticleVector object containing the current velocities of all atoms. If no velocities are defined, the return value is `None`. Note that the return value is not a copy of the current state but a reference to it; its data will change when any changes are made to the current velocities.

- setVelocities(velocities, block=`1`)

  Set the current atom velocities to the values contained in the ParticleVector object velocities. If velocities is None, the velocity information is removed from the universe.

  This operation is thread-safe; it blocks other threads that want to access the velocities while the data is being updated. If this is not desired (e.g. when calling from a routine that handles locking itself), the optional parameter block should be set to 0.

- initializeVelocitiesToTemperature(temperature)

  Generate random velocities for all atoms from a Boltzmann distribution at the given temperature.

- scaleVelocitiesToTemperature(temperature, block=`1`)

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

  This operation is thread-safe; it blocks other threads that want to access the velocities while the data is being updated. If this is not desired (e.g. when calling from a routine that handles locking itself), the optional parameter block should be set to 0.

- distanceConstraintList()

  Returns the list of distance constraints.

- numberOfDistanceConstraints()

  Returns the number of distance constraints.

- setBondConstraints()

  Sets distance constraints for all bonds.

- removeDistanceConstraints()

  Removes all distance constraints.

- enforceConstraints(configuration=`None`, velocities=`None`)

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

- adjustVelocitiesToConstraints(velocities=`None`, block=`1`)

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

  This operation is thread-safe; it blocks other threads that want to access the velocities while the data is being updated. If this is not desired (e.g. when calling from a routine that handles locking itself), the optional parameter block should be set to 0.

- forcefield()

  Returns the force field.

- energy(subset1=`None`, subset2=`None`, small_change=`0`)

  Returns the energy. Without any parameters, the energy is calculated for the whole universe. If subset1 is given, only the energy terms within the atoms in subset1 are calculated. If subset1 and subset2 are given, only the energy terms between atoms of the two subsets are evaluated. The parameter small_change can be set to one in order to obtain a faster energy evaluation when the current configuration differs from the one during the last energy evaluation only by small displacements.

- energyAndGradients(subset1=`None`, subset2=`None`, small_change=`0`)

  Returns the energy and the energy gradients (a ParticleVector).

- energyAndForceConstants(subset1=`None`, subset2=`None`, small_change=`0`)

  Returns the energy and the force constants (a SymmetricParticleTensor).

- energyGradientsAndForceConstants(subset1=`None`, subset2=`None`, small_change=`0`)

  Returns the energy, the energy gradients (a ParticleVector), and the force constants (a SymmetricParticleTensor).

- energyTerms(subset1=`None`, subset2=`None`, small_change=`0`)

  Returns a dictionary containing the energy values for each energy term separately. The energy terms are defined by the force field.

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

  Returns the distance vector between p1 and p2 (i.e. the vector from p1 to p2) in the configuration conf. p1 and p2 can be vectors or subsets of the universe, in which case their center-of-mass positions are used. If conf is `None`, the current configuration of the universe is used. The result takes the universe topology (periodic boundary conditions etc.) into account.

- distance(p1, p2, conf=`None`)

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

- angle(p1, p2, p3, conf=`None`)

  Returns the angle between the distance vectors |p1|-|p2| and |p3|-|p2|.

- dihedral(p1, p2, p3, p4, conf=`None`)

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

- basisVectors()

  Returns the basis vectors of the elementary cell of a periodic universe. For a non-periodic universe the return value is `None`.

- reciprocalBasisVectors()

  Returns the reciprocal basis vectors of the elementary cell of a periodic universe. For a non-periodic universe the return value is `None`.

- cellVolume()

  Returns the volume of the elementary cell of a periodic universe. For a non-periodic universe the return value is `None`.

- largestDistance()

  Returns the largest possible distance that any two points can have in the universe. Returns `None` if no such upper limit exists.

- contiguousObjectOffset(objects=`None`, conf=`None`, box_coordinates=`0`)

  Returns a ParticleVector with displacements relative to the configuration 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`. If no object list is specified, the list of elements of the universe is used. The configuration defaults to the current configuration of the universe.

- contiguousObjectConfiguration(objects=`None`, conf=`None`)

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

- realToBoxCoordinates(vector)

  Returns the box coordinate equivalent of 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. For a nonperiodic universe, vector is returned unchanged.

- boxToRealCoordinates(vector)

  Returns the real-space equivalent of the box coordinate vector.

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

- map(function)

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

- setFromTrajectory(trajectory, step=`None`)

  Set the state of the universe to the one stored in the given step of the given trajectory. If no step number is given, the most recently written step is used for a restart trajectory, and the first step (number zero) for a normal trajectory.

  This operation is thread-safe; it blocks other threads that want to access the configuration or velocities while the data is being updated.