3 Source Code Overview (Prev) 5 Developer Information (Next)

Simpatico is designed to be extensible. Users may extend to any simulation program in the package by writing new C++ classes to implement new capabilities. We will refer to such new classes as "user classes". User classes may define new data analysis algorithms, Monte Carlo moves, molecule dynamics integrators, potential energy functions, molecular species, and file formats.

Most types of new user class must be subclasses of an existing abstract base class that defines the interface for a particular element of a simulation. For example, a class that implements a new Monte Carlo move for the mcSim Monte Carlo program must be defined in the McMd namespace and must be a subclass of the McMd::McMove base class. User classes are compiled using the same build system as that used to compile the base source code, and are compiled along with the base code. To make that possible, source files for user classes must be placed within one of several special directories within the simpatico src/ directory tree that are provided for this purpose. When a simulation is run, a user class is generally enabled by adding an associated parameter file block at an appropriate location within the simulation parameter file. Thus, for example, the appearance within of the parameter file block for a new subclass of McMove within the McMoveManager block of the parameter file for an mcSim simulation would instruct the mcSim program to add an instance of the new class to the list of Monte Carlo move objects from which it selects at random during the simulation.

Incorporating a new user class into a simpatico program thus generally involves three steps:

Write a new class. In most cases, thus must be a subclass of some existing base class.
Add the new class to the simpatico build system, so that it may be compiled.
Enable a simulation program to recognize the associated parameter file block.

Each of these steps is described in more detail in what follows. A new file can be added to the build system (step 2) simply by adding the name of the source file to a list in a file named "sources.mk" in the directory that contains the source file, as discussed here. To enable a simulation program to read the parameter file block associated with a new class, the user must generally modify the behavior of an assocaited Factory class that is responsible for parsing the relevant part of the parameter file. The simplest way to do this is to edit the source code of the Factory class, as discussed here.

The following pages describe procedures for adding user classes in more detail.

Contents: