CAMPARI Installation

Coding Style:

CAMPARI is - with the exception of the use of external libraries - written entirely in Fortran which utilizes some features of the 2003 standard but is otherwise compliant with the 90/95 standard. The 2003 features employed in CAMPARI are mostly restricted to class-type structures and dynamically sized arrays.
CAMPARI uses - with very few exceptions - dynamic memory allocation and calculations on small systems usually do not require more than a few MB of memory. This is implemented exclusively via arrays which have the ALLOCATABLE attribute and not through pointers. However, the memory footprint for large systems may grow unfavorably with system size both in terms of stack usage and in terms of total memory usage. In case of stack overflows, CAMPARI will typically exit with an otherwise undocumented segmentation fault (this behavior is compiler-dependent and can often be remedied by manually increasing stack size for the shell from which CAMPARI is started [ulimit]). CAMPARI uses stack-allocated variables in particular in the inner loops of dynamics-based calculations. For total memory exceptions, disabling some of the calculation's optional features will be the only solution.
The source code frequently contains comparisons of floating point numbers which entails all the possible pitfalls of intrinsically inaccurate floating point arithmetics. Only some sensitive operations are made safe (precision-tolerant). The code assumes double precision throughout so aggressive optimization strategies of modern compilers have to be evaluated carefully (not all algorithms may tolerate precision loss, and will respond with warning messages that may or may not imply that results are compromised). Basically, in most cases CAMPARI silently relies on hardware and compiler to implement floating-point arithmetics standards such as IEEE 754-2008.
Lastly, for efficiency reasons, the code attempts to provide vectorizable loops in crucial execution paths as much as possible. This is the simplest form of parallelism and supported (often by default) by almost all modern compilers. Vectorization increases time required for compilation, but can very substantially reduce runtime. It is important as well to point out that it in general increases the accuracy of sums accumulating very many small floating-point numbers (as is almost universally the case in the types of applications CAMPARI supports).
In summary, the compiler needs to be able to handle the following:
  • Allocatable arrays of variables of derived type which contain further allocatable arrays of built-in types
  • Preprocessing of C-style directives (#ifdef ... #endif and so on)
  • Beyond standard math functions, support for built-in functions floor, ceiling, and erf (the latter is not formally part of the 2003 standard)
  • A way to set default floating point constants to double precision (this is crucial to avoid down-conversion of constants which may cause major problems in algorithms relying explicitly on double precision)

Compiler Optimization:

The code was developed on UNIX systems with the Intel Fortran compiler and mostly run on Intel CPUs. This implies that executables generated with this particular combination of compiler and processor tend to run faster than alternatives (different processor or different compiler). Users should keep this in mind. Publicly available benchmarks of Fortran compilers (such as those available at polyhedron) can be useful but tend to have less than the generality one would expect due to software specificity, choice of compiler flags, and so on. As mentioned above, aggressive optimization studies will have to be evaluated for each calculation.

Installation Requirements:

  •  Unix-type OS (note that CAMPARI has been compiled on Linux, Windows, and MacOS), but not on any other OS such as Solaris, or Irix and not on any chip architecture but recent Intel and AMD processor lines (for example not on PowerPC, Compaq (DEC) Alpha, ...))
  •  A Fortran03 compiler with the above attributes (we have used Intel, SUN, and GNU compilers)
  •  For the MPI version: a Fortran03-compiled MPI implementation, against which to link the code (we strongly recommend OpenMPI, and this is often part of the default system installation)
  •  For writing xtc-files: a properly compiled XDR-library (see here) to link against, which includes Fortran bindings
  •  For using particle-mesh Ewald summation (see here): a properly compiled FFTW (this may be available as part of your system installation and can then be linked by passing '-lfftw3' to the linker)
  •  For using the preconditioned SHAKE algorithm to maintain holonomic constraints (see here) or principal component analysis (see here): a properly compiled LAPACK -library to link against (for example version 3.2.2 with double precision routines → on UNIX, this often this will be part of the default system installation and may be activated by passing '-llapack' to the compiler)
  •  For writing NetCDF-files: a properly compiled NetCDF-library (see here) to link against which includes Fortran 90 API (developed and maintained by Unidata; this may be available as part of your system installation and can then be linked by passing '-lnetcdf -lnetcdff' to the linker)
  •  A tar-ball (archived) or similar full copy of the CAMPARI distribution
  • Possibly a C- and C++-compiler to compile auxiliary libraries

Getting CAMPARI:

The obvious first step is to extract the archive to your favorite destination (${CAMPARI_HOME}) or to get a copy through CVS if you are connected to a current CVS repository. Unlike most current Linux/Unix software, CAMPARI does not employ an explicit build system or configuration tool (e.g., autoconf/automake or cmake) beyond a simple Makefile. The compilation task is so uniform that the required settings are small in number. The downside is that portability has to be ensured explicitly by the user by providing the correct flags to the compiler. This "localization" happens in a dedicated file edited by the user and the global Makefile expects this file to be called "Makefile.local" and to be located in the source-subdirectory of the main distribution tree. Hence:

    [user {subdir}]$ cvs checkout campari

