OpenMD is written in C++. Compiling is the process of turning this C++ code into instructions that the computer’s processor can understand.

We’re going to assume here that you have already built and installed all of the prerequisites. If you haven’t done that, go install all of the required stuff and come back. We’ll wait.

Now that you’ve got all the stuff you need, you are ready to compile OpenMD on any unix-like operating system (including Mac OS).  We’re going to assume that you know how to use a command line interface and are comfortable with basic unix commands. The commands below are written assuming you are using bash (or the Bourne-Again SHell). Setting environment variables in csh or tcsh is just a little bit different.

Basic build procedure

The most important thing to do is to download the latest release of the OpenMD code:

curl -o OpenMD-3.0.tar.gz http://openmd.org/releases/OpenMD-3.0.tar.gz

The recommended way to build OpenMD is to use a separate source and build directory; for example, OpenMD-3.0 and build. The first step is to create these directories:

tar zxf OpenMD-3.0.tar.gz
mkdir build

Now you need to run cmake to configure the build. The following will configure the build to use all of the default options:

cd build
cmake ../OpenMD-3.0

If you need to specify a particular compiler, you can do that with environment variables before the cmake line:

export CXX=/opt/local/bin/mpicxx
cmake ../OpenMD-3.0

If you need to specify an option, use the -D switch to cmake. For example, the following line sets the value of CMAKE_INSTALL_PREFIX and CMAKE_BUILD_TYPE:

cmake ../OpenMD-3.0 -DCMAKE_INSTALL_PREFIX=~/Tools -DCMAKE_BUILD_TYPE=DEBUG

We will discuss various possible options later.

At this point, it would be a good idea to compile OpenMD:

make

Have a coffee while the magic happens. If you have a multi-processor machine and would prefer an espresso, try a parallel build instead:

make -j 4

And finally, as root (or using sudo) you should install it:

umask 0022; sudo make install

Local build

With the right sort of environment variable magic (see below), you can actually use OpenMD straight from the build folder. But life is a bit easier if you install it somewhere, either system-wide or locally.

By default, OpenMD is installed in /usr/local on a Unix-like system. This requires root access (or sudo). Even if you do have root access, you may not want to overwrite an existing installation or you may want to avoid conflicts with a version of OpenMD installed by your package manager.

The solution to all of these problems is to do a local install into a directory somewhere in your home folder. An additional advantage of a local install is that if you ever want to uninstall it, all you need to do is delete the installation directory; removing the files from a global install is more work.

To configure cmake to install into ~/Tools/openmd-install, for example, you would do the following:

cmake ../OpenMD-3.0 -DCMAKE_INSTALL_PREFIX=~/Tools/openmd-install

Then you can run make and make install without needing root access:

make && make install

Troubleshooting build problems

  • CMake caches some variables from run-to-run. How can I wipe the cache to start from scratch?
    Delete CMakeCache.txt in the build directory. This is also a very useful file to look into if you have any problems.
  • What environment variables affect how OpenMD finds force field and data files?
    FORCE_PARAM_PATH – This environment variable is used by OpenMD to find the location of the data files used for force fields and atom sizes, etc. If you get errors about not being able to find some .txt files, then you should set this to the name of the folder containing files such as Amber.frc and element.txt. These are typically installed to /usr/local/openmd/forceFields

  • CMake honors user umask settings for creating directories.  To get predictable results please set umask explicitly before running the make install command.

Advanced build options

  • How do I do a debug build?
    -DCMAKE_BUILD_TYPE=Debug does a debug build (gcc -g).
    To revert to a regular build use -DCMAKE_BUILD_TYPE=Release.
  • How do I see what commands cmake is using to build?
    Run Make as follows:

    VERBOSE=1 make
  • How do I build the Doxygen documentation?If CMake found the “doxygen” program in your PATH, an optional build target called “doc” is created. If the Doxygen executable was not on the PATH, you will need to specify its location with -DDOXYGEN_EXECUTABLE=wherever. To build the documentation, type:
    make doc