4 Extending Simpatico (Prev/Up) 4.2 Base Classes (Next)

Before writing a user class, one must decide where the new class fits within the structure of the existing source code. Specifically, one must first choose in which namespace it should be defined, and where the code should be placed within a directory tree.

Namespaces and Directories

Every class and function in the simpatico source code is defined within one of five C++ namespaces, named Util, Simp, McMd, DdMd and Tools. The source code for each namespace is located within a corresponding corresponding subdirectory of the simpatico/src directory, as indicated in the following table:

Namespace	directory	purpose
Util	src/util	General scientific computing utilities
Simp	src/simp	Classes available in all simpatico programs.
McMd	src/mcMd	Classes used by mcSim and/or mdSim single-processor programs.
DdMd	src/ddMd	Classes used in ddSim parallel MD simulation program.
Tools	src/tools	Classes used in ppMd analysis program (under development).

The subdirectories of the src/ directory that each contain the source code for a namespace, such as src/util or src/mcMd, are referred to in what follows as a "namespace level" directories.

Every new user class must also be defined within one of these namespaces. The choice of namespace depends on the intended purpose of the class:

Classes that provide new simulation algorithms, analysis algorithms or file formats for use with the ddSim parallel program should be in namespace DdMd.
Classes that provide new simulation algorithms (MC moves or Monte Carlo integrators), analysis algorithms, or file formats for the mdSim and/or mcSim program should be in namespace McMd.
Classes that define potential energy functions or molecular species definitions should be placed namespace Simp.
Classes that provide new features for the ppMd postprocessor should be defined in namespace Tools.

The DdMd, McMd, and Tools namespaces are mutually exclusive. Classes defined in the DdMd namespace are available for use in the ddSim program, but are not accessible in the mcSim or mdSim single processor programs, or the ppMd postprocessor. Classes defined in the McMd namespace are accessible for use in either mcSim or mdSim, but not in ddSim in ppMd. Classes defined in the Simp namespace can, however, be made accessible for use in any simulation or analysis program.

As already noted, most types of user classes must be derived from a base class that represents a particular element of a simulation, such as an analysis or simulation algorithm. All of the relevant base classes are listed and discussed on the next page.

User File Directories

Header and source files for user classes must be placed in specific locations within the simpatico src/ directory tree, in directories that are provided for this purpose. Each namespace level directory contains two subdirectories named user/ and modules/ that are intended as locations for user files. Thus, for example, user classes that are defined in the DdMd namespace should be placed in either src/ddMd/user or src/ddMd/modules directory subtree.

Two slightly different methods of adding new classes are described in what follows, which differ in (among other things) where these files should be located. Specifically, different methods are recommended for:

Adding a few user classes for personal use (Method 1), or
Creating a module of related classes for distribution (Method 2)

The procedure for adding a few files for personal use (Method 1) is somewhat simpler, and is what most people should try first. Method 2 should be considered by developers who want to distribute a set of related classes in a form that is convenient for other potential users.

The choice of a location for user files should be governed by the following convention:

Classes that are intended only for personal use (method 1) should be placed in the user/ subdirectory of the relevant namespace level directory.
Modules that are intended for distribution (method 2) should be placed in the relevant modules/ subdirectory.

In method 2, each module should be placed in a separate subdirectory of the modules/ subdirectory of the relevant namespace level directory.

Most of the user/ and modules/ subdirectories of the namespace level directories in the simpatico repository contain no source files, and are provided only as locations for users to add their own files. The directory src/mcMd/modules, however, contains a subdirectory src/mcMd/modules/sliplink that contains a complete module, as an example.

4 Extending Simpatico (Prev/Up) 4.2 Base Classes (Next)