Simpatico  v1.10
2.4.2 Parameter Files: mdSim and mcSim

2.4.1 Parameter Files: Syntax (Prev)         2.4.3 Parameter Files: ddSim (Next)

The parameter file formats for mdSim and mcSim simulations are similar in many respects, and so will be discussed together.

Example (for mcSim):

An example of a parameter file for an mdSim molecular dynamics simulation was shown on the previous page. Here is a corresponding example for an mcSim Monte Carlo simulation:

McSimulation{
FileMaster{
commandFileName commands
inputPrefix in/
outputPrefix out/
}
nAtomType 2
nBondType 1
atomTypes A 1.0
B 1.0
maskedPairPolicy MaskBonded
SpeciesManager{
Homopolymer{
moleculeCapacity 50
nAtom 8
atomType 0
bondType 0
}
Homopolymer{
moleculeCapacity 50
nAtom 8
atomType 1
bondType 0
}
}
Random{
seed 13451892
}
McSystem{
pairStyle LJPair
bondStyle HarmonicBond
McPairPotential{
epsilon 1.000000000000e+00 1.300000000000e+00
1.300000000000e+00 1.000000000000e+00
sigma 1.000000000000e+00 1.000000000000e+00
1.000000000000e+00 1.000000000000e+00
cutoff 1.122460000000e+00 1.122460000000e+00
1.122460000000e+00 1.122460000000e+00
maxBoundary cubic 10.5
}
BondPotential{
kappa 2.000000000000e+03
length 1.000000000000e+00
}
EnergyEnsemble{
type isothermal
temperature 1.000000000000e+00
}
BoundaryEnsemble{
type rigid
}
}
McMoveManager{
HybridMdMove{
probability 0.002000000000e+00
nStep 20
MdSystem{
MdPairPotential{
maxBoundary cubic 10.5
PairList{
atomCapacity 1000
pairCapacity 10000
skin 3.000000000000e-01
}
}
NveVvIntegrator{
dt 5.000000000000e-03
}
}
}
AtomDisplaceMove{
probability 0.479000000000e+00
speciesId 0
delta 0.05
}
AtomDisplaceMove{
probability 0.479000000000e+00
speciesId 1
delta 0.05
}
CfbReptationMove{
probability 0.020000000000e+00
speciesId 0
nTrial 20
hasAutoCorr 0
}
CfbReptationMove{
probability 0.020000000000e+00
speciesId 1
nTrial 20
hasAutoCorr 0
}
}
AnalyzerManager{
baseInterval 1000
LogProgress{
interval 10000
}
DumpConfig{
interval 1000
outputFileName dump/config.
}
McEnergyOutput{
interval 1000
outputFileName energy
}
RadiusGyration{
interval 1000
outputFileName RadiusGyration
nSamplePerBlock 10
speciesId 0
}
}
writeRestartInterval 10000
writeRestartFileName restart
}

Overview

The format is shown below for an mcSim file for a code with all potential types enabled at compile time (with bond, angle, dihedral and external potentials). Most parameters are shown in the format "label type" where type is the type of variable expected. Optional parameters are shown in square brackets, using the format [label type = default], where default is the default value assigned to the variable if this line is absent from the parameter file.

McSimulation{
FileMaster{ ... }
nAtomType int
[nBondType int = 0]
[nAngleType int = 0]
[nDihedralType int = 0]
[hasExternal bool = 0]
atomTypes string (name) float (mass)
...
maskedPairPolicy string
SpeciesManager{ ... }
Random{ ... }
McSystem{ ... }
McMoveManager{ ... }
AnalyzerManager{ ... }
writeRestartInterval int
writeRestartFileName string
}

The corresponding format for an mdSim file is:

MdSimulation{
FileMaster{ ... }
nAtomType int
[nBondType int = 0]
[nAngleType int = 0]
[nDihedralType int = 0]
[hasExternal bool = 0]
atomTypes string (name) float (mass)
...
maskedPairPolicy string
SpeciesManager{ ... }
Random{ ... }
MdSystem{ ... }
AnalyzerManager{ ... }
writeRestartInterval int
writeRestartFileName string
}

The two formats are similar in most respects. The most important differences are:

The following parameters appear in the main block in the format for either type of simulation:

The optional parameters nBondType, nAngleType and nDihedralType are each set to 0 by default. A value of zero for each of these parameters indicates that the associated type of covalent potential is disabled. Each type of covalent energy is thus disabled by default, and can be enabled by assigning nBondType, nAngleType or nDihedralType an appropriate nonzero value.

External one-body potentials are also disabled by default but can enabled by assigning the parameter hasExternal a value 1 (true) in the parameter file. The parameter hasExternal is set to 0 (false) by default, if not present in the parameter file.

The writeRestartInterval and writeRestartFileName parameters are discussed in more detail here.

FileMaster

The FileMaster block is associated with an instance of the class Util::FileMaster. This block contains several string parameters that specify locations of input and output files. The string "commandFileName" is the name of the command file that controls program execution after the parameter file is processed. The "inputPrefix" string is prepended to the names of input configuration files and other input files. The "outputPrefix" string is predended to the names of most output files.

