Box Module¶

Overview

freud.box.Box

The freud Box class for simulation boxes.

Details

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

class freud.box.Box¶

Bases: object

The freud Box class for simulation boxes.

This class defines an arbitrary triclinic geometry within which all points are confined. By convention, the freud Box is centered at the origin ([0, 0, 0]), with the extent in each dimension described by the half-open interval [-L/2, L/2). For more information, see the documentation on boxes and periodic boundary conditions.

Also available as freud.Box.

Parameters:

Lx (float, optional) – The x-dimension length.
Ly (float, optional) – The y-dimension length.
Lz (float, optional) – The z-dimension length (Default value = 0).
xy (float, optional) – The xy tilt factor (Default value = 0).
xz (float, optional) – The xz tilt factor (Default value = 0).
yz (float, optional) – The yz tilt factor (Default value = 0).
is2D (bool, optional) – Whether the box is 2-dimensional. Uses Lz == 0 if None. (Default value = None)

L¶

Get or set the box lengths along x, y, and z.

Type:: \(\left(3, \right)\) numpy.ndarray

L_inv¶

The inverse box lengths.

Type:: \(\left(3, \right)\) numpy.ndarray

Lx¶

Get or set the x-dimension length.

Type:: float

Ly¶

Get or set the y-dimension length.

Type:: float

Lz¶

Get or set the z-dimension length.

Type:: float

center(self, vecs, masses=None)¶

Subtract center of mass from an array of vectors, using periodic boundaries.

This calculation accounts for periodic images. This Wikipedia page describes the mathematics of this method.

Example:

>>> import freud
>>> box = freud.Box.cube(10)
>>> points = [[-1, -1, 0], [-1, 1, 0], [2, 0, 0]]
>>> box.center(points)
array([[-0.8154068, -1.0000002,  0.       ],
       [-0.8154068,  1.       ,  0.       ],
       [ 2.1845937,  0.       ,  0.       ]], dtype=float32)

Parameters:

vecs (\(\left(N, 3\right)\) numpy.ndarray) – Vectors to center.
masses (\(\left(N, 3\right)\) numpy.ndarray) – Masses corresponding to each vector, defaulting to 1 if not provided or None (Default value = None).

Returns:

Vectors with center of mass subtracted.

Return type:

\(\left(N, 3\right)\) numpy.ndarray

center_of_mass(self, vecs, masses=None)¶

Compute center of mass of an array of vectors, using periodic boundaries.

This calculation accounts for periodic images. This Wikipedia page describes the mathematics of this method.

Example:

>>> import freud
>>> import numpy as np
>>> box = freud.Box.cube(10)
>>> points = [[-1, -1, 0], [-1, 1, 0], [2, 0, 0]]
>>> np.mean(points, axis=0)  # Does not account for periodic images
array([0., 0., 0.])
>>> box.center_of_mass(points)  # Accounts for periodic images
array([-0.1845932,  0.       ,  0.       ])

Parameters:

vecs (\(\left(N, 3\right)\) numpy.ndarray) – Vectors used to find center of mass.
masses (\(\left(N,\right)\) numpy.ndarray) – Masses corresponding to each vector, defaulting to 1 if not provided or None (Default value = None).

Returns:

Center of mass.

Return type:

\(\left(3, \right)\) numpy.ndarray

compute_all_distances(self, query_points, points)¶

Calculate distances between all pairs of query points and points, using periodic boundaries.

Distances are calculated pairwise, i.e. distances[i, j] is the distance from query_points[i] to points[j].

Parameters:

query_points (\(\left(N_{query\_points}, 3 \right)\) numpy.ndarray) – Array of query points.
points (\(\left(N_{points}, 3 \right)\) numpy.ndarray) – Array of points with same length as query_points.

Returns:

Array of distances between query points and points.

Return type:

\(\left(N_{query\_points}, N_{points}, \right)\) numpy.ndarray

compute_distances(self, query_points, points)¶

Calculate distances between two sets of points, using periodic boundaries.

Distances are calculated row-wise, i.e. distances[i] is the distance from query_points[i] to points[i].

Parameters:

query_points (\(\left(N, 3\right)\) numpy.ndarray) – Array of query points.
points (\(\left(N, 3\right)\) numpy.ndarray) – Array of points.

Returns:

Array of distances between query points and points.

Return type:

\(\left(N, \right)\) numpy.ndarray

contains(self, points)¶

Compute a boolean array (mask) corresponding to point membership in a box.

This calculation computes particle membership based on conventions defined by Box, ignoring periodicity. This means that in a cubic (3D) box with dimensions L, particles would be considered inside the box if their coordinates are between [-L/2, L/2]. Particles laying at a coordinate such as [0, L, 0] would be considered outside the box. More information about coordinate conventions can be found in the documentation on Using boxes and periodic boundary conditions.

Example:

>>> import freud
>>> box = freud.Box.cube(10)
>>> points = [[-4, 0, 0], [10, 0, 0], [0, -7, 0]]
>>> box.contains(points)
array([ True, False, False])

Parameters:: points (\(\left(N, 3\right)\) numpy.ndarray) – Array of points.
Returns:: Array of booleans, where True corresponds to points within the box, and False corresponds to points outside the box.
Return type:: \(\left(N, \right)\) numpy.ndarray

classmethod cube(cls, L=None)¶

Construct a cubic box with equal lengths.

Parameters:: L (float) – The edge length
Returns:: The resulting box object.
Return type:: freud.box.Box

cubic¶

Whether the box is a cube.

Type:: bool

dimensions¶

Get or set the number of dimensions (2 or 3).

Type:: int

