3.4 Simp namespace (Prev) 3.6 DdMd namespace (Next)

The McMd namespace contains most of the classes used to construct Monte Carlo and molecular dynamics simulations. All class names mentioned on this web page that are not explicitly qualified by namespace identifier are defined in the McMd namespace. In many cases, analogous classes with identical names are defined in the DdMd namespace (e.g., McMd::Atom vs. DdMd::Atom).

Chemical structure

An Atom object represents a point particle that is part of a Molecule. Each Atom has a position, velocity and force, each of which is represented by a Util::Vector object. The velocity and force vectors are not used in many MC move algorithms, but are provided even in MC simulations for use in hybrid MC/MD algorithms. An Atom has an integer atom type index, and an integer id that is unique within the simulation. The atom type ids are used to identify atom types within the calculation of non-bonded pair interactions. Each Atom is associated with a parent Molecule object, and can return a reference to its parent Molecule.

Each Atom is also associated with a Mask object that contains a list of other atoms for which the nonbonded pair interaction with the target atom is suppressed (i.e., "masked").

The Group < int N > class template is a template class 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. These are referred to throughout the code as Bond, Angle, and Torsion objects, but these names are typedefs for Group<2>, Group<3>, and Group<4>. A Group < N > object has an array of N pointers to N Atom objects that interact via an N-body covalent interaction. It also has an integer group type id, which is used to associate different sets of interaction parameters to groups with different group type id values.

A Molecule object represents a chemical molecule, i.e., a specific set of atoms that are connected by covalent bonds. Each Molecule is associated with a list of constituent Atom objects. Each Molecule is also associated with lists of Bond, Angle, and Torsion objects. The Molecule class provides methods to access its constituent Atom and Group < N > objects, using a local indexing scheme in which Atom and Group < N > objects are indexed from zero within each molecule of a species. For example, the method Atom& Molecule::atom(i) returns a reference to Atom number i of the invoking molecule, where i ranges from 0 up to one less than the number of atoms in the molecule. Each Molecule belongs to a molecular species, and holds a pointer to an associated Simp::Species object that contains a description of the structure of each molecule in the species.

See also: Chemistry Module See also: Species Module

Systems

A System object represents a set of interacting molecules within a region of space. McSystem and MdSystem are subclasses of System that are specialized for MD and MC simulations, respectively.

An instance of the System base class has:

Containers that hold pointers to all molecules in this System.
a Util::Boundary object.
a Util::EnergyEnsemble object.
a Util::BoundaryEnsemble object.

A System provides methods to access and manage molecules. It provides methods to add and remove molecules, to iterate over all the molecules of each species, and to choose a molecule of a specified species at random (for Monte Carlo moves).

The McSystem and MdSystem subclasses each have associated potential energy classes (discussed below). These are members of the subclasses, rather than the base System class, because some potential energies require different interfaces for MC and MD simulations.

An MdSystem also has an associated molecular dynamics integrator, which is an instance of MdIntegrator (see below).

In MC simulations, the parent McSimulation (discussed below) has an McMoveManager container that holds a set of instances of McMove, which represent different Monte Carlo moves.

Potential energies

The McMd "potential" classes in the mcMd/potentials/ directory are polymorphic classes that provide virtual methods to calculate specific contributions to energies and atomic forces for an entire System, as well as for small groups (e.g., pairs) of interacting atoms. The classes BondPotential, AnglePotential, DihedralPotential provide interfaces for bond, angle, and dihedral potentials, respectively, which are used in both MD and MC simulations. The classes McPairPotential and MdPairPotential provide slightly different interfaces for nonbonded pair interactions for use in MC and MD simulations, respectively. Every potential class provides an energy() method that returns the associated energy for the entire system. The covalent potential energy classes (BondPotential, AnglePotential, and DihedralPotential) and the MdPairPotential class all provide an addForces() method that adds the contribution of the associated type of interaction to the atomic forces for every atom in the system. The covalent potential energy classes and McPairPotential all provide an atomEnergy() method that returns the value of a particular energy contribution (i.e., the nonbonded pair energy or covalent bond energy) for a specific atom, for use in MC algorithms.

The "potential" classes discussed above are abstract base classes. An implementation of each of the potential energy classes is provided by an associated class template. Each such potential energy template takes one of the Interaction classes defined in the Simp namespace as a template argument, and has an instance of that Interaction class as a private member. The name of each template is obtained by adding the suffix "Impl" (for "implementation") to the name of the parent abstract potential class. Thus, for example, MdPairPotentialImpl<LJPair> is a concrete subclass of MdPairPotential for Lennard-Jones pair interactions, which uses an instance of the Simp::LJPair interaction class to calculate pair energies and forces for individual nonbonded pairs of atoms.

