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>

Module author: Carl Simon Adorf <csadorf@umich.edu>

Module author: Bradley Dice <bdice@bradleydice.com>

Changed in version 0.7.0: Added box periodicity interface

For more information about the definition of the simulation box, please see:

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)
Return type:(float, float, float)
Lx

Length of the x-dimension of the box.

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

Length of the y-dimension of the box.

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

Length of the z-dimension of the box.

Getter:Returns this box’s z-dimension length
Setter:Sets this box’s z-dimension length
Type: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
Setter:Sets this box’s number of dimensions
Type: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.

For more information and the source for this code, see: http://hoomd-blue.readthedocs.io/en/stable/box.html

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
Returns:Image index vector
Return type: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)
Return type:(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)
Returns: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)
Return type:(float, float, float)
getLx(self)

Length of the x-dimension of the box.

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

Length of the y-dimension of the box.

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

Length of the z-dimension of the box.

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

Get the box’s periodicity in each dimension.

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

Get the box periodicity in the x direction.

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

Get the box periodicity in the y direction.

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

Get the box periodicity in the z direction.

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

Return the tilt factor xy.

Returns:xy tilt factor
Return type:float
getTiltFactorXZ(self)

Return the tilt factor xz.

Returns:xz tilt factor
Return type:float
getTiltFactorYZ(self)

Return the tilt factor yz.

Returns:yz tilt factor
Return type:float
getVolume(self)

Return the box volume (area in 2D).

Returns:box volume
Return type:float
is2D(self)

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

Returns:True if 2D, False if 3D
Return type: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
Returns:Vector of real coordinates \(\left(x, y, z\right)\)
Return type: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
Returns: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)
Setter:Set this box’s periodicity in each dimension
Type: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
Return type:list of lists, shape 3x3
to_tuple()[source]

Returns the box as named tuple.

Returns:box parameters
Return type: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
Note:

vecs are returned in place (nothing returned)

volume

Return the box volume (area in 2D).

Returns:box volume
Return type: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
Note:vecs are returned in place (nothing returned)
xy

Tilt factor xy of the box.

Returns:xy tilt factor
Return type:float
xz

Tilt factor xz of the box.

Returns:xz tilt factor
Return type:float
yz

Tilt factor yz of the box.

Returns:yz tilt factor
Return type:float