Compiling HOOMD

Table of contents:

• Software Prerequisites
• Building on Windows
• Building on linux
• Building on Mac OSX
• Build options

---

Software Prerequisites

HOOMD requires a number of prerequisite software packages and libraries to be compiled.

• Python >= 2.3
• boost >= 1.32.0
• CMake >= 2.6.0
  • >= 2.6.2 is recommended because of numerous bug fixes
• Compiler to build source
  • gcc on Linux
  • Visual Studio Express 2005 on Windows XP
  • all code is standard c++ and should work on nearly any other (recent) compiler
  • note: Visual Studio 9 (aka 2008) should work with CUDA 2.1 and boost 1.37, but this configuration has not yet been tested
• CUDA Toolkit and the appropriate NVIDIA display driver:
  • optional, but needed to enable GPU support
• Subversion
• Doxygen >= 1.5.6
  • optional but needed if you wish to build the detailed developer documentation

Links:
Python - http://www.python.org/
Boost - http://www.boost.org/
CMake - http://www.cmake.org/
CUDA - http://developer.nvidia.com/object/cuda.html
Subversion - http://subversion.tigris.org/
Doxygen - http://www.stack.nl/~dimitri/doxygen/manual.html

Building on Windows

1. Install prerequisite software
Click for detailed instructions: Installing Software Prerequisites on Windows

2. Get source code

• Option 1) download and unpack source code from: http://www.ameslab.gov/hoomd/
• Option 2) Get the latest development source with subversion This command (assuming you've installed the command line svn tools)

   $ svn co https://svn2.assembla.com/svn/hoomd/branches/hoomd-0.8 hoomd
  

  will create a directory hoomd in your current working directory which will contain the current development version of the source code. You can perform the same operation by right clicking a folder and choosing "SVN Checkout..." when using TortoiseSVN.

Developers with commit access planning to make changes to the code must use option 2.

3. Run CMake

You should now have a directory hoomd on your hard drive with a subdirectory src containing the source code. CMake must be run to generate the visual studio project that will compile HOOMD.

1. Start cmake-gui
2. Set C:\Users\user\hoomd\src (modifying to match the location of your hoomd src directory) in the box labeled "Where is the Source code".
3. Set C:\Users\user\hoomd\msvc (again, modified to mach the location of your hoomd directory) in the box labeled "Where to build the binaries"
4. You should now have a screen that looks like this:
   
5. Click configure and a dialog pops up:
   
6. Select the IDE you installed (most likely Visual Studio 8 2005) and click OK.
7. After a short wait while CMake should display a screen that looks like this:
   
   If you received an error message instead, it is possible that you are missing one of the prerequisite software packages or it is installed to a non-standard location. In the second case, you can click on the text box with CMAKE-SOMETHING-NOTFOUND in it and specify the full path to the corresponding file or directory.
8. You can configure any of the build options on this screen to your liking. See Build options for more information on what these options do.
9. Click configure several times until all the red options turn white. Then click generate the create project file.
10. Close CMake

4. Compile HOOMD
Open up the HOOMD.sln project in visual studio. Press F7 (or use the GUI build button) to build all executables. You can also make a single target the active project (right click and choose set as startup project) and press F7 to build only it.

Source can be modified in visual studio, but any files added to the project must be done via CMake. In most cases, a file can be added simply by placing it in the proper directory and then rerunning CMake.

If you have a system with more than 1 CPU core, you can greatly improve the performance of the build by making use of all cores. In VS2005, navigate to the menu item Tools->Options. In the left tab, select Projects And Solutions->Build and Run. Set the value for the maximum number of parallel project builds to be the total number of CPU cores in your system. There is more information at http://msdn2.microsoft.com/en-us/library/y0xettzf.aspx .

---

Building on linux

1. Install prerequisite software
Click for detailed instructions: Installing Software Prerequisites on Linux

2. Get source code

• Option 1) download and unpack source code from: http://www.ameslab.gov/hoomd/
• Option 2) Get the latest development source with subversion This command

   $ svn co https://svn2.assembla.com/svn/hoomd/branches/hoomd-0.8 hoomd
  

  will create a directory hoomd in your current working directory which will contain the current development version of the source code.

3. Run CMake
CMake needs to be run to generate the make files to compile HOOMD.

 $ cd hoomd
 $ mkdir bin
 $ cd bin
 $ cmake-gui ../src