Input and output files can be placed in separate directories by giving directory names for these two prefixes, in which case the prefix strings should end with a backslash (directory separator). In the above example, by setting "inputPrefix" to "in/" and "outputPrefix" to "out/", we have specified that input files should be read from subdirectory "in" and output files should be written to a subdirectory named "out".

MaskedPairPolicy

The parameter maskedPairPolicy is represented internally by an instance of the enum McMd::MaskPolicy. This can have values MaskBonded or MaskNone, which are represented in the parameter file by strings "MaskBonded" or "maskBonded" and "MaskNone" or "maskNone", respectively. The value "MaskBonded" indicates that nonbonded pair interactions between bonded atoms should be suppressed or "masked", i.e., there should be no non-bonded pair interaction between pairs of atoms that are directly connected by a two-body covalent bond. The value "MaskNone" indicates, conversely, that the nonbonded pair interaction should operate between any two atoms that are separated by a distance less than the appropriate pair potential cutoff length.

Random

The Random block is associated with a Util::Random object. The only parameter this block is a "seed" for the Mersenne-Twister random number generator. The seed value must be an unsigned (non-negative) 32 bit integer, in the range 0 <= seed < 4294967296.

SpeciesManager

The SpeciesManager block contains a sequence of one or more polymorphic blocks, each of which contains the appropriate file format for a subclass of McMd::Species. Each such subclass describes a different class of molecules, and so requires a different file format. Instances of the base class McMd::Species use a file format that is flexible enough to describe any molecular structure.

McSystem and MdSystem

The format for an McSystem subblock of an MdSimulation is:

McSystem{
pairStyle string
[bondStyle string]
[angleStyle string]
[dihedralStyle string]
[externalStyle string]
McPairPotential{ ... }
BondPotential{ ... }
EnergyEnsemble{ ... }
BoundaryEnsemble{ ... }
}

The format for an MdSystem subblock of an MdSimulation block is:

McSystem{
pairStyle string
bondStyle string
angleStyle string
dihedralStyle string
externalStyle string
MdPairPotential{ ... }
[BondPotential{ ... }]
[EnergyEnsemble{ ... }]
[BoundaryEnsemble{ ... }]
MdIntegrator{ ... }
}

Each of the allowed values for each of each "style" string variables is given by the name of an "interaction" class that implements the energy and force calculation for the specified potential energy function. Source files for interaction classes of different types (pair interactions, bond interactions, etc.) are located in different subdirectories of the src/simp/interaction directory.

The only differences between an MdSystem block and an McSystem block are:

In the above description of the MdSystem block, MdIntegrator{ ... } denotes a polymorphic block that must contain the file format for a subclass of the McMd::MdIntegrator base class, with an opening line that specifies the desired subclass (e.g., NvtIntegrator{...}).

Potential Energy "Styles"

For both types of System, values of the potential energy "style" parameters (pairStyle, bondStyle, etc.) are strings that specify the names specific potential energy functions for nonbonded pair, covalent and external potentials, respectively. For example, pairStyle may be assigned a value LJPair to indicate a Lennard-Jones pair interaction or DpdPair to indicate the type of soft interaction used in dissipative particle dynamics simulations. Similarly, the bondStyle string may be assigned a value HarmonicBond to indicate a harmonic potential with a nonzero rest length, or FeneBond to indicate a finitely-extensible nonlinear element (FENE) bond potential energy function.

Pair Potentials

MC and MD simulations use slightly different classes with different parameter file formats to evaluate non-bonded pair potentials. This is necessary because different data structures are used to efficiently keep track of non-bonded neighbors in MC and MD simulations. The McMd::McPairPotential class, which is used in MC simulations, uses a cell list (an instance of McMd::CellList) to identify particles that are close enough to interact. The McMd::MdPairPotential, which is used in MD simulations, instead uses a Verlet pair list (an instance of McMd::PairList) for force and energy calculations, though it constructs a private cell list to periodically rebuild the pair list. The parameter file formats for both of these classes contain the parameters required to specify the pair potential energy function and some extra parameters required to create the cell list or pair list.

In an McSystem, the McPairPotential subblock contains the parameters required by a specific pairStyle (e.g., by the LJPair style, in our example), followed by a maxBoundary parameter. The maxBoundary parameter describes the dimensions of the largest expected dimensions of the periodic boundary. The maxBoundary parameter is used to allocate memory for a cell list before the simulation begins. Only enough memory is allocated for the number of cells required for the boundary condition specified by maxBoundary, using a cell size that must be at least as large as the largest pair potential cutoff parameter. In NVE and NVT simulations, maxBoundary can safely be chosen to be equal be equal to the actual rigid boundary (which is specified in an input configuration file). In NPT and NPH simulations, however, maxBoundary must be chosen large enough to guarantee that adequate memory is allocated to accomodate any fluctuation in system size that may occur during a simulation. The CellList does not occupy a large amount of memory, so their is little cost in choosing a maxBoundary that is somewhat larger than is likely to be needed.

