Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
Compiling HOOMD-blue

Table of contents:

Software Prerequisites

HOOMD-blue requires a number of prerequisite software packages and libraries. Detailed instructions on installing these on the various platforms that hoomd supports are included below: Build instructions for Linux and Mac..

  • Required to compile:
    • Python >= 2.3
    • boost >= 1.32.0
    • CMake >= 2.6.2
    • C++ Compiler (must be compatible with CUDA)
    • CUDA Toolkit >= 4.0
  • Useful developer tools
    • Git >= 1.7.0
    • Doxygen >= 1.7.5

Build instructions for Linux and Mac.

Detailed instructions are organized into separate pages below.

Build options

Here is a list of all the build options that can be changed by CMake. To changes these settings, cd to your build directory and run

 $ ccmake .

or run cmake-gui and point it to your build directory. After changing an option, press c to configure then press g to generate. The makefile/IDE project is now updated with the newly selected options.

  • BUILD_TESTING - Enables the compilation of unit tests
  • CMAKE_BUILD_TYPE - sets the build type (Makefile generation only, XCode and Visual Studio can change the build type from within their GUIs)
    • Debug - Compiles debug information into the library and executables. Enables asserts to check for programming mistakes. HOOMD-blue will run very slow if compiled in Debug mode, but problems are easier to identify.
    • Release - All compiler optimizations are enabled and asserts are removed. Recommended for production builds: required for any benchmarking.
  • ENABLE_CUDA - Enable compiling of the GPU accelerated computations using CUDA
    • Requires the CUDA Toolkit to be installed
  • ENABLE_DOXYGEN - enables the generation of detailed user and developer documentation
    • Requires doxygen to be installed
    • Defaults to off if doxygen is older than 1.5.6. You can manually turn it on, but expect doxygen errors and possible missing output from the generated documentation.
  • ENABLE_OCELOT - compiles hoomd against ocelot instead of the CUDA runtime
  • ENABLE_OPENMP - enables the generation of a multi-core capable hoomd using OpenMP. Can only be enabled if your compiler supports OpenMP.
  • ENABLE_VALGRIND - (Linux only) Runs every unit test through valgrind for hardcore testing/debugging.
  • ENABLE_ZLIB - Links hoomd to libz (must be available) and enables direct writing of zlib compressed files from dump.bin
  • SINGLE_PRECISION - Controls precision
    • When set to ON, all calculations are performed in single precision.
    • When set to OFF, all calculations are performed in double precision.
    • Must be set to ON to enable the ENABLE_CUDA option (HOOMD-blue has not yet been updated to perform double precision calculations)

There are a few options for controlling the CUDA compilation.

  • CUDA_ARCH_LIST - A semicolon separated list of GPU architecture to compile in. Portions of HOOMD are optimized for specific hardware architectures, but those optimizations are only activated when they are compiled in. By default, all known architectures supported by the installed CUDA toolkit are activated in the list. There is no disadvantage to doing so, except perhaps a slightly larger executable size and compile times. The CUDA programming guide contains list of which GPUs are which compute version in Appendix A. Note: while sm_21 is a hardware architecture, nvcc does not treat it differently from sm_20. 21 should not be added to CUDA_ARCH_LIST.
  • CUDA_BUILD_CUBIN - Enables a display of register usage for each kernel compiled.
  • NVCC_FLAGS - Allows additional flags to be passed to nvcc.

The following are advanced variables, and thus will only show when CMake's advanced mode is turned on. You really shouldn't change these from their defaults unless you really know what you are doing.

  • ENABLE_STATIC - Controls the compiling and linking of static libraries
    • When set to ON, libhoomd is compiled as a static library and all other libraries (i.e. boost) are linked statically if possible.
    • When set to OFF, libhoomd is compiled as a dynamic library and all other libraries are linked dynamically if possible.
    • Note 2: ENABLE_STATIC defaults OFF and can only be set ON from the command line and when configuring a clean build directory. Example:
       ccmake -D ENABLE_STATIC=ON ../hoomd

Building a plugin for HOOMD-blue

