To construct a complete simulation a user must either write a customized subclass of McSystem or MdSystem, or use one of our examples of such a subclass. The job of such a user-defined subclass is to implement a mechanism to add objects to the simulation that represent optional elements, i.e., elements that are needed in some simulations but not others. To create an executable program, a user will also also needs to write (or use one or our examples of) a very short main program, as discussed below.
Examples of user-defined subclasses of McSystem and MdSystem, respectively, are are provided in:
The main program must create an instance of a user-defined subclass of McSystem or MdSystem, and invoke methods of that object to read the required input files and to run the simulation. The essential lines of of our example program for MC simulation thus look like this:
int main { MyMcSystem sys; \\ Read the parameter file from standard input sys.read(stdin) \\ Run the simulation sys.run() }
The parameter file contains all the parameters required by a simulation, including both physical parameters such as the temperature and potential energy parameters, and instructions for the simulation algorithm, such as the choice of Monte Carlo moves to be used for a Monte Carlo simulation or the choice of time step for an MD simulation.
The configuration file contains the current configuration of the system, including the size and dimensions of the simulation box, all of the particle positions, and the number of molecules of each species.
Access to a subclass of Species, McMove, or Diagnostic is provided by including the subclass header in the definition of a user-defined subclass of McSystem or MdSystem, and by adding a few lines of code to one of three factory functions, named speciesFactory, mcMoveFactory, and diagnosticFactory. Each of these factory functions is a virtual function that takes a subclass name string as a parameter and (if the class name is recognized) returns a base class pointer to a new instance of the desired subclass. The factory functions are invoked by methods of System and McSystem methods that read the input parameter and configuration files, and are used to create new instances of classes whose names are specified in an input file. The implementation of each factory function thus defines a set of subclasses of Species, McMove, or Diagnostic whose names will be recognized if encountered in the appropriate input file. The content of the actual input files defines what objects of will actually be instantiated and used in a simulation.
The parameter file for an MC simulation contains a list of what Monte Carlo moves that should be used in the simulation. Each Monte Carlo moves is represented by a section of the file that starts with the name of the corresponding subclass of McMove, followed by any parameters required by that type of move (e.g., the maximum displacement for a simple single particle displacement move). To add a specified Monte Carlo move to a simulation, while reading that part of the parameter file, the McSystem::read(FILE *) method reads the name of a subclass of McMove, and then passes it to the virtual mcmoveFactory() method. If the mcmoveFactory() method recognizes the McMove subclass name, creates an object of that subclass and returns a pointer to the new object. The McSystem read() method then reads the probability per elementary step that the move will be executed, and then (indirectly) invokes the read() method of the newly created McMove object to read in whatever parameters that type of Monte Carlo move may need.
The parameter file format for both MC and MD simulations also contains an analogous (possibly empty) list of Diagnostic objects that should be added to the simulation. Each of these is also identified by a class name, followed by whatever parameters are required by that type of Diagnostic object. A Diagnostic object represents a file output and/or data analysis operation that must be carried out at a specified frequency, specified as a number of elementary MC moves or MD time steps. A Diagnostic may either dump data to a file or carry out some on-the-fly statistical analysis (e.g., evaluting an average value for a specific quantity) and output results at the end of the simulation, or both.
The configuration file for a MC or MD simulation contains a similar sequence of sections that represent different molecular species. Each of these is identified by the name of a subclass of Species, followed by the number of molecules of that species in the System, and by any structural parameters required to define the structure of the species (i.e., the number of particles per chain in a linear homopolymer species).
To make it easy to recompile a simulation with a different choice of potentials, the classes that represent the nonbonded potential and the covalent bond potential are referred to throughout the core classes via typedefs named PairPotential and BondPotential, which can be redefined. These typedefs are defined in the header files src/base/PairPotential.h and src/base/BondPotential.h, which also include the header files for the actual pair and bond potential classes (e.g., LJPair and HarmonicBond). See the documentation for these typedefs for an explanation of how to recompile with different potential classes by changing a few lines in each of these header files.
> make all
This documentation is generated by dOxygen. To regenerate all of the API documentation from comments in the source code, enter the command
> make doc
from within the src directory. The html documentation is deposited in the doc/api directory. Entering 'make cleandoc' from the src directory will remove all the html documentation.
Contributors:
1.4.7