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:
  • Lx (float) – Length of side x.
  • Ly (float) – Length of side y.
  • Lz (float) – Length of side z.
  • xy (float) – Tilt of xy plane.
  • xz (float) – Tilt of xz plane.
  • yz (float) – Tilt of yz plane.
  • is2D (bool) – Specify that this box is 2-dimensional, default is 3-dimensional.
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 properties 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_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]
is2D

Return if box is 2D (True) or 3D (False).

Returns:True if 2D, False if 3D.
Return type:bool
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_dict

Return box as dictionary.

Returns:Box parameters
Return type:dict
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

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. If True, 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.