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:

http://hoomd-blue.readthedocs.io/en/stable/box.html

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)¶

Convert a vector of relative box coordinates (each in [0..1]) into absolute coordinates

Parameters:	f (list[float, float, float]) – list[fx, fy, fz]
Returns:	list[x, y, z]
Return type:	list[float, float, float]

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<=i<d) of the lattice vector, where d is 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:	list of 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([x, y, z], dtype=numpy.float32)) – Fractional coordinates between 0 and 1 within parallelpipedal box
Returns:	A vector inside the box corresponding to f

makeFraction(self, vec)¶

Convert fractional coordinates into real coordinates

Parameters:	vec (numpy.ndarray([x, y, z], dtype=numpy.float32)) – Coordinates within parallelpipedal box
Returns:	Fractional vector inside the box corresponding to f

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)¶

Wrap a given array of vectors back into the box from python

Parameters:	vecs – numpy array of vectors (Nx3) (or just 3 elements) to wrap
Note:	vecs 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 back into the box from python

Parameters:	vecs – numpy array of vectors (Nx3) (or just 3 elements) to wrap
Note:	vecs 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