Periodic boundary conditions¶

Introduction¶

All simulations executed in HOOMD-blue occur in a triclinic simulation box with periodic boundary conditions in all three directions. A triclinic box is defined by six values: the extents \(L_x\), \(L_y\) and \(L_z\) of the box in the three directions, and three tilt factors \(xy\), \(xz\) and \(yz\).

The parameter matrix \(\mathbf{h}\) is defined in terms of the lattice vectors \(\vec a_1\), \(\vec a_2\) and \(\vec a_3\):

\[\mathbf{h} \equiv \left( \vec a_1, \vec a_2, \vec a_3 \right)\]

By convention, the first lattice vector \(\vec a_1\) is parallel to the unit vector \(\vec e_x = (1,0,0)\). The tilt factor \(xy\) indicates how the second lattice vector \(\vec a_2\) is tilted with respect to the first one. It specifies many units along the x-direction correspond to one unit of the second lattice vector. Similarly, \(xz\) and \(yz\) indicate the tilt of the third lattice vector \(\vec a_3\) with respect to the first and second lattice vector.

Definitions and formulas for the cell parameter matrix¶

The full cell parameter matrix is:

\begin{eqnarray*} \mathbf{h}& =& \left(\begin{array}{ccc} L_x & xy L_y & xz L_z \\ 0 & L_y & yz L_z \\ 0 & 0 & L_z \\ \end{array}\right) \end{eqnarray*}

The tilt factors \(xy\), \(xz\) and \(yz\) are dimensionless. The relationships between the tilt factors and the box angles \(\alpha\), \(\beta\) and \(\gamma\) are as follows:

\begin{eqnarray*} \cos\gamma \equiv \cos(\angle\vec a_1, \vec a_2) &=& \frac{xy}{\sqrt{1+xy^2}}\\ \cos\beta \equiv \cos(\angle\vec a_1, \vec a_3) &=& \frac{xz}{\sqrt{1+xz^2+yz^2}}\\ \cos\alpha \equiv \cos(\angle\vec a_2, \vec a_3) &=& \frac{xy \cdot xz + yz}{\sqrt{1+xy^2} \sqrt{1+xz^2+yz^2}} \end{eqnarray*}

Given an arbitrarily oriented lattice with box vectors \(\vec v_1, \vec v_2, \vec v_3\), the HOOMD-blue box parameters for the rotated box can be found as follows.

\begin{eqnarray*} L_x &=& v_1\\ a_{2x} &=& \frac{\vec v_1 \cdot \vec v_2}{v_1}\\ L_y &=& \sqrt{v_2^2 - a_{2x}^2}\\ xy &=& \frac{a_{2x}}{L_y}\\ L_z &=& \vec v_3 \cdot \frac{\vec v_1 \times \vec v_2}{\left| \vec v_1 \times \vec v_2 \right|}\\ a_{3x} &=& \frac{\vec v_1 \cdot \vec v_3}{v_1}\\ xz &=& \frac{a_{3x}}{L_z}\\ yz &=& \frac{\vec v_2 \cdot \vec v_3 - a_{2x}a_{3x}}{L_y L_z} \end{eqnarray*}

Example:

# boxMatrix contains an arbitrarily oriented right-handed box matrix.
v[0] = boxMatrix[:,0]
v[1] = boxMatrix[:,1]
v[2] = boxMatrix[:,2]
Lx = numpy.sqrt(numpy.dot(v[0], v[0]))
a2x = numpy.dot(v[0], v[1]) / Lx
Ly = numpy.sqrt(numpy.dot(v[1],v[1]) - a2x*a2x)
xy = a2x / Ly
v0xv1 = numpy.cross(v[0], v[1])
v0xv1mag = numpy.sqrt(numpy.dot(v0xv1, v0xv1))
Lz = numpy.dot(v[2], v0xv1) / v0xv1mag
a3x = numpy.dot(v[0], v[2]) / Lx
xz = a3x / Lz
yz = (numpy.dot(v[1],v[2]) - a2x*a3x) / (Ly*Lz)

Initializing a system with a triclinic box¶

You can specify all parameters of a triclinic box in a GSD file.

You can also pass a hoomd.data.boxdim argument to the constructor of any initialization method. Here is an example for hoomd.deprecated.init.create_random():

init.create_random(box=data.boxdim(L=18, xy=0.1, xz=0.2, yz=0.3), N=1000))

This creates a triclinic box with edges of length 18, and tilt factors \(xy =0.1\), \(xz=0.2\) and \(yz=0.3\).

You can also specify a 2D box to any of the initialization methods:

init.create_random(N=1000, box=data.boxdim(xy=1.0, volume=2000, dimensions=2), min_dist=1.0)

Change the simulation box¶

The triclinic unit cell can be updated in various ways.

Resizing the box¶

The simulation box can be gradually resized during a simulation run using hoomd.update.box_resize.

To update the tilt factors continuously during the simulation (shearing the simulation box with Lees-Edwards boundary conditions), use:

update.box_resize(xy = variant.linear_interp([(0,0), (1e6, 1)]))

This command applies shear in the \(xy\) -plane so that the angle between the x and y-directions changes continuously from 0 to \(45^\circ\) during \(10^6\) time steps.

hoomd.update.box_resize can change any or all of the six box parameters.

NPT or NPH integration¶

In a constant pressure ensemble, the box is updated every time step, according to the anisotropic stresses in the system. This is supported by: