Environment Module

Overview

freud.environment.BondOrder Compute the bond order diagram for the system of particles.
freud.environment.LocalDescriptors Compute a set of descriptors (a numerical “fingerprint”) of a particle’s local environment.
freud.environment.MatchEnv Clusters particles according to whether their local environments match or not, according to various shape matching metrics.
freud.environment.Pairing2D Compute pairs for the system of particles.
freud.environment.AngularSeparation Calculates the minimum angles of separation between particles and references.

Details

The environment module contains functions which characterize the local environments of particles in the system. These methods use the positions and orientations of particles in the local neighborhood of a given particle to characterize the particle environment.

class freud.environment.BondOrder(rmax, k, n, nBinsT, nBinsP)

Compute the bond order diagram for the system of particles.

Available modes of calculation:

  • If mode='bod' (Bond Order Diagram, default): Create the 2D histogram containing the number of bonds formed through the surface of a unit sphere based on the azimuthal \(\left( \theta \right)\) and polar \(\left( \phi \right)\) angles.
  • If mode='lbod' (Local Bond Order Diagram): Create the 2D histogram containing the number of bonds formed, rotated into the local orientation of the central particle, through the surface of a unit sphere based on the azimuthal \(\left( \theta \right)\) and polar \(\left( \phi \right)\) angles.
  • If mode='obcd' (Orientation Bond Correlation Diagram): Create the 2D histogram containing the number of bonds formed, rotated by the rotation that takes the orientation of neighboring particle j to the orientation of each particle i, through the surface of a unit sphere based on the azimuthal \(\left( \theta \right)\) and polar \(\left( \phi \right)\) angles.
  • If mode='oocd' (Orientation Orientation Correlation Diagram): Create the 2D histogram containing the directors of neighboring particles (\(\hat{z}\) rotated by their quaternion), rotated into the local orientation of the central particle, through the surface of a unit sphere based on the azimuthal \(\left( \theta \right)\) and polar \(\left( \phi \right)\) angles.

Module author: Erin Teich <erteich@umich.edu>

Parameters:
  • r_max (float) – Distance over which to calculate.
  • k (unsigned int) – Order parameter i. To be removed.
  • n (unsigned int) – Number of neighbors to find.
  • n_bins_t (unsigned int) – Number of \(\theta\) bins.
  • n_bins_p (unsigned int) – Number of \(\phi\) bins.
Variables:
  • bond_order (\(\left(N_{\phi}, N_{\theta} \right)\) numpy.ndarray) – Bond order.
  • box (freud.box.Box) – Box used in the calculation.
  • theta (\(\left(N_{\theta} \right)\) numpy.ndarray) – The values of bin centers for \(\theta\).
  • phi (\(\left(N_{\phi} \right)\) numpy.ndarray) – The values of bin centers for \(\phi\).
  • n_bins_theta (unsigned int) – The number of bins in the \(\theta\) dimension.
  • n_bins_phi (unsigned int) – The number of bins in the \(\phi\) dimension.
accumulate

Calculates the correlation function and adds to the current histogram.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points used to calculate bonds.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations used to calculate bonds.
  • points ((\(N_{particles}\), 3) –
  • optional) – Points used to calculate bonds. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 3) numpy.ndarray) – Orientations used to calculate bonds. Uses ref_orientations if not provided or None.
  • mode (str, optional) – Mode to calculate bond order. Options are 'bod', 'lbod', 'obcd', or 'oocd' (Default value = 'bod').
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
compute

Calculates the bond order histogram. Will overwrite the current histogram.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points used to calculate bonds.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations used to calculate bonds.
  • points ((\(N_{particles}\), 3) –
  • optional) – Points used to calculate bonds. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 3) –
  • optional) – Orientations used to calculate bonds. Uses ref_orientations if not provided or None.
  • mode (str, optional) – Mode to calculate bond order. Options are 'bod', 'lbod', 'obcd', or 'oocd' (Default value = 'bod').
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
reset

Resets the values of the bond order in memory.

class freud.environment.LocalDescriptors(box, nNeigh, lmax, rmax)

Compute a set of descriptors (a numerical “fingerprint”) of a particle’s local environment.

The resulting spherical harmonic array will be a complex-valued array of shape (num_bonds, num_sphs). Spherical harmonic calculation can be restricted to some number of nearest neighbors through the num_neighbors argument; if a particle has more bonds than this number, the last one or more rows of bond spherical harmonics for each particle will not be set.

Module author: Matthew Spellings <mspells@umich.edu>

