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

Apply geometric cluster algorithm (GCA) moves. 

Quickly compress a hard particle system to a target box. 
Details
HPMC updaters.

class
hoomd.hpmc.update.
BoxMC
(seed, betaP, trigger=1)¶ Apply box updates to sample isobaric and related ensembles.
 Parameters
seed (int) – random number seed for MC box changes
betaP (
float
orhoomd.variant.Variant
) – \(\frac{p}{k_{\mathrm{B}}T}\) (units of inverse area in 2D or inverse volume in 3D).trigger (hoomd.trigger.Trigger) – 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.BoxMC
supports both isotropic (all box sides changed equally) and anisotropic volume change moves as well as shearing of the simulation box. Multiple types of box moves can be applied simultaneously during a simulation. For this purpose, each type of box move has an associated weight that determines the relative frequency of a box move happening relative to the others. By default, no moves are applied (weight values for all move types default to 0). After a box trial move is proposed, all the particle positions are scaled into the new box. Trial moves are then accepted, if they do not produce an overlap, according to standard Metropolis criterion and rejected otherwise.
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).
 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.
 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(Lx, Ly, Lz)
.
 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(xy, xz, yz)
.reduce
(float)  Maximum number of lattice vectors of shear to allow before applying lattice reduction. Values less than 0.5 disable shear reduction.
 Type

property
aspect_moves
¶ The accepted and rejected aspect moves.
(0, 0) when not attached.
(
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
.

class
hoomd.hpmc.update.
Clusters
(seed, swap_type_pair, delta_mu=0, move_ratio=0.5, flip_probability=0.5, swap_move_ratio=0.5, trigger=1)¶ Apply geometric cluster algorithm (GCA) moves.
 Parameters
seed (int) – Random number seed.
swap_type_pair (list[tuple[str, str]]) – A pair of two types whose identities may be swapped.
move_ratio (float) – Set the ratio between pivot and reflection moves.
flip_probability (float) – Set the probability for transforming an individual cluster.
swap_move_ratio (float) – Set the ratio between type swap moves and geometric moves.
trigger (Trigger) – 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.
With depletants, Clusters are defined by a simple distance cutoff criterion. Two particles belong to the same cluster if the circumspheres of the depletantexcluded volumes overlap.
Supported moves include pivot moves (point reflection), line reflections (pi rotation around an axis), and type swaps. Only the pivot move is rejection free. 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. 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.
Note
The type swap move only works between two types of equal sized, unorientable (
orientable``=``False
) spherical particles and exchanges their identities.Threading
The
Clusters
updater support threaded execution on multiple CPU cores.
property
counter
¶ Get the number of accepted and rejected cluster moves.
 Returns
A counter object with pivot, reflection, and swap properties. Each property is a list of accepted moves and rejected moves since the last run.
Note
None
when the simulation run has not started.

property
pivot_moves
¶ Number of accepted and rejected pivot moves.
 Returns
A tuple of (accepted moves, rejected moves) since the last run.
(
Loggable
: category=”sequence”)

class
hoomd.hpmc.update.
QuickCompress
(trigger, target_box, seed, max_overlaps_per_particle=0.25, min_scale=0.99)¶ Quickly compress a hard particle system to a target box.
 Parameters
trigger (Trigger) – Update the box dimensions on triggered time steps.
seed (int) – Random number seed.
target_box (Box) – 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
:L_new = scale * L_current
for each box parameter and then scaling the particle positions into the new box. If there are more thanmax_overlaps_per_particle * N_particles
hard particle overlaps in the system, the box move is rejected. Otherwise, the small number of overlaps remain.QuickCompress
then waits until local MC trial moves provided by the HPMC integrator remove all overlaps before it makes another box change.Note
The target box size may be larger or smaller than the current system box, and also may have different tilt factors. When the target box parameter is larger than the current, it scales by
L_new = 1/scale * L_current
QuickCompress
adjusts the value ofscale
based on the particle and translational trial move sizes to ensure that the trial moves will be able to remove the overlaps. It chooses a value ofscale
randomly 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.MoveSizeTuner
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.
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

property
complete
¶ True when the box has achieved the target.