4.5 Sub-Factories (Prev) 5 Developer Information (Next)

A module is a set of classes that were designed for a specific application area, packaged in a manner that is designed to facilitate use by people other than the developer.

Writing a Module

By convention, each module should be installed in a separate subdirectory of the modules/ directory of the relevant namespace level directory. A module named "stuff" that adds features to the mcSim and/or mdSim programs should thus installed in a directory src/mcMd/modules/stuff, and should contain source files for classes that are defined in the McMd namespace.

An example of complete McMd module is given in the directory src/mcMd/modules/slipLink directory. This module provides features that allow an mcSim Monte Carlo simulation to be used to simulate a model of polymer chains with transient slip-links between pairs of chains, for use as a coarse-grained model of entanglements in models with soft pair interactions that would otherwise allow polymers to cut throughou one another.

A module directory generally contains the following types of files:

Feature Classes: Source files for a set of C++ "feature" classes that implement new features, such as data analysis algorithms, Monte Carlo moves or molecular dynamics integrators. Each feature class is generally a subclass of an appropriate base class defined in the same namespace.
Factory Classes: Source files for more associated factory classes that can construct instances of the feature classes, so that they can be added to a simulation at run time by adding appropriate blocks to a parameter file. For example, and McMd module that provides classes that are subclasses of both McMd::Analyzer (data analysis algorithms) and subclasses of McMd::McMove (Monte Carlo moves) would also include source files for a subclass of McMd::Analyzer and a subclass of McMd::McMove.
Makefiles: Makefiles and makefile fragments within a module follow conventions completely analogous to those used throughout the simpatico source code. Name conventions in these files should be based on the assumption that the module will be installed in a specific subdirectory of a modules/ directory within the simpatico src/ directory tree, and will be compiled along with the rest of the simpatico source code.
Module Wrapper Class: A module wrapper class is a class that has one or more Factory classes as member variables and that encapsulates the code required to register each of the module factory class as a subfactory of the corresponding default factory class. By convention, a module wrapper class has a constructor that takes the main simulation object as an argument and that registers each such module factory class as a subfactory of the corresponding default factory class.

The module defined in src/mcMd/modules/slipLink contains source files that define two factory classes named SliplinkMcAnalyzerFactory and SliplinkMcMoveFactory, which are used to construct Analyzer and McMove feature classes, respectively. The implementation of the factory() member function of each such factory class can construct an instance of any of the feature classes of the appropriate type and return a pointer to this new object when passed the appropriate class name as an argument. See the source files for these classes for examples.

The sliplink module also contains a module wrapper class named SliplinkMcModule that is designed to integrates the module into an mcSim Monte Carlo simulation. This class has instances of SliplinkMcAnalyzerFactory and SliplinkMcMoveFactory as member variables. The constructor for this class, implemented in the file src/mcMd/moduless/sliplink/SliplinkMcModule.cpp, takes a reference to the parent McSimulation object as an argument and includes statements that register instances of the factory classes defined in the module as subfactories of the corresponding default factory classes.

Using a Module

To compile a simpatico program that uses a particular module, a user must generally go through the following set of steps:

Install the contents of the directory containing the module source files in the appropriate location within a modules/ directory in the users simpatico src/ directory tree.
Modify the sources.mk file in the relevant modules/ directory (i.e., mcMd/modules or ddMd/modules) so as to enable the new module to be compiled along with the rest of the source code. Notes about how to do this are given in the default copy of this sources.mk file.
Use the configure script or edit the appropriate config.mk files to enable any features of simpatico that are required for the module to function. In the case of the McMd sliplink module that is provided as an example, the user must uncomment the line that defines the macro MCMD_LINK in the file src/mcMd/config.mk before compiling to enable the use of slip links throughout the source code.
Modify the relevant main program so as to include the header file for the module wrapper class and to construct an instance of that class (see below for an example).
Compile all the code in the namespace containing the relevant simpatico program or programs, by entering "make mcMd" or "make ddMd".

Adding a Module to the Main Program

In order to use the slipLink module, which is designed to be used with the mcSim program, the user would have to modify the main MC program, in file src/mcMd/mcSim.cpp, by adding a line

#include <mcMd/modules/sliplink/SliplinkMcModule.h>

to include the header file for the module wrapper class, and adding a line

McMd::SliplinkMcModule module(simulation);

to create an instance of that class, in which simulation is the name of the main McMd::McSimulation object. Since the constructor for the module wrapper class takes the main simulation object as an argument, the SliplinkMcModule object must be constructed after the main simulation object but before reading the parameter file.

The resulting modified main program, with some comments removed, is shown below:

#include <mcMd/mcSimulation/McSimulation.h>
#include <mcMd/modules/sliplink/SliplinkMcModule.h>
int main(int argc, char **argv)
{
   #ifdef UTIL_MPI
   MPI::Init();
   McMd::McSimulation simulation(MPI::COMM_WORLD);
   #else
   McMd::McSimulation simulation;
   #endif
   // Create an instance of the module wrapper
   McMd::SliplinkMcModule module(simulation);
   // Process command line options
   simulation.setOptions(argc, argv);
   // Read parameters from default parameter file
   simulation.readParam();
   
   // Read command script to run simulation
   simulation.readCommands();
   #ifdef UTIL_MPI
   MPI::Finalize();
   #endif
   return 0;
}

Because the code to register any factory classes defined in a module is invoked in the constructor of the module wrapper class, the user merely has to create an instance of the module wrapper class in order to enable use of the corresponding module.

Note that users are free to modify the user copy of files that contain any file such as mcSim.cpp that contains the main program for a simulation, because these main simulation program files are not kept under repository control. Instead, the the default repository version of each such main program file is kept in a separate file named, e.g., mcSim.cpp_r, that is under repository control and a copy of the user file is created by the setup script by making a copy of the repository version. This scheme is used throughout the simpatico source code to distinguish user files that users might need to edit from default respository versions of the same file.

4.5 Sub-Factories (Prev) 4 Extending Simpatico (Up) 5 Developer Information (Next)