Note: If you are logged into the system remotely, you can launch the text mode tool ccmake instead of cmake-gui. Press "h" for help on using the text mode tool or see http://www.cmake.org/HTML/RunningCMake.html

You will then see a screen that looks like this:

Click configure. You should now see a screen like this:

Choose your preferred build environment and click OK. This guide assumes that "Unix Makefiles" was chosen.

Now you should see a screen like this:

If you are building with GPU support enabled, check the ENABLE_CUDA box.

To generate the makefiles now, click configure several times until all the red settings turn white, then click generate.

You can also scroll down the list of options. Setting the checkbox options will control whether certain features are compiled in. You must click configure after any change. Note that in some cases, changing an option to ON will cause other options to appear. Some options controlled by changing text strings. See Build options for more information on what these options do.

It is possible that some of your libraries may be in non-standard paths. If this is the case, CMake will report an error after you click configure. The offending library will be labeled something like CMAKE_LIB_NOTFOUND. If you know where the library is, you can specify the full path here and click configure again.

Make sure to click generate again after you make any changes. When you are done, close cmake-gui.

4. Compile HOOMD
CMake generated make files for make. Just run

 $ make -j4

in the bin directory to compile everything. This documentation will even be generated if ENABLE_DOXYGEN is selected. The -j4 option lets make compile 4 files at once. It's best to set the value to twice the number of CPU cores in your system.

5(option a). Install to your home directory (so only you can run it)
Re-enter the CMake options screen:

 $ cmake-gui ../src

Set the CMAKE_INSTALL_PREFIX option to a directory of your choice: i.e. /home/joeuser/software/hoomd. Configure, configure and generate again as you did before. When you are back at the command line, execute:

 $ make install

to install HOOMD to the path you specified.

To run HOOMD, either execute /home/joeuser/software/hoomd/bin/hoomd or add /home/joeuser/software/hoomd/bin to your $PATH and run hoomd.

5(option b). Install to a system directory (so any user can run it)
Note: You must be root do do this (or run the "make install" command with sudo). Re-enter the CMake options screen:

 $ cmake-gui ../src

Set the CMAKE_INSTALL_PREFIX option to /opt/hoomd Configure, configure and generate again as you did before. When you are back at the command line, execute:

 $ make install

to install HOOMD to the path you specified.

To make the command hoomd available on the $PATH for users, you can either add /opt/hoomd/bin to the system $PATH or make a soft link /usr/bin/hoomd pointing to /opt/hoomd/bin/hoomd.

---

Building on Mac OSX

1. Install prerequisite software
Click for detailed instructions: Installing Software Prerequisites on Mac OS X

2. Get source code

• Option 1) download and unpack source code from: http://www.ameslab.gov/hoomd/
• Option 2) Get the latest development source with subversion This command

   $ svn co https://svn2.assembla.com/svn/hoomd/branches/hoomd-0.8 hoomd
  

  will create a directory hoomd in your current working directory which will contain the current development version of the source code.

3. Run CMake
First, click on the CMake icon to run CMake. Enter the location where you extracted the HOOMD source code in the "Where is the source code box". Specify where you want the binaries built in the "Where to build the binaries box" (usually in a directory called bin next to the source code). You should now have a screen that looks like this:

Click configure and CMake will ask you about the build environment. You have two options here. If there is a particular code editor you prefer and you want to compile by running make on the command line, select Unix Makefiles and press enter. If you would rather use XCode as an IDE, select XCode and press enter.

You will then see a screen that looks like this:

(this image was captured using the Unix Makefiles generator. Your screen may be slightly different if you chose Xcode)

If you are building with GPU support enabled, check the ENABLE_CUDA box.

To generate the makefiles (or XCode project) now, click configure several times until all the red settings turn white, then click generate.

You can also scroll down the list of options. Setting the checkbox options will control whether certain features are compiled in. You must click configure after any change. Note that in some cases, changing an option to ON will cause other options to appear. Some options controlled by changing text strings. See Build options for more information on what these options do.

It is possible that some of your libraries may be in non-standard paths. If this is the case, CMake will report an error after you click configure. The offending library will be labeled something like CMAKE_LIB_NOTFOUND. If you know where the library is, you can specify the full path here and click configure again.

Make sure to click generate again after you make any changes. When you are done, close cmake-gui.

