Data Module¶

Overview

`freud.data.UnitCell`	Class to represent the unit cell of a crystal structure.
`freud.data.make_random_system`	Helper function to make random points with a cubic or square box.

Details

The freud.data module provides certain sample data sets and utility functions that are useful for testing and examples.

Stability

freud.data is unstable. When upgrading from version 2.x to 2.y (y > x), existing freud scripts may need to be updated. The API will be finalized in a future release.

class freud.data.UnitCell(box, basis_positions=[[0, 0, 0]])[source]¶

Bases: object

Class to represent the unit cell of a crystal structure.

This class represents the unit cell of a crystal structure, which is defined by a lattice and a basis. It provides the basic attributes of the unit cell as well as enabling the generation of systems of points (optionally with some noise) from the unit cell.

Parameters:

box – A box-like object (see from_box()) containing the lattice vectors of the unit cell.
basis_positions ((\(N_{points}\), 3) numpy.ndarray) – The basis of the unit cell in fractional coordinates (Default value = [[0, 0, 0]]).

property a1¶

The first lattice vector.

Type:: \((3, )\) np.ndarray

property a2¶

The second lattice vector.

Type:: \((3, )\) np.ndarray

property a3¶

The third lattice vector.

Type:: \((3, )\) np.ndarray

property basis_positions¶

The basis positions.

Type:: \((N_{points}, 3)\) np.ndarray

classmethod bcc()[source]¶

Create a body-centered cubic (bcc) unit cell.

Returns:: A body-centered cubic unit cell.
Return type:: UnitCell

property box¶

The box instance containing the lattice vectors.

Type:: freud.box.Box

property dimensions¶

The dimensionality of the unit cell.

Type:: int

classmethod fcc()[source]¶

Create a face-centered cubic (fcc) unit cell.

Returns:: A face-centered cubic unit cell.
Return type:: UnitCell

generate_system(num_replicas=1, scale=1, sigma_noise=0, seed=None)[source]¶

Generate a system from the unit cell.

The box and the positions are expanded by scale, and then Gaussian noise with standard deviation sigma_noise is added to the positions. All points are wrapped back into the box before being returned.

Parameters:

num_replicas (tuple or int) – If provided as a single number, the number of replicas in all dimensions. If a tuple, the number of times replicated in each dimension. Must be of the form (nx, ny, 1) for 2D boxes (Default value = 1).
scale (float) – Factor by which to scale the unit cell (Default value = 1).
sigma_noise (float) – The standard deviation of the normal distribution used to add noise to the positions in the system (Default value = 0).
seed (int) – If provided, used to seed the random noise generation. Not used unless sigma_noise > 0 (Default value = None).

Returns:

A system-like object (see from_system).

Return type:

tuple (freud.box.Box, np.ndarray)

Note

Positions are generated in the order of the instance’s basis_positions. The first \(N_{replica}\) positions come from the first basis position, the next \(N_{replica}\) the second, etc. This behavior is analoguous to numpy.repeat rather than numpy.tile. To generate the indices use the following expression.

if isinstance(n_repeats, int):
    N = n_repeats ** dimension
else:
    N = np.prod(n_repeats)
indices = np.repeat(np.arange(len(uc.basis_positions)), N)

Below is an example of expanding basis position properties (in this case, types) to a replicated lattice.

Example:

>>> uc = freud.data.UnitCell.bcc()
>>> n_repeats = (10, 5, 4)
>>> system = uc.generate_system(n_repeats)
>>> N = np.prod(n_repeats)
>>> indices = np.repeat(np.arange(len(uc.basis_positions)), N)
>>> # An array of types for all points
>>> types = np.array([0, 1])[indices]
>>> len(types)
400

classmethod hex()[source]¶

Create a hexagonal unit cell.

Returns:: A hexagonal unit cell.
Return type:: UnitCell

property lattice_vectors¶

The matrix of lattice vectors.

Type:: \((3, 3)\) np.ndarray

classmethod sc()[source]¶

Create a simple cubic (sc) unit cell.

Returns:: A simple cubic unit cell.
Return type:: UnitCell

classmethod square()[source]¶

Create a square unit cell.

Returns:: A square unit cell.
Return type:: UnitCell

freud.data.make_random_system(box_size, num_points, is2D=False, seed=None)[source]¶

Helper function to make random points with a cubic or square box.

Parameters:

box_size (float) – Size of box.
num_points (int) – Number of points.
is2D (bool) – If true, creates a 2D system. (Default value = False).
seed (int) – Random seed to use. (Default value = None).

Returns:

Generated box and points.

Return type:

tuple (freud.box.Box, \(\left(num\_points, 3\right)\) numpy.ndarray)