hoomd.hpmc.update

Overview

BoxMC

Apply box updates to sample isobaric and related ensembles.

Clusters

Apply geometric cluster algorithm (GCA) moves.

MuVT

Insert and remove particles in the muVT ensemble.

QuickCompress

Quickly compress a hard particle system to a target box.

Shape

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 non-overlapping 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

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 single BoxMC 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 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) \(\delta_\mathrm{volume}\).

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 \(\delta_\mathrm{aspect} [\mathrm{dimensionless}]\).

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 \((\delta_{\mathrm{length},x}, \delta_{\mathrm{length},y}, \delta_{\mathrm{length},z}) [\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 \((\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

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)

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

Mixed precision

Clusters uses reduced precision floating point arithmetic when checking for particle overlaps in the local particle reference frame.

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.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 grand-canonical) 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 of hoomd.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 of ngibbs.

trigger

Select the timesteps on which to perform cluster moves.

Type

int

transfer_types

List of type names that are being transferred from/to the reservoir or between boxes

Type

list

max_volume_rescale

Maximum step size in ln(V) (applies to Gibbs ensemble)

Type

float

move_ratio

The ratio between volume and exchange/transfer moves (applies to Gibbs ensemble)

Type

float

ntrial

(default: 1) Number of configurational bias attempts to swap depletants

Type

float

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

dict

property exchange_moves

Count of the accepted and rejected paricle exchange moves.

None when not attached

(Loggable: category=”sequence”)

Type

tuple[int, int]

property insert_moves

Count of the accepted and rejected paricle insertion moves.

None when not attached

(Loggable: category=”sequence”)

Type

tuple[int, int]

property remove_moves

Count of the accepted and rejected paricle removal moves.

None when not attached

(Loggable: category=”sequence”)

Type

tuple[int, int]

property volume_moves

Count of the accepted and rejected paricle volume moves.

None when not attached

(Loggable: category=”sequence”)

Type

tuple[int, int]

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 (see BoxMC 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 until hoomd.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 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.MoveSize 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.

Warning

Use QuickCompress OR BoxMC. 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.

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.

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)
trigger

Call the updater on triggered time steps.

Type

Trigger

shape_move

Type of shape move to apply when updating shape definitions

Type

ShapeMove

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

bool

type_select

Number of types to change every time the updater is called.

Type

int

nsweeps

Number of times to update shape definitions during each triggered timesteps.

Type

int

property particle_volumes

Volume of a single particle for each type.

(Loggable: category=”scalar”)

Type

list[float]

property shape_move_energy

Energy penalty due to shape changes.

(Loggable: category=”scalar”)

Type

float

property shape_moves

Count of the accepted and rejected shape moves.

(Loggable: category=”sequence”)

Type

tuple[int, int]