University of Michigan Logo
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.

  • Required to compile:
    • Python >= 2.6
    • boost >= 1.39.0
    • CMake >= 2.6.2
    • C++ Compiler
    • CUDA Toolkit >= 5.0
  • For parallel builds
    • MPI (generic, or with CUDA-Support: MVAPICH2 >= 1.8, OpenMPI >= 1.7)
  • Useful developer tools
    • Git >= 1.7.0
    • Doxygen >= 1.8.5

For a discussion of which kind of MPI library is best for your situation, see Best practices. See Compiling with MPI enabled for instructions on building an MPI enabled hoomd.


Build instructions

Detailed instructions are organized into separate pages.


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 .

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 (case sensitive)
    • 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.
    • RelWithDebInfo - Compiles with optimizations and debug symbols. Useful for profiling benchmarks.
    • 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. Defaults on if the CUDA toolkit is found. Defaults off if the CUDA toolkit is not found.
  • ENABLE_DOXYGEN - enables the generation of detailed user and developer documentation (Defaults off)
  • ENABLE_OCELOT - compiles hoomd against ocelot instead of the CUDA runtime
  • ENABLE_VALGRIND - Runs every unit test through valgrind.
  • 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.
  • ENABLE_MPI - Enable multi-processor/GPU simulations using MPI
    • When set to ON (default if any MPI library is found automatically by CMake), multi-GPU simulations are supported
    • When set to OFF, HOOMD always runs in single-GPU mode
  • ENABLE_MPI_CUDA - Enable CUDA-aware MPI library support
    • Requires a MPI library with CUDA support to be installed
    • When set to ON (default if a CUDA-aware MPI library is detected), HOOMD-blue will make use of the capability of the MPI library to accelerate CUDA-buffer transfers
    • When set to OFF, standard MPI calls will be used
    • Warning: Manually setting this feature to ON when the MPI library does not support CUDA may result in a crash of HOOMD-blue

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: nvcc does not treat sm_21 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.

Building a plugin for HOOMD-blue

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

Method 1: 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
  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

You should develop your plugin in a directory outside hoomd_install_location and using a revision control software. You would not 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
init.whatever(...)
plugin_name.whatever(...)

Method 2: 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