2.12 Compile Time Options

2.11 Multi-System Simulations (Prev)         3 Source Code Overview (Next)

The source code for all of the simpatico programs contain some features that be enabled (included in the executable) or disabled (excluded from the executable) when the program is compiled via conditional compilation of some parts of the code. This page lists these optional features, and explains how they may be enabled or disabled.

When an optional feature that is disabled by default is enabled, the build system normally adds a suffix to the name of the resulting executable to indicate the additional feature. Users must thus understand the relationship and file name suffixes in order to invoke the resulting executable file by the correct name.

Configure script

The simplest way to enable or disable features is by using a configure script to set options before compiling or recompiling a program. The root simpatico/ directory and each build directory (bld/parallel, bld/serial or src/) each contain a bash script named "configure". The configure script in each build directory must be invoked from the root of that build directory (the directory that contains the script), and can be used enable or disable features of code built in that build directory, without effecting code built in other directories. The configure script in the simpatico/ root directory must be invoked from the root directory, and can be used to simultaneously enable or disable features in both the bld/serial and bld/parallel directories (i.e., to both serial and parallel programs).

All of the configure scripts have a similar command line interface. Each optional feature of simpatico is associated with a specific single character unix command line option. Each such command line option takes a value 1 or 0 as a required argument to indicate that the associated feature should be enabled (1) or disabled (0). Thus for example, to disable debugging (option -g) and enable 3-body angle potentials (option -a) one would invoke

> ./configure -g0 -a1

One would invoke this command from a build directory to apply these changes only to code built in that directory, i.e., in the bld/parallel or bld/serial directory for out-of source builds of parallel and serial programs, respectively, and in the src/ directory for in-source builds. Invoking the same command from the simpatico/ root directory would apply this set of changes to code built in both bld/serial and bld/parallel directories. As shown by this example, more than one feature may be enabled or disabled in a single command. The configure scripts in the build directories and the configure script in the simpatico/ directory accept the same set of options, with one exception: the script in the simpatico/ directory does not accept the -m option that enables or disables MPI.

Each such option of a configure script in a build directory causes the script to edit one of several configuration files named "config.mk" in that build directory, by either uncommenting (to enable) or commenting out (to disable) the definition of an associated makefile variable. Generally, each such makefile variables has the same name as a corresponding C++ preprocessor macro that is used to control conditional compilation in C++ files. It is also possible to enable or disable features by manually editing these files.

The configure script in the simpatico/ root directory works by simply calling the configure scripts in the bld/serial and bld/parallel directories. Calling the simpatico/configure script with some set of options is thus completely equivalent to calling the configure scripts in bld/serial and bld/parallel with the same set of options.

Overview

The following table lists the most important compile time options. Specific optional features are each discussed in more detail below. Each row of the table lists (in order):

• description: description of the feature
• option: the associated command line option for the configure script
• default: whether the feature is ON or OFF by default
• suffix: the suffix that is added to executable names if the default setting is modified
• variable: the name of the associated makefile variable and C++ preprocessor macro (these are always the same)
• file: path of the config.mk file that contains a definition of the makefile variable, relative to the root of the build directory

The optional features are:

description	option	default	suffix	macro	file
Debugging - enables additional error checks	-g	OFF	_g	UTIL_DEBUG	util/config.mk
Message Passing Interface (MPI)	-m	OFF / ON	_m	UTIL_MPI	config.mk
Bond potentials	-b	ON	_nb	SIMP_BOND	simp/config.mk
Angle potentials	-a	OFF	_a	SIMP_ANGLE	simp/config.mk
Dihedral potentials	-d	OFF	_d	SIMP_DIHEDRAL	simp/config.mk
External potentials	-e	OFF	_e	SIMP_EXTERNAL	simp/config.mk
Links (mutable bonds)	-l	OFF	_l	MCMD_LINKS	mcMd/config.mk
Free energy perturbation	-f	OFF	_f	MCMD_PERTURB	mcMd/config.mk
Modifiers	-u	OFF	_u	DDMD_MODIFIERS	ddMd/config.mk

Optional features

We now discuss each option in a bit more detail:

