Environment Module#
Overview
Compute the bond orientational order diagram for the system of particles. 

Compute a set of descriptors (a numerical "fingerprint") of a particle's local environment. 

Clusters particles according to whether their local environments match or not, using various shape matching metrics defined in [TvAG19]. 

Find matches between local arrangements of a set of points and a provided motif, as done in [TvAG19]. 

Calculates the minimum angles of separation between orientations and global orientations. 

Calculates the minimum angles of separation between orientations and query orientations. 

Calculates the maximal projection of nearest neighbor bonds for each particle onto some set of reference vectors, defined in the particles' local reference frame. 
Details
The freud.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.AngularSeparationGlobal#
Bases:
_Compute
Calculates the minimum angles of separation between orientations and global orientations.
 property angles#
\(\left(N_{orientations}, N_{global\_orientations}\right)\)
numpy.ndarray
: The global angles in radians.
 compute(self, global_orientations, orientations, equiv_orientations=np.array([[1, 0, 0, 0]]))#
Calculates the minimum angles of separation between
global_orientations
andorientations
, checking for underlying symmetry as encoded inequiv_orientations
. The result is stored in theglobal_angles
class attribute. Parameters:
global_orientations ((\(N_{global}\), 4)
numpy.ndarray
) – Set of global orientations to calculate the order parameter.orientations ((\(N_{particles}\), 4)
numpy.ndarray
) – Orientations to calculate the order parameter.equiv_orientations ((\(N_{equiv}\), 4)
numpy.ndarray
, optional) – The set of all equivalent quaternions that map the particle to itself (the elements of its rotational symmetry group). Important:equiv_orientations
must include both \(q\) and \(q\), for all included quaternions. Note that this calculation assumes that all points in the system share the same set of equivalent orientations. (Default value =[[1, 0, 0, 0]]
)
 class freud.environment.AngularSeparationNeighbor#
Bases:
_PairCompute
Calculates the minimum angles of separation between orientations and query orientations.
 property angles#
The neighbor angles in radians. The angles are stored in the order of the neighborlist object.
 Type:
\(\left(N_{bonds}\right)\)
numpy.ndarray
 compute(self, system, orientations, query_points=None, query_orientations=None, equiv_orientations=np.array([[1, 0, 0, 0]]), neighbors=None)#
Calculates the minimum angles of separation between
orientations
andquery_orientations
, checking for underlying symmetry as encoded inequiv_orientations
. The result is stored in theneighbor_angles
class attribute. Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.orientations ((\(N_{points}\), 4)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the correlation function. Uses the system’s points ifNone
(Default value =None
).query_orientations ((\(N_{query\_points}\), 4)
numpy.ndarray
, optional) – Query orientations used to calculate bonds. Usesorientations
ifNone
. (Default value =None
).equiv_orientations ((\(N_{equiv}\), 4)
numpy.ndarray
, optional) – The set of all equivalent quaternions that map the particle to itself (the elements of its rotational symmetry group). Important:equiv_orientations
must include both \(q\) and \(q\), for all included quaternions. Note that this calculation assumes that all points in the system share the same set of equivalent orientations. (Default value =[[1, 0, 0, 0]]
)neighbors (
freud.locality.NeighborList
or dict, optional) – Either aNeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).
 default_query_args#
No default query arguments.
 property nlist#
The neighbor list from the last compute.
 class freud.environment.BondOrder#