Or:

    [user {subdir}]$ tar -xjvf campari.tar.bz2

Then:

    [user {subdir}]$ cd campari/source
    [user source]$ touch Makefile.local

Makefile:

A Makefile is nothing but an advanced shell script (using its own scripting language) containing a series of compilation and linking commands to produce an executable from a set of sources. One of its core features is to use time stamps on source files to allow for safe incremental compilation (i.e., to re-compile only those source files that have changed since the last compilation and to make sure all libraries and binaries are up-to-date). The global Makefile is located in the source-directory and uses two auxiliary files: the aforementioned "Makefile.local" and a file called "DEPENDENCIES", which has to reside in the source-directory as well. The latter is automatically generated from the source files by executing:

    [user source]$ ./make_dependencies.sh .

The customization in "Makefile.local" requires two elements: 1) defining directories for the local CAMPARI distribution, and 2) defining compilers and compiler flags to be used:
Example of location-specific parameters in "Makefile.local":
-----------------------------------------------------------
CAMPARI_HOME=/software/campari

# x86_64 locale (Default)
ARCH=x86_64
BIN_DIR=${CAMPARI_HOME}/bin
LIB_DIR=${CAMPARI_HOME}/lib
SRC_DIR=${CAMPARI_HOME}/source
#
# compiler settings
WARNFLAGS= -warn alignments -warn declarations -warn usage -warn general -warn ignore_loc -warn truncated_source -warn uncalled -warn unused
FF =ifort
LFLAGS =-O3
EXTRA_LIBS=/software/NetCDF/Intel/lib/libnetcdff.a /software/NetCDF/Intel/lib/libnetcdf.a /software/xdr/x86_64/libxdrf.a /software/fftw/lib/libfftw3.a
FFLAGS =-DLINK_NETCDF -DLINK_XDR -DLINK_LAPACK -DDISABLE_FLOAT -DLINK_FFTW -I/software/fftw-3.2.2/include -I/software/NetCDF/netcdf-4.1.1/include ${WARNFLAGS} -axSSE4.2 -xSSE4.2 -llapack
MPIFF =mpif90 # wrapper around ifort
MPILFLAGS =-O3
MPIFFLAGS =${FFLAGS}
MPIEXTRA_LIBS=${EXTRA_LIBS}
-----------------------------------------------------------

The above "Makefile.local" illustrates settings for a standard installation using Intel compilers. Note that the settings for CAMPARI_HOME and SRC_DIR have to correspond to the extracted archive (see above) while those for BIN_DIR and LIB_DIR are arbitrary. The global Makefile contains a fair amount of default settings which can be used as inspiration for customizing "Makefile.local" to a different compiler. Note that these default flags are always passed to the compiler, but that not every compiler has consistent naming of required flags achieving the same thing. It therefore may be necessary to edit the Makefile itself and (un)comment the choices for variables GNUDEFAULTS, GNUDEBUG, SUNDEFAULTS, SUNDEBUG, INTELDEFAULTS, and INTELDEBUG as needed. The reason that these settings are not migrated into "Makefile.local" is that there they are not optional and resultant code may fail or function inefficiently if these options are changed for the respective target compiler.
One note on the passed flag DISABLE_FLOAT: for a while, CAMPARI could be compiled globally as a single-precision variant by omitting this flag. This is presently not possible. Single precision floating point arithmetics are only permissible in certain computations and the necessary effort to identify just the eligible ones has simply not been undertaken. That is why DISABLE_FLOAT should always be passed to the compiler (even though it presently has no effect).

Standard (non-MPI) Installation:

To actually compile the code for serial execution, first create the directories ${LIB_DIR}/${ARCH} and ${BIN_DIR}/${ARCH} if they do not exist already (this follows the example above):

    [user source]$ mkdir ../lib
    [user source]$ mkdir ../lib/x86_64
    [user source]$ mkdir ../bin
    [user source]$ mkdir ../bin/x86_64

Now do:

    [user source]$ make campari

Given the warning messages requested, you should see warnings about the use of intrinsic erf() in Fortran 2003 code, potential warnings about unused variables but no major or other minor complaints. The compilation takes a while to complete since the optimization procedures (vectorization, etc ...) require variable dependency checks in complicated loop structures which often will require a lot of physical memory and CPU time.
The processes executed by the Makefile will compile all module definition files mod_bar.f90 into module information files ${LIB_DIR}/${ARCH}/bar.mod as well as regular module object files ${LIB_DIR}/${ARCH}/bar.o. Similarly, source-files foo.f90 will be compiled into object files ${LIB_DIR}/${ARCH}/foo.o. Once finished, the Makefile will create a library out of all the object files called lcampari.a in ${LIB_DIR}/${ARCH}, and finally link the actual executable ("campari" in ${BIN_DIR}/${ARCH}/). In the future, after applying certain changes to the source code, CAMPARI may be compiled incrementally by executing the same command again. Note that if heavily used module files are changed, many source files will have to be re-compiled (see DEPENDENCIES).

