|
Simpatico
v1.10
|
2.3 Running a simulation (Prev) 2.4.2 Parameter Files: mdSim and mcSim (Next)
A similar syntax is used for all simpatico parameter files. To illustrate it, let's start with an example:
Shown below is a complete parameter file for a simple mdSim MD simulation. Other example parameter files for mcSim and ddSim are shown in subsequent pages, and further examples can be found in the simpatico/examples/ directory.
A simpatico parameter file consists of a series of nested blocks that begin an end with curly brackets, much like a C program.
The SpeciesManager block of an mdSim or mcSim parameter file contains information about molecular structure. This example shown below sets up a system that contains a mixture of two types of homogeneous linear polymers, which are represented by two instances of the class McMd::Homopolymer. Each species has 8 atoms per molecule (nAtom = 8). One species has atoms of type index 0 (atomType = 0), the other has atoms of type 1 (atomType = 1). Enough memory will be allocated when the program is initialized to accomodate up to 100 molecules of each type (moleculeCapacity = 100).
The potential energy is defined within the MdSystem block by the pairStyle and bondStyle strings, and by the contents of the PairPotential and BondPotential subblocks. In this example, the potential energy contains a Lennard-Jones (pairStyle = "LJPair") non-bonded pair interaction and a harmonic (bondStyle = "HarmonicBond") bond interaction between neighboring beads in each chain, with no angle or dihedral potentials.
The simulation will use a constant energy (NVE) velocity-Verlet integration algorithm (an instance of McMd::NveVvIntegrator) with a time step of dt = 0.005.
A Simpatico parameter file consists of a set of nested blocks delimited by curly brackets, much like a C program. Each block begins with a line containing a label for the block followed by an opening curly bracket, and ends with a line containing a closing curly bracket. Each block may contain both the values of individual parameters and nested subblocks.
Each parameter is given by an entry containing a label string, which is the name of the parameter, followed by its value. For example, the above file sets the parameter nAtomType (the number of distinct atom types) to 2.
The order of appearance of elements within each block of a parameter file is generally fixed (i.e., hard-coded) by the implementation of the function that reads each block. The use of a fixed file format signficantly simplifies the design of the functions that read the parameter file and initialize a simulation.
The decision to use a fixed file format for the parameter file is one case in which programmer-friendliness and maintainability have been prioritized over end-user friendliness. To make it easier for users to debug errors in the parameter file, however, Simpatico provides very explicit error messages in response to errors in the parameter file. If the expected label for a parameter or block is not found at the expected position in a parameter file, each Simpatico program will output a message indicating exactly what label was expected and what label was actually read, and then halt execution. These error messages are particularly easy to interpret if one uses the "-e" command line option when invoking the program. This option causes each block and parameter in the parameter file to be echoed to standard output immediately after it is read, thus allowing one to see exactly where in the file the error was encountered. The hierarchical nature of the file format is also designed to make it easy, if necessary, for a user to find the section of code that reads any section of the parameter file in order to resolve remaining ambiguities, as discussed in more detail below.
The hierarchical nesting of blocks in a parameter file directly reflects the hierarchical organization of C++ objects in the underlying C++ code. Each block in the parameter file corresponds to a specific C++ object. In the Simpatico source code, objects are organized into a hierarchy in which each object can have any number of "children" but only one "parent". A child object is either a member variable of its parent or a dynamically allocated object that the parent is responsible for creating and destroying. Every object in this hierarchy is responsible for reading a corresponding block in the parameter file. The root node of this herarchy is the main simulation object, which is an instance of McMd::McSimulation for mcSim simulations, McMd::MdSimulation for mdSim simulations, or DdMd::Simulation for ddSim simulations.
The parameter file block associated with a C++ object normally contains all information necessary to initialize the state of that object, and its children. The function that reads the body of an associated block in the parameter file is a member function of the associated class named "readParameters". If an object has children associated with nested subblocks in the parameter file, this function invokes a corresponding member function of each child in order to read the associated subblock.
Each parameter block begins with a line containing a label, following by an opening curly bracket ("{"). The label is the name of the class of the associated C++ object. No white space may appear between the class name and the opening bracket. For example, the block that initializes the McMd::MdSystem object in the above example begins with the line "MdSystem{". Each block ends with a matched closing bracket (i.e., "}"). The label in the opening line contains the class name, but (for the sake of brevity) does not include the name of the enclosing namespace (e.g., Util, Simp, McMd, or DdMd). Nested blocks are indented as a matter of convention, though indentation and extra white space are actually ignored when the file is parsed.
Each parameter block may contain values of any number of individual parameters, in addition to any number of nested subblocks. The value of each parameter that is represented by a built-in C++ variable (e.g., an int, double, bool, or std::string) is given on a single line that contains a label string followed by the parameter value. Each label must be a single word, with no white space. The label for each parameter corresponds to the name of an associated variable, which is always a private or protected member variable of the enclosing class. By convention, names of all private and protected class members in Simpatico end with a trailing underscore ("_"). The associated parameter file label is given by the member variable name without the trailing underscore.
For example, the number of atom types in an McMd::MdSimulation object is given by private member variable named nAtomType_. The value of McMd::MdSimulation is preceded in the parameter file by a label "nAtomType". This parameter appears within the MdSimulation{...} parameter file block.
The values of some parameters are stored as instances of non-primitive data types, such as enumerations or small classes, that are defined within the Simpatico source code. In these cases, as for primitive C++ variables, each parameter is given on a single line containing a label followed by a text representation of its value. In these cases, however, the text representation of the "value" of each such non-primitive variable must be defined by iostream extractor (>>) and insertor (<<) operators that are defined for that data type. For example, in the above file, the "type" member of the Util::EnergyEnsemble object is an instance of the enumeration Util::EnergyEnsemble::Type. This enum can have values ADIABATIC (constant energy) or ISOTHERMAL (constant temperature). The value of this variable is read by an overloaded extractor (>>) operator that recognizes either lower case "adiabatic" or upper case "ADIABATIC" as valid string representations of the ADIABATIC enum value.
Some parameters are also stored internally in one-dimensional (1D) arrays. A 1D array of parameters is given in a parameter file by a sequence of lines in which the first line contains the label (the name of the array variable) and the value of the first element, while subsequent lines contain values of subsequent elements. For example, the atomTypes member of an MdSimulation is an array that contains nAtomType instances of class AtomType. The string representation of an AtomType, which is defined by an extractor (>>) operator, contains a name string ("A" or "B" in this example) followed by a floating point value for the mass. (The mass is 1.0 for both types in the example). The number of elements in such an array must be known before the array is read, and is passed as a parameter to the function that reads an array of parameters. In this case, the number of elements in the atomTypes array is given by the value of "nAtomType", which appears before the "atomTypes" array in the file format. In the example, because nAtomType = 2, the atomTypes array contains two lines.
Variables that are stored internally in two-dimensional arrays or Util::Matrix objects also use a multi-line parameter file format. In this case, the first line contains a label (the name of the associated 2D array or Util::Matrix variable), followed by the elements of the first row, with subsequent rows on subsequent lines. In the above example, this format is used for the epsilon, sigma, and cutoff members of an LJPair pair potential object, which are each 2 x 2 matrices in this example. In LJPair, of these parameters is stored internally as a two dimensional C-array, in which epsilon[i][j] is the value of the Lennard-Jones epsilon parameter for interactions between atoms of types i and j, for 0 < i, j <= nAtomType.
The meaning of most parameter labels should be self-explanatory. When they are not, the conventions used in this file format are designed to make it easy for users to look up the meaning of the variable in the html documentation or source code: Each parameter in this file format is labelled by the name of an associated member variable of a class. The relevant class is given by the class name in the first line of the intermost enclosing block. The meaning of every member variable that appears in the parameter file is explained in the html documentation for that class, and in the header (*.h) file of the enclosing class.
Each parameter in a parameter file may be either required or optional. Most parameters are required. The entry for a required parameter (the label and value) must appear at a specific position in a file format, or execution will halt. The entry for an optional parameter line may be either present or absent. If an optional parameter is absent from a parameter file, the associated variable is assigned a default value, and the program continues on to the next parameter in the expected file format.
The parameter nBondType in the above example is an optional parameter. This parameter specifies how many distinct types of covalent bond can exist in a simulation. If the line containing the nBondType parameter were missing, nBondType would be set to zero by default. Setting nBondType to 0 de-activates the bond potential, which would be the appropriate setting for a simulation of point particles (e.g., liquid Argon). The bond potential can thus be disabled either by explicitly setting nBondType to zero, or by leaving this line out of the parameter file. In versions of the program that are compiled with angle and dihedral potentials enabled, the optional nBondType parameter may be followed by optional nAngleType and nDihedralType parameters. Each of these enables the corresponding angle or dihedral potential if it is assigned a nonzero values, and each of these is also set to zero by default, thus disabling the associated potential. In versions of the program that are compiled with external potential enabled, the optional parameters nBondType, nAngleType, and nDihedralType are followed by an optional boolean variable named hasExternal that is set false (0) by default. The hasExternal parameter thus enables the external potential if it is set to true (1) or disables the external potential when set to false (0) or absent.
Some parameters or blocks in a parameter file may be required only if parameters that have been read previously take on specific values. Generally, the format does not require or allow entry of parameters if it is already known that their values would be meaningless or irrelevent on the basis of parameter values that appear earlier in the parameter file. For example, the "bondStyle" parameter and the "BondPotential" block parameter are required if and only if nBondType has been assigned a positive value, nBondType > 0, thereby enabling the inclusion of bond potential. Similarly "angleStyle" and "AnglePotential" would be required immediately after "bondStyle" and "BondPotential", respectively, if and only if nAngleType > 0.
Some blocks in a simpatico parameter file are "polymorphic". A polymorphic parameter file block is one that may contain the format appropriate to any of several possible subclasses of a particular base class. The desired subclass is identified by the class name label in the opening line of such a block. The use of polymorphic blocks allows a user to choose at run time which elements of a simulation (e.g., which among several possible integration algorithms, analyzers, and file formats) should be used in a particular simulation.
For example, the parameter file shown above contains a polymorphic block associated with the molecular dynamics integrator. This block is the last element within the MdSystem block. This block is allowed to contain the parameter file format for any one of several possible subclasses of McMd::MdIntegrator, each of which implements a different molecular dynamics integration algorithm. In the example, this block begins with a label "NveVvIntegrator{" that identifies a subclass McMd::NveVvIntegrator. This class implements a constant energy (NVE) velocity Verlet algorithm. To instead use an McMd::NvtNhIntegrator, which implements a constant temperature (NVT) Nose-Hoover integrator, the user would replace this block by the appropriate file format for an McMd::NvtNhIntegrator, which would begin with the line "NvtNhIntegrator{". Different file formats are generally required for different subclasses. For example, the format for an McMd::NvtNhIntegrator contains a parameter that controls the strength of the coupling of the system to an auxiliary variable that acts as a heat bath, while no such parameter is needed in an McMd::NveVvIntegrator.
Links to user documentation of parameter file formats for a variety of polymorphic classes that implement different simulation or analysis features given in Section 2.9 Run-Time Options.
The code required to parse a polymorphic block relies on an associated "Factory" class, which is responsible for recognizing all of the valid subclass names of an associated base class, and being able to construct a new instance of a specified subclass. Factory classes are discussed in more detail here.
The above example file contains two blocks labelled "SpeciesManager" and "AnalyzerManager" that are examples of "Manager" classes. The parameter block associated with each Manager class contains a sequence of polymorphic subblocks, separated by spaces. Each such subblock may contain the file format for any known subclass of the associated base class (e.g., any subclass of McMd::Species or McMd::Analyzer). A Manager block may contain any number of such subblocks, followed by a closing bracket on a line by itself.
A Manager class is used to allow a user to specify an arbitrary number of instances of different subclasses of a particular base class for use in a simulation. Thus for example, the sub-blocks of the SpeciesManager block lists all of the molecular species that may be present in a particular simulation. Each such sublock describes the chemical structure of a different species of molecule, each of which is represented by an instance of a subclass of McMd::Species. Each subblocks of the AnalyzerManager block instead specifies a subclasses of McMd::Analyzer that implements a data analysis and/or data output operation that should be invoked periodically during a simulation. The parameter file format for an mcSim Monte Carlo (MC) simulation also has an McMoveManager block that contains subblocks associated with different Markov MC moves that should be chosen at random at each step of a Markov MC simulation.
In mcSim and mdSim simulations, the McMd::McSystem or McMd::MdSystem object has several associated types of potential energy. In a ddSim simulation, corresponding potential energies objects are members of the main DdMd::Simulation object. The default versions of all three programs implement only a non-bonded pair potential and a bond potential. Other types of potential energy, such as 3-body bond angle and 4-body dihedral potentials or an external one-bondy potential, may be enabled by invoking the configure script from the appropriate build directory and recompiling.
At run time, a user may choose from among several functional forms for each type of potential energy by specifying a "style" parameter string. For example, the type of nonbonded pair potential function is specified by the value of the string "pairStyle". This can take on values such as "LJPair", corresponding to a Lennard-Jones potential, or "DpdPair", corresponding to the soft potential typically used in dissipative particle dynamics (DPD) simulations. Each of the allowed values of this pair style string corresponds to the name of class defined in the src/simp/pair directory. Similarly, "bondStyle" can take on values such as "HarmonicBond" or "FeneBond", which are the names of classes defined in the directory src/simp/bond. The classes that represent particular potential energy functions are referred to in what follows as "interaction" classes, and are all defined within the "Inter" namespace. In the above example, the "pairStyle" and "bondStyle" parameters appear near the top of the MdSystem block. The parameter file format for a code compiled with angle and dihedral potentials enabled would also contain "angleStyle" and "dihedralStyle" strings to specify choices of angle and dihedral interaction classes. These "style" variables are followed by a set of blocks that contain the parameters for different types of potential energy (pair, bond, etc.). In the above example, these blocks are labelled "MdPairPotential" and "BondPotential". Each of these blocks contains the set of parameters required by the potential energy function specified by the corresponding "style" variable, which are different for different interaction styles. The parameter file blocks for pair potential classes contain parameters that are required to set up a cell list and/or a Verlet pair list, as discussed in more detail in subsequent pages.
To use this file format effectively, and diagnose errors, it is useful for users to understand how it is parsed. As already noted, each block in a parameter file is associated with an object that is an instance of a class whose class name is given explicitly in the first line of the block. Each such class must be a subclass of Util::ParamComposite that (with a few exceptions) provides an implementation of the virtual method Util::ParamComposite::readParameters(std::istream&). The readParameters() member function of each class reads the body of the associated parameter file block, and thus defines defines the order in which individual parameters and nested sub-blocks must appear within the body of the associated parameter file block.
If other forms of documentation are not sufficient to answer a question about the parameter file format for a particular class, it may thus be useful to look at the source code for the "readParameters" function of that class. An html copy of the implementation of this function can be obtained by opening the class documentation (accessed via either the "Modules" or "Classes" link at the top of any page of this html documentation), clicking on the brief description of "readParameters" to get the long function description, and then clicking on a link to a line number to open an html version of the function definition. An explanation of the programming conventions used in all readParameters() methods is given here.
2.3 Running a simulation (Prev) 2.4 Parameter Files (Up) 2.4.2 Parameter Files: mdSim and mcSim (Next)
1.8.11