hpmc.update

Overview

BoxMC

Apply box updates to sample isobaric and related ensembles.

Clusters

Apply geometric cluster algorithm (GCA) moves.

QuickCompress

Quickly compress a hard particle system to a target box.

Details

HPMC updaters.

class hoomd.hpmc.update.BoxMC(betaP, trigger=1)

Apply box updates to sample isobaric and related ensembles.

Parameters

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 and ln 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

dict

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

dict

length

Parameters for isobaric box length moves that change box lengths independently. The dictionary has the following keys:

  • weight (float) - Maximum change of HOOMD-blue box parameters Lx, Ly, and Lz.

  • delta (tuple[float, float, float]) - Maximum change of the box lengths (Lx, Ly, Lz) \([\mathrm{length}]\).

Type

dict

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

dict

instance

When using multiple BoxMC updaters in a single simulation, give each a unique value for instance so they generate different streams of random numbers.

Type

int

property aspect_moves

The accepted and rejected aspect moves.

(0, 0) before the first call to Simulation.run.

(Loggable: category=”sequence”)

Type

tuple[int, int]

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 to Simulation.run, counter is None.

property shear_moves

The accepted and rejected shear moves.

(0, 0) before the first call to Simulation.run.

(Loggable: category=”sequence”)

Type

tuple[int, int]

property volume_moves

The accepted and rejected volume and length moves.

(0, 0) before the first call to Simulation.run.

(Loggable: category=”sequence”)

Type

tuple[int, int]

class hoomd.hpmc.update.Clusters(pivot_move_probability=0.5, flip_probability=0.5, trigger=1)

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 (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.

Implicit depletants are supported and simulated on-the-fly, 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 rejection-free for anisotropic particles, but the algorithm is then no longer ergodic for those and needs to be combined with local moves.

Threading

The Clusters updater support threaded execution on multiple CPU cores.

pivot_move_probability

Set the probability for attempting a pivot move.

Type

float

flip_probability

Set the probability for transforming an individual cluster.

Type

float

trigger

Select the timesteps on which to perform cluster moves.

Type

Trigger

property avg_cluster_size

the typical size of clusters.

None when not attached.

(Loggable: category=”scalar”)

Type

float

class hoomd.hpmc.update.QuickCompress(trigger, target_box, 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.

  • 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 than max_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 of scale 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 of scale randomly between max(min_scale, 1.0 - min_move_size / max_diameter) and 1.0 where min_move_size is the smallest MC translational move size adjusted by the acceptance ratio and max_diameter is the circumsphere diameter of the largest particle type.

Tip

Use the hoomd.hpmc.tune.MoveSizeTuner in conjunction with QuickCompress 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.

trigger

Update the box dimensions on triggered time steps.

Type

Trigger

target_box

Dimensions of the target box.

Type

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

float

min_scale

The minimum scale factor to apply to box dimensions.

Type

float

instance

When using multiple QuickCompress updaters in a single simulation, give each a unique value for instance so that they generate different streams of random numbers.

Type

int

property complete

True when the box has achieved the target.