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

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.8154063, -1.       ,  0.       ],
[-0.8154063,  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

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.18459368,  0.        ,  0.        ])

Parameters
• vecs ($$\left(N, 3\right)$$ numpy.ndarray) – Vectors used to find center of mass.

• masses ($$\left(N, 3\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

classmethod cube(type cls, L=None)

Construct a cubic box with equal lengths.

Parameters

L (float) – The edge length

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.

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

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

get_box_vector

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

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

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.

Returns

Absolute coordinate vector(s).

Return type

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

make_fractional

Convert absolute coordinates into fractional coordinates.

Parameters

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

Returns

Fractional coordinate vector(s).

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

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

to_dict

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

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

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
Returns

Unwrapped vector(s).

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*L_y, L_y, 0)$$.

Type

$$(3, )$$ np.ndarray

v3

The third box vector $$(xz*L_z, yz*L_z, L_z)$$.

Type

$$(3, )$$ np.ndarray

volume

The box volume (area in 2D).

Type

float

wrap

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

Returns

Vector(s) wrapped into the box.

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