• Debugging (UTIL_DEBUG): The debugging feature enables a variety of run-time sanity checks that are disabled for speed when debuggin is disalbed. Among other things, it turns on automatic run time checking of array bounds in the container classes that are used throughout the code. These additional checks slows down execution very slightly, but are often extremely helpful in tracking down bugs or building confidence in correctness during development and debugging of new features. This feature effects code in every namespace and program.
• Message Passing Interface (UTIL_MPI): The MPI feature must be enabled in order to build any parallel program. Specifically, it must be enabled to build either the ddSim MD program, which uses a domain-decomposition algorithm, or the multi-processor versions of mcSim and mdSim, which allow "embarrassingly parallel" MC and MD simulations with one system on each processor. MPI is disabled by default in the bld/parallel directory, which is intended to be used to build parallel programs, and disabled by default in the bld/serial directory, which is intended to be used to build the single processor mcSim and mdSim programs. It is also disabled by the default in the src/ directory (i.e., in in-source builds). The makefile system is designed to make it unnecessary for users to explicitly enable or disable MPI when code is built using the makefile targets mcMd, mcMd-mpi, and ddMd in the makefiles in each of these build directories (i.e., in bld/parallel, bld/serial, and src/ directories), because these targets all explicitly enable or disable MPI, as appropriate, before compiling any code. Specifically "make mcMd" explicitly disables MPI and the other two targets enable MPI in bld/parallel before compiling any source files or building libraries. The only time that users should have to invoke configure with the -m option is if they want to compile MPI-enabled or MPI-disabled versions of specific source files or namespace level libraries in the src/ directory (which can be used to compile either parallel or serial code) by invoking make from a namespace or lower-level subdirectory. When MPI is enabled, a suffix _m is added to the names of MPI-enabled versions of the libraries libutil.a, libinter.a and libmcMd.a, and to the names of the mcSim and mdSim executables. No such suffix is added to the name of the libDdMd.a library or ddSim executable, because MPI is not an optional feature of the domain-decomposition code, but is required for this code to compile and function.
• Bond potentials (SIMP_BOND): This option enables the inclusion of energies and forces arising from covalent two-body potentials in all programs. This is enabled by default.
• Angle potentials (SIMP_ANGLE): This option enables the inclusion of covalent three-body bending potentials in all programs. This is currently disabled by default.
• Dihedral potentials (SIMP_DIHEDRAL): This option enables the inclusion of covalent four-body dihedral potentials in all programs. This is disabled by default.
• External potentials (SIMP_EXTERNAL): This option enables the inclusion of one-particle external potentials in all programs. These are potential energies that depend on the position and type of an atom. This is disabled by default.
• Links (MCMD_LINK): This feature enables the inclusion of mutable bonds, that can be created or destroyed during the course of a simulation, within mcSim and mdSim programs. Mutable links can use the same set of interaction potentials as covalent bonds, but require a different set of data structures to keep track of their creation and destruction. They were introduced to allow simulation of transient network models with reactions that create or destroy bonds. There is no analogous run-time feature in the DdMd namespace, but it would relatively easy to create one as a Modifier (see below). Links are disabled by default.
• Free energy perturbation (MCMD_PERTURB): This feature allows a user to use a single parameter file to initialize embarassingly simulations of multiple systems with slightly different values for one or more parameters. This arrangement is used in algorithms such as free energy perturbation calculations and replica exchange simulations. This feature is only available in the McMd namespace, for use in parallel versions of mcSim and mdSim. There is no analogous feature in the DdMd namespace or ddSim program. This feature is disabled by default, and is functional only if MPI is also enabled.
• Modifiers (DDMD_MODIFIERS): This feature enables the addition of modifiers (subclasses of DdMd::Modifier) to a ddSim program. Modifiers are classes that can take essentially arbitrary actions modify the state of the system within the main integration loop of a simulation, and thereby change its time evolution. When modifiers are enabled, the parameter file may contain an optional ModifierManager{...} block immediately after the Integrator block. If this feature is enabled at compile time but this block is absent from the parameter file, it will be assumed that there are no modifiers.
• Molecules (DDMD_MOLECULES): This feature enables data structures that associate each atom with a parent molecule. This information is not used or required by the force or integration algorithms, but is useful for some types of data analysis. Defining DDMD_MOLECULES associates a DdMd::AtomContext struct with each atom. This struct contains an integer id for the molecule to which the atom belongs, and id for the species of molecule, and an index for the position of the atom within the molecule. Meaningful values are set for these indices only if this information is included in the input configuration file. File formats that include this information may be selected by passing the SET_CONFIG_IO command is passed an argument "DdMdConfig_Molecule" or "DdMdOrderedConfigIo_Molecule" before invoking the READ_CONFIG command.

