hoomd.hpmc.update
Overview
Apply box updates to sample isobaric and related ensembles. 

Apply geometric cluster algorithm (GCA) moves. 

Insert and remove particles in the muVT ensemble. 

Quickly compress a hard particle system to a target box. 

Apply shape updates to the shape definitions defined in the integrator. 
Details
HPMC updaters.
HPMC updaters work with the hpmc.integrate.HPMCIntegrator
to apply changes to
the system consistent with the particle shape and defined interaction energies.
The BoxMC
, Clusters
, and MuVT
updaters apply trial moves that enable
enhanced sampling or the equilibration of different ensembles. QuickCompress
helps prepare nonoverlapping configurations of particles in a given box shape.
 class hoomd.hpmc.update.BoxMC(trigger, betaP)
Bases:
Updater
Apply box updates to sample isobaric and related ensembles.
 Parameters
betaP (hoomd.variant.variant_like) – \(\frac{p}{k_{\mathrm{B}}T}\) \([\mathrm{length}^{2}]\) in 2D or \([\mathrm{length}^{3}]\) in 3D.
trigger (hoomd.trigger.trigger_like) – Select the timesteps to perform box trial moves.
Use
BoxMC
in conjunction with an HPMC integrator to allow the simulation box to undergo random fluctuations at constant pressure, or random deformations at constant volume.BoxMC
supports both isotropic and anisotropic volume change moves as well as shearing of the simulation box. A singleBoxMC
instance may apply multiple types of box moves during a simulation run.Box move types
By default, no moves are applied (the weight values for all move types default to 0). In a given timestep, the type of move is selected randomly with probability:
\[p = \frac{w_k}{\sum_k w_k}\]where \(w_k\) is the weight of the move type.
A given box move proposes a trial simulation box \((L_x^t, L_y^t, L_z^t, xy^t, xz^t, yz^t)\) as a change from the current box: \((L_x, L_y, L_z, xy, xz, yz)\). The form of the change depends on the selected move type:
volume
(mode='standard'
): Change the volume (or area in 2D) of the simulation box while maining fixed aspect ratios \(Lx/Ly\), \(Lx/Lz\). In 3D:\[\begin{split}V^t &= V + u \\ L_x^t &= \left( \frac{Lx}{Ly} \frac{Lx}{Lz} V^t \right)^{1/3} \\ L_y^t &= L_x^t \frac{Ly}{Lx} \\ L_z^t &= L_x^t \frac{Lz}{Lx} \\ xy^t &= xy \\ xz^t &= xz \\ yz^t &= yz \\\end{split}\]where \(u\) is a random value uniformly distributed in the interval \([\delta_\mathrm{volume}, \delta_\mathrm{volume}]\).
In 2D:
\[\begin{split}V^t &= V + u \\ L_x^t &= \left( \frac{Lx}{Ly} V^t \right)^{1/2} \\ L_y^t &= L_x^t \frac{Ly}{Lx} \\ xy^t &= xy \\\end{split}\]volume
(mode='ln'
): Change the volume (or area in 2D) of the simulation box while maining fixed aspect ratios \(Lx/Ly\), \(Lx/Lz\). In 3D:\[\begin{split}V^t &= V e^u \\ L_x^t &= \left( \frac{Lx}{Ly} \frac{Lx}{Lz} V^t \right)^{1/3} \\ L_y^t &= L_x^t \frac{Ly}{Lx} \\ L_z^t &= L_x^t \frac{Lz}{Lx} \\ xy^t &= xy \\ xz^t &= xz \\ yz^t &= yz \\\end{split}\]where \(u\) is a random value uniformly distributed in the interval \([\delta_\mathrm{volume}, \delta_\mathrm{volume}]\).
In 2D:
\[\begin{split}V^t &= V e^u \\ L_x^t &= \left( \frac{Lx}{Ly} V^t \right)^{1/2} \\ L_y^t &= L_x^t \frac{Ly}{Lx} \\ xy^t &= xy \\\end{split}\]aspect
: Change the aspect ratio of the simulation box while maintaining a fixed volume. In 3D:\[\begin{split}L_k^t & = \begin{cases} L_k(1 + a) & u < 0.5 \\ L_k \frac{1}{1+a} & u \ge 0.5 \end{cases} \\ L_{m \ne k}^t & = L_m \sqrt{\frac{L_k}{L_k^t}} & xy^t &= xy \\ xz^t &= xz \\ yz^t &= yz \\\end{split}\]where \(u\) is a random value uniformly distributed in the interval \([0, 1]\), \(a\) is a random value uniformly distributed in the interval \([0, \delta_\mathrm{aspect}]\) and \(k\) is randomly chosen uniformly from the set \(\{x, y, z\}\).
In 2D:
\[\begin{split}L_k^t & = \begin{cases} L_k(1 + a) & u < 0.5 \\ L_k \frac{1}{1+a} & u \ge 0.5 \end{cases} \\ L_{m \ne k}^t & = L_m \frac{L_k}{L_k^t} \\ xy^t &= xy \\\end{split}\]length
: Change the box lengths:\[L_k^t = L_k + u\]where \(u\) is a random value uniformly distributed in the interval \([\delta_{\mathrm{length},k}, \delta_{\mathrm{length},k}]\), and \(k\) is randomly chosen uniformly from the set \(\{a : a \in \{x, y, z\}, \delta_{\mathrm{length},a} \ne 0 \}\).
shear
: Change the box shear parameters. In 3D:\[\begin{split}(xy^t, xz^t, yz^t) = \begin{cases} \left(xy + s_{xy}, \enspace xz, \enspace yz \right) & u < \frac{1}{3} \\ \left( xy^t = xy, \enspace xz + s_{xz}, \enspace yz \right) & \frac{1}{3} \le u < \frac{2}{3} \\ \left( xy^t = xy, \enspace xz, \enspace yz + s_{yz} \right) & \frac{2}{3} \le u \le 1 \\ \end{cases} \\\end{split}\]where \(u\) is a random value uniformly distributed in the interval \([0, 1]\) and \(s_k\) is a random value uniformly distributed in the interval \([\delta_{\mathrm{shear},k}, \delta_{\mathrm{shear},k}]\).
BoxMC
attempts and records trial moves for shear parameters even when \(\delta_{\mathrm{shear},k}=0\).In 2D:
\[xy^t = xy + s_{xy}\]
Acceptance
All particle particle positions are scaled into the trial box to form the trial configuration \(C^t\):
\[\vec{r}_i^t = s_x \vec{a}_1^t + s_y \vec{a}_2^t + s_z \vec{a}_3^t  \frac{\vec{a}_1^t + \vec{a}_2^t + \vec{a}_3^t}{2}\]where \(\vec{a}_k^t\) are the new box vectors determined by \((L_x^t, L_y^t, L_z^t, xy^t, xz^t, yz^t)\) and the scale factors are determined by the current particle position \(\vec{r}_i\) and the box vectors \(\vec{a}_k\):
\[\vec{r}_i = s_x \vec{a}_1 + s_y \vec{a}_2 + s_z \vec{a}_3  \frac{\vec{a}_1 + \vec{a}_2 + \vec{a}_3}{2}\]The trial move is accepted with the probability:
\[\begin{split}p_\mathrm{accept} = \begin{cases} \exp((\beta \Delta H + \beta \Delta U)) & \beta \Delta H + \beta \Delta U > 0 \\ 1 & \beta \Delta H + \beta \Delta U \le 0 \\ \end{cases}\end{split}\]where \(\Delta U = U^t  U\) is the difference in potential energy, \(\beta \Delta H = \beta P (V^t  V)  N_\mathrm{particles} \cdot \ln(V^t / V)\) for most move types. It is \(\beta P (V^t  V)  (N_\mathrm{particles}+1) \cdot \ln(V^t / V)\) for ln volume moves.
When the trial move is accepted, the system state is set to the the trial configuration. When it is not accepted, the move is rejected and the state is not modified.
Mixed precision
BoxMC
uses reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame. volume
Parameters for isobaric volume moves that scale the box lengths uniformly. The dictionary has the following keys:
weight
(float)  Relative weight of volume box moves.mode
(str) standard
proposes changes to the box volume andln
proposes changes to the logarithm of the volume. Initially starts off in ‘standard’ mode.delta
(float)  Maximum change in V or ln(V) where V is box area (2D) or volume (3D) \(\delta_\mathrm{volume}\).
 Type
 aspect
