# hpmc.update¶

Overview

 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.Clusters(seed, swap_types, 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_types (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 cut-off criterion. Two particles belong to the same cluster if the circumspheres of the depletant-excluded 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.

The type swap move works between two types of spherical particles and exchanges their identities.

The Clusters updater support threaded execution on multiple CPU cores.

seed

Random number seed.

Type

int

swap_types

A pair of two types whose identities may be swapped.

Type

list

move_ratio

Set the ratio between pivot and reflection moves.

Type

float

flip_probability

Set the probability for transforming an individual cluster.

Type

float

swap_move_ratio

Set the ratio between type swap moves and geometric moves.

Type

float

trigger

Select the timesteps on which to perform cluster moves.

Type

Trigger

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.

Type

tuple[int, int]

property reflection_moves

Number of accepted and rejected reflection moves.

Returns

A tuple of (accepted moves, rejected moves) since the last run.

Type

tuple[int, int]

property swap_moves

Number of accepted and rejected swap moves.

Returns

A tuple of (accepted moves, rejected moves) since the last run.

Type

tuple[int, int]

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 (where the smallest value of scale is min_scale) 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

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.

Run completion

When the box reaches the target box size and there are no overlaps in the current configuration, QuickCompress will flag that it is complete, which will end the Simulation.run loop.

Note

When the Simulation.run loop ends after the requested number of steps, the final system configuration may include particle overlaps and the box size will be somewhere between the initial box and target_box.

Warning

If the the requested target_box is too small to attain, QuickCompress will not complete and the Simulation.run loop will end after the requested number of time steps.

trigger

Update the box dimensions on triggered time steps.

Type

Trigger

seed

Random number seed.

Type

int

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

property complete

True when the operation is complete.

Simulation.run stops the running whenever any operation in the Simulation is complete.