Order Module¶
Overview
Compute the cubatic order parameter [HAG15] for a system of particles using simulated annealing instead of NewtonRaphson root finding. 

Compute the nematic order parameter for a system of particles. 

Calculates the \(k\)atic order parameter for 2D systems. 

Compute the translational order parameter for each particle. 

Compute the rotationally invariant Steinhardt order parameter \(q_l\) or \(w_l\) for a set of points [Ste83]. 

Identifies solidlike clusters using dot products of \(q_{lm}\). 

Calculates a measure of total rotational autocorrelation. 
Details
The freud.order
module contains functions which compute order
parameters for the whole system or individual particles. Order parameters take
bond order data and interpret it in some way to quantify the degree of order in
a system using a scalar value. This is often done through computing spherical
harmonics of the bond order diagram, which are the spherical analogue of
Fourier Transforms.

class
freud.order.
Cubatic
¶ Bases:
freud.util._Compute
Compute the cubatic order parameter [HAG15] for a system of particles using simulated annealing instead of NewtonRaphson root finding.
 Parameters
t_initial (float) – Starting temperature.
t_final (float) – Final temperature.
scale (float) – Scaling factor to reduce temperature.
n_replicates (unsigned int, optional) – Number of replicate simulated annealing runs. (Default value =
1
).seed (unsigned int, optional) – Random seed to use in calculations. If
None
, system time is used. (Default value =None
).

compute
(self, orientations)¶ Calculates the perparticle and global order parameter.
 Parameters
orientations ((\(N_{particles}\), 4)
numpy.ndarray
) – Orientations as angles to use in computation.

property
cubatic_tensor
¶ Rank 4 homogeneous tensor representing the optimal systemwide coordinates.
 Type
\(\left(3, 3, 3, 3 \right)\)
numpy.ndarray

property
global_tensor
¶ Rank 4 tensor corresponding to the global orientation. Computed from all orientations.
 Type
\(\left(3, 3, 3, 3 \right)\)
numpy.ndarray

n_replicates
¶ Number of replicate simulated annealing runs.
 Type
unsigned int

property
orientation
¶ The quaternion of global orientation.
 Type
\(\left(4 \right)\)
numpy.ndarray

property
particle_order
¶ Order parameter.
 Type
\(\left(N_{particles} \right)\)
numpy.ndarray

seed
¶ Random seed to use in calculations.
 Type
unsigned int

