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

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

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

Computes the PMFT [vAAS+13, vAKA+14] in coordinates \(x\), \(y\), \(z\). 
Details
The freud.pmft
module allows for the calculation of the Potential of
Mean Force and Torque (PMFT) [vAAS+13, vAKA+14] 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:
_PMFT
Computes the PMFT [vAAS+13, vAKA+14] 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(self, system, orientations, query_points=None, query_orientations=None, neighbors=None, reset=True)#
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:
_PMFT
Computes the PMFT [vAAS+13, vAKA+14] in coordinates \(x\), \(y\).
There are 3 degrees of translational and rotational freedom in 2 dimensions, so this class implicitly integrates over the rotational degree of freedom of the second particle.
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(self, system, query_orientations, query_points=None, neighbors=None, reset=True)#
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(self, ax=None)#
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:
_PMFT
Computes the PMFT [vAAS+13, vAKA+14] 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(self, system, orientations, query_points=None, query_orientations=None, neighbors=None, reset=True)#
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:
_PMFT
Computes the PMFT [vAAS+13, vAKA+14] in coordinates \(x\), \(y\), \(z\).
There are 6 degrees of translational and rotational freedom in 3 dimensions, so this class is implicitly integrates out the orientational degrees of freedom in the system associated with the points. All calculations are done in the reference from of the query points.
 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(self, system, query_orientations, query_points=None, equiv_orientations=None, neighbors=None, reset=True)#
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