In an MdSystem, the MdPairPotential block contains the same parameters as for an McPotential, followed by additional parameters required to construct a Verlet pair list. The format is:

MdPairPotential{
(Interaction parameters)
maxBoundary [string (boundary type)] [float (dimension)] ...
PairList{ ... }
}

The interaction parameters for each pair style include parameters that specify the cutoff distance beyond which the pair potential is approximated by zero for pairs with all combinations of particle types. The format of the PairList subblock is:

PairList{
atomCapacity [int]
pairCapacity [int]
skin [float]
}

The value of atomCapacity is the maximum number of distinct atoms. The value of pairCapacity is the maximum number of distinct pairs within the Verlet list cutoff range. The Verlet list cutoff range is given by the sum of the largest pair potential cutoff plus the value of the "skin" parameter.

The pair list in an MD simulation is rebuilt whenever one or more atoms in the simulation has moved a distance skin/2 or greater since the last time the pair list was rebuilt. Increasing the value chosen for the "skin" parameter will thus generally cause the pair list to be rebuilt less frequently, but will increase the number of pairs retained in the pair list, and thus increase the cost of evaluating nonbonded forces that once every time step. There is thus an optimum value for each system. If the optimum value is not adequately known from previous experience, it can be identified by timing a few short trial simulations on a particular system with different values for the skin parameter.

Covalent Potentials (optional)

For bond, angle and dihedral covalent potentials, the style string value (e.g., bondStyle) and the associated potential energy block (e.g., BondPotential) must be present if and only if a nonzero value has been explicitly assigned in the main McSimulation or MdSimulation block to the associated parameter nBondType, nAngleType, or nDihedralType, respectively, thus enabling the use of the associated type of covalent potential. Recall that nBondType, nAngleType, and nDihedralType variables are optional variables that are set to zero by default, if the parameter is not present, thus disabling all covalent potentials by default.

The file format for each of the these covalent potential parameter file blocks simply contains the parameters required to define the associated potential energy function. The names and meanings of these parameters are different for different potential energy "styles", and are defined for each style by the readParameters() member function of the associated interaction class. The format for each such covalent potential energy block is thus the same as the parameter file format for the interaction class whose name is given by the associated style variable. For example, if bondStyle is assigned the value "HarmonicBond", then the file format for BondPotential block contains a list of the parameters required to define one or more type of harmonic bond. This format, which is defined by the HarmonicBond class, contains an array kappa of spring constants (one per bond type) and a corresponding array of equilibrium bond lengths.

External Potential (optional)

An external potential is a potential energy that acts on each atom independently, and that depends only on the position and type of the atom. External potentials are disabled by default by may be enabled in either an MC or MD simulation by explicitly assigning a true (1) to the optional parameter hasExternal in the main McSimulation or MdSimulation block. The externalStyle parameter and ExternalPotential parameter block should be present within the McSystem or MdSystem block if and only if hasExternal has been explicitly set to true. The value of the externalStyle string gives the name of an external interaction class that is chosen from among those defined in the simp/interaction/external directory. The ExternalPotential parameter file block contains only parameters required to define an external potential, in a format that is different for different external potential styles, and is defined by the readParameters() function of the specified external interaction class.

Energy Ensemble

The EnergyEnsemble and BoundaryEnsemble blocks are associated with instances of Util::EnergyEnsemble and Util::BoundaryEnsemble respectively. The EnergyEnsemble block specifies the type of statistical ensemble for energy fluctuations, which can be "adiabatic" (i.e., constant energy) or "isothermal". If the ensemble type is isothermal (as in the above example for mcSim), this this block must also contains a "temperature" parameter.

Only an "isothermal" ensemble makes sense for an MC simulation, but an "adiabatic" ensemble is used for MD integrators that conserve energy or (for isobaric boundary ensembles) enthalpy. For isothermal simulations, temperature is specified as a value for kT, in units of energy.

Boundary Ensemble

The BoundaryEnsemble block has a type parameter that is a string whose value must be either "rigid" (i.e., constant volume) or "isobaric". If the type is isobaric, the type parameter must be followed by a "pressure" parameter whose value specifies the target pressure in units of energy per volume.

AnalyzerManager

The AnalyzerManager block of the main McSimulation or MdSimulation block contains a single integer parameter named baseInterval, followed by a sequence of polymorphic blocks associated with subclasses of McMd::Analyzer. Most subclasses of McMd::Analyzer implement an operation that calculates one or more physical properties and either outputs data or carries out a statistical analysis, or both. Each analyzer has an parameter named "interval" that specifies how often this operation should be invoked: Each analyzer is invoked when the global step counter is an integer multiple of its interval parameter. The interval for each analyzer must be a multiple of baseInterval.


2.4.1 Parameter Files: Syntax (Prev)         2.4 Parameter Files (Up)         2.4.3 Parameter Files: ddSim (Next)

Generated on Wed Mar 7 2018 12:59:45 for Simpatico by   doxygen 1.8.11