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. 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
¶ 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.8154063, -1. , 0. ], [-0.8154063, 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
¶ 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.18459368, 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
-
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
¶ 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
¶ 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
¶ 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.- Returns
Absolute coordinate vector(s).
- Return type
\(\left(3, \right)\) or \(\left(N, 3\right)\)
numpy.ndarray
-
make_fractional
¶ Convert absolute coordinates into fractional coordinates.
- Parameters
absolute_coordinates (\(\left(3, \right)\) or \(\left(N, 3\right)\)
numpy.ndarray
) – Absolute coordinate vector(s).- Returns
Fractional coordinate vector(s).
- 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
¶ 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
¶ 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
¶ 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
¶ 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).
- Returns
Unwrapped vector(s).
- 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
¶ 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).- Returns
Vector(s) wrapped into the box.
- Return type
\(\left(3, \right)\) or \(\left(N, 3\right)\)
numpy.ndarray