3.5 McMd namespace (Prev) 3.7 Tools namespace (Next)

The DdMd namespace contains classes used to construct parallel domain decomposition molecular dynamics simulations. All class names mentioned on this web page that are not explicitly qualified by a namespace identifier are defined in the DdMd namespace.

Many classes in the DdMd namespace have names that are similar or identical to those of analogous classes in the McMd namespace. We recommend that you at least skim the documentation for the McMd namespace before reading this discussion of the DdMd namespace.

Chemical structure

The src/ddMd/chemistry directory contains a set of classes that describe atoms and molecular topology that are (for the most part) closely analogous to classes introduced in the McMd namespace. Corresponding classes often have the same names: McMd::Atom and DdMd::Atom are both classes that represent a point particle.

A DdMd::Atom (like an McMd::Atom) has a position, velocity and force, an integer atom type index (typeId), and a global index (id). Each Atom is also associated with a Mask object that contains a list of integer ids of other atoms for which the nonbonded pair interaction with the target atom is suppressed (i.e., "masked").

In a parallel MD simulation, an Atom on a particular processor may either be a "local" atom, which is owned by that processor, or it may be "ghost". A ghost is an atom that is slightly outside the domain of atoms owned by this processor, and which is thus owned by a neighboring processor, but whose position must be known on this processor in order to calculate forces for local atoms with which it interacts. The "Atom::isGhost()" method returns a boolean true if an atom is a ghost and false if it is a local atom.

The Group < int N > class template is a class template for objects that represent a small group of N covalently interacting atoms. Specializations with N=2, 3, and 4 are used to represent 2-body covalent bonds, 3-body angle interaction groups, and 4-body dihedral interaction groups, respectively. A Group < N > object has an array of N integer ids for N interacting Atom objects, a corresponding array of N pointers to these objects, for a set of atoms that interact via an N-body covalent interaction. A group also has an integer group type id for the group.

In a domain decomposition algorithm, atoms may migrate between processors as a result of changes in position. When ownwership of an atom is transferred from one processor to another, all of the Group < N > objects to which the atom belongs are also sent to the new owner. The atom ids and group type id that are stored in a Group < N > are permanent identifiers, which are sent between processors when the Group migrates. The pointers to atoms must be reset after each Group is received.

Each Atom may be owned by only one processor, but may appear as a ghost one or more other processors. Each Group < N > object is "owned" by every processor that owns one or more of its constituent atoms, and thus could conceivably be owned by up to N processors.

The code in the DdMd namespace does not involve any concept of a molecule, or of a molecular species. The topology of each molecule is defined implicitly by a set of Group objects. Correspondingly, there is no Molecule or Species class in this namespace.

Storage classes

Storage classes are classes that manage and provide access to sets of Atom < N > and Group < N > objects for one processor. The AtomStorage class manages separate sets of local and ghost Atom objects for one processor. The GroupStorage<int N> class manages the set of Group < N > objects (i.e., bonds, angles, or dihedrals) that are currently owned by this processor.

Each of the storage classes provides two services:

Memory Pool: A storage class allocates an underlying block of memory (a C array) for Atom and/or Group objects and keeps track of unused locations in this block.
Object access: A storage maintains a set of pointers to Atom or Group < N > objects present on this processor, and can provide an iterator for each such set.

Each storage provides an interface for adding and removing Atom or Group objects as a result of atom migration. To add an object, one must call a method that provides the address of an unused location in the memory pool. When an object is deleted, the associated memory is returned to the "reservoir" of unused memory locations.

Potential energy classes

The "potential" classes in the DdMd namespace are closely analogous to those in the McMd namespace: Each potential class is a polymorphic classes that provide virtual methods to calculate specific contributions to energies and atomic forces for an entire System. The classes PairPotential, BondPotential, AnglePotential, DihedralPotential and ExternalPotential in the DdMd namespace provide interfaces for nonbonded pair, bond, angle, dihedral, and external potentials, respectively. Each potential energy class provides an addForces() method that adds forces arising from the corresponding potential energy to every local atom on this processor.

The potential classes discussed above are abstract base classes. The implementation of each such potential energy classes is provided by an associated class template that takes one of the Interaction classes defined in the Simp namespace as a template argument. Thus, for example, the template instantiation PairPotentialImpl<LJPair> is a concrete subclass of PairPotential for Lennard-Jones pair interactions. The template uses uses an instance of the LJPair interaction class to calculate pair energies and forces for individual nonbonded pairs of atoms in the inner loop of the addForces() method.

The choice of which interaction class to use for each type of potential energy is specified in the parameter file by the parameters pairStyle, BondStyle, etc. The value of each such "style" variable is the name of the desired interaction class. For example, specifying a "pairStyle" to be "LJPair" instructs the main Simulation object to construct an instance of MdPairPotentialImpl<LJPair>, which is then accessed through a PairPotential* base class pointer.

The implementation of each covalent potential energy class uses an associated storage class to provide iterators for all Group < N > objects of the required type. The PairPotentialImpl template uses an internal PairList object, which contains a Verlet pair list.

Interprocessor communication

The src/ddMd/communicate directory contains a set of classes that are used to communicate between processors, to transfer ownership of atoms and groups between processors, and to update positions of ghosts.

The Exchanger class implements the main domain decomposition communication algorithms. The exchange() method first exchanges ownership of atoms that have migrated between processors, and then exchanges ghosts. This method is called only on time steps when the pair list must be rebuilt. The update() method is called every time step that exchange() is not called, and updates the positions of ghost atoms.

The AtomDistributor, AtomCollector classes, and the GroupDistributor < N > and GroupCollector < N > class templates are utility classes that are used in the implementation of ConfigIo classes that read and write configuration files. All file I/O operations are handled by a single master processor. When a configuration file is read, the "Distributor" classes are used to distribute atoms and groups from the master processor to the processors that own these objects. When a configuration file is written, the "Collector" classes collect atoms and groups from all processors and sends them to a master processor.

The Buffer class provides an interface for blocks of memory that are used for MPI communication. The Buffer class is used by all of the other communication classes discussed above.

Molecular dynamics integrators

DdMd molecular dynamics integration algorithms are represented by subclasses of Integrator. Each Integrator implements a method run(int nStep) method that runs a simulation of a prescribed number of steps. An Integrator may store internal state variables that are specific to the algorithm and that must be retained between steps.

Modifier algorithms

The src/ddMd/modifier directory contains a set of classes that can be used to modify the basic integration algorithm by periodically modifying the state of the system during integration. Modifier is an abstract base class for classes that implement such algorithms. ModifierManager is a container for Modifier objects. Modifiers are disabled by default, but may be enabled by invoking ./configure -u1.

Data Analysis

The src/ddMd/analyzer directory contains a set of classes that are used for data analysis. DdMd::Analyzer is an abstract base class for classes that implement data analysis and/or data output operations. AnalyzerManager is a container for all of the Analyzer objects associated with a particular simulation.

Simulation

A Simulation object is the top level object in a DdMd simulation. There is no distinction in the DdMd namespace between a "System" and a "Simulation". Every Simulation has:

an AtomStorage that stores both local and ghost atoms
GroupStorage < N > objects that can store bonds (N=2), angles (N=3), and dihedrals (N=4)
a set of potential energy classes for nonbonded, bonded, and external potentials
a Simp::Boundary object, which defines periodic boundary conditions
a Simp::EnergyEnsemble object, which defines the energy ensemble
a Simp::BoundaryEnsemble object, which defines the volume/pressure ensemble
an Integrator, which integrates the equations of motion
a Domain, which defines the spatial decomposition among processors
an Exchanger, which implements interprocessor communication
a ConfigIo, which read and write configuration files
a Buffer to provide memory for communication
a Util::Random random number generator object
an AnalyzerManager container for associated Analyzer data analysis objects
an ModifierManager container for associated Modifier objects (if enabled at compile time).