Box Module¶

Overview

freud.box.Box The freud Box class for simulation boxes.

Details

The box module provides the Box class, which defines the geometry of the simulation box. The module natively supports periodicity by providing the fundamental features for wrapping vectors outside the box back into it.

class freud.box.Box(Lx, Ly, Lz, xy, xz, yz, is2D=None)¶

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

The Box class is defined according to the conventions of the HOOMD-blue simulation software. For more information, 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.

Variables:

xy (float) – The xy tilt factor.
xz (float) – The xz tilt factor.
yz (float) – The yz tilt factor.
L (tuple, settable) – The box lengths
Lx (tuple, settable) – The x-dimension length.
Ly (tuple, settable) – The y-dimension length.
Lz (tuple, settable) – The z-dimension length.
Linv (tuple) – The inverse box lengths.
volume (float) – The box volume (area in 2D).
dimensions (int, settable) – The number of dimensions (2 or 3).
periodic (list, settable) – Whether or not the box is periodic.

cube(type cls, L=None)¶

Construct a cubic box with equal lengths.

Parameters:	L (float) – The edge length

from_box(type cls, box, dimensions=None)¶

Initialize a box instance from a box-like object.

Parameters:	box – A box-like object dimensions (int) – Dimensionality of the box (Default value = None)

Note

Objects that can be converted to freud boxes include lists like [Lx, Ly, Lz, xy, xz, yz], dictionaries with keys 'Lx', 'Ly', 'Lz', 'xy', 'xz', 'yz', 'dimensions', namedtuples with properties Lx, Ly, Lz, xy, xz, yz, dimensions, 3x3 matrices (see from_matrix()), or existing freud.box.Box objects.

If any of Lz, xy, xz, yz are not provided, they will be set to 0.

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.

If the optional dimensions argument is given, this will be used as the box dimensionality. Otherwise, the box dimensionality will be detected from the dimensions of the provided box. If no dimensions can be detected, the box will be 2D if Lz == 0, and 3D otherwise.

Returns:	The resulting box object.
Return type:	`freud.box:Box`

from_matrix(type cls, boxMatrix, dimensions=None)¶

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

Parameters:	boxMatrix (array-like) – A 3x3 matrix or list of lists dimensions (int) – Number of dimensions (Default value = None)

getCoordinates(self, f)¶

Alias for makeCoordinates()

Deprecated since version 0.8: Use makeCoordinates() instead.

Parameters:	f (\(\left(3\right)\) `numpy.ndarray`) – Fractional coordinates \(\left(x, y, z\right)\) between 0 and 1 within parallelepipedal box.

getImage(self, vec)¶

Returns the image corresponding to a wrapped vector.

New in version 0.8.

Parameters:	vec (\(\left(3\right)\) `numpy.ndarray`) – Coordinates of unwrapped vector.
Returns:	Image index vector.
Return type:	\(\left(3\right)\) `numpy.ndarray`

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\).
Return type:	list[float, float, float]

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:	This box’s xy tilt factor.
Return type:	float

getTiltFactorXZ(self)¶

Return the tilt factor xz.

Returns:	This box’s xz tilt factor.
Return type:	float

getTiltFactorYZ(self)¶

Return the tilt factor yz.

Returns:	This box’s 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 (\(\left(3\right)\) `numpy.ndarray`) – 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 (\(\left(3\right)\) `numpy.ndarray`) – Real coordinates within parallelepipedal box.
Returns:	A fractional coordinate vector.
Return type:	list[float, float, float]

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.

square(type cls, L=None)¶

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

Parameters:	L (float) – The edge length

to_dict(self)¶

Return box as dictionary.

Returns:	Box parameters
Return type:	dict

to_matrix(self)¶

Returns the box matrix (3x3).

Returns:	box matrix
Return type:	list of lists, shape 3x3

to_tuple(self)¶

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 (\(\left(3\right)\) or \(\left(N, 3\right)\) `numpy.ndarray`) – Single vector or array of \(N\) vectors. The vectors are modified in place. imgs (\(\left(3\right)\) or \(\left(N, 3\right)\) `numpy.ndarray`) – Single image index or array of \(N\) image indices.
Returns:	Vectors unwrapped by the image indices provided.
Return type:	\(\left(3\right)\) or \(\left(N, 3\right)\) `numpy.ndarray`

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 (\(\left(3\right)\) or \(\left(N, 3\right)\) `numpy.ndarray`) – Single vector or array of \(N\) vectors. The vectors are altered in place and returned.
Returns:	Vectors wrapped into the box.
Return type:	\(\left(3\right)\) or \(\left(N, 3\right)\) `numpy.ndarray`