Parameters:
  • num_neighbors (unsigned int) – Maximum number of neighbors to compute descriptors for.
  • lmax (unsigned int) – Maximum spherical harmonic \(l\) to consider.
  • rmax (float) – Initial guess of the maximum radius to looks for neighbors.
  • negative_m (bool) – True if we should also calculate \(Y_{lm}\) for negative \(m\).
Variables:
  • sph (\(\left(N_{bonds}, \text{SphWidth} \right)\) numpy.ndarray) – A reference to the last computed spherical harmonic array.
  • num_particles (unsigned int) – The number of particles.
  • num_neighbors (unsigned int) – The number of neighbors.
  • l_max (unsigned int) – The maximum spherical harmonic \(l\) to calculate for.
  • r_max (float) – The cutoff radius.
compute

Calculates the local descriptors of bonds from a set of source points to a set of destination points.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • num_neighbors (unsigned int) – Number of neighbors to compute with or to limit to, if the neighbor list is precomputed.
  • points_ref ((\(N_{particles}\), 3) numpy.ndarray) – Source points to calculate the order parameter.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Destination points to calculate the order parameter (Default value = None).
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientation of each reference point (Default value = None).
  • mode (str, optional) – Orientation mode to use for environments, either 'neighborhood' to use the orientation of the local neighborhood, 'particle_local' to use the given particle orientations, or 'global' to not rotate environments (Default value = 'neighborhood').
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds or 'precomputed' if using computeNList() (Default value = None).
computeNList

Compute the neighbor list for bonds from a set of source points to a set of destination points.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • points_ref ((\(N_{particles}\), 3) numpy.ndarray) – Source points to calculate the order parameter.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Destination points to calculate the order parameter (Default value = None).
class freud.environment.MatchEnv(box, rmax, k)

Clusters particles according to whether their local environments match or not, according to various shape matching metrics.

Module author: Erin Teich <erteich@umich.edu>

Parameters:
  • box (freud.box.Box) – Simulation box.
  • rmax (float) – Cutoff radius for cell list and clustering algorithm. Values near the first minimum of the RDF are recommended.
  • k (unsigned int) – Number of nearest neighbors taken to define the local environment of any given particle.
Variables:
  • tot_environment (\(\left(N_{particles}, N_{neighbors}, 3\right)\) numpy.ndarray) – All environments for all particles.
  • num_particles (unsigned int) – The number of particles.
  • num_clusters (unsigned int) – The number of clusters.
  • clusters (\(\left(N_{particles}\right)\) numpy.ndarray) – The per-particle index indicating cluster membership.
cluster

Determine clusters of particles with matching environments.

Parameters:
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Destination points to calculate the order parameter.
  • threshold (float) – Maximum magnitude of the vector difference between two vectors, below which they are “matching.”
  • hard_r (bool) – If True, add all particles that fall within the threshold of m_rmaxsq to the environment.
  • registration (bool) – If True, first use brute force registration to orient one set of environment vectors with respect to the other set such that it minimizes the RMSD between the two sets.
  • global_search (bool) – If True, do an exhaustive search wherein the environments of every single pair of particles in the simulation are compared. If False, only compare the environments of neighboring particles.
  • env_nlist (freud.locality.NeighborList, optional) – NeighborList to use to find the environment of every particle (Default value = None).
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find neighbors of every particle, to compare environments (Default value = None).
getEnvironment

Returns the set of vectors defining the environment indexed by i.

Parameters:i (unsigned int) – Environment index.
Returns:The array of vectors.
Return type:\(\left(N_{neighbors}, 3\right)\) numpy.ndarray
isSimilar

Test if the motif provided by refPoints1 is similar to the motif provided by refPoints2.

Parameters:
  • refPoints1 ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up motif 1.
  • refPoints2 ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up motif 2.
  • threshold (float) – Maximum magnitude of the vector difference between two vectors, below which they are considered “matching.”
  • registration (bool, optional) – If True, first use brute force registration to orient one set of environment vectors with respect to the other set such that it minimizes the RMSD between the two sets (Default value = False).
Returns:

A doublet that gives the rotated (or not) set of refPoints2, and the mapping between the vectors of refPoints1 and refPoints2 that will make them correspond to each other. Empty if they do not correspond to each other.

Return type:

tuple ((\(\left(N_{particles}, 3\right)\) numpy.ndarray), map[int, int])

matchMotif

Determine clusters of particles that match the motif provided by refPoints.