Parameters for isovolume aspect ratio moves. The dictionary has the following keys:
weight
(float)  Relative weight of aspect box moves.delta
(float)  Maximum relative change of box aspect ratio \(\delta_\mathrm{aspect} [\mathrm{dimensionless}]\).
 Type
 length
Parameters for isobaric box length moves that change box lengths independently. The dictionary has the following keys:
weight
(float)  Maximum change of HOOMDblue box parameters Lx, Ly, and Lz.delta
(tuple[float, float, float])  Maximum change of the box lengths \((\delta_{\mathrm{length},x}, \delta_{\mathrm{length},y}, \delta_{\mathrm{length},z}) [\mathrm{length}]\).
 Type
 shear
Parameters for isovolume box shear moves. The dictionary has the following keys:
weight
(float)  Relative weight of shear box moves.delta
(tuple[float, float, float])  maximum change of the box tilt factor \((\delta_{\mathrm{shear},xy}, \delta_{\mathrm{shear},xz}, \delta_{\mathrm{shear},yz}) [\mathrm{dimensionless}]\).reduce
(float)  Maximum number of lattice vectors of shear to allow before applying lattice reduction. Values less than 0.5 disable shear reduction.
 Type
 instance
When using multiple
BoxMC
updaters in a single simulation, give each a unique value forinstance
so they generate different streams of random numbers. Type
 property aspect_moves
