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:
Parameters: 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.
- periodic_x (bool, settable) – Whether or not the box is periodic in x.
- periodic_y (bool, settable) – Whether or not the box is periodic in y.
- periodic_z (bool, settable) – Whether or not the box is periodic in z.
-
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'
, namedtuples with propertiesLx, 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: freud.box:Box
-
classmethod
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
¶
-
getImage
¶ 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
-
getLatticeVector
¶ 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]
-
makeFraction
¶ 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]
-
classmethod
square
(type cls, L=None)¶ Construct a 2-dimensional (square) box with equal lengths.
Parameters: L (float) – The edge length
-
to_matrix
¶ Returns the box matrix (3x3).
Returns: box matrix Return type: list of lists, shape 3x3
-
to_tuple
¶ Returns the box as named tuple.
Returns: Box parameters Return type: namedtuple
-
unwrap
¶ 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
- vecs (\(\left(3\right)\) or \(\left(N, 3\right)\)
-
wrap
¶ 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