Data Module

Overview

freud.data.UnitCell

Class to represent the unit cell of a crystal structure.

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

Returns

A bcc 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 crystal.

Returns

An fcc 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)

property lattice_vectors

The matrix of lattice vectors.

Type

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

classmethod sc()[source]

Create a simple cubic crystal.

Returns

An sc unit cell.

Return type

UnitCell

classmethod square()[source]

Create a square crystal.

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.

This function has a side effect, by setting the random seed of numpy if a seed is specified.

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)