The accepted and rejected aspect moves.
(0, 0) before the first call to
Simulation.run
.(
Loggable
: category=”sequence”)
 property counter
Trial move counters.
The counter object has the following attributes:
volume
:tuple
[int
,int
]  Number of accepted and rejected volume and length moves.shear
:tuple
[int
,int
]  Number of accepted and rejected shear moves.aspect
:tuple
[int
,int
]  Number of accepted and rejected aspect moves.
Note
The counts are reset to 0 at the start of each call to
hoomd.Simulation.run
. Before the first call toSimulation.run
,counter
isNone
.
 property shear_moves
The accepted and rejected shear moves.
(0, 0) before the first call to
Simulation.run
.(
Loggable
: category=”sequence”)
 class hoomd.hpmc.update.Clusters(pivot_move_probability=0.5, flip_probability=0.5, trigger=1)
Bases:
Updater
Apply geometric cluster algorithm (GCA) moves.
 Parameters
pivot_move_probability (float) – Set the probability for attempting a pivot move.
flip_probability (float) – Set the probability for transforming an individual cluster.
trigger (hoomd.trigger.trigger_like) – Select the timesteps on which to perform cluster moves.
The GCA as described in Liu and Lujten (2004), http://doi.org/10.1103/PhysRevLett.92.035504 is used for hard shape, patch interactions and depletants. Implicit depletants are supported and simulated onthefly, as if they were present in the actual system.
Supported moves include pivot moves (point reflection) and line reflections (pi rotation around an axis). With anisotropic particles, the pivot move cannot be used because it would create a chiral mirror image of the particle, and only line reflections are employed. In general, line reflections are not rejection free because of periodic boundary conditions, as discussed in Sinkovits et al. (2012), http://doi.org/10.1063/1.3694271 . However, we restrict the line reflections to axes parallel to the box axis, which makes those moves rejectionfree for anisotropic particles, but the algorithm is then no longer ergodic for those and needs to be combined with local moves.
Mixed precision
Clusters
uses reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame.
 class hoomd.hpmc.update.MuVT(transfer_types, ngibbs=1, max_volume_rescale=0.1, volume_move_probability=0.5, trigger=1)
Bases:
Updater
Insert and remove particles in the muVT ensemble.
 Parameters
