Migrating to the latest version¶
Migrating to HOOMD-blue 5¶
Breaking changes to existing functionalities¶
hoomd.snapshot.from_gsd_snapshot
hoomd.util.GPUNotAvailableError
box1
,box2
, andvariant
arguments tohoomd.update.BoxResize
.Use
box
.
hpmc.pair.user.CPPPotentialBase
,hpmc.pair.user.CPPPotential
,hpmc.pair.user.CPPPotentialUnion
,hpmc.integrate.HPMCIntegrator.pair_potential
Use a
hoomd.hpmc.pair.Pair
potential withhpmc.integrate.HPMCIntegrator.pair_potentials
.
hoomd.hpmc.external.user.CPPExternalPotential
Use
hoomd.hpmc.external.Linear
or a custom component (compiled).
hoomd.hpmc.update.BoxMC.betaP
Set
hoomd.hpmc.update.BoxMC.P
toP = betaP / beta
and set the appropriatekT = 1/beta
in the integrator.
hoomd.hpmc.update.Clusters
is renamed tohoomd.hpmc.update.GCA
.Device.gpu_ids
.Use
Device.gpu_id
.
HPMCIntegrator.external_potential
.Use
HPMCIntegrator.external_potentials
hoomd.hpmc.external.wall.WallPotential
is nowhoomd.hpmc.external.WallPotential
.hoomd.hpmc.external.field.Harmonic
is nowhoomd.hpmc.external.Harmonic
.
Removed functionalities¶
_InternalCustomUpdater.update
_InternalCustomTuner.tune
_InternalCustomWriter.write
HDF5Log.write
Implicit depletants from HPMC.
Device.num_cpu_threads
.Single-process multi-GPU code path.
Migrating to HOOMD-blue 4¶
Breaking changes to existing functionalities¶
For some functionalities, you will need to update your scripts to use a new API:
hoomd.md.dihedral.Harmonic
charges
key inRigid.body
.Pass charges to
Rigid.create_bodies
or set in the system state.
diameters
key inRigid.body
.Set diameters in system state.
hoomd.md.methods.NVE
.Use
hoomd.md.methods.ConstantVolume
withthermostat=None
.
hoomd.md.methods.NVT
.Use
hoomd.md.methods.ConstantVolume
with ahoomd.md.methods.thermostats.MTTK
thermostat.
hoomd.md.methods.Berendsen
.Use
hoomd.md.methods.ConstantVolume
with ahoomd.md.methods.thermostats.Berendsen
thermostat.
hoomd.md.methods.NPH
.Use
hoomd.md.methods.ConstantPressure
withthermostat=None
.
hoomd.md.methods.NPT
.Use
hoomd.md.methods.ConstantPressure
with ahoomd.md.methods.thermostats.MTTK
thermostat.
hoomd.write.GSD.log
.hoomd.mesh.Mesh().triangles
.Use
hoomd.mesh.Mesh().triangulation
inhoomd.mesh.Mesh
to define the mesh triangulation.
hoomd.md.pair.Gauss
.hoomd.md.external.wall.Gauss
.msg_file
property and argument inhoomd.device.Device
.Use
message_filename
.
sdf
property ofhoomd.hpmc.compute.SDF
.Use
sdf_compression
.
hoomd.write.GSD
no longer writesparticles/diameter
by default.Set
write_diameter
as needed.
alpha
property ofhoomd.md.methods.Langevin
,hoomd.md.methods.Brownian
,hoomd.md.methods.OverdampedViscous
,hoomd.md.methods.rattle.Langevin
,hoomd.md.methods.rattle.Brownian
, andhoomd.md.methods.rattle.OverdampedViscous
.Use the
gamma
property.
The
dynamic
property and argument ofhoomd.write.GSD
no longer enforces'property'
as an always dynamic quantity. Users must include'property'
,'particles/position'
and/or'particles/orientation'
as needed indynamic
lists that contain other fields.hoomd.write.GSD
aggressively buffers output. Callhoomd.write.GSD.flush
to write the buffer to disk when opening a file for reading that is still open for writing. There is no need to callflush
in normal workflows when files are closed and then opened later for reading.
Removed functionalities¶
HOOMD-blue 4 removes functionalities deprecated in v3.x releases:
hoomd.md.pair.aniso.ALJ.mode
parameterhoomd.md.pair.aniso.Dipole.mode
parameterhoomd.device.GPU.memory_traceback
parameter
Reintroducing hoomd.mpcd
¶
hoomd.mpcd
was previously available in HOOMD 2, but it was not available in HOOMD 3 because its
API needed to be significantly rewritten. It is reintroduced in HOOMD 4 with all classes and methods
renamed to be consistent with the rest of HOOMD’s API. The most significant changes for users are:
The way MPCD particle data is stored and initialized has changed. MPCD particles are now part of
hoomd.State
, so HOOMD and MPCD particles need to be initialized together rather than separately.After initialization, most objects now need to be attached to the
hoomd.mpcd.Integrator
, similarly to other features migrated from HOOMD 2 to HOOMD 3.The
hoomd.mpcd.geometry.ParallelPlates
andhoomd.mpcd.geometry.PlanarPore
streaming geometries have been rotated to the xy plane from the xz plane.MPCD particle sorting is not enabled by default but is still highly recommended for performance. Users should explicitly create a
hoomd.mpcd.tune.ParticleSorter
and attach it to thehoomd.mpcd.Integrator
.
Please refer to the module-level documentation and examples for full details of the new API. Some common changes that you may need to make to your HOOMD 2 scripts are:
Feature |
Change |
---|---|
Create snapshots using |
|
Specify cell size using |
The cell size is fixed at 1.0. |
Initialize MPCD particles with |
|
Initialize MPCD particles randomly with |
Not currently supported |
Initialize HOOMD particles from a file, then add MPCD particles through |
Use |
Bounce-back integration of HOOMD particles using |
Use |
Bounce-back streaming of MPCD particles using |
Use |
Fill geometry with virtual particles using |
Use |
Change sorting period of automatically created |
Explicitly create a |
Have HOOMD automatically validate my streaming geometry fits inside my box |
No longer performed. Users should make sure their geometries make sense |
Have HOOMD automatically validate my particles are inside my streaming geometry |
Call |
For developers, the following are the most significant changes to be aware of:
The MPCD namespace is
hoomd::mpcd
.hoomd::mpcd::SystemData
has been removed. Classes should accepthoomd::SystemDefinition
instead and useSystemDefinition::getMPCDParticleData()
.Force and geometry files have been renamed.
Bounce-back streaming methods are now templated on both geometries and forces, rather than using polymorphism for the forces. This means that combinations of geometries and forces need to be compiled when new classes are added. CMake can automatically generate the necessary files if new geometries and forces are added to the appropriate lists. Python will automatically deduce the right C++ class names if standard naming conventions are followed; otherwise, explicit registration is required.
The virtual particle filler design has been refactored to enable other methods for virtual particle filling. Fillers that derived from the previous
hoomd::mpcd::VirtualParticleFiller
should inherit fromhoomd::mpcd::ManualVirtualParticleFiller
instead.
Compiling¶
HOOMD-blue v4 no longer builds on macOS with
ENABLE_GPU=on
.Use the CMake options
HOOMD_LONGREAL_SIZE
andHOOMD_SHORTREAL_SIZE
to control the floating point precision of the calculations. These replace theSINGLE_PRECISION
andHPMC_MIXED_PRECISION
options from v3.
Components¶
Remove
fix_cudart_rpath(_${COMPONENT_NAME})
from your componentsCMakeLists.txt
Use
LongReal
andShortReal
types in new code.Scalar
will be removed in a future release (v5 or later).Replace any use of
hpmc::OverlapReal
withShortReal
.Remove
needsDiameter
andsetDiameter
methods in potential evaluator classes.
Migrating to HOOMD-blue 3¶
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-blue 3 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.