4. Compile HOOMD
If you generated make files, just run

 $ make -j4

in the bin directory to compile everything and generate this documentation. The -j4 option lets make compile 4 files at once. It's best to set the value to twice the number of CPU cores in your system.

If you generated an XCode project, open it in XCode and click the build button to compile HOOMD. Note that while source code can be edited via XCode, any files added to the project must be done with CMake, not the XCode project management. In most cases, this can be done by simply adding the file to the proper directory and rerunning CMake.

5(option a). Install to your home directory (so only you can run it)
Re-enter the CMake options screen:

 $ cmake-gui ../src

Set the CMAKE_INSTALL_PREFIX option to a directory of your choice: i.e. /home/joeuser/software/hoomd. Configure, configure and generate again as you did before. When you are back at the command line, execute:

 $ make install

(or build the INSTALL target in XCode) to install HOOMD to the path you specified.

To run HOOMD, either execute /home/joeuser/software/hoomd/bin/hoomd or add /home/joeuser/software/hoomd/bin to your $PATH and run hoomd.

5(option b). Install to a system directory (so any user can run it)
Note: You must be root do do this (or run the "make install" command with sudo). Re-enter the CMake options screen:

 $ cmake-gui ../src

Set the CMAKE_INSTALL_PREFIX option to /opt/hoomd Configure, configure and generate again as you did before. When you are back at the command line, execute:

 $ make install

(or build the INSTALL target in XCode) to install HOOMD to the path you specified.

To make the command hoomd available on the $PATH for users, you can either add /opt/hoomd/bin to the system $PATH or make a soft link /usr/bin/hoomd pointing to /opt/hoomd/bin/hoomd.

---

Build options

Here is a list of all the build options that can be changed by CMake.

• 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 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_MINIMAL_INSTALL - when set to ON, only the minum number of files installed need to run hoomd simulations and benchmarks
• BUILD_TESTING - Enables the compilation of unit tests
• ENABLE_VALGRIND - (Linux only) Runs every unit test through valgrind for hardcore testing/debugging. If used with CUDA, device emulation mode is recommended.
• 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 (GPUs are single precision)

There are a few options for controlling the CUDA compilation.

• CUDA_ARCH - Sets the GPU architecture to compile for. Parts of HOOMD will run significantly faster when run on compute 1.1 or newer GPUs, but only if HOOMD is compiled for that that target. The CUDA programming guide has a nice list of which GPUs are which compute version in Appendix A.
  • 10 - compile for compute 1.0 and newer devices. Executable will run on all CUDA GPUs, but no fast code paths are activated.
  • 11 - compile for compute 1.1 and newer devices. Some faster code paths are activated.
  • 12 - compile for compute 1.2 and newer devices. Currently, nothing more is added vs. 11.
  • 13 - compile for compute 1.3 and newer devices. Currently, nothing is is added vs. 12.
• CUDA_BUILD_CUBIN - Enables a display of register usage for each kernel compiled.
• CUDA_BUILD_TYPE - Controls device/emulation builds
  • Device - will compile all GPU kernels to run on the GPU hardware
  • Emulation - will compile all GPU kernels in a CPU emulation mode. This emulation mode is very slow, but does allow developers without G80 cards to compile and test changes to GPU-related code. Actual kernel development is not recommended without a hardware device to run on.
• NVCC_USER_FLAGS - Allows additional flags to be passed to nvcc.
  • If you are building HOOMD for execution solely on G200 and newer GPUs, set NVCC_USER_FLAGS to -arch;sm_13;-DARCH_SM13 to take advantage of the hardware features present in those GPUs. This boosts HOOMD's overall performance.

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.

• DISABLE_ULF_WORKAROUND - Disables the compiling of several workarounds that make HOOMD stable for long run times. Set this to ON if you are a developer wanting to test and tune HOOMD for the highest performance. If you are building HOOMD for production simulation runs, set this ON only at the risk of your own sanity.
• ENABLE_CAC_GPU_ID - Defaults to ON on nyx and OFF on all other machines. Setting this to ON enables all HOOMD executables to run on the GPU specified in the CAC_GPU_ID environment variable.
• 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: ENABLE_STATIC=OFF is not supported on windows.
  • Note 2: ENABLE_STATIC defaults ON and can only be set off from the command line and when configuring a clean build directory. Example:

     ccmake -D ENABLE_STATIC=OFF ../src