Bases:
_SpatialHistogram
Compute the bond orientational order diagram for the system of particles.
The bond orientational order diagram (BOOD) is a way of studying the average local environments experienced by particles. In a BOOD, a particle and its nearest neighbors (determined by either a prespecified number of neighbors or simply a cutoff distance) are treated as connected by a bond joining their centers. All of the bonds in the system are then binned by their azimuthal (\(\theta\)) and polar (\(\phi\)) angles to indicate the location of a particle’s neighbors relative to itself. The distance between the particle and its neighbor is only important when determining whether it is counted as a neighbor, but is not part of the BOOD; as such, the BOOD can be viewed as a projection of all bonds onto the unit sphere. The resulting 2D histogram provides insight into how particles are situated relative to oneanother in a system.
This class provides access to the classical BOOD as well as a few useful variants. These variants can be accessed via the
mode
arguments to thecompute()
method. Available modes of calculation are:'bod'
(Bond Order Diagram, default): This mode constructs the default BOOD, which is the 2D histogram containing the number of bonds formed through each azimuthal \(\left( \theta \right)\) and polar \(\left( \phi \right)\) angle.'lbod'
(Local Bond Order Diagram): In this mode, a particle’s neighbors are rotated into the local frame of the particle before the BOOD is calculated, i.e. the directions of bonds are determined relative to the orientation of the particle rather than relative to the global reference frame. An example of when this mode would be useful is when a system is composed of multiple grains of the same crystal; the normal BOOD would show twice as many peaks as expected, but using this mode, the bonds would be superimposed.'obcd'
(Orientation Bond Correlation Diagram): This mode aims to quantify the degree of orientational as well as translational ordering. As a first step, the rotation that would align a particle’s neighbor with the particle is calculated. Then, the neighbor is rotated around the central particle by that amount, which actually changes the direction of the bond. One example of how this mode could be useful is in identifying plastic crystals, which exhibit translational but not orientational ordering. Normally, the BOOD for a plastic crystal would exhibit clear structure since there is translational order, but with this mode, the neighbor positions would actually be modified, resulting in an isotropic (disordered) BOOD.'oocd'
(Orientation Orientation Correlation Diagram): This mode is substantially different from the other modes. Rather than compute the histogram of neighbor bonds, this mode instead computes a histogram of the directors of neighboring particles, where the director is defined as the basis vector \(\hat{z}\) rotated by the neighbor’s quaternion. The directors are then rotated into the central particle’s reference frame. This mode provides insight into the local orientational environment of particles, indicating, on average, how a particle’s neighbors are oriented.
 Parameters:
bins (unsigned int or sequence of length 2) – If an unsigned int, the number of bins in \(\theta\) and \(\phi\). If a sequence of two integers, interpreted as
(num_bins_theta, num_bins_phi)
.mode (str, optional) – Mode to calculate bond order. Options are
'bod'
,'lbod'
,'obcd'
, or'oocd'
(Default value ='bod'
).
 bin_centers#
The centers of each bin in the histogram (has the same shape as the histogram itself).
 Type:
 property bin_counts#
The bin counts in the histogram.
 Type:
 bin_edges#
The edges of each bin in the histogram (is one element larger in each dimension than the histogram because each bin has a lower and upper bound).
 Type:
 property bond_order#
Bond order.
 Type:
\(\left(N_{\phi}, N_{\theta} \right)\)
numpy.ndarray
 bounds#
A list of tuples indicating upper and lower bounds of each axis of the histogram.
 property box#
Box used in the calculation.
 Type:
 compute(self, system, orientations=None, query_points=None, query_orientations=None, neighbors=None, reset=True)#
Calculates the correlation function and adds to the current histogram.
 Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.orientations ((\(N_{points}\), 4)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds. Uses identity quaternions ifNone
(Default value =None
).query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the correlation function. Uses the system’s points ifNone
(Default value =None
).query_orientations ((\(N_{query\_points}\), 4)
numpy.ndarray
, optional) – Query orientations used to calculate bonds. Usesorientations
ifNone
. (Default value =None
).neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).reset (bool) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).
 default_query_args#
No default query arguments.
 class freud.environment.EnvironmentCluster#
Bases:
_MatchEnv
Clusters particles according to whether their local environments match or not, using various shape matching metrics defined in [TvAG19].
 property cluster_environments#
\(\left(N_{clusters}, N_{neighbors}, 3\right)\)
numpy.ndarray
): The environments for all clusters.
 property cluster_idx#
The perparticle index indicating cluster membership.
 Type:
\(\left(N_{particles}\right)\)
numpy.ndarray
 compute(self, system, threshold, neighbors=None, env_neighbors=None, registration=False, global_search=False)#
