QuickCompress

class hoomd.hpmc.update.QuickCompress(trigger, target_box, max_overlaps_per_particle=0.25, min_scale=0.99, allow_unsafe_resize=False)

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 or hoomd.variant.box.BoxVariant) – 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.

  • allow_unsafe_resize (bool) – When True, box moves are proposed independent of particle translational move sizes.

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. For more control over the rate of compression, use a BoxVariant for target_box.

QuickCompress 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} \min( xy + (1-s) \cdot xy_\mathrm{target}, xy_\mathrm{target} ) & xy_\mathrm{target} < xy \\ \max( xy + (1-s) \cdot xy_\mathrm{target}, xy_\mathrm{target} ) & xy_\mathrm{target} \ge xy \end{cases} \\ xz' &= \begin{cases} \min( xz + (1-s) \cdot xz_\mathrm{target}, xz_\mathrm{target} ) & xz_\mathrm{target} < xz \\ \max( xz + (1-s) \cdot xz_\mathrm{target}, xz_\mathrm{target} ) & xz_\mathrm{target} \ge xz \end{cases} \\ yz' &= \begin{cases} \min( yz + (1-s) \cdot yz_\mathrm{target}, yz_\mathrm{target} ) & yz_\mathrm{target} < yz \\ \max( yz + (1-s) \cdot yz_\mathrm{target}, 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} \min( xy + (1-s) \cdot xy_\mathrm{target}, xy_\mathrm{target} ) & xy_\mathrm{target} < xy \\ \max( xy + (1-s) \cdot xy_\mathrm{target}, 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. If allow_unsafe_resize is True, box move sizes will be uniformly distributed between min_scale and 1.0 (with no consideration of min_move_size).

When using a BoxVariant for target_box, complete returns True if the current simulation box is equal to the box corresponding to target_box evaluated at the current timestep and there are no overlaps in the system. To ensure the updater has compressed the system to the final target box, use a condition that checks both the complete attribute of the updater and the simulation timestep. For example:

target_box = hoomd.variant.box.InverseVolumeRamp(
    sim.state.box, sim.state.box.volume / 2, 0, 1_000)
qc = hoomd.hpmc.update.QuickCompress(10, target_box)
while (
    sim.timestep < target_box.t_ramp + target_box.t_start or
    not qc.complete):
    sim.run(100)

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, allow_unsafe_resize must be set to True to progress toward the target box. Decrease max_overlaps_per_particle when using this setting to prevent unresolvable overlaps.

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.

Members inherited from AutotunedObject:

property kernel_parameters

Kernel parameters. Read more...

property is_tuning_complete

Check if kernel parameter tuning is complete. Read more...

tune_kernel_parameters()

Start tuning kernel parameters. Read more...

Members inherited from Integrator:

trigger

The trigger to activate this operation. Read more...

Members defined in QuickCompress:

target_box

The variant for the dimensions of the target box.

Type:

BoxVariant

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

allow_unsafe_resize

When True, box moves are proposed independent of particle translational move sizes.

Type:

bool

property complete

True when the box has achieved the target.