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 along x, y, and z.

  • Lx (float, settable) – The x-dimension length.

  • Ly (float, settable) – The y-dimension length.

  • Lz (float, 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)

getImage

Returns the image corresponding to a wrapped vector.

New in version 0.8.

Parameters

vecs (\(\left(3\right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Coordinates of a single vector or array of \(N\) unwrapped vectors.

Returns

Image index vector.

Return type

\(\left(3\right)\) or \(\left(N, 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

makeCoordinates

Convert fractional coordinates into real coordinates.

Parameters

fractions (\(\left(3\right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Fractional coordinates between 0 and 1 within parallelepipedal box.

Returns

Vectors of real coordinates: \(\left(3\right)\) or \(\left(N, 3\right)\).

Return type

\(\left(3\right)\) or \(\left(N, 3\right)\) numpy.ndarray

makeFraction

Convert real coordinates into fractional coordinates.

Parameters

vecs (\(\left(3\right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Real coordinates within parallelepipedal box.

Returns

Fractional coordinate vectors: \(\left(3\right)\) or \(\left(N, 3\right)\).

Return type

\(\left(3\right)\) or \(\left(N, 3\right)\) numpy.ndarray

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 (\(\left(N_{buffer}, 3\right)\) numpy.ndarray) – The buffer particle positions.

  • buffer_ids (\(\left(N_{buffer}\right)\) numpy.ndarray) – The buffer particle 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 or list of 3 floats) – 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.