Box

class hoomd.Box(Lx, Ly, Lz=0, xy=0, xz=0, yz=0)

Define box dimensions.

Parameters:

• Lx (float) – box extent in the x direction \([\mathrm{length}]\).

• Ly (float) – box extent in the y direction \([\mathrm{length}]\).

• Lz (float) – box extent in the z direction \([\mathrm{length}]\).

• xy (float) – tilt factor xy \([\mathrm{dimensionless}]\).

• xz (float) – tilt factor xz \([\mathrm{dimensionless}]\).

• yz (float) – tilt factor yz \([\mathrm{dimensionless}]\).

Particles in a simulation exist in a triclinic box with periodic boundary conditions. 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 is defined in terms of the lattice vectors \(\vec a_1\), \(\vec a_2\) and \(\vec a_3\):

\[\left( \vec a_1, \vec a_2, \vec a_3 \right)\]

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. Similarly, \(xz\) and \(yz\) indicate the tilt of the third lattice vector \(\vec a_3\) with respect to the first and second lattice vector.

The full cell parameter matrix is:

\[\begin{split}\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{split}\]

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{split}\cos\gamma &= \cos(\angle\vec a_1, \vec a_2) &=& \frac{xy}{\sqrt{1+xy^2}}\\ \cos\beta &= \cos(\angle\vec a_1, \vec a_3) &=& \frac{xz}{\sqrt{1+xz^2+yz^2}}\\ \cos\alpha &= \cos(\angle\vec a_2, \vec a_3) &=& \frac{xy \cdot xz + yz}{\sqrt{1+xy^2} \sqrt{1+xz^2+yz^2}}\end{split}\]

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

\[\begin{split}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{split}\]

Box images

HOOMD-blue always stores particle positions \(\vec{r}\) inside the primary box image which includes the origin at the center. The primary box image include the left, bottom, and back face while excluding the right, top, and front face. In cubic boxes, this implies that the particle coordinates in the primary box image are in the interval \(\left[ -\frac{L}{2},\frac{L}{2} \right)\).

Unless otherwise noted in the documentation, operations apply the minimum image convention when computing pairwise interactions between particles:

\[\vec{r}_{ij} = \mathrm{minimum\_image}(\vec{r}_j - \vec{r}_i)\]

When running simulations with a fixed box size, use the particle images \(\vec{n}\) to compute the unwrapped coordinates:

\[\vec{r}_\mathrm{unwrapped} = \vec{r} + n_x \vec{a}_1 + n_y \vec{a}_2 + n_z \vec{a}_3\]

Two dimensional systems

Set Lz == 0 to make the box 2D. 2D boxes ignore xz and yz. Changing the box dimensionality from 2D to 3D (or from 3D to 2D) during a simulation will result in undefined behavior.

In 2D boxes, volume is in units of \([\mathrm{length}]^2\).

Factory Methods

Box has factory methods to enable easier creation of boxes: cube, square, from_matrix, from_basis_vectors, and from_box. See each method’s documentation for more details.

Example:

box = hoomd.Box(Lx=10, Ly=20, Lz=30, xy=0.5, xz=0.2, yz=0.1)

See also

hoomd.State.box

hoomd.State.set_box

property L

The box lengths, [Lx, Ly, Lz] \([\mathrm{length}]\).

Can be set with a float which sets all lengths, or a length 3 vector.

Example:

box.L = (15, 30, 60)

Type:

(3, ) numpy.ndarray of float

property Lx

The length of the box in the x dimension \([\mathrm{length}]\).

Example:

box.Lx = 15

Type:

float

property Ly

The length of the box in the y dimension \([\mathrm{length}]\).

Example:

box.Ly = 30

Type:

float

property Lz

The length of the box in the z dimension \([\mathrm{length}]\).

Example:

box.Lz = 60

Type:

float

__eq__(other)

Test if boxes are equal.

__neq__(other)

Test if boxes are not equal.

__reduce__()

Reduce values to picklable format.

__repr__()

Executable representation of the object.

classmethod cube(L)

Create a cube with side lengths L.

Parameters:

L (float) – The box side length \([\mathrm{length}]\).

Returns:

The created 3D box.

Return type:

hoomd.Box

Example:

box = hoomd.Box.cube(L=13)

property dimensions

The dimensionality of the box.

If Lz == 0, the box is treated as 2D, otherwise it is 3D. This property is not settable.

Example:

if box.dimensions == 2:
    pass

Type:

int

classmethod from_basis_vectors(box_matrix)

Initialize a Box instance from a box matrix.

Parameters:

box_matrix ((3, 3) numpy.ndarray of float) – A 3x3 matrix or list of lists representing a set of lattice basis vectors.

Note

The created box will be rotated with respect to the lattice basis. As a consequence the output of to_matrix will not be the same as the input provided to this function. This function also returns a rotation matrix comensurate with this transformation. Using this rotation matrix users can rotate the original points into the new box by applying the rotation to the points.

Note

When passing a 2D basis vectors, the third vector should be set to all zeros, while first two vectors should have the last element set to zero.

Returns:

A tuple containing:

• hoomd.Box: The created box configured according to the given basis vectors.

• numpy.ndarray: A 3x3 floating-point rotation matrix that can be used to transform the original basis vectors to align with the new box basis vectors.

Return type:

tuple[hoomd.Box, numpy.ndarray]

Example:

points = np.array([[0, 0, 0], [0.5, 0, 0], [0.25, 0.25, 0]])
box, rotation = hoomd.Box.from_basis_vectors(
    box_matrix=[[1, 1, 0], [1, -1, 0], [0, 0, 1]]
)
rotated_points = rotation @ points

classmethod from_box(box)

Initialize a Box instance from a box-like object.

Parameters:

box (box_like) – A box-like object.

Note

If all values are provided, a triclinic box will be constructed. If only Lx, Ly, Lz are provided, an orthorhombic box will be constructed. If only Lx, Ly are provided, a rectangular (2D) box will be constructed.

Returns:

The resulting box object.

Return type:

hoomd.Box

Example:

box = hoomd.Box.from_box(box=[10, 20, 30, 0.5, 0.2, 0.1])

classmethod from_matrix(box_matrix)

Create a box from an upper triangular matrix.

Parameters:

box_matrix ((3, 3) numpy.ndarray of float) –

An upper triangular matrix representing a box. The values for Lx, Ly, Lz, xy, xz, and yz are related to the matrix:

\[\begin{split}\begin{bmatrix} L_x & L_y \cdot xy & L_z \cdot xz \\ 0 & L_y & L_z \cdot yz \\ 0 & 0 & L_z \end{bmatrix}\end{split}\]

Returns:

The created box.

Return type:

hoomd.Box

Example:

box = hoomd.Box.from_matrix(
    box_matrix = [[10, 12, 14],
                  [0, 8, 16],
                  [0, 0, 18]])

property is2D

Flag whether the box is 2D.

If Lz == 0, the box is treated as 2D, otherwise it is 3D. This property is not settable.

Example:

if box.is2D:
    pass

Type:

bool

property periodic

The periodicity of each dimension.

periodic is always (True, True, True) for the box associated with the simulation State. Some components of periodic may be False in the hoomd.data.LocalSnapshot box attribute in MPI domain decomposition simulations. This indicates which box directions are communicated with neighboring ranks (False) and which are not (True).

Type:

(3, ) numpy.ndarray of bool

scale(s)

Scale box dimensions.

Scales the box in place by the given scale factors. Tilt factors are not modified.

Parameters:

s (float or list[float]) – scale factors in each dimension. If a single float is given then scale all dimensions by s; otherwise, s must be a sequence of 3 values used to scale each dimension.

Returns:

self

Examples:

box.scale(2)

box.scale((1, 2, 4))

classmethod square(L)

Create a square with side lengths L.

Parameters:

L (float) – The box side length \([\mathrm{length}]\).

Returns:

The created 2D box.

Return type:

hoomd.Box

box = hoomd.Box.square(L=128)

property tilts

The box tilts, [xy, xz, yz].

Can be set using one tilt for all axes or three tilts. If the box is 2D xz and yz will automatically be set to zero.

Example:

box.tilts = (1.1, 0.8, 0.2)

Type:

(3, ) numpy.ndarray of float

to_matrix()

(3, 3) numpy.ndarray float: The upper triangular matrix that defines the box.

[[Lx, Ly * xy, Lz * xz],
 [0,  Ly,      Lz * yz],
 [0,  0,       Lz]]

Example:

matrix = box.to_matrix()

property volume

Volume of the box.

\([\mathrm{length}]^{2}\) in 2D and \([\mathrm{length}]^{3}\) in 3D.

When setting volume the aspect ratio of the box is maintained while the lengths are changed.

Example:

box.volume = 2000

Type:

float

property xy

The tilt for the xy plane.

Example:

box.xy = 1.1

Type:

float

property xz

The tilt for the xz plane.

Example:

box.xz = 0.8

Type:

float

property yz

The tilt for the yz plane.

Example:

box.yz = 0.2

Type:

float