This use of templates to implement potential energies was chosen in order to allow the user to choose a form of each potential energy at run time without sacrificing efficiency, and without redundant code. Because the interaction class methods are not virtual, this design allows each template to implement an inner loop for force or energy calculations that is free of virtual function calls, and allows the compiler to inline many force and energy interaction functions.

The choice of which interaction class to use for each type of potential energy is specified in the parameter file by the string 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" in an MD program instructs the program to construct and use an instance of MdPairPotentialImpl<LJPair>.

Molecular dynamics integrators

Molecular dynamics integration algorithms are represented by subclasses of MdIntegrator. Each MdIntegrator is associated with a parent MdSystem. Each MdIntegrator implements a step() method that applies one complete MD step to the molecules of the associated System. An MdIntegrator may store internal state variables that are specific to the algorithm and that must be retained between steps.

Monte Carlo moves

Monte Carlo move algorithms are represented by subclasses of McMove. Each McMove implements a move() method that attempts a Markov move, decides whether to accept or reject it, and then updates or restores the state of the associated McSystem or (in Gibbs ensemble) McSystems.

Analyzers and Accumulators

Analyzer is an abstract base class for objects that represent data analysis or data output operations that must be carried out periodically during a simulation. Each Analyzer has a sample() method that is called to implement the desired operation, and an integer "interval" member that specifies the number of MD steps or MC moves that should elapse between subsequent invocations of sample(). The simplest subclasses of Analyzer periodically output values of specific variables for later analysis. Other analyzers evaluate statistical properties of particular physical quantities, e.g., they may evaluate the average, variance, distribution, and/or autocorrelation of a sequence of values. The DumpConfig class outputs a sequence of complete configuration files for postprocessing

Analyzers that execute a statistical analysis are usually implemented using one of the accumulator classes from the src/util/accumulators directory. Each accumulator class models an abstract mathematical operations, such as evaluation of an average, a histogram, or an autorcorrelation function.

Simulations

A complete MC or MD simulation is represented by a Simulation object. MdSimulation and McSimulation subclasses of Simulation are used for MD and MC simulations of a single system, respectively. Each Simulation object has:

One or more McSystem or MdSystem objects.
a SpeciesManager that holds a set of Simp::Species objects.
a Util::Random random number generator.
An AnalyzerManager that holds a set of Analyzer objects.

The Simulation is also responsible for reading a command file, for implementing the main simulation loop, and managing a memory pool of Molecule objects for each species. An MdSimulation contains one McSystem. An McSimulation contains one MdSystem.

Both MdSimulation and McSimulation provide a readCommands() method that reads a command file and implements commands in sequence. The SIMULATE command causes the simulation to invoke the simulate() method of either class, which implements the main simulation loop.

The simulate() method of an McSimulation implements a loop in which each step involves a choice of one of several possible Monte Carlo Markov moves. An McSimulation has an McMoveManager that holds pointers to a set of McMove objects. The McMoveManager provides a method to choose one of the moves at random, weighted by a user-defined probabilities. Each step of the main loop in the simulate() method chooses one of these McMove objects and invokes its move() method.

The simulate() method of an MdSimulation repeatedly calls the step() method of the MdIntegrator associated with its MdSystem.

The analyze() method of an MdSimulation or McSimulation reads a series of config files that have been written during a previous simulation by a DumpConfig Analyzer object. The analyze() method implements a loop that reads in configuration files and applies each of the Analyzer objects.

The getMolecule() and returnMolecule() are used to manage a memory pool (or "reservoir") of Molecule objects of each species that have not been assigned to any physical system. Classes that read the initial configuration from a file repeatedly call getMolecule() to retrieve an unused molecule from this pool. Monte Carlo moves that remove and insert molecules (not yet implemented) should use the same methods to manage memory.

The conceptual distinction between a System and a Simulation is somewhat arbitrary, and is not necessary in simulations of single system. Distinct Simulation and System classes were introduced to allow for eventual implementation of Gibbs ensemble simulations. In a Gibbs ensemble simulation, the molecules of each Species will be divided among two or more System sub-objects, and each System will maintain a record of which molecules are currently in that system. The main simulation loop was implemented in the parent Simulation object, rather than within a System, in order to allow for Gibbs ensemble molecular exchange moves, which are MC moves that involve two systems.