Determine clusters of particles with matching environments.
An environment is defined by the bond vectors between a particle and its neighbors as defined by
env_neighbors
. For example,env_neighbors= {'num_neighbors': 8}
means that every particle’s local environment is defined by its 8 nearest neighbors. Then, each particle’s environment is compared to the environments of particles that satisfy a different cutoff parameterneighbors
. For example,neighbors={'r_max': 3.0}
means that the environment of each particle will be compared to the environment of every particle within a distance of 3.0.Two environments are compared using pointset registration.
The thresholding criterion we apply in order to determine if the two point sets match is quite conservative: the two point sets match if and only if, for every pair of matched points between the sets, the distance between the matched pair is less than
threshold
.When
registration=False
, environments are not rotated prior to comparison between them. Which pairs of vectors are compared depends on the order in which the vectors of the environment are traversed.When
registration=True
, we use the Kabsch algorithm to find the optimal rotation matrix mapping one environment onto another. The Kabsch algorithm assumes a onetoone correspondence between points in the two environments. However, we typically do not know which point in one environment corresponds to a particular point in the other environment. The brute force solution is to try all possible correspondences, but the resulting combinatorial explosion makes this problem infeasible, so we use the thresholding criterion above to terminate the search when we have found a permutation of points that results in a sufficiently low RMSD.Note
Using a distance cutoff for
env_neighbors
could lead to situations where thecluster_environments
contain different numbers of neighbors. In this case, the environments which have a number of neighbors less than the environment with the maximum number of neighbors \(k_{max}\) will have their entry incluster_environments
padded with zero vectors. For example, a cluster environment with \(m < k\) neighbors, will have \(k  m\) zero vectors at the end of its entry incluster_environments
.Warning
All vectors of
cluster_environments
andpoint_environments
are defined with respect to the query particle. Zero vectors are only used to pad the cluster vectors so that they have the same shape. In a future version of freud, zeropadding will be removed.Warning
Comparisons between two environments are only made when both environments contain the same number of neighbors. However, no warning will be given at runtime if mismatched environments are provided for comparison.
Example:
>>> import freud >>> # Compute clusters of particles with matching environments >>> box, points = freud.data.make_random_system(10, 100, seed=0) >>> env_cluster = freud.environment.EnvironmentCluster() >>> env_cluster.compute( ... system = (box, points), ... threshold=0.2, ... neighbors={'num_neighbors': 6}, ... registration=False, ... global_search=False) freud.environment.EnvironmentCluster()
 Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.threshold (float) – Maximum magnitude of the vector difference between two vectors, below which they are “matching”. Typically, a good choice is between 10% and 30% of the first well in the radial distribution function (this has distance units).
neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments. Defines the neighbors used for comparing different particle environments (Default value: None).env_neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments. Defines the neighbors used as the environment of each particle. IfNone
, the value provided forneighbors
will be used (Default value: None).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. Enabling this option incurs a significant performance penalty. (Default value =
False
)global_search (bool, optional) – If True, do an exhaustive search wherein the environments of every single pair of particles are compared. Thus it is equivalent to including all particles in the system in
'neighbors'
. If False, only compare the environments of neighboring particles. Enabling this option incurs a significant performance penalty. (Default value =False
)
 default_query_args#
No default query arguments.
 property num_clusters#
The number of clusters.
 Type:
unsigned int
 plot(self, ax=None)#
Plot cluster distribution.
 Parameters:
ax (
matplotlib.axes.Axes
, optional) – Axis to plot on. IfNone
, make a new figure and axis. (Default value =None
) Returns:
Axis with the plot.
 Return type:
 property point_environments#
\(\left(N_{points}, N_{neighbors}, 3\right)\)
numpy.ndarray
: All environments for all points.
 class freud.environment.EnvironmentMotifMatch#
Bases:
_MatchEnv
Find matches between local arrangements of a set of points and a provided motif, as done in [TvAG19].
A particle’s environment can only match the motif if it contains the same number of neighbors as the motif. Any environment with a different number of neighbors than the motif will always fail to match the motif. See
freud.environment.EnvironmentCluster.compute
for the matching criterion. compute(self, system, motif, threshold, neighbors=None, registration=False)#
 Determine which particles have local environments