Parameters:
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Particle positions.
  • refPoints ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up the motif against which we are matching.
  • threshold (float) – Maximum magnitude of the vector difference between two vectors, below which they are considered “matching.”
  • registration (bool, optional) – If True, first use brute force registration to orient one set of environment vectors with respect to the other set such that it minimizes the RMSD between the two sets (Default value = False).
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
minRMSDMotif

Rotate (if registration=True) and permute the environments of all particles to minimize their RMSD with respect to the motif provided by refPoints.

Parameters:
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Particle positions.
  • refPoints ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up the motif against which we are matching.
  • registration (bool, optional) – If True, first use brute force registration to orient one set of environment vectors with respect to the other set such that it minimizes the RMSD between the two sets (Default value = False).
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
Returns:

Vector of minimal RMSD values, one value per particle.

Return type:

\(\left(N_{particles}\right)\) numpy.ndarray

minimizeRMSD

Get the somewhat-optimal RMSD between the set of vectors refPoints1 and the set of vectors refPoints2.

Parameters:
  • refPoints1 ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up motif 1.
  • refPoints2 ((\(N_{particles}\), 3) numpy.ndarray) – Vectors that make up motif 2.
  • registration (bool, optional) – If true, first use brute force registration to orient one set of environment vectors with respect to the other set such that it minimizes the RMSD between the two sets (Default value = False).
Returns:

A triplet that gives the associated min_rmsd, rotated (or not) set of refPoints2, and the mapping between the vectors of refPoints1 and refPoints2 that somewhat minimizes the RMSD.

Return type:

tuple (float, (\(\left(N_{particles}, 3\right)\) numpy.ndarray), map[int, int])

setBox

Reset the simulation box.

Parameters:box (freud.box.Box) – Simulation box.

Note

Pairing2D is deprecated and is replaced with Bond Module.

class freud.environment.Pairing2D(rmax, k, compDotTol)

Compute pairs for the system of particles.

Module author: Eric Harper <harperic@umich.edu>

Deprecated since version 0.8.2: Use freud.bond instead.

Parameters:
  • rmax (float) – Distance over which to calculate.
  • k (unsigned int) – Number of neighbors to search.
  • compDotTol (float) – Value of the dot product below which a pair is determined.
Variables:
compute

Calculates the correlation function and adds to the current histogram.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Orientations to use in computation.
  • compOrientations ((\(N_{particles}\), 4) numpy.ndarray) – Possible orientations to check for bonds.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
class freud.environment.AngularSeparation(box, rmax, n)

Calculates the minimum angles of separation between particles and references.

Module author: Erin Teich

Module author: Andrew Karas

Parameters:
  • rmax (float) – Cutoff radius for cell list and clustering algorithm. Values near the first minimum of the RDF are recommended.
  • n (int) – The number of neighbors.
Variables:
  • nlist (freud.locality.NeighborList) – The neighbor list.
  • n_p (unsigned int) – The number of particles used in computing the last set.
  • n_ref (unsigned int) – The number of reference particles used in computing the neighbor angles.
  • n_global (unsigned int) – The number of global orientations to check against.
  • neighbor_angles ((\(\left(N_{neighbors}, \right)\) numpy.ndarray) – The neighbor angles in radians.
  • global_angles (\(\left(N_{particles}, N_{global} \right)\) numpy.ndarray) – The global angles in radians.
computeGlobal

Calculates the minimum angles of separation between global_ors and ors, checking for underlying symmetry as encoded in :code`equiv_quats`.

Parameters:
  • ors ((\(N_{particles}\), 3) numpy.ndarray) – Orientations to calculate the order parameter.
  • global_ors ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations to calculate the order parameter.
  • equiv_quats ((\(N_{particles}\), 4) numpy.ndarray) – The set of all equivalent quaternions that takes the particle as it is defined to some global reference orientation. Important: equiv_quats must include both \(q\) and \(-q\), for all included quaternions.
computeNeighbor

Calculates the minimum angles of separation between ref_ors and ors, checking for underlying symmetry as encoded in equiv_quats.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_ors ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations used to calculate the order parameter.
  • ors ((\(N_{particles}\), 3) numpy.ndarray) – Orientations used to calculate the order parameter.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points used to calculate the order parameter.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points used to calculate the order parameter.
  • equiv_quats ((\(N_{particles}\), 4) numpy.ndarray, optional) – The set of all equivalent quaternions that takes the particle as it is defined to some global reference orientation. Important: equiv_quats must include both \(q\) and \(-q\), for all included quaternions.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).