3.3 Util namespace (Prev) 3.5 McMd namespace (Next)

The Simp namespace contains general classes for molecular simulations that are accessible to all simpatico simulation and analysis programs, but that are two domain specific to be included in the Util namespace. A distinction is made between Util and Simp namespaces because the src/util directory that contains code in the Util namespace is maintained as a separate git repository that is available for use in scientific computing projects. All of the code in the Simp namespace is in the directory src/simp.

Interactions

Classes in the directory src/interaction are "interaction" classes that define potential energy functions. These classes are all in subdirectory src/simp/interaction. Different subdirectories of src/simp/interaction contain classes that define, respectively:

nonbonded pair interactions ( pair/ )
covalent 2-body bond potentials (bond/ )
covalent 3- body angle interactions ( angle/ )
covalent 4- body dihedral interactions ( dihedral/ )
external one-body potentials ( external/ )
coulomb interactions (coulomb/ )

The same set of interaction classes are used in both the McMd namespace, to implement mcSim and mdSim, and in the DdMd namespace, to implement ddSim.

Interaction classes are simple, nonpolymorphic classes that generally provide methods to calculate the energy and forces for small groups of interacting atoms, such as individual pairs, or groups of 3 or 4 for the angle and dihedral interactions. Each interaction class implements a specific functional form for the interaction, and has member variables that store parameters required by that functional form. Thus, for example the "LJPair" class provides methods to calculate the Lennard-Jones nonbonded pair energy and force for a single pair of non-bonded atoms. The "HarmonicBond" class provides analogous methods for a harmonic covalent bond potential. The interaction classes are non-polymorphic: they have no virtual methods and are not descended from a common base class. All interaction classes of the same type (e.g. all pair interaction classes) must, however, have the same interface for energy and force methods, to allow different interaction classes of the same type to be used interchangeably in C++ templates.

The McMd and DdMd namespaces each also contain a separate set of "potential" classes. The purpose of the "potential" classes is distnct from that of the "interaction" classes in the Simp namespace. A "potential" class provides methods to calculate energies and atomic forces for an entire system as well as (in some cases) for individual atoms or molecules within a system. A potential class that is intended for use in a molecular dynamics simulation will provide a function to calculate the contribution to the forces on all the atoms in a system arising from a particular potential energy contribution, such as pair or bond energies. The implementation this function will involve a loop over groups of interacting atoms (nonbonded or bonded pairs). A similar loop is used to compute total energy or total stress arising from a particular potential energy contribution. The code to loop over interacting groups is implemented by a "potential" class defined in the McMd or DdMd namespace, while functions of an associated interaction class is used to evaluate the relevant forces or energies for a single group (e.g., pair) within such a loop.

Molecular Species

A Species object contains a description of the chemical structure (connectivity) of a molecular species, i.e., of a set of structurally identical molecules. The Species class is a polymorphic base class. The default implementation of Species simply reads all of the information needed to describe an arbitary molecule from file, i.e., it reads a list of atom types, and information about which atoms are connected by bonds or other 3- and 4- body groups. Subclasses of Species can be used to describe either unique structures (e.g., water or methane) or categories of molecule (e.g., linear bead-spring polymers) for which the structure is partly determined in part by parameters that must be read from an input file (e.g., the chain length and monomer types for a linear homopolymer). Each subclass of Species is responsible for defining its own input parameter format and for reading and writing the information it needs to fully specify a chemical structure. Several simple subclasses of Species are distributed with Simpatico, and users can write others.

Species Module

Boundary

A Util::Boundary object defines periodic boundary conditions for a simulation. A Boundary contains the dimensions of periodic simulation unit cell, and provides methods to calculate separation vectors and distances using the nearest image convention, and to shift a position Vector into the primary unit cell.

In the current implementation, the name Boundary is a typedef for the class OrthorhombicBoundary. The use of a typedef is intended to make it easier to later develop versions of the code with more general boundaries (e.g., non-orthogonal axes).

Statistical ensembles

EnergyEnsemble, BoundaryEnsemble, and SpeciesEnsemble are simple classes that specify the statistical ensemble to be used to sample fluctuations in energy, boundary volume and/or shape, and number of molecules of each species, respectively. Each such ensemble has a type, to specify whether the associated macroscopic variable is constrained or has a Boltzmann weight, and can also store for an intensive parameter or parameters required to define the Boltzmann weight. For example, the EnergyEnsemble type can be "adiabatic" or "isothermal", and stores a value of the temperature if the type is isothermal. Each System has one associated EnergyEnsemble object and one associated BoundaryEnsemble object. Each Species object will have [not yet implemented] one associated SpeciesEnsemble object.