PMFT Module¶
Overview
Computes the PMFT [vAKA+14][vAAS+13] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\). 

Computes the PMFT [vAKA+14][vAAS+13] for systems described by coordinates \(x\), \(y\), \(\theta\). 

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\). 

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\), \(z\). 
Details
The freud.pmft
module allows for the calculation of the Potential of
Mean Force and Torque (PMFT) [vAKA+14][vAAS+13] in a
number of different coordinate systems. The shape of the arrays computed by
this module depend on the coordinate system used, with space discretized into a
set of bins created by the PMFT object’s constructor. Each query point’s
neighboring points are assigned to bins, determined by the relative positions
and/or orientations of the particles. Next, the pair correlation function
(PCF) is computed by normalizing the binned histogram, by dividing out the
number of accumulated frames, bin sizes (the Jacobian), and query point
number density. The PMFT is then defined as the negative logarithm of the PCF.
For further descriptions of the numerical methods used to compute the PMFT,
refer to the supplementary information of [vAKA+14].
Note
The coordinate system in which the calculation is performed is not the same as the coordinate system in which particle positions and orientations should be supplied. Only certain coordinate systems are available for certain particle positions and orientations:
2D particle coordinates (position: [\(x\), \(y\), \(0\)], orientation: \(\theta\)):
\(r\), \(\theta_1\), \(\theta_2\).
\(x\), \(y\).
\(x\), \(y\), \(\theta\).
3D particle coordinates:
\(x\), \(y\), \(z\).
Note
For any bins where the histogram is zero (i.e. no observations were made
with that relative position/orientation of particles), the PMFT will return
nan
.

class
freud.pmft.
PMFTR12
¶ Bases:
freud.pmft._PMFT
Computes the PMFT [vAKA+14][vAAS+13] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\).
Note
2D:
freud.pmft.PMFTR12
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Parameters
r_max (float) – Maximum distance at which to compute the PMFT.
bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(r\), \(\theta_1\), and \(\theta_2\). If a sequence of three integers, interpreted as
(num_bins_r, num_bins_t1, num_bins_t2)
.

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

bounds
¶ A list of tuples indicating upper and lower bounds of each axis of the histogram.

property
box
¶ The box object used in the last computation.
 Type

compute
¶ Calculates the PMFT.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.orientations ((\(N_{points}\), 4) or (\(N_{points}\),)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds. If the array is onedimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the PMFT. Uses the system’s points ifNone
(Default value =None
).query_orientations ((\(N_{query\_points}\), 4)
numpy.ndarray
, optional) – Query orientations associated with query points that are used to calculate bonds. If the array is onedimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis. Usesorientations
ifNone
. (Default value =None
).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).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
¶ The default query arguments are
{'mode': 'ball', 'r_max': self.r_max}
.

property
pmft
¶ The discrete potential of mean force and torque.
 Type
np.ndarray

class
freud.pmft.
PMFTXY
¶ Bases:
freud.pmft._PMFT
Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\).
Since there are 3 degrees of translational and rotational freedom in 2 dimensions, this class is implicitly integrating out one of them. Specifically, by comparison to
PMFTXYT
we see that the missing dimension is the relative orientation of the second particle. Note that this degree of freedom is still accounted for in the Jacobian of this calculation.Note
2D:
freud.pmft.PMFTXY
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Parameters
x_max (float) – Maximum \(x\) distance at which to compute the PMFT.
y_max (float) – Maximum \(y\) distance at which to compute the PMFT.
bins (unsigned int or sequence of length 2) – If an unsigned int, the number of bins in \(x\) and \(y\). If a sequence of two integers, interpreted as
(num_bins_x, num_bins_y)
.

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

bounds
¶ A list of tuples indicating upper and lower bounds of each axis of the histogram.

property
box
¶ The box object used in the last computation.
 Type

compute
¶ Calculates the PMFT.
Note
The orientations of the system points are irrelevant for this calculation because that dimension is integrated out. The provided
query_orientations
are therefore always associated withquery_points
(which are equal to the system points if noquery_points
are explicitly provided). Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.query_orientations ((\(N_{query\_points}\), 4) or (\(N_{query\_points}\),)
numpy.ndarray
) – Query orientations associated with query points that are used to calculate bonds. If the array is onedimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the PMFT. Uses the system’s points 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
¶ The default query arguments are
{'mode': 'ball', 'r_max': self.r_max}
.

