Building from source¶
To build the HOOMD-blue from source:
-
micromamba install cmake eigen git python numpy pybind11
-
git clone --recursive git@github.com:glotzerlab/hoomd-blue.git
Change to the repository directory:
cd hoomd-blue
-
cmake -B build -S . -GNinja
-
cd build
ninja
-
python3 -m pytest hoomd
Install the package (optional):
ninja install
To build the documentation from source (optional):
-
micromamba install sphinx sphinx-copybutton furo nbsphinx ipython
-
sphinx-build -b html sphinx-doc html
The sections below provide details on each of these steps.
Install prerequisites¶
You will need to install a number of tools and libraries to build HOOMD-blue. The options
ENABLE_MPI
, ENABLE_GPU
, ENABLE_TBB
, and ENABLE_LLVM
each require additional
libraries when enabled.
Install the required dependencies:
micromamba install cmake eigen git python numpy pybind11
Install additional packages needed to run the unit tests:
micromamba install pytest
Install additional packages needed to build the documentation:
micromamba install sphinx sphinx-copybutton furo nbsphinx ipython
Note
This guide assumes that you use the micromamba package manager. Adjust the commands appropriately for the package manager of your choice.
Warning
When using a conda-forge
environment for development, make sure that the environment does
not contain clang
, gcc
, or any other compiler or linker. These interfere with the native
compilers on your system and will result in compiler errors when building, linker errors when
running, or segmentation faults.
General requirements:
C++17 capable compiler
CMake
NumPy
pybind11
Python
Eigen
For MPI parallel execution (required when ENABLE_MPI=on
):
A MPI library (tested with OpenMPI)
cereal
For GPU execution (required when ENABLE_GPU=on
):
NVIDIA CUDA Toolkit
OR
AMD ROCm
HIP [with
hipcc
andhcc
as backend]rocFFT
rocPRIM
rocThrust
hipCUB
roctracer-dev
Note
When ENABLE_GPU=on
, HOOMD-blue will default to CUDA. Set HOOMD_GPU_PLATFORM=HIP
to
choose HIP.
For threaded parallelism on the CPU (required when ENABLE_TBB=on
):
Intel Threading Building Blocks
For runtime code generation (required when ENABLE_LLVM=on
):
LLVM
libclang-cpp
To build the documentation:
sphinx
sphinx-copybutton
furo
nbsphinx
ipython
Obtain the source¶
Clone using Git:
git clone --recursive git@github.com:glotzerlab/hoomd-blue.git
Release tarballs are also available as GitHub release assets.
See also
See the git book to learn how to work with Git repositories.
Important
HOOMD-blue uses Git submodules. Clone with the --recursive
to clone the submodules.
Execute git submodule update --init
to fetch the submodules each time you switch branches
and the submodules show as modified.
Configure¶
Use CMake to configure the HOOMD-blue build directory:
cd {{ path/to/hoomd-blue/repository }}
cmake -B build -S . -GNinja
Pass -D<option-name>=<value>
to cmake
to set options on the command line.
Options that find libraries and executables take effect only on a clean invocation of CMake. To set
these options, first remove CMakeCache.txt
from the build directory and then run cmake
with
these options on the command line.
Python_EXECUTABLE
- Specify whichpython
to build against. Example:/usr/bin/python3
.Default:
python3.x
found by CMake’s FindPython.
CMAKE_CUDA_COMPILER
- Specify whichnvcc
orhipcc
to build with.Default: location of
nvcc
detected on$PATH
.
MPI_HOME
(env var) - Specify the location where MPI is installed.Default: location of
mpicc
detected on the$PATH
.
<package-name>_ROOT
- Specify the location of a package.Default: Found on the CMake search path.
Other option changes take effect at any time:
BUILD_HPMC
- When enabled, build thehoomd.hpmc
module (default:on
).BUILD_MD
- When enabled, build thehoomd.md
module (default:on
).BUILD_METAL
- When enabled, build thehoomd.metal
module (default:on
).BUILD_MPCD
- When enabled, build thehoomd.mpcd
module.hoomd.md
must also be built. (default: same asBUILD_MD
).BUILD_TESTING
- When enabled, build unit tests (default:on
).CMAKE_BUILD_TYPE
- Sets the build type (case sensitive) Options:Debug
- Compiles debug information into the library and executables. Enables asserts to check for programming mistakes. HOOMD-blue will run slow when compiled inDebug
mode, but problems are easier to identify.RelWithDebInfo
- Compiles with optimizations and debug symbols.Release
- (default) All compiler optimizations are enabled and asserts are removed. Recommended for production builds.
CMAKE_INSTALL_PREFIX
- Directory to install HOOMD-blue. Defaults to the root path of the found Python executable.ENABLE_LLVM
- Enable run time code generation with LLVM.ENABLE_GPU
- When enabled, compiled GPU accelerated computations (default:off
).HOOMD_GPU_PLATFORM
- Choose eitherCUDA
orHIP
as a GPU backend (default:CUDA
).HOOMD_SHORTREAL_SIZE
- Size in bits of theShortReal
type (default:32
).When set to
32
, perform force computations, overlap checks, and other local calculations in single precision.When set to
64
, perform all calculations in double precision.
HOOMD_LONGREAL_SIZE
- Size in bits of theLongReal
type (default:64
).When set to
64
, store particle coordinates, sum quantities, and perform integration in double precision.When set to
32
, store particle coordinates, sum quantities, and perform integration in single precision. NOT RECOMMENDED, HOOMD-blue fails validation tests whenHOOMD_LONGREAL_SIZE == HOOMD_SHORTREAL_SIZE == 32
.
ENABLE_MPI
- Enable multi-processor/GPU simulations using MPI.When set to
on
, multi-processor/multi-GPU simulations are supported.When set to
off
(the default), always run in single-processor/single-GPU mode.
ENABLE_TBB
- Enable support for Intel’s Threading Building Blocks (TBB).When set to
on
, HOOMD-blue will use TBB to speed up calculations in some classes on multiple CPU cores.
PYTHON_SITE_INSTALL_DIR
- Directory to installhoomd
to relative toCMAKE_INSTALL_PREFIX
. Defaults to thesite-packages
directory used by the found Python executable.
These options control CUDA compilation via nvcc
:
CUDA_ARCH_LIST
- A semicolon-separated list of GPU architectures to compile.
Tip
Pass the following options to CMake to optimize the build for your processor:
-DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native
Build the package¶
After configuring, build HOOMD-blue with:
cd build
ninja
The build
directory now contains a fully functional HOOMD-blue package.
Execute ninja
again any time you modify the code, test scripts, or CMake scripts.
Tip
ninja
will automatically execute cmake
as needed. You do NOT need to execute
cmake
yourself every time you build HOOMD-blue.
Run tests¶
Use pytest to execute unit tests:
python3 -m pytest hoomd
Install the package¶
Execute:
ninja install
to install HOOMD-blue into your Python environment.
Warning
This will overwrite any HOOMD-blue that you may have installed by other means.
To use the compiled HOOMD-blue without modifying your environment, set PYTHONPATH
:
export PYTHONPATH={{ path/to/hoomd-blue/repository/build }}
Build the documentation¶
Run Sphinx to build HTML documentation:
sphinx-build -b html sphinx-doc html
Open the file html/index.html
in your web browser to view the documentation.
Tip
Add the sphinx options -a -n -W -T --keep-going
to produce docs with consistent links in
the side panel and provide more useful error messages.