BoxMC¶

class hoomd.hpmc.update.BoxMC(trigger, P)¶

Bases: Updater

Apply box updates to sample isobaric and related ensembles.

Parameters:

P (hoomd.variant.variant_like) – The pressure \(P\) \([\mathrm{energy}] \cdot [\mathrm{length}^{-2}]\) in 2D or \([\mathrm{energy}] \cdot [\mathrm{length}^{-3}]\) in 3D.
trigger (hoomd.trigger.trigger_like) – 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, 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 \(\beta = \frac{1}{kT}\) (set in HPMCIntegrator.kT) and \(\Delta U = U^t - U\) is the difference in potential energy. \(\Delta H = P (V^t - V) - N_\mathrm{particles} \cdot \ln(V^t / V) / \beta\) for most move types. It is \(P (V^t - V) - (N_\mathrm{particles}+1) \cdot \ln(V^t / V) / \beta\) 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.

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 BoxMC:

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

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

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

P¶

The pressure \(P\) \([\mathrm{energy} \ \mathrm{length}^{-2}]\) in 2D or \([\mathrm{energy} \ \mathrm{length}^{-3}]\) in 3D.

Type:: hoomd.variant.Variant

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

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

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]