Skip to content

BUILDING.rst

Latest commit

 

History

History
345 lines (205 loc) · 9.13 KB

BUILDING.rst

File metadata and controls

345 lines (205 loc) · 9.13 KB

Building from source

To build the HOOMD-blue from source:

  1. Install prerequisites:

    micromamba install cmake eigen git ninja numpy pybind11 python

  2. Obtain the source:

    git clone --recursive git@github.com:glotzerlab/hoomd-blue.git

  3. Change to the repository directory:

    cd hoomd-blue

  1. Configure:

    cmake -B build -S . -GNinja

  2. Build the package:

    cd build
    ninja

  1. Run tests:

    python3 -m pytest hoomd

  1. Install the package (optional):

    ninja install

To build the documentation from source (optional):

  1. Install prerequisites:

    micromamba install sphinx furo nbsphinx ipython

  2. Build the documentation:

    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 and ENABLE_GPU each require additional libraries when enabled.

Install the required dependencies:

micromamba install cmake eigen git ninja numpy pybind11 python

Install additional packages needed to run the unit tests:

micromamba install pytest rowan

Install additional packages needed to build the documentation:

micromamba install sphinx 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 and hcc 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.

To build the documentation:

  • sphinx
  • 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.

.. seealso::

    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 which python to build against. Example: /usr/bin/python3.
  • CMAKE_CUDA_COMPILER - Specify which nvcc or hipcc 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 the hoomd.hpmc module (default: on).
  • BUILD_MD - When enabled, build the hoomd.md module (default: on).
  • BUILD_METAL - When enabled, build the hoomd.metal module (default: on).
  • BUILD_MPCD - When enabled, build the hoomd.mpcd module. hoomd.md must also be built. (default: same as BUILD_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 in Debug 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_GPU - When enabled, compiled GPU accelerated computations (default: off).
  • HOOMD_GPU_PLATFORM - Choose either CUDA or HIP as a GPU backend (default: CUDA).
  • HOOMD_SHORTREAL_SIZE - Size in bits of the ShortReal type (default: 32).
    • When set to 32, perform HPMC overlap checks in single precision.
    • When set to 64, perform all calculations in double precision.
  • HOOMD_LONGREAL_SIZE - Size in bits of the LongReal 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 when HOOMD_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.
  • PYTHON_SITE_INSTALL_DIR - Directory to install hoomd to relative to CMAKE_INSTALL_PREFIX. Defaults to the site-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 :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.