Scope conventions

The names of the makefile variables associated with different compile time options, such as UTIL_DEBUG, contain suffixes that identify which namespaces they may appear in or affect. The source code for simpatico simulation programs is divided into four namespaces named Util, Simp, McMd and DdMd. Classes in these namespaces are located in corresponding directories src/util, src/simp, src/mcMd, and src/ddMd, respectively. Some of these namespaces depend on others: A namespace A is said to depend upon a second namespace B if some code in the namespace A uses classes or other names defined in the namespace B. There is a strict hierarchy of dependencies among namespaces: The Util namespace does not depend on any other namespace. The Simp namespace depends only upon Util. The McMd and DdMd namespaces each depend on Util and Simp, but not on each other.

The names of makefile variables that are used to enable optional features all have prefixes UTIL_, SIMP_, MCMD_ or DDMD_ that reflect their scope, using the same conventions as those used for dependencies among source code files in different namespaces. Preprocessor macros whose names begin with DDMD_, which are defined in src/dMd/config.mk, only appear in the DdMd namespace (the src/ddMd directory). Preprocessor macros whose names begin with MCMD_, which are defined in /src/mcMd/config.mk, only appear in the source code of the McMd namespace. Macros with names that begin with SIMP_ are defined in simp/config.mk, and may appear or be included in the source code of the Simp, McMd and DdMd namespaces (the src/simp/, src/mcMd/, and src/dMd/ directories), but not in the Util namespace (the src/util directory). Macros with names that begin with UTIL_ are global: They can appear or be included in the source code in any namespace.

File name suffixes

When an executable is built with one or more of these optional features enabled, the makefile system appends a set of suffixes to the names of the executable file that identify which features are enabled in that executable. This convention is intended to make it easy for users to maintain different executables with different features enabled. The suffix for each optional feature is listed in the above table. Each file name suffix consists of an underscore followed by a one or two character code. In most cases, the suffix character is the same as the name of the command line option used by the configure script to enable or disable the feature.

For example, the suffix associated with the debugging feature is "_g". A development version of the mcSim executable, which was compiled with debugging enabled, but no other optional features, would thus be named "mdSim_g". The default name version of a multi-processor MPI-enabled version of mcSim with angle and dihedral potentials would be "mcSim_m_a_d".

The same file name suffixes are also appended to the base names of libraries that contain code with particular features enabled. Thus, for example, a version of the libutil library that was compiled with MPI and debugging enabled would be called libutil_m_g.a by default.

Suffixes are added to executable and library names for optional non-default compile-time features that affect code in that executable or library. When MPI is enabled, however, no "_m" suffix is added to the name of the ddSim executable or the libddMd.a library, because MPI is not an optional feature, but is required for ddSim to function.

Boundary Type

The choice of lattice system for the periodic unit cell (i.e., cubic, tetragonal, or orthorombic) is defined in Simpatico by a C++ typedef named Util::Boundary. This typedef is defined in the file src/mcMd/boundary/Boundary.h. By default, Util::Boundary is defined to be a synonym for the class Util::OrthorhombicBoundary, which defines a unit cell with three orthogonal axes of arbitrary length. Throughout the source code, however, the class that represents the periodic boundary conditions is referred to only via the typedef Util::Boundary, rather than by an explict class name, such as Util::OrthorhombicBoundary. This is designed to make it easy for users to change the unit cell type at compile time by changing this typedef to refer to, for example, Util::MonoclinicBoundary, and recompiling the program.

We have chosen to use a typedef rather than a polymorphic classes for the boundary conditions because of concerns about efficiency. The Boundary class provides methods that calculate separations using the minimum image convention, which are called repeatedly in the inner loops of both MD and MC simulations. The use of a polymorphic class with virtual functions would be the most flexible solution. This would allow the user to choose a boundary type at run time, but would also prevent inlining of the minimum image separation calculations. This is one case where we chose to favor efficiency over run-time flexibility.

2.11 Multi-System Simulations (Prev)         2 User Guide (Up)         3 Source Code Overview (Next)