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(self, box, ref_points, ref_orientations, points, orientations, str mode='bod', nlist=None)

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 to calculate bonds.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations to calculate bonds.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the bonding.
  • orientations ((\(N_{particles}\), 3) numpy.ndarray) – Orientations to calculate the bonding.
  • 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(self, box, ref_points, ref_orientations, points, orientations, mode='bod', nlist=None)

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 to calculate bonds.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations to calculate bonds.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the bonding.
  • orientations ((\(N_{particles}\), 3) numpy.ndarray) – Orientations to calculate the bonding.
  • 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).
getBondOrder(self)

Get the bond order.

Returns:Bond order.
Return type:\(\left(N_{\phi}, N_{\theta} \right)\) numpy.ndarray
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getNBinsPhi(self)

Get the number of bins in the \(\phi\)-dimension of histogram.

Returns:\(N_{\phi}\)
Return type:unsigned int
getNBinsTheta(self)

Get the number of bins in the \(\theta\)-dimension of histogram.

Returns:\(N_{\theta}\).
Return type:unsigned int
getPhi(self)

Get \(\phi\).

Returns:Values of bin centers for \(\phi\).
Return type:\(\left(N_{\phi} \right)\) numpy.ndarray
getTheta(self)

Get \(\theta\).

Returns:Values of bin centers for \(\theta\).
Return type:\(\left(N_{\theta} \right)\) numpy.ndarray
reduceBondOrder(self)

Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.environment.BondOrder.getBondOrder().

resetBondOrder(self)

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(self, box, unsigned int num_neighbors, points_ref, points=None, orientations=None, mode='neighborhood', nlist=None)

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(self, box, points_ref, points=None)

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).
getLMax(self)

Get the maximum spherical harmonic \(l\) to calculate for.

Returns:\(l\).
Return type:unsigned int
getNP(self)

Get the number of particles.

Returns:\(N_{particles}\).
Return type:unsigned int
getNSphs(self)

Get the number of neighbors.

Returns:\(N_{neighbors}\).
Return type:unsigned int
getRMax(self)

Get the cutoff radius.

Returns:\(r\).
Return type:float
getSph(self)

Get a reference to the last computed spherical harmonic array.

Returns:Order parameter.
Return type:\(\left(N_{bonds}, \text{SphWidth} \right)\) numpy.ndarray
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.
cluster(self, points, threshold, hard_r=False, registration=False, global_search=False, env_nlist=None, nlist=None)

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).
getClusters(self)

Get a reference to the particles, indexed into clusters according to their matching local environments.

Returns:Clusters.
Return type:\(\left(N_{particles}\right)\) numpy.ndarray
getEnvironment(self, i)

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
getNP(self)

Get the number of particles.

Returns:\(N_{particles}\).
Return type:unsigned int
getNumClusters(self)

Get the number of clusters.

Returns:\(N_{clusters}\).
Return type:unsigned int
getTotEnvironment(self)

Returns the matrix of all environments for all particles.

Returns:The array of vectors.
Return type:\(\left(N_{particles}, N_{neighbors}, 3\right)\) numpy.ndarray
isSimilar(self, refPoints1, refPoints2, threshold, registration=False)

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(self, points, refPoints, threshold, registration=False, nlist=None)

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(self, points, refPoints, registration=False, nlist=None)

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(self, refPoints1, refPoints2, registration=False)

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

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(self, box, points, orientations, compOrientations, nlist=None)

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).
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getMatch(self)

Get the match.

Returns:The match.
Return type:\(\left(N_{particles}\right)\) numpy.ndarray
getPair(self)

Get the pair.

Returns:The pair.
Return type:\(\left(N_{particles}\right)\) numpy.ndarray
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.
computeGlobal(self, global_ors, ors, equiv_quats)

Calculates the minimum angles of separation between global_ors and ors, checking for underlying symmetry as encoded in 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(self, box, ref_ors, ors, ref_points, points, equiv_quats, nlist=None)

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.
  • orientations ((\(N_{particles}\), 3) numpy.ndarray) – Orientations to calculate the order parameter.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations to calculate the order parameter.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points to calculate the order parameter.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the order parameter.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
  • 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 – Neighborlist to use to find bonds (Default value = None).
getGlobalAngles(self)

The global angles in radians

Returns:Angles in radians.
Return type:\(\left(N_{particles}, N_{global} \right)\) numpy.ndarray
getNGlobal(self)

Get the number of global orientations to check against.

Returns:\(N_{global orientations}\).
Return type:unsigned int
getNP(self)

Get the number of particles used in computing the last set.

Returns:\(N_{particles}\).
Return type:unsigned int
getNReference(self)

Get the number of reference particles used in computing the neighbor angles.

Returns:\(N_{particles}\).
Return type:unsigned int
getNeighborAngles(self)

The neighbor angles in radians.

Returns:Angles in radians.
Return type:\(\left(N_{reference}, N_{neighbors} \right)\) numpy.ndarray