Box Module¶
Overview
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
ifNone
. (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
- 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 orNone
(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, 3\right)\)
numpy.ndarray
) – Masses corresponding to each vector, defaulting to 1 if not provided orNone
(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 fromquery_points[i]
topoints[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 asquery_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 fromquery_points[i]
topoints[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)¶
Returns 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 dimensionsL
, 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 here and here.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(type cls, L=None)¶
Construct a cubic box with equal lengths.
- Parameters
L (float) – The edge length
- classmethod 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'
, objects with attributesLx, Ly, Lz, xy, xz, yz, dimensions
, 3x3 matrices (seefrom_matrix()
), or existingfreud.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 onlyLx, 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 thedimensions
of the provided box. If no dimensions can be detected, the box will be 2D ifLz == 0
, and 3D otherwise.- Returns
The resulting box object.
- Return type
- classmethod from_matrix(type cls, box_matrix, dimensions=None)¶
Initialize a Box instance from a box matrix.
For more information and the source for this code, see: https://hoomd-blue.readthedocs.io/en/stable/box.html
- Parameters
box_matrix (array-like) – A 3x3 matrix or list of lists
dimensions (int) – Number of dimensions (Default value =
None
)
- 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
- 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
orNone
) – The array in which to place the absolute coordinates. It must be of dtype np.float32. IfNone
, 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
orNone
) – The array in which to place the fractional positions. It must be of dtype np.float32. IfNone
, 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
- 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. IfNone
, 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()
ormatplotlib.axes.Axes.plot()
.**kwargs – Passed on to
mpl_toolkits.mplot3d.Axes3D.plot()
ormatplotlib.axes.Axes.plot()
.
- classmethod 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.
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
- 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
orNone
) – The array in which to place the unwrapped vectors. It must be of dtype np.float32. IfNone
, 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*L_y, L_y, 0)\).
- Type
\((3, )\)
np.ndarray
- v3¶
The third box vector \((xz*L_z, yz*L_z, L_z)\).
- Type
\((3, )\)
np.ndarray
- 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
orNone
) – The array in which to place the wrapped vectors. It must be of dtype np.float32. IfNone
, 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