Migrating to HOOMD v3#
HOOMD v3 introduces many breaking changes for both users and developers in order to provide a cleaner Python interface, enable new functionalities, and move away from unsupported tools. This guide highlights those changes.
Overview of API changes#
HOOMD v3 introduces a completely new API. All classes have been renamed to match PEP8 naming guidelines and have new or renamed parameters, methods, and properties. See the tutorials and the Python module documentation for full class-level details.
Here is a module level overview of features that have been moved or removed:
v2 module, class, or method |
Replaced with |
---|---|
|
|
|
Removed. Use Python standard libraries for timing. |
|
Removed. See Citing HOOMD-blue. |
|
|
|
|
|
|
|
|
|
|
|
|
|
Removed. Use an external tool. |
|
|
|
Removed. Use Python standard libraries for option parsing. |
|
Some classes have been moved to |
|
Enable GPU profiling with |
|
|
|
|
|
|
|
|
|
|
|
Removed. This is not needed. |
|
|
|
Removed. |
|
|
|
|
|
Removed functionality#
HOOMD v3 removes old APIs, unused functionality, and features better served by other codes:
Feature |
Replace with |
---|---|
Python 2.7 |
Python >= 3.6 |
Compute < 6.0 GPUs |
Compute >= 6.0 GPUs |
|
|
|
Parameters and type parameters accessed by properties. |
|
|
|
No longer needed. |
hoomd.deprecated
:
Feature |
Replace with |
---|---|
|
Offline analysis: e.g. Freud’s msd module. |
|
|
|
|
|
|
|
|
|
Feature |
Replace with |
---|---|
|
no longer needed |
|
|
|
n/a |
|
no longer needed |
|
no longer needed |
|
no longer needed |
|
no longer needed |
|
set |
Feature |
Replace with |
---|---|
|
Pass group to integration method. |
|
n/a |
|
Per-type |
|
hoomd.cgcmm
:
Feature |
Replace with |
---|---|
|
no longer needed |
|
no longer needed |
hoomd.dem
:
Feature |
Replace with |
---|---|
DEM pair potentials |
ALJ pair potential in |
Not yet ported#
The following v2 functionalities have not yet been ported to the v3 API. They may be added in a future 3.x release:
HPMC box volume move size tuner.
These contributed functionalities rely on the community for support. Please contact the developers if you have an interest in porting these in a future release:
hoomd.hdf5
hoomd.metal
hoomd.mpcd
Compiling#
CMake 3.8 or newer is required to build HOOMD v3.0.
To compile with GPU support, use the option
ENABLE_GPU=ON
.UPDATE_SUBMODULES
no longer exists. Users and developers should usegit clone --recursive
,git submodule update
andgit submodule sync
as appropriate.COPY_HEADERS
no longer exists. HOOMD will pull headers from the source directory when needed.CMAKE_INSTALL_PREFIX
is set to the Pythonsite-packages
directory (if not explicitly set by the user).cereal, eigen, and pybind11 headers must be provided to build HOOMD. See Installing binaries for details.
BUILD_JIT
is replaced withENABLE_LLVM
.
Components#
HOOMD now uses native CUDA support in CMake. Use
CMAKE_CUDA_COMPILER
to specify a specificnvcc
orhipcc
. Plugins will require updates toCMakeLists.txt
to compile.cu
files.Remove
CUDA_COMPILE
.Pass
.cu
sources directly topybind11_add_module
.Add
NVCC
as a compile definition to.cu
sources.
External components require additional updates to work with v3. See
example_plugin
for details:Remove
FindHOOMD.cmake
.Replace
include(FindHOOMD.cmake)
withfind_package(HOOMD 3.Y REQUIRED)
(where 3.Y is the minor version this plugin is compatible with).Always force set
CMAKE_INSTALL_PREFIX
to${HOOMD_INSTALL_PREFIX}
.Replace
PYTHON_MODULE_BASE_DIR
withPYTHON_SITE_INSTALL_DIR
.Replace all
target_link_libraries
andset_target_properties
withtarget_link_libraries(_${COMPONENT_NAME} PUBLIC HOOMD::_hoomd)
(can linkHOOMD::_md
,HOOMD::_hpmc
, etc. if necessary).
Numerous C++ class APIs have changed, been removed, or renamed. Review the header files to see new class signatures. These changes may require you to update your component accordingly. Some of the more notable changes include:
Variant
has been completely rewritten.Trigger
replaces periodic and variable period scheduling.NeighborList
has aaddRCutMatrix
method clients must use to specify the maximum cutoff radii per type pair.timestep
is now of typeuint64_t
.Saru
has been removed. UseRandomGenerator
.RandomGenerator
is now constructed with aSeed
andCounter
object that support 64-bit timesteps.m_seed
is no longer present in individual operation objects. Use the global seed provided bySystemDefinition
.The HPMC integrators have been heavily refactored.
HPMC GPU kernels are now instantiated by template .cu files that are generated by CMake at configure time.
ParticleGroup
instances are now constructed from immutable, reusable, and user-customizableParticleFilter
instances.All GPU code is now written with HIP to support NVIDIA and AMD GPUs.
ActiveForceCompute
always uses particle orientation in combination with per-type active forces and torques.getProvidedLogQuantities
andgetLogQuantities
have been removed. Provide loggable properties instead.Removed the Sphere, Ellipsoid, and oneD constraints. Replaced with the more general RATTLE integration methods and Manifold classes.
Removed the Enforce2D and TempRescale Updaters. Enforce2D is not needed for 2D simulations, and TempRescale has been replaced by
thermalize_
methods.Removed Doxygen configuration scripts. View the document for classes in the source files.
Particle types may no longer be added after a Simulation is initialized. Classes no longer need to subscribe to the types added signal and reallocate data structures when the number of types changes.