# Box Module¶

Contains data structures for simulation boxes.

## Simulation Box¶

class freud.box.Box(*args, **kwargs)[source]

The freud Box class for simulation boxes.

Module author: Richmond Newman <newmanrs@umich.edu>

Changed in version 0.7.0: Added box periodicity interface

Parameters: Lx (float) – Length of side x Ly (float) – Length of side y Lz (float) – Length of side z xy (float) – Tilt of xy plane xz (float) – Tilt of xz plane yz (float) – Tilt of yz plane is2D (bool) – Specify that this box is 2-dimensional, default is 3-dimensional.
L

Return the lengths of the box as a tuple (x, y, z).

Linv

Return the inverse lengths of the box (1/Lx, 1/Ly, 1/Lz).

Returns: dimensions of the box as (1/Lx, 1/Ly, 1/Lz) (float, float, float)
Lx

Length of the x-dimension of the box.

Getter: Returns this box’s x-dimension length Sets this box’s x-dimension length float
Ly

Length of the y-dimension of the box.

Getter: Returns this box’s y-dimension length Sets this box’s y-dimension length float
Lz

Length of the z-dimension of the box.

Getter: Returns this box’s z-dimension length Sets this box’s z-dimension length float
classmethod cube(L)[source]

Construct a cubic box with equal lengths.

Parameters: L (float) – The edge length
dimensions

Number of dimensions of this box (only 2 or 3 are supported).

Getter: Returns this box’s number of dimensions Sets this box’s number of dimensions int
classmethod from_box(box)[source]

Initialize a box instance from another box instance.

classmethod from_matrix(boxMatrix, dimensions=None)[source]

Initialize a box instance from a box matrix.

getCoordinates(self, f)

Alias for makeCoordinates()

Deprecated since version 0.8: Use makeCoordinates() instead.

getImage(self, vec)

Returns the image corresponding to a wrapped vector.

New in version 0.8.

Parameters: vec (numpy.ndarray, shape= $$\left(3\right)$$, dtype= numpy.float32) – Coordinates of unwrapped vector Image index vector numpy.ndarray, shape= $$\left(3\right)$$, dtype= numpy.int32
getL(self)

Return the lengths of the box as a tuple (x, y, z).

Returns: dimensions of the box as (x, y, z) (float, float, float)
getLatticeVector(self, i)

Get the lattice vector with index $$i$$.

Parameters: i (unsigned int) – Index ($$0 \leq i < d$$) of the lattice vector, where $$d$$ is the box dimension (2 or 3) lattice vector with index $$i$$
getLinv(self)

Return the inverse lengths of the box (1/Lx, 1/Ly, 1/Lz).

Returns: dimensions of the box as (1/Lx, 1/Ly, 1/Lz) (float, float, float)
getLx(self)

Length of the x-dimension of the box.

Returns: This box’s x-dimension length float
getLy(self)

Length of the y-dimension of the box.

Returns: This box’s y-dimension length float
getLz(self)

Length of the z-dimension of the box.

Returns: This box’s z-dimension length float
getPeriodic(self)

Get the box’s periodicity in each dimension.

Returns: Periodic attributes in x, y, z list[bool, bool, bool]
getPeriodicX(self)

Get the box periodicity in the x direction.

Returns: True if periodic, False if not bool
getPeriodicY(self)

Get the box periodicity in the y direction.

Returns: True if periodic, False if not bool
getPeriodicZ(self)

Get the box periodicity in the z direction.

Returns: True if periodic, False if not bool
getTiltFactorXY(self)

Return the tilt factor xy.

Returns: xy tilt factor float
getTiltFactorXZ(self)

Return the tilt factor xz.

Returns: xz tilt factor float
getTiltFactorYZ(self)

Return the tilt factor yz.

Returns: yz tilt factor float
getVolume(self)

Return the box volume (area in 2D).

Returns: box volume float
is2D(self)

Return if box is 2D (True) or 3D (False).

Returns: True if 2D, False if 3D bool
makeCoordinates(self, f)

Convert fractional coordinates into real coordinates.

Parameters: f (numpy.ndarray, shape= $$\left(3\right)$$, dtype= numpy.float32) – Fractional coordinates $$\left(x, y, z\right)$$ between 0 and 1 within parallelepipedal box Vector of real coordinates $$\left(x, y, z\right)$$ list[float, float, float]
makeFraction(self, vec)

Convert real coordinates into fractional coordinates.

Parameters: vec (numpy.ndarray, shape= $$\left(3\right)$$, dtype= numpy.float32) – Real coordinates within parallelepipedal box A fractional coordinate vector
periodic

Box periodicity in each dimension.

Getter: Returns this box’s periodicity in each dimension (True if periodic, False if not) Set this box’s periodicity in each dimension list[bool, bool, bool]
set2D(self, val)

Set the dimensionality to 2D (True) or 3D (False).

Parameters: val (bool) – 2D=True, 3D=False
setL(self, L)

Set all side lengths of box to L.

Parameters: L (float) – Side length of box
setPeriodic(self, x, y, z)

Set the box’s periodicity in each dimension.

Parameters: x (bool) – True if periodic in x, False if not y (bool) – True if periodic in y, False if not z (bool) – True if periodic in z, False if not
setPeriodicX(self, val)

Set the box periodicity in the x direction.

Parameters: val (bool) – True if periodic, False if not
setPeriodicY(self, val)

Set the box periodicity in the y direction.

Parameters: val (bool) – True if periodic, False if not
setPeriodicZ(self, val)

Set the box periodicity in the z direction.

Parameters: val (bool) – True if periodic, False if not
classmethod square(L)[source]

Construct a 2-dimensional (square) box with equal lengths.

Parameters: L (float) – The edge length
to_matrix()[source]

Returns the box matrix (3x3).

Returns: box matrix list of lists, shape 3x3
to_tuple()[source]

Returns the box as named tuple.

Returns: box parameters namedtuple
unwrap(self, vecs, imgs)

Unwrap a given array of vectors inside the box back into real space, using an array of image indices that determine how many times to unwrap in each dimension.

Parameters: vecs (numpy.ndarray, shape= $$\left(3\right)$$ or $$\left(N, 3\right)$$, dtype= numpy.float32) – Single vector or array of $$N$$ vectors imgs (numpy.ndarray, shape= $$\left(3\right)$$ or $$\left(N, 3\right)$$, dtype= numpy.int32) – Single image index or array of $$N$$ image indices vecs are returned in place (nothing returned)
volume

Return the box volume (area in 2D).

Returns: box volume float
wrap(self, vecs)

Wrap a given array of vectors from real space into the box, using the periodic boundaries.

Note

Since the origin of the box is in the center, wrapping is equivalent to applying the minimum image convention to the input vectors.

Parameters: vecs (numpy.ndarray, shape= $$\left(3\right)$$ or $$\left(N, 3\right)$$, dtype= numpy.float32) – Single vector or array of $$N$$ vectors vecs are returned in place (nothing returned)
xy

Tilt factor xy of the box.

Returns: xy tilt factor float
xz

Tilt factor xz of the box.

Returns: xz tilt factor float
yz

Tilt factor yz of the box.

Returns: yz tilt factor float