trigger (int) – Number of timesteps between grand canonical insertions
transfer_types (list) – List of type names that are being transferred from/to the reservoir or between boxes
ngibbs (int) – The number of partitions to use in Gibbs ensemble simulations (if == 1, perform grand canonical muVT)
max_volume_rescale (float) – maximum step size in ln(V) (applies to Gibbs ensemble)
move_ratio (float) – (if set) Set the ratio between volume and exchange/transfer moves (applies to Gibbs ensemble)
The muVT (or grandcanonical) ensemble simulates a system at constant fugacity.
Gibbs ensemble simulations are also supported, where particles and volume are swapped between two or more boxes. Every box correspond to one MPI partition, and can therefore run on multiple ranks. Use the
ranks_per_partition
argument ofhoomd.communicator.Communicator
to enable partitioned simulations.Mixed precision
MuVT
uses reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame.Note
Multiple Gibbs ensembles are also supported in a single parallel job, with the
ngibbs
option to update.muvt(), where the number of partitions can be a multiple ofngibbs
. transfer_types
List of type names that are being transferred from/to the reservoir or between boxes
 Type
 move_ratio
The ratio between volume and exchange/transfer moves (applies to Gibbs ensemble)
 Type
 fugacity
Particle fugacity \([\mathrm{volume}^{1}]\) (default: 0).
 Type
TypeParameter
[particle type
,float
]
 property N
Map of number of particles per type.
None when not attached.
(
Loggable
: category=”object”) Type
 property exchange_moves
Count of the accepted and rejected paricle exchange moves.
None when not attached
(
Loggable
: category=”sequence”)
 property insert_moves
Count of the accepted and rejected paricle insertion moves.
None when not attached
(
Loggable
: category=”sequence”)
 class hoomd.hpmc.update.QuickCompress(trigger, target_box, max_overlaps_per_particle=0.25, min_scale=0.99)
Bases:
Updater
Quickly compress a hard particle system to a target box.
 Parameters
trigger (hoomd.trigger.trigger_like) – Update the box dimensions on triggered time steps.
target_box (hoomd.box.box_like) – Dimensions of the target box.
max_overlaps_per_particle (float) – The maximum number of overlaps to allow per particle (may be less than 1  e.g. up to 250 overlaps would be allowed when in a system of 1000 particles when max_overlaps_per_particle=0.25).
min_scale (float) – The minimum scale factor to apply to box dimensions.
Use
QuickCompress
in conjunction with an HPMC integrator to scale the system to a target box size.QuickCompress
can typically compress dilute systems to near random close packing densities in tens of thousands of time steps.It operates by making small changes toward the
target_box
, but only when there are no particle overlaps in the current simulation state. In 3D:\[\begin{split}L_x' &= \begin{cases} \max( L_x \cdot s, L_{\mathrm{target},x} ) & L_{\mathrm{target},x} < L_x \\ \min( L_x / s, L_{\mathrm{target},x} ) & L_{\mathrm{target},x} \ge L_x \end{cases} \\ L_y' &= \begin{cases} \max( L_y \cdot s, L_{\mathrm{target},y} ) & L_{\mathrm{target},y} < L_y \\ \min( L_y / s, L_{\mathrm{target},y} ) & L_{\mathrm{target},y} \ge L_y \end{cases} \\ L_z' &= \begin{cases} \max( L_z \cdot s, L_{\mathrm{target},z} ) & L_{\mathrm{target},z} < L_z \\ \min( L_z / s, L_{\mathrm{target},z} ) & L_{\mathrm{target},z} \ge L_z \end{cases} \\ xy' &= \begin{cases} \max( xy \cdot s, xy_\mathrm{target} ) & xy_\mathrm{target} < xy \\ \min( xy / s, xy_\mathrm{target} ) & xy_\mathrm{target} \ge xy \end{cases} \\ xz' &= \begin{cases} \max( xz \cdot s, xz_\mathrm{target} ) & xz_\mathrm{target} < xz \\ \min( xz / s, xz_\mathrm{target} ) & xz_\mathrm{target} \ge xz \end{cases} \\ yz' &= \begin{cases} \max( yz \cdot s, yz_\mathrm{target} ) & yz_\mathrm{target} < yz \\ \min( yz / s, yz_\mathrm{target} ) & yz_\mathrm{target} \ge yz \end{cases} \\\end{split}\]and in 2D:
\[\begin{split}L_x' &= \begin{cases} \max( L_x \cdot s, L_{\mathrm{target},x} ) & L_{\mathrm{target},x} < L_x \\ \min( L_x / s, L_{\mathrm{target},x} ) & L_{\mathrm{target},x} \ge L_x \end{cases} \\ L_y' &= \begin{cases} \max( L_y \cdot s, L_{\mathrm{target},y} ) & L_{\mathrm{target},y} < L_y \\ \min( L_y / s, L_{\mathrm{target},y} ) & L_{\mathrm{target},y} \ge L_y \end{cases} \\ L_z' &= L_z \\ xy' &= \begin{cases} \max( xy \cdot s, xy_\mathrm{target} ) & xy_\mathrm{target} < xy \\ \min( xy / s, xy_\mathrm{target} ) & xy_\mathrm{target} \ge xy \end{cases} \\ xz' &= xz \\ yz' &= yz \\\end{split}\]where the current simulation box is \((L_x, L_y, L_z, xy, xz, yz)\), the target is \((L_{\mathrm{target},x}, L_{\mathrm{target},y}, L_{\mathrm{target},z}, xy_\mathrm{target}, xz_\mathrm{target}, yz_\mathrm{target})\), the new simulation box set is \((L_x', L_y', L_z', xy', xz', yz')\) and \(s\) is the scale factor chosen for this step (see below).
QuickCompress
scales particle coordinates (seeBoxMC
for details) when it sets a new box.When there are more than
max_overlaps_per_particle * N_particles
hard particle overlaps in the system in the new box, the box move is rejected. Otherwise, the small number of overlaps remain when the new box is set.QuickCompress
then waits untilhoomd.hpmc.integrate.HPMCIntegrator
makes local MC trial moves that remove all overlaps.QuickCompress
adjusts the value of \(s\) based on the particle and translational trial move sizes to ensure that the trial moves will be able to remove the overlaps. It randomly chooses a value of \(s\) uniformly distributed betweenmax(min_scale, 1.0  min_move_size / max_diameter)
and 1.0 wheremin_move_size
is the smallest MC translational move size adjusted by the acceptance ratio andmax_diameter
is the circumsphere diameter of the largest particle type.Tip
Use the
hoomd.hpmc.tune.MoveSize
in conjunction withQuickCompress
to adjust the move sizes to maintain a constant acceptance ratio as the density of the system increases.Warning
When the smallest MC translational move size is 0,
QuickCompress
will scale the box by 1.0 and not progress toward the target box.Warning
Use
QuickCompress
ORBoxMC
. Do not use both at the same time.Mixed precision
QuickCompress
uses reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame. max_overlaps_per_particle
The maximum number of overlaps to allow per particle (may be less than 1  e.g. up to 250 overlaps would be allowed when in a system of 1000 particles when max_overlaps_per_particle=0.25).
 Type
 instance