Linking against external libraries:

In general, external libraries are necessary to support certain features within CAMPARI as outlined above. The user may instruct the preprocessor to include the respective sections of code by passing flags to it: LINK_FFTW to link against the library for fast discrete Fourier transforms, LINK_LAPACK to link against the LAPACK linear algebra library, LINK_XDR to link against compression routines needed to write trajectory data in .xtc-format, and LINK_NETCDF to link against routines to create NetCDF data archives (see example "Makefile.local" above and section on installation requirements). For successful compilation and linking, two extensions are required:
  1. Pass the environmental LINK_FOO to the compiler (flag -DLINK_FOO).
  2. Point the compiler to the library using the EXTRA_LIBS macro in Makefile.local (e.g., EXTRA_LIBS=${whatever_path}/libfoo.a)
Note that the order in which external libraries are linked may matter. A symbol occurring in a library function called by a CAMPARI function must be defined after the library function has been defined. This means that if the symbol is defined in "libfoo1.a" and the library function in "libfoo2.a" the correct order of linking is "libfoo2.a libfoo1.a". Normally, an external library should of course contain all its symbols.
The XDR library requires special comments: CAMPARI supports .xtc-files for writing and reading trajectory data. These highly compressed binary files are employed by the GROMACS simulation software which has by now incorporated its own XDR support due to a lack of an officially supported distribution (original credits to Frans van Hoesel). For reference, CAMPARI provides a minimal XDR distribution in the root directory: "xdr_basic.tar.bz2". Unpack this archive, edit the Makefile and compile it (see supplied README.txt).

MPI installation:

The Message Passing Interface (MPI) is a standard for creating parallel software, i.e., programs running simultaneously in multiple instances on different processors or processor cores. These instances exchange information by passing messages to one another. This is what MPI libraries accomplish.
Changes from serial to parallel versions of a program are often relatively large since meaningful parallelism requires exchange and synchronization of information between the individual instances as well as ordering mechanism for sensitive operations (writing to files, etc ...) which may otherwise entail race conditions. The Makefile therefore treats the serial and parallel version independently with completely separate directories for all libraries and binaries.
To install CAMPARI's MPI version, install an MPI distribution first (like OpenMpi), if it is not already installed on your system. Usually, when building MPI from source, there is a chance to supply a Fortran90 compiler, which will then generate an MPI-compiler (like "mpif90") which is automatically linked against that MPI library. It is crucial to either compile the MPI library yourself or to create an appropriate wrapper compiler by passing on additional flags and libraries to MPIEXTRA_LIBS and MPIFFLAGS in "Makefile.local". Precompiled libraries such as those found in RPMs may not provide adequate wrapper compilers on their own. To figure out which compiler was used to compile the libraries, "mpif90 -showme" is a command that might work.
Using the above example, next create a new directory (if it does not exist already):

    [user source]$ mkdir ../lib/x86_64/mpi

Now do:

    [user source]$ make campari_mpi

This will compile all module definition files mod_bar.f90 into module information files ${LIB_DIR}/${ARCH}/mpi/bar.mod as well as regular module object files ${LIB_DIR}/${ARCH}/mpi/bar.o. It will furthermore compile all source-files foo.f90 into ${LIB_DIR}/${ARCH}/mpi/foo.o, create a library out of all the object files called lcampari_mpi.a in ${LIB_DIR}/${ARCH}/mpi and finally compile and link the actual executable ("campari_mpi" in ${BIN_DIR}/${ARCH} which can be used in conjunction with mpirun).
As you can tell, all object files (and even the Fortran90 module declarations) are kept in separate directories such that both targets can be dealt with independently.
Note that CAMPARI does not (yet) support standard domain-wise parallelization as most other molecular simulation packages (see here).

Cleaning up:

Execute:

    [user source]$ make clean

to delete all objects and libraries in ${LIB_DIR}/${ARCH} and ${LIB_DIR}/${ARCH}/mpi, respectively and also wipe out the binaries "campari" and "campari_mpi" in ${BIN_DIR}/${ARCH}. Note that it is possible to support multiple architectures within the same tree, since ${ARCH} will be different, and only the "currently active" distributions will be cleaned up (or compiled for that matter). Note that this will also delete copies of module files (or symbolic links to module files) belonging to other software libraries, which feature the same ending. This situation may arise when trying to simplify the linking process for certain compilers.

Execute:

    [user source]$ make objclean

to just delete all object files and libraries.


Design downloaded from free website templates.