Box Module¶
Overview
freud.box.Box |
The freud Box class for simulation boxes. |
freud.box.ParticleBuffer |
Replicates particles outside the box via periodic images. |
Details
The Box
class defines the geometry of a simulation box. The module
natively supports periodicity by providing the fundamental features for
wrapping vectors outside the box back into it. The ParticleBuffer
class is used to replicate particles across the periodic boundary to assist
analysis methods that do not recognize periodic boundary conditions or extend
beyond the limits of one periodicity of the box.
Box¶
-
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)
-
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]
-
makeCoordinates
¶ 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
¶ 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
Particle Buffer¶
-
class
freud.box.
ParticleBuffer
(box)¶ Replicates particles outside the box via periodic images.
Module author: Ben Schultz <baschult@umich.edu>
Module author: Bradley Dice <bdice@bradleydice.com>
New in version 0.11.
Parameters: box (
freud.box.Box
) – Simulation box.Variables: - buffer_particles (
numpy.ndarray
) – The buffer particles. - buffer_ids (
numpy.ndarray
) – The buffer ids. - buffer_box (
freud.box.Box
) – The buffer box, expanded to hold the replicated particles.
-
compute
¶ Compute the particle buffer.
Parameters: - points ((\(N_{particles}\), 3)
numpy.ndarray
) – Points used to calculate particle buffer. - buffer (float) – Buffer distance for replication outside the box.
- images (bool) – If
False
(default),buffer
is a distance. IfTrue
,buffer
is a number of images to replicate in each dimension. Note that one image adds half of a box length to each side, meaning that one image doubles the box side lengths, two images triples the box side lengths, and so on.
- points ((\(N_{particles}\), 3)
- buffer_particles (