PMFT Module¶
Overview
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\). |
|
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] for systems described by coordinates \(x\), \(y\), \(\theta\) listed in the |
|
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\) listed in the |
|
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\), \(z\), listed in the |
Details
The freud.pmft
module allows for the calculation of the Potential of
Mean Force and Torque (PMFT) [vanAndersKlotsa2014] [vanAndersAhmed2014] 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 reference point’s
neighboring points are assigned to bins, determined by the relative positions
and/or orientations of the particles. Next, the positional correlation function
(PCF) is computed by normalizing the binned histogram, by dividing out the
number of accumulated frames, bin sizes (the Jacobian), and reference 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 [vanAndersKlotsa2014].
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 PCF will be zero
and the PMFT will return nan
.
PMFT \(\left(r, \theta_1, \theta_2\right)\)¶
-
class
freud.pmft.
PMFTR12
(r_max, n_r, n_t1, n_t2)¶ Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] 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]
. Failing to set z=0 will lead to undefined behavior.Module author: Eric Harper <harperic@umich.edu>
Module author: Vyas Ramasubramani <vramasub@umich.edu>
- Parameters
r_max (float) – Maximum distance at which to compute the PMFT.
n_r (unsigned int) – Number of bins in \(r\).
n_t1 (unsigned int) – Number of bins in \(\theta_1\).
n_t2 (unsigned int) – Number of bins in \(\theta_2\).
- Variables
box (
freud.box.Box
) – Box used in the calculation.bin_counts (\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\)) – Bin counts.
PCF (\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\)) – The positional correlation function.
PMFT (\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\)) – The potential of mean force and torque.
r_cut (float) – The cutoff used in the cell list.
R (\(\left(N_{r}\right)\)
numpy.ndarray
) – The array of \(r\)-values for the PCF histogram.T1 (\(\left(N_{\theta1}\right)\)
numpy.ndarray
) – The array of \(\theta_1\)-values for the PCF histogram.T2 (\(\left(N_{\theta2}\right)\)
numpy.ndarray
) – The array of \(\theta_2\)-values for the PCF histogram.inverse_jacobian (\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\)) – The inverse Jacobian used in the PMFT.
n_bins_R (unsigned int) – The number of bins in the \(r\)-dimension of the histogram.
n_bins_T1 (unsigned int) – The number of bins in the \(\theta_1\)-dimension of the histogram.
n_bins_T2 (unsigned int) – The number of bins in the \(\theta_2\)-dimension of the histogram.
-
accumulate
¶ Calculates the positional correlation function and adds to the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
compute
¶ Calculates the positional correlation function for the given points. Will overwrite the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
reset
¶ Resets the values of the PCF histograms in memory.
PMFT \(\left(x, y\right)\)¶
-
class
freud.pmft.
PMFTXY2D
(x_max, y_max, n_x, n_y)¶ Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\) listed in the
X
andY
arrays.The values of \(x\) and \(y\) at which to compute the PCF are controlled by
x_max
,y_max
,n_x
, andn_y
parameters to the constructor. Thex_max
andy_max
parameters determine the minimum/maximum distance at which to compute the PCF andn_x
andn_y
are the number of bins in \(x\) and \(y\).Note
2D:
freud.pmft.PMFTXY2D
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Failing to set z=0 will lead to undefined behavior.Module author: Eric Harper <harperic@umich.edu>
Module author: Vyas Ramasubramani <vramasub@umich.edu>
- Parameters
- Variables
box (
freud.box.Box
) – Box used in the calculation.bin_counts (\(\left(N_{y}, N_{x}\right)\)
numpy.ndarray
) – Bin counts.PCF (\(\left(N_{y}, N_{x}\right)\)
numpy.ndarray
) – The positional correlation function.PMFT (\(\left(N_{y}, N_{x}\right)\)
numpy.ndarray
) – The potential of mean force and torque.r_cut (float) – The cutoff used in the cell list.
X (\(\left(N_{x}\right)\)
numpy.ndarray
) – The array of \(x\)-values for the PCF histogram.Y (\(\left(N_{y}\right)\)
numpy.ndarray
) – The array of \(y\)-values for the PCF histogram.jacobian (float) – The Jacobian used in the PMFT.
n_bins_X (unsigned int) – The number of bins in the \(x\)-dimension of the histogram.
n_bins_Y (unsigned int) – The number of bins in the \(y\)-dimension of the histogram.
-
accumulate
¶ Calculates the positional correlation function and adds to the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
compute
¶ Calculates the positional correlation function for the given points. Will overwrite the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
plot
¶ Plot PMFTXY2D.
- Parameters
ax (
matplotlib.axes.Axes
) – Axis to plot on. IfNone
, make a new figure and axis. (Default value =None
)- Returns
Axis with the plot.
- Return type
-
reset
¶ Resets the values of the PCF histograms in memory.
PMFT \(\left(x, y, \theta\right)\)¶
-
class
freud.pmft.
PMFTXYT
(x_max, y_max, n_x, n_y, n_t)¶ Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] for systems described by coordinates \(x\), \(y\), \(\theta\) listed in the
X
,Y
, andT
arrays.The values of \(x, y, \theta\) at which to compute the PCF are controlled by
x_max
,y_max
, andn_x
,n_y
,n_t
parameters to the constructor. Thex_max
andy_max
parameters determine the minimum/maximum \(x, y\) values (\(\min \left(\theta \right) = 0\), (\(\max \left( \theta \right) = 2\pi\)) at which to compute the PCF andn_x
,n_y
,n_t
are the number of bins in \(x, y, \theta\).Note
2D:
freud.pmft.PMFTXYT
is only defined for 2D systems. The points must be passed in as[x, y, 0]
. Failing to set z=0 will lead to undefined behavior.Module author: Eric Harper <harperic@umich.edu>
Module author: Vyas Ramasubramani <vramasub@umich.edu>
- Parameters
- Variables
box (
freud.box.Box
) – Box used in the calculation.bin_counts (\(\left(N_{\theta}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – Bin counts.PCF (\(\left(N_{\theta}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – The positional correlation function.PMFT (\(\left(N_{\theta}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – The potential of mean force and torque.r_cut (float) – The cutoff used in the cell list.
X (\(\left(N_{x}\right)\)
numpy.ndarray
) – The array of \(x\)-values for the PCF histogram.Y (\(\left(N_{y}\right)\)
numpy.ndarray
) – The array of \(y\)-values for the PCF histogram.T (\(\left(N_{\theta}\right)\)
numpy.ndarray
) – The array of \(\theta\)-values for the PCF histogram.jacobian (float) – The Jacobian used in the PMFT.
n_bins_X (unsigned int) – The number of bins in the \(x\)-dimension of the histogram.
n_bins_Y (unsigned int) – The number of bins in the \(y\)-dimension of the histogram.
n_bins_T (unsigned int) – The number of bins in the \(\theta\)-dimension of the histogram.
-
accumulate
¶ Calculates the positional correlation function and adds to the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
compute
¶ Calculates the positional correlation function for the given points. Will overwrite the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
) – Reference orientations as angles used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),)
numpy.ndarray
, optional) – Orientations as angles used in computation. Usesref_orientations
if not provided orNone
.nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
reset
¶ Resets the values of the PCF histograms in memory.
PMFT \(\left(x, y, z\right)\)¶
-
class
freud.pmft.
PMFTXYZ
(x_max, y_max, z_max, n_x, n_y, n_z)¶ Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\), \(z\), listed in the
X
,Y
, andZ
arrays.The values of \(x, y, z\) at which to compute the PCF are controlled by
x_max
,y_max
,z_max
,n_x
,n_y
, andn_z
parameters to the constructor. Thex_max
,y_max
, andz_max
parameters] determine the minimum/maximum distance at which to compute the PCF andn_x
,n_y
, andn_z
are the number of bins in \(x, y, z\).Note
3D:
freud.pmft.PMFTXYZ
is only defined for 3D systems. The points must be passed in as[x, y, z]
.Module author: Eric Harper <harperic@umich.edu>
Module author: Vyas Ramasubramani <vramasub@umich.edu>
- 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.
n_x (unsigned int) – Number of bins in \(x\).
n_y (unsigned int) – Number of bins in \(y\).
n_z (unsigned int) – Number of bins in \(z\).
shiftvec (list) – Vector pointing from
[0, 0, 0]
to the center of the PMFT.
- Variables
box (
freud.box.Box
) – Box used in the calculation.bin_counts (\(\left(N_{z}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – Bin counts.PCF (\(\left(N_{z}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – The positional correlation function.PMFT (\(\left(N_{z}, N_{y}, N_{x}\right)\)
numpy.ndarray
) – The potential of mean force and torque.r_cut (float) – The cutoff used in the cell list.
X (\(\left(N_{x}\right)\)
numpy.ndarray
) – The array of \(x\)-values for the PCF histogram.Y (\(\left(N_{y}\right)\)
numpy.ndarray
) – The array of \(y\)-values for the PCF histogram.Z (\(\left(N_{z}\right)\)
numpy.ndarray
) – The array of \(z\)-values for the PCF histogram.jacobian (float) – The Jacobian used in the PMFT.
n_bins_X (unsigned int) – The number of bins in the \(x\)-dimension of the histogram.
n_bins_Y (unsigned int) – The number of bins in the \(y\)-dimension of the histogram.
n_bins_Z (unsigned int) – The number of bins in the \(z\)-dimension of the histogram.
-
accumulate
¶ Calculates the positional correlation function and adds to the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 4)
numpy.ndarray
) – Reference orientations as quaternions used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 4)
numpy.ndarray
, optional) – Orientations as quaternions used in computation. Usesref_orientations
if not provided orNone
.face_orientations ((\(N_{particles}\), 4)
numpy.ndarray
, optional) – Orientations of particle faces to account for particle symmetry. If not supplied by user, unit quaternions will be supplied. If a 2D array of shape (\(N_f\), 4) or a 3D array of shape (1, \(N_f\), 4) is supplied, the supplied quaternions will be broadcast for all particles. (Default value =None
).nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
compute
¶ Calculates the positional correlation function for the given points. Will overwrite the current histogram.
- Parameters
box (
freud.box.Box
) – Simulation box.ref_points ((\(N_{particles}\), 3)
numpy.ndarray
) – Reference points used in computation.ref_orientations ((\(N_{particles}\), 4)
numpy.ndarray
) – Reference orientations as quaternions used in computation.points ((\(N_{particles}\), 3)
numpy.ndarray
, optional) – Points used in computation. Usesref_points
if not provided orNone
.orientations ((\(N_{particles}\), 4)
numpy.ndarray
, optional) – Orientations as quaternions used in computation. Usesref_orientations
if not provided orNone
.face_orientations ((\(N_{particles}\), 4)
numpy.ndarray
, optional) – Orientations of particle faces to account for particle symmetry. If not supplied by user, unit quaternions will be supplied. If a 2D array of shape (\(N_f\), 4) or a 3D array of shape (1, \(N_f\), 4) is supplied, the supplied quaternions will be broadcast for all particles. (Default value =None
).nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
-
reset
¶ Resets the values of the PCF histograms in memory.