class
freud.order.
Hexatic
¶ Bases:
freud.locality._PairCompute
Calculates the \(k\)atic order parameter for 2D systems.
The \(k\)atic order parameter (called the hexatic order parameter for \(k = 6\)) is analogous to Steinhardt order parameters, and is used to measure order in the bonds of 2D systems.
The \(k\)atic order parameter for a particle \(i\) and its \(n\) neighbors \(j\) is given by:
\(\psi_k \left( i \right) = \frac{1}{n} \sum_j^n e^{i k \phi_{ij}}\)
The parameter \(k\) governs the symmetry of the order parameter and typically matches the number of neighbors to be found for each particle. The quantity \(\phi_{ij}\) is the angle between the vector \(r_{ij}\) and \(\left(1, 0\right)\).
If the weighted mode is enabled, contributions of each neighbor are weighted. Neighbor weights \(w_j\) default to 1 but are defined for a
freud.locality.NeighborList
fromfreud.locality.Voronoi
or one with userprovided weights. The formula is modified as follows:\(\psi'_k \left( i \right) = \frac{1}{\sum_j^n w_j} \sum_j^n w_j e^{i k \phi_{ij}}\)
The hexatic order parameter as written above is complexvalued. The magnitude of the complex value,
np.abs(hex_order.particle_order)
, is frequently what is desired when determining the \(k\)atic order for each particle. The complex phase anglenp.angle(hex_order.particle_order)
indicates the orientation of the bonds as an angle measured counterclockwise from the vector \(\left(1, 0\right)\). The complex valued order parameter is not rotationally invariant because of this phase angle, but the magnitude is rotationally invariant.Note
2D:
freud.order.Hexatic
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Parameters
k (unsigned int, optional) – Symmetry of order parameter (Default value =
6
).weighted (bool, optional) – Determines whether to use neighbor weights in the computation of spherical harmonics over neighbors. If enabled and used with a Voronoi neighbor list, this results in the 2D Minkowski Structure Metrics \(\psi'_k\) [MKSTM13] (Default value =
False
).

compute
(self, system, neighbors=None)¶ Calculates the hexatic order parameter.
Example:
>>> box, points = freud.data.make_random_system( ... box_size=10, num_points=100, is2D=True, seed=0) >>> # Compute the hexatic (6fold) order for the 2D system >>> hex_order = freud.order.Hexatic(k=6) >>> hex_order.compute(system=(box, points)) freud.order.Hexatic(...) >>> print(hex_order.particle_order) [...]
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.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
¶ The default query arguments are
{'mode': 'nearest', 'num_neighbors': self.k}
.

k
¶ Symmetry of the order parameter.
 Type
unsigned int

property
particle_order
¶ Order parameter.
 Type
\(\left(N_{particles} \right)\)
numpy.ndarray

plot
(self, ax=None)¶ Plot order parameter 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

class
freud.order.
Nematic
¶ Bases:
freud.util._Compute
Compute the nematic order parameter for a system of particles.
 Parameters
u (\(\left(3 \right)\)
numpy.ndarray
) – The nematic director of a single particle in the reference state (without any rotation applied).

compute
(self, orientations)¶ Calculates the perparticle and global order parameter.
Example:
>>> orientations = np.array([[1, 0, 0, 0]] * 100) >>> director = np.array([1, 1, 0]) >>> nematic = freud.order.Nematic(director) >>> nematic.compute(orientations) freud.order.Nematic(u=[...])
 Parameters
orientations (\(\left(N_{particles}, 4 \right)\)
numpy.ndarray
) – Orientations to calculate the order parameter.

property
director
¶ The average nematic director.
 Type
\(\left(3 \right)\)
numpy.ndarray

property
nematic_tensor
¶ 3x3 matrix corresponding to the average particle orientation.
 Type
\(\left(3, 3 \right)\)
numpy.ndarray

property
particle_tensor
¶ \(\left(N_{particles}, 3, 3 \right)\)
numpy.ndarray
: One 3x3 matrix perparticle corresponding to each individual particle orientation.

u
¶ The normalized reference director (the normalized vector provided on construction).
 Type
\(\left(3 \right)\)
numpy.ndarray

class
freud.order.
RotationalAutocorrelation
¶ Bases:
freud.util._Compute
Calculates a measure of total rotational autocorrelation.
For any calculation of rotational correlations of extended (i.e. nonpoint) particles, encoding the symmetries of these particles is crucial to appropriately determining correlations. For systems of anisotropic particles in three dimensions, representing such equivalence can be quite mathematically challenging. This calculation is based on the hyperspherical harmonics as laid out in [KDvAG19]. Generalizations of spherical harmonics to four dimensions, hyperspherical harmonics provide a natural basis for periodic functions in 4 dimensions just as harmonic functions (sines and cosines) or spherical harmonics do in lower dimensions. The idea behind this calculation is to embed orientation quaternions into a 4dimensional space and then use hyperspherical harmonics to find correlations in a symmetryaware fashion.
The choice of the hyperspherical harmonic parameter \(l\) determines the symmetry of the functions. The output is not a correlation function, but rather a scalar value that measures total system orientational correlation with an initial state. As such, the output can be treated as an order parameter measuring degrees of rotational (de)correlation. For analysis of a trajectory, the compute call needs to be done at each trajectory frame.
 Parameters
l (int) – Order of the hyperspherical harmonic. Must be a positive, even integer.

compute
(self, ref_orientations, orientations)¶ Calculates the rotational autocorrelation function for a single frame.
 Parameters
ref_orientations ((\(N_{orientations}\), 4)
numpy.ndarray
) – Orientations for the initial frame.orientations ((\(N_{orientations}\), 4)
numpy.ndarray
) – Orientations for the frame of interest.

property
particle_order
¶ Rotational autocorrelation values calculated for each orientation.
 Type
(\(N_{orientations}\))
numpy.ndarray

class
freud.order.
SolidLiquid
¶ Bases:
freud.locality._PairCompute
Identifies solidlike clusters using dot products of \(q_{lm}\).
The solidliquid order parameter [tW95][FHND10] uses a Steinhardtlike approach to identify solidlike particles. First, a bond parameter \(q_l(i, j)\) is computed for each neighbor bond.
If
normalize_q
is true (default), the bond parameter is given by \(q_l(i, j) = \frac{\sum_{m=l}^{l} \text{Re}~q_{lm}(i) q_{lm}^*(j)} {\sqrt{\sum_{m=l}^{l} \lvert q_{lm}(i) \rvert^2} \sqrt{\sum_{m=l}^{l} \lvert q_{lm}(j) \rvert^2}}\)If
normalize_q
is false, then the denominator of the above expression is left out.Next, the bonds are filtered to keep only “solidlike” bonds with \(q_l(i, j)\) above a cutoff value \(q_{threshold}\).
If a particle has more than \(S_{threshold}\) solidlike bonds, then the particle is considered solidlike. Finally, solidlike particles are clustered.
 Parameters
l (unsigned int) – Spherical harmonic quantum number l.
q_threshold (float) – Value of dot product threshold when evaluating \(q_l(i, j)\) to determine if a bond is solidlike. For \(l=6\), 0.7 is generally good for FCC or BCC structures [FHND10].
solid_threshold (unsigned int) – Minimum required number of adjacent solidlike bonds for a particle to be considered solidlike for clustering. For \(l=6\), 68 is generally good for FCC or BCC structures.
normalize_q (bool) – Whether to normalize the dot product (Default value =
True
).

property
cluster_idx
¶ \(\left(N_{particles}\right)\)
numpy.ndarray
: Solidlike cluster indices for each particle.

property
cluster_sizes
¶ The sizes of all clusters.
 Type
\((N_{clusters}, )\)
np.ndarray

compute
(self, system, neighbors=None)¶ Compute the order parameter.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.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.

l
¶ Spherical harmonic quantum number l.
 Type
unsigned int

property
largest_cluster_size
¶ The largest cluster size.
 Type
unsigned int

property
nlist
¶ Neighbor list of solidlike bonds.

property
num_connections
¶ The number of solidlike bonds for each particle.
 Type
\(\left(N_{particles}\right)\)
numpy.ndarray

plot
(self, ax=None)¶ Plot solidlike 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
ql_ij
¶ Bond dot products \(q_l(i, j)\). Indexed by the elements of
self.nlist
. Type
\(\left(N_{bonds}\right)\)
numpy.ndarray

class
freud.order.
Steinhardt
¶ Bases:
freud.locality._PairCompute
Compute the rotationally invariant Steinhardt order parameter \(q_l\) or \(w_l\) for a set of points [Ste83].
Implements the local rotationally invariant \(q_l\) or \(w_l\) order parameter described by Steinhardt. For a particle \(i\), we calculate the average order parameter by summing the spherical harmonics between particle \(i\) and its neighbors \(j\) in a local region:
\(\overline{q}_{lm}(i) = \frac{1}{N_b} \displaystyle\sum_{j=1}^{N_b} Y_{lm}(\theta(\vec{r}_{ij}), \phi(\vec{r}_{ij}))\).
For \(q_l\), this is then combined in a rotationally invariant fashion to remove local orientational order as follows:
\(q_l(i)=\sqrt{\frac{4\pi}{2l+1} \displaystyle\sum_{m=l}^{l} \overline{q}_{lm}^2 }\).
For \(w_l\), it is then defined as a weighted average over the \(\overline{q}_{lm}(i)\) values using Wigner 3j symbols (ClebschGordan coefficients). The resulting combination is rotationally (i.e. frame) invariant.
The average argument in the constructor provides access to a variant of this parameter that performs a average over the first and second shell combined [LD08]. To compute this parameter, we perform a second averaging over the first neighbor shell of the particle to implicitly include information about the second neighbor shell. This averaging is performed by replacing the value \(\overline{q}_{lm}(i)\) in the original definition by the average value of \(\overline{q}_{lm}(k)\) over all the \(k\) neighbors of particle \(i\) as well as itself.
If the weighted mode is enabled in the constructor, the contributions of each neighbor are weighted. Neighbor weights \(w_j\) default to 1 but are defined for a
freud.locality.NeighborList
fromfreud.locality.Voronoi
or one with userprovided weights. The formula is modified as follows:\(\overline{q}'_{lm}(i) = \frac{1}{\sum_j^n w_j} \displaystyle\sum_{j=1}^{N_b} w_j Y_{lm}(\theta(\vec{r}_{ij}), \phi(\vec{r}_{ij}))\).
\(q'_l(i)=\sqrt{\frac{4\pi}{2l+1} \displaystyle\sum_{m=l}^{l} \overline{q}'_{lm}^2 }\).
The
norm
attribute argument provides normalized versions of the order parameter, where the normalization is performed by averaging the \(q_{lm}\) values over all particles before computing the order parameter of choice.Note
The value of perparticle order parameter will be set to NaN for particles with no neighbors. We choose this value rather than setting the order parameter to 0 because in more complex order parameter calculations (such as when computing the \(w_l\)), it is possible to observe a value of 0 for the perparticle order parameter even with a finite number of neighbors. If you would like to ignore this distinction, you can mask the output order parameter values using NumPy:
numpy.nan_to_num(particle_order)
. Parameters
l (unsigned int) – Spherical harmonic quantum number l.
average (bool, optional) – Determines whether to calculate the averaged Steinhardt order parameter (Default value =
False
).wl (bool, optional) – Determines whether to use the \(w_l\) version of the Steinhardt order parameter (Default value =
False
).weighted (bool, optional) – Determines whether to use neighbor weights in the computation of spherical harmonics over neighbors. If enabled and used with a Voronoi neighbor list, this results in the 3D Minkowski Structure Metrics \(q'_l\) [MKSTM13] (Default value =
False
).wl_normalize (bool, optional) – Determines whether to normalize the \(w_l\) version of the Steinhardt order parameter (Default value =
False
).

compute
(self, system, neighbors=None)¶ Compute the order parameter.
Example:
>>> box, points = freud.data.make_random_system(10, 100, seed=0) >>> ql = freud.order.Steinhardt(l=6) >>> ql.compute((box, points), {'r_max':3}) freud.order.Steinhardt(l=6, ...)
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.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.

l
¶ Spherical harmonic quantum number l.
 Type
unsigned int

property
particle_order
¶ Variant of the Steinhardt order parameter for each particle (filled with
nan
for particles with no neighbors). Type
\(\left(N_{particles}\right)\)
numpy.ndarray

plot
(self, ax=None)¶ Plot order parameter 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
ql
¶ \(\left(N_{particles}\right)\)
numpy.ndarray
: \(q_l\) Steinhardt order parameter for each particle (filled withnan
for particles with no neighbors). This is always available, no matter which options are selected.

class
freud.order.
Translational
¶ Bases:
freud.locality._PairCompute
Compute the translational order parameter for each particle.
The translational order parameter is used to measure order in the bonds of 2D systems. The translational order parameter for a particle \(i\) and its \(n\) neighbors \(j\) is given by a sum over the neighbors, treating the 2D vectors between each pair of particles as a complex number with real part corresponding to the xcomponent of the vector and imaginary part corresponding to the ycomponent of the vector, divided by a normalization constant \(k\):
\(\psi\left( i \right) = \frac{1}{k} \sum_j^n x_{ij} + y_{ij} i\)
The translational order parameter as written above is complexvalued.
Note
2D:
freud.order.Translational
is only defined for 2D systems. The points must be passed in as[x, y, 0]
.Note
This class is slated for deprecation and will be removed in freud 3.0.
 Parameters
k (float, optional) – Normalization of order parameter (Default value =
6.0
).

compute
(self, system, neighbors=None)¶ Calculates the local descriptors.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.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
¶ The default query arguments are
{'mode': 'nearest', 'num_neighbors': int(self.k)}
.

property
particle_order
¶ Order parameter.
 Type
\(\left(N_{particles} \right)\)
numpy.ndarray