When using multiple
QuickCompress
updaters in a single simulation, give each a unique value forinstance
so that they generate different streams of random numbers. Type
 property complete
True when the box has achieved the target.
 class hoomd.hpmc.update.Shape(trigger, shape_move, pretend=False, type_select=1, nsweeps=1)
Bases:
Updater
Apply shape updates to the shape definitions defined in the integrator.
See also
hoomd.hpmc.shape_move
describes the shape alchemy algorithm. Parameters
trigger (hoomd.trigger.trigger_like) – Call the updater on triggered time steps.
shape_move (ShapeMove) – Type of shape move to apply when updating shape definitions
pretend (
bool
, optional) – When True the updater will not actually update the shape definitions. Instead, moves will be proposed and the acceptance statistics will be updated correctly (default:False
).type_select (
int
, optional) – Number of types to change every time the updater is called (default: 1).nsweeps (
int
, optional) – Number of times to update shape definitions during each triggered timesteps (default: 1).
Shape support.
See
hoomd.hpmc.shape_move
for supported shapes.Example:
mc = hoomd.hpmc.integrate.ConvexPolyhedron() mc.shape["A"] = dict(vertices=numpy.asarray([(1, 1, 1), (1, 1, 1), (1, 1, 1), (1, 1, 1)])) vertex_move = hoomd.hpmc.shape_move.Vertex(stepsize={'A': 0.01}, param_ratio=0.2, volume=1.0) updater = hoomd.hpmc.update.Shape(shape_move=vertex_move, trigger=hoomd.trigger.Periodic(1), type_select=1, nsweeps=1)
 pretend
When True the updater will not actually update the shape definitions, instead moves will be proposed and the acceptance statistics will be updated correctly.
 Type