matching the given environment motif.
Warning
Comparisons between two environments are only made when both environments contain the same number of neighbors. However, no warning will be given at runtime if mismatched environments are provided for comparison.
 Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.motif ((\(N_{points}\), 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 “matching”. Typically, a good choice is between 10% and 30% of the first well in the radial distribution function (this has distance units).
neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments. Defines the environment of the query particles (Default value: None).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).
 default_query_args#
No default query arguments.
 property matches#
A boolean array indicating whether each point matches the motif.
 Type:
(\(N_{points}\))
numpy.ndarray
 property point_environments#
\(\left(N_{points}, N_{neighbors}, 3\right)\)
numpy.ndarray
: All environments for all points.
 class freud.environment.LocalBondProjection#
Bases:
_PairCompute
Calculates the maximal projection of nearest neighbor bonds for each particle onto some set of reference vectors, defined in the particles’ local reference frame.
 compute(self, system, orientations, proj_vecs, query_points=None, equiv_orientations=np.array([[1, 0, 0, 0]]), neighbors=None)#
Calculates the maximal projections of nearest neighbor bonds (between
points
andquery_points
) onto the set of reference vectorsproj_vecs
, defined in the local reference frames of thepoints
as defined by the orientationsorientations
. This computation accounts for the underlying symmetries of the reference frame as encoded inequiv_orientations
. Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.orientations ((\(N_{points}\), 4)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds.proj_vecs ((\(N_{vectors}\), 3)
numpy.ndarray
) – The set of projection vectors, defined in the query particles’ reference frame, to calculate maximal local bond projections onto.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the correlation function. Uses the system’s points ifNone
(Default value =None
). (Default value =None
).equiv_orientations ((\(N_{equiv}\), 4)
numpy.ndarray
, optional) – The set of all equivalent quaternions that map the particle to itself (the elements of its rotational symmetry group). Important:equiv_orientations
must include both \(q\) and \(q\), for all included quaternions. Note that this calculation assumes that all points in the system share the same set of equivalent orientations. (Default value =[[1, 0, 0, 0]]
)neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).
 default_query_args#
No default query arguments.
 property nlist#
The neighbor list from the last compute.
 property normed_projections#
\(\left(N_{bonds}, N_{projection\_vecs} \right)\)
numpy.ndarray
: The projection of each bond between query particles and their neighbors onto each of the projection vectors, normalized by the length of the bond.
 property projections#
\(\left(N_{bonds}, N_{projection\_vecs} \right)\)
numpy.ndarray
: The projection of each bond between query particles and their neighbors onto each of the projection vectors.
 class freud.environment.LocalDescriptors#
Bases:
_PairCompute
Compute a set of descriptors (a numerical “fingerprint”) of a particle’s local environment.
The resulting spherical harmonic array will be a complexvalued array of shape
(num_bonds, num_sphs)
. Spherical harmonic calculation can be restricted to some number of nearest neighbors through themax_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. This feature is useful for computing descriptors on the same system but with different subsets of neighbors; afreud.locality.NeighborList
with the correct ordering can then be reused in multiple calls tocompute()
with different values ofmax_num_neighbors
to compute descriptors for different local neighborhoods with maximum efficiency. Parameters:
l_max (unsigned int) – Maximum spherical harmonic \(l\) to consider.
negative_m (bool, optional) – True if we should also calculate \(Y_{lm}\) for negative \(m\). (Default value =
True
)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'
).
 compute(self, system, query_points=None, orientations=None, neighbors=None, max_num_neighbors=0)#
Calculates the local descriptors of bonds from a set of source points to a set of destination points.
 Parameters:
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the correlation function. Uses the system’s points ifNone
(Default value =None
).orientations ((\(N_{points}\), 4)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds.neighbors (
freud.locality.NeighborList
or dict, optional) –Either a
NeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).max_num_neighbors (unsigned int, optional) – Hard limit on the maximum number of neighbors to use for each particle for the given neighborfinding algorithm. Uses all neighbors if set to 0 (Default value = 0).
 default_query_args#
No default query arguments.
 l_max#
The maximum spherical harmonic \(l\) calculated for.
 Type:
unsigned int
 mode#
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. Type:
 property nlist#
The neighbor list from the last compute.
 property num_sphs#
The last number of spherical harmonics computed. This is equal to the number of bonds in the last computation, which is at most the number of
points
multiplied by the lower of thenum_neighbors
arguments passed to the last compute call or the constructor (it may be less if there are not enough neighbors for every particle). Type:
unsigned int
 property sph#
\(\left(N_{bonds}, \text{SphWidth} \right)\)
numpy.ndarray
: The last computed spherical harmonic array.