Box Module

Overview

freud.box.Box

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. By convention, the freud Box is centered at the origin ([0, 0, 0]), with the extent in each dimension described by the half-open interval [-L/2, L/2). 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 if None. (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

Lx

Get or set the x-dimension length.

Type

float

Ly

Get or set the y-dimension length.

Type

float

Lz

Get or set the z-dimension length.

Type

float

center(self, vecs, masses=None)

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.8154068, -1.0000002,  0.       ],
       [-0.8154068,  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 or None (Default value = None).

Returns

Vectors with center of mass subtracted.

Return type

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

center_of_mass(self, vecs, masses=None)

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.1845932,  0.       ,  0.       ])
Parameters
  • vecs (\(\left(N, 3\right)\) numpy.ndarray) – Vectors used to find center of mass.

  • masses (\(\left(N,\right)\) numpy.ndarray) – Masses corresponding to each vector, defaulting to 1 if not provided or None (Default value = None).

Returns

Center of mass.

Return type

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

compute_all_distances(self, query_points, points)

Calculate distances between all pairs of query points and points, using periodic boundaries.

Distances are calculated pairwise, i.e. distances[i, j] is the distance from query_points[i] to points[j].

Parameters
  • query_points (\(\left(N_{query\_points}, 3 \right)\) numpy.ndarray) – Array of query points.

  • points (\(\left(N_{points}, 3 \right)\) numpy.ndarray) – Array of points with same length as query_points.

Returns

Array of distances between query points and points.

Return type

\(\left(N_{query\_points}, N_{points}, \right)\) numpy.ndarray

compute_distances(self, query_points, points)

Calculate distances between two sets of points, using periodic boundaries.

Distances are calculated row-wise, i.e. distances[i] is the distance from query_points[i] to points[i].

Parameters
  • query_points (\(\left(N, 3\right)\) numpy.ndarray) – Array of query points.

  • points (\(\left(N, 3\right)\) numpy.ndarray) – Array of points.

Returns

Array of distances between query points and points.

Return type

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

contains(self, points)

Compute a boolean array (mask) corresponding to point membership in a box.

This calculation computes particle membership based on conventions defined by Box, ignoring periodicity. This means that in a cubic (3D) box with dimensions L, particles would be considered inside the box if their coordinates are between [-L/2, L/2]. Particles laying at a coordinate such as [0, L, 0] would be considered outside the box. More information about coordinate conventions can be found in the documentation on Using boxes and periodic boundary conditions.

Example:

>>> import freud
>>> box = freud.Box.cube(10)
>>> points = [[-4, 0, 0], [10, 0, 0], [0, -7, 0]]
>>> box.contains(points)
array([ True, False, False])
Parameters

points (\(\left(N, 3\right)\) numpy.ndarray) – Array of points.

Returns

Array of booleans, where True corresponds to points within the box, and False corresponds to points outside the box.

Return type

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

classmethod cube(type cls, L=None)

Construct a cubic box with equal lengths.

Parameters

L (float) – The edge length

Returns

The resulting box object.

Return type

freud.box.Box

cubic

Whether the box is a cube.

Type

bool

dimensions

Get or set the number of dimensions (2 or 3).

Type

int

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 attributes 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, box_matrix, dimensions=None)

Initialize a Box instance from a box matrix.

For more information and the source for this code, see: HOOMD-blue’s box documentation .

Parameters
  • box_matrix (array-like) – A 3x3 matrix or list of lists

  • dimensions (int) – Number of dimensions (Default value = None)

Returns

The resulting box object.

Return type

freud.box.Box

get_box_vector(self, i)

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(self, vecs)

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

is2D

Whether the box is 2D.

Type

bool

make_absolute(self, fractional_coordinates, out=None)

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.

  • out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the absolute coordinates. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns

Absolute coordinate vector(s). If out is provided, a reference to it is returned.

Return type

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

make_fractional(self, absolute_coordinates, out=None)

Convert absolute coordinates into fractional coordinates.

Parameters
  • absolute_coordinates (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray) – Absolute coordinate vector(s).

  • out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the fractional positions. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns

Fractional coordinate vector(s). If out is provided, a reference to it is returned.

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

periodic_x

Get or set the periodicity of the box in x.

Type

bool

periodic_y

Get or set the periodicity of the box in y.

Type

bool

periodic_z

Get or set the periodicity of the box in z.

Type

bool

plot(self, title=None, ax=None, image=[0, 0, 0], *args, **kwargs)

Plot a Box object.

Parameters
classmethod square(type cls, L=None)

Construct a 2-dimensional (square) box with equal lengths.

Parameters

L (float) – The edge length

Returns

The resulting box object.

Return type

freud.box.Box

to_dict(self)

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

dict

to_matrix(self)

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(self, vecs, imgs, out=None)

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).

  • out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the unwrapped vectors. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns

Unwrapped vector(s). If out is provided, a reference to it is returned.

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 \times L_y, L_y, 0)\).

Type

\((3, )\) np.ndarray

v3

The third box vector \((xz \times L_z, yz \times L_z, L_z)\).

Type

\((3, )\) np.ndarray

volume

The box volume (area in 2D).

Type

float

wrap(self, vecs, out=None)

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).

  • out (\(\left(3, \right)\) or \(\left(N, 3\right)\) numpy.ndarray or None) – The array in which to place the wrapped vectors. It must be of dtype numpy.float32. If None, this function will return a newly allocated array (Default value = None).

Returns

Vector(s) wrapped into the box. If out is provided, a reference to it is returned.

Return type

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

xy

Get or set the xy tilt factor.

Type

float

xz

Get or set the xz tilt factor.

Type

float

yz

Get or set the yz tilt factor.

Type

float