There are several methods that can be used to build code that interfaces with hoomd.

Method 1: Build an executable that uses hoomd as a library

First, understand that building an executable linked to hoomd for the purposes of running a simulation is not a supported configuration. The developers will not respond to or fix bugs found while using such a setup. There are many levels of configuration and performance tuning that are handled at the python script level, and the C++ API is mainly designed to interface with python.

However, there are many cases when building a simple quick test executable is desirable (i.e. to test or debug a new feature that does not yet have a python interface). So a simple method to build such executables is provided.

To setup for use:

  1. Compile hoomd normally
  2. 'make install' hoomd to a desired location (i.e. your home directory)
  3. Add hoomd_install_location/bin to your PATH as usual
  4. Add `hoomd-config.sh --ldpath to your DYLD / LD library paths (if you compiled with ENABLE_STATIC=off)

Here is a short example program that does nothing except calculate lj pair forces once.

// include hoomd.h to get all of the built in hoomd classes
#include "hoomd/hoomd.h"
using namespace boost;

int main()
    const unsigned int N = 5000;

    boost::shared_ptr<ExecutionConfiguration> exec_conf(new ExecutionConfiguration(ExecutionConfiguration::GPU));

    // create a random particle system to sum forces on
    RandomInitializer rand_init(N, Scalar(0.2), Scalar(0.9), "A");
    shared_ptr<SystemDefinition> sysdef(new SystemDefinition(rand_init, exec_conf));
    shared_ptr<ParticleData> pdata = sysdef->getParticleData();

    shared_ptr<NeighborListBinned> nlist(new NeighborListBinned(sysdef, Scalar(3.0), Scalar(0.8)));

    shared_ptr<PotentialPairLJ> fc1(new PotentialPairLJ(sysdef, nlist));
    fc1->setRcut(0, 0, Scalar(3.0));

    // setup some values for alpha and sigma
    Scalar epsilon = Scalar(1.0);
    Scalar sigma = Scalar(1.2);
    Scalar alpha = Scalar(0.45);
    Scalar lj1 = Scalar(4.0) * epsilon * pow(sigma,Scalar(12.0));
    Scalar lj2 = alpha * Scalar(4.0) * epsilon * pow(sigma,Scalar(6.0));

    // specify the force parameters

    // compute the forces

To compile this sample (or any code written similarly), just run

$ g++ -o test test.cc `hoomd-config.sh --cflags --libs`

(obviously, this works on linux and mac only)

Method 2: Write a full-fledged plugin in python only

Some plugins can be implemented fully in python, providing high-level code for configuring or running simulations.

In order to use such a plugin, one must first:

  1. Compile hoomd normally
  2. 'make install' hoomd to a desired location (i.e. your home directory)
  3. Add hoomd_install_location/bin to your PATH as usual

Create a directory to contain the python module for the plugin:

cd hoomd_install_location/lib/hoomd/python-module/hoomd_plugins
mkdir plugin_name
cd plugin_name
touch __init__.py

Note: It is highly recommended that you develop your plugin in a directory outside hoomd_install_location and using a revision control software. You wouldn't want to loose the code you've written when hoomd is uninstalled! In this case, you can just copy the module to the hoomd-plugins directory to install it.

cp -R plugin_name hoomd_install_location/lib/hoomd/python-module/hoomd_plugins

Once the plugin is written and installed, it can be used in a hoomd script like so:

from hoomd_script import *
from hoomd_plugins import plugin_name


Method 3: Write a full-fledged plugin with C++ code included

For high performance, execution on the GPU, or other reasons, part of a plugin can be written in C++. To write a plugin that incorporates such code, 'make install' hoomd as normal. Then copy the directory hoomd_install_location/share/hoomd/plugin_template_cpp to a new working space and modify it to implement your plugin. See the README file in that directory for full documentation. Examples of new pair and bond potentials are available in hoomd_install_location/share/hoomd/plugin_template_evaluators_ext

Documentation for HOOMD-blue v0.11.3
Generated on Wed Apr 10 2013 12:15:22 for HOOMD-blue by doxygen 1.8.0