classmethod from_box(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', objects with attributes 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

classmethod from_box_lengths_and_angles(cls, L1, L2, L3, alpha, beta, gamma, dimensions=None)¶

Construct a box from lengths and angles (in radians).

All the angles provided must be between 0 and \(\pi\).

Parameters:

L1 (float) – The length of the first lattice vector.
L2 (float) – The length of the second lattice vector.
L3 (float) – The length of the third lattice vector.
alpha (float) – The angle between second and third lattice vector in radians (must be between 0 and \(\pi\)).
beta (float) – The angle between first and third lattice vector in radians (must be between 0 and \(\pi\)).
gamma (float) – The angle between the first and second lattice vector in radians (must be between 0 and \(\pi\)).
dimensions (int) – The number of dimensions (Default value = None).

Returns:

The resulting box object.

Return type:

freud.box.Box

classmethod from_matrix(cls, box_matrix, dimensions=None)¶

Initialize a Box instance from a box matrix.

For more information and the source for this code, see: HOOMD-blue’s box documentation .

Parameters:

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

Returns:

The resulting box object.

Return type:

freud.box.Box

get_box_vector(self, i)¶

Get the box vector with index \(i\).

Parameters:: i (unsigned int) – Index (\(0 \leq i < d\)) of the box vector, where \(d\) is the box dimension (2 or 3).
Returns:: Box vector with index \(i\).
Return type:: \(\left(3, \right)\) numpy.ndarray

get_images(self, vecs)¶

Returns the images corresponding to unwrapped vectors.

Parameters:: vecs (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Coordinates of unwrapped vector(s).
Returns:: Image index vector(s).
Return type:: \(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray

is2D¶

Whether the box is 2D.

Type:: bool

make_absolute(self, fractional_coordinates, out=None)¶

Convert fractional coordinates into absolute coordinates.

Parameters:

fractional_coordinates (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Fractional coordinate vector(s), between 0 and 1 within parallelepipedal box.
out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the absolute coordinates. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns:

Absolute coordinate vector(s). If out is provided, a reference to it is returned.

Return type:

\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray

make_fractional(self, absolute_coordinates, out=None)¶

Convert absolute coordinates into fractional coordinates.

Parameters:

absolute_coordinates (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Absolute coordinate vector(s).
out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the fractional positions. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns:

Fractional coordinate vector(s). If out is provided, a reference to it is returned.

Return type:

\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray

periodic¶

Get or set the periodicity of the box in each dimension.

Type:: \(\left(3, \right)\) numpy.ndarray

periodic_x¶

Get or set the periodicity of the box in x.

Type:: bool

periodic_y¶

Get or set the periodicity of the box in y.

Type:: bool

periodic_z¶

Get or set the periodicity of the box in z.

Type:: bool

plot(self, title=None, ax=None, image=[0, 0, 0], *args, **kwargs)¶

Plot a Box object.

Parameters:

title (str) – Title of the graph. (Default value = None).
ax (matplotlib.axes.Axes) – Axes object to plot. If None, make a new axes and figure object. If plotting a 3D box, the axes must be 3D. (Default value = None).
image (list) – The periodic image location at which to draw the box (Default value = [0, 0, 0]).
*args – Passed on to mpl_toolkits.mplot3d.Axes3D.plot() or matplotlib.axes.Axes.plot().
**kwargs – Passed on to mpl_toolkits.mplot3d.Axes3D.plot() or matplotlib.axes.Axes.plot().

classmethod square(cls, L=None)¶

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

Parameters:: L (float) – The edge length
Returns:: The resulting box object.
Return type:: freud.box.Box

to_box_lengths_and_angles(self)¶

Return the box lengths and angles.

Returns:: The box vector lengths and angles in radians \((L_1, L_2, L_3, \alpha, \beta, \gamma)\).
Return type:: tuple

to_dict(self)¶

Return box as dictionary.

Example:

>>> box = freud.box.Box.cube(L=10)
>>> box.to_dict()
{'Lx': 10.0, 'Ly': 10.0, 'Lz': 10.0,
 'xy': 0.0, 'xz': 0.0, 'yz': 0.0, 'dimensions': 3}

Returns:: Box parameters
Return type:: dict

to_matrix(self)¶

Returns the box matrix (3x3).

Example:

>>> box = freud.box.Box.cube(L=10)
>>> box.to_matrix()
array([[10.,  0.,  0.],
       [ 0., 10.,  0.],
       [ 0.,  0., 10.]])

Returns:: Box matrix
Return type:: \(\left(3, 3\right)\) numpy.ndarray

unwrap(self, vecs, imgs, out=None)¶

Unwrap an 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) – Vector(s) to be unwrapped.
imgs (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Image indices for vector(s).
out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the unwrapped vectors. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns:

Unwrapped vector(s). If out is provided, a reference to it is returned.

Return type:

\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray

v1¶

The first box vector \((L_x, 0, 0)\).

Type:: \((3, )\) np.ndarray

v2¶

The second box vector \((xy \times L_y, L_y, 0)\).

Type:: \((3, )\) np.ndarray

v3¶

The third box vector \((xz \times L_z, yz \times L_z, L_z)\).

Type:: \((3, )\) np.ndarray

volume¶

The box volume (area in 2D).

Type:: float

wrap(self, vecs, out=None)¶

Wrap an array of vectors into the box, using 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) – Unwrapped vector(s).
out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the wrapped vectors. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns:

Vector(s) wrapped into the box. If out is provided, a reference to it is returned.

Return type:

\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray

xy¶

Get or set the xy tilt factor.

Type:: float

xz¶

Get or set the xz tilt factor.

Type:: float

yz¶

Get or set the yz tilt factor.

Type:: float