Hard particle Monte Carlo¶
HOOMD-blue can perform simulations of hard particles using the Monte Carlo method (
particles are defined by their shape, and the
HPMC integrator supports
polygons, spheropolygons, polyhedra, spheropolyhedra, ellipsoids, faceted ellipsoids, spheres,
indented spheres, and unions of shapes. HPMC can make both constant volume and constant pressure
box moves (
hpmc.update.BoxMC), perform cluster moves (
and can compute the pressure during constant volume simulations (
HPMC can also apply external and pair potentials to the particles. Use
hpmc.external.field.Harmonic to restrain particles to a lattice (e.g. for Frenkel-Ladd
hpmc.external.user.CPPExternalPotential to implement arbitrary external fields
(e.g. gravity). Use
hpmc.pair.user to define arbitrary pairwise interactions between particles.
hoomd.version.hpmc_built indicates whether the build supports HPMC simulations.
Tutorial: Introducing HOOMD-blue
HOOMD-blue can perform molecular dynamics simulations (
md) with NVE, NVT, NPT, NPH, Langevin,
Brownian, overdamped viscous integration methods (
md.methods), and energy minimization
md.minimize). Unless otherwise stated in the documentation, all integration methods integrate
both translational and rotational degrees of freedom. Some integration methods support manifold
md.methods.rattle). HOOMD-blue provides a number of pair potentials (
including pair potentials that depend on particle orientation (
md.pair.aniso) and many body
md.many_body). HOOMD-blue also provides bond potentials and distance constraints
commonly used in atomistic and coarse-grained force fields (
md.special_pair) and can model rigid bodies
md.constrain.Rigid). External fields
md.external.field apply potentials based only on the
particle’s position and orientation, including walls (
md.external.wall) to confine particles in a
specific region of space.
md.long_range provides long ranged interactions, including the PPPM
method for electrostatics. HOOMD-blue enables active matter simulations with
md.update.ActiveRotationalDiffusion. At runtime,
hoomd.version.md_built indicates whether the
build supports MD simulations.
Tutorial: Introducing Molecular Dynamics
HOOMD-blue is a Python package and is designed to interoperate with other packages in the scientific
Python ecosystem and to be extendable in user scripts. To enable interoperability, all operations
provide access to useful computed quantities as properties in native Python types or numpy arrays
where appropriate. Additionally,
md.force.Force provide direct access to
particle properties and forces using Python array protocols. Users can customize their simulation or
extend HOOMD-blue with functionality implemented in Python code by subclassing
hoomd.tune.CustomTuner, or by using the HOOMD-blue API in combination with other Python packages
to implement methods that couple simulation, analysis, and multiple simulations (such as umbrella
Tutorial: Custom Actions in Python
CPU and GPU devices¶
HOOMD-blue can execute simulations on CPUs or GPUs. Typical simulations run more efficiently on
GPUs for system sizes larger than a few thousand particles, although this strongly depends on the
details of the simulation. The provided binaries support NVIDIA GPUs. Build from source to enable
preliminary support for AMD GPUs. CPU support is always enabled. GPU support must be enabled at
compile time with the
ENABLE_GPU CMake option (see Building from source). Select the device to use at
run time with the
device module. Unless otherwise stated in the documentation,
all operations and methods support GPU execution. At runtime,
whether the build supports GPU devices.
Autotuned kernel parameters¶
HOOMD-blue automatically tunes kernel parameters to improve performance when executing on a GPU device. During the first 1,000 - 20,000 timesteps of the simulation run, HOOMD-blue will change kernel parameters each time it calls a kernel. Kernels compute the same output regardless of the parameter (within floating point precision), but the parameters have a large impact on performance.
Check to see whether tuning is complete with the
is_tuning_complete attribute of your simulation’s
Operations. For example, use this to run timed benchmarks after the performance stabilizes.
The optimal parameters can depend on the number of particles in the simulation and the density, and
may vary weakly with other system properties. To maintain peak performance, call
tune_kernel_parmeters to tune the parameters again after
making a change to your system.
AutotunedObject provides a settable dictionary parameter with the current kernel parameters in
kernel_parameters. Use this to inspect the
autotuner’s behavior or override with specific values (e.g. values saved from a previous execution).
HOOMD-blue can use the message passing interface (MPI) to execute simulations in less time using
more than one CPU core or GPU. Unless otherwise stated in the documentation, all operations and
methods support MPI parallel execution. MPI support is optional, requires a compatible MPI library,
and must be enabled at compile time with the
ENABLE_MPI CMake option (see Building from source).
hoomd.version.mpi_enabled indicates whether the build supports MPI.
Tutorial: Parallel Simulation With MPI
Some operations in HOOMD-blue can use multiple CPU threads in a single process. Control this with
device.Device.num_cpu_threads property. In this release, threading support in HOOMD-blue is
very limited and only applies to implicit depletants in
hpmc.pair.user.CPPPotentialUnion. Threading must must be enabled at compile time with the
ENABLE_TBB CMake option (see Building from source). At runtime,
whether the build supports threaded execution.
Run time compilation¶
Some operations allow the user to provide arbitrary C++ code that HOOMD-blue compiles at run time
and executes during the simulation.
hpmc.external.user enable users to apply
arbitrary pair and external potentials to particles in HPMC simulations.
supports both CPUs and NVIDIA GPUs while
hpmc.external.user only supports CPUs. Run time
compilation must be enabled at compile time with the
ENABLE_LLVM CMake option (see
Building from source). At runtime,
hoomd.version.llvm_enabled indicates whether the build supports run
HOOMD-blue performs computations with mixed floating point precision. There is a high precision
type and a reduced precision type. All particle properties are stored in the high precision
type, and most operations also perform all computations with high precision. Operations that do not
mention “Mixed precision” in their documentation perform all calculations in high percision. Some
operations use reduced precision when possible to improve performance, as detailed in the
documentation for each operation. In this release, only
hpmc implements mixed precision.
The precision is set at compile time with the
ENABLE_HPMC_MIXED_PRECISION CMake options (see Building from source). By default, the high precision
width is 64 bits and the reduced precision width is 32 bits. At runtime,
hoomd.version.floating_point_precision indicates the width of the floating point types.
Plugin code that provides additional functionality to HOOMD-blue may be implemented in pure Python or as a package with C++ compiled libraries.