plot
¶ Plot PMFTXY.
 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
pmft
¶ The discrete potential of mean force and torque.
 Type
np.ndarray

class
freud.pmft.
PMFTXYT
¶ Bases:
freud.pmft._PMFT
Computes the PMFT [vAKA+14][vAAS+13] for systems described by coordinates \(x\), \(y\), \(\theta\).
Note
2D:
freud.pmft.PMFTXYT
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Parameters
x_max (float) – Maximum \(x\) distance at which to compute the PMFT.
y_max (float) – Maximum \(y\) distance at which to compute the PMFT.
bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(x\), \(y\), and \(t\). If a sequence of three integers, interpreted as
(num_bins_x, num_bins_y, num_bins_t)
.

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

bounds
¶ A list of tuples indicating upper and lower bounds of each axis of the histogram.

property
box
¶ The box object used in the last computation.
 Type

compute
¶ Calculates the PMFT.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.orientations ((\(N_{points}\), 4) or (\(N_{points}\),)
numpy.ndarray
) – Orientations associated with system points that are used to calculate bonds. If the array is onedimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the PMFT. Uses the system’s points ifNone
(Default value =None
).query_orientations ((\(N_{query\_points}\), 4)
numpy.ndarray
, optional) – Query orientations associated with query points that are used to calculate bonds. If the array is onedimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis. 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
¶ The default query arguments are
{'mode': 'ball', 'r_max': self.r_max}
.

property
pmft
¶ The discrete potential of mean force and torque.
 Type
np.ndarray

class
freud.pmft.
PMFTXYZ
¶ Bases:
freud.pmft._PMFT
Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\), \(z\).
Since there are 6 degrees of translational and rotational freedom in 3 dimensions, this class is implicitly integrating out three of them. In particular, we are disregarding the orientational degrees of freedom in the system. The simplest parameterization of these degrees is using Euler angles. The total volume of orientations that are implicitly integrated out by this calculation can be computed by an explicit integral over the Euler angles:
\[\int_0^{2\pi} \int_0^\pi \int_0^{2\pi} \sin \theta d\phi d\theta d\psi = 8 \pi^2\]For more information on this calculation, see [GMS63] (the equation is also reproduced without proof at https://en.wikipedia.org/wiki/3D_rotation_group#Spherical_harmonics). This prefactor of \(8 \pi^2\) is accounted for in the Jacobian used to compute the
PMFTXYZ
. Parameters
x_max (float) – Maximum \(x\) distance at which to compute the PMFT.
y_max (float) – Maximum \(y\) distance at which to compute the PMFT.
z_max (float) – Maximum \(z\) distance at which to compute the PMFT.
bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(x\), \(y\), and \(z\). If a sequence of three integers, interpreted as
(num_bins_x, num_bins_y, num_bins_z)
.shiftvec (list) – Vector pointing from
[0, 0, 0]
to the center of the PMFT.

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

bounds
¶ A list of tuples indicating upper and lower bounds of each axis of the histogram.

property
box
¶ The box object used in the last computation.
 Type

compute
¶ Calculates the PMFT.
Note
The orientations of the system points are irrelevant for this calculation because that dimension is integrated out. The provided
query_orientations
are therefore always associated withquery_points
(which are equal to the system points if noquery_points
are explicitly provided. Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.query_orientations ((\(N_{points}\), 4)
numpy.ndarray
) – Query orientations associated with query points that are used to calculate bonds.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the PMFT. Uses the system’s points ifNone
(Default value =None
).equiv_orientations ((\(N_{faces}\), 4)
numpy.ndarray
, optional) – Orientations to be treated as equivalent to account for symmetry of the points. For instance, if thequery_points
are rectangular prisms with the long axis corresponding to the xaxis, then a point at \((1, 0, 0)\) and a point at \((1, 0, 0)\) are symmetrically equivalent and can be counted towards both the positive and negative bins. If not supplied by user orNone
, a unit quaternion will be used (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
¶ The default query arguments are
{'mode': 'ball', 'r_max': self.r_max}
.

property
pmft
¶ The discrete potential of mean force and torque.
 Type
np.ndarray