PMFT Module¶
Overview
freud.pmft.PMFTR12 |
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\). |
freud.pmft.PMFTXYT |
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] for systems described by coordinates \(x\), \(y\), \(\theta\) listed in the X , Y , and T arrays. |
freud.pmft.PMFTXY2D |
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\) listed in the X and Y arrays. |
freud.pmft.PMFTXYZ |
Computes the PMFT [vanAndersKlotsa2014] [vanAndersAhmed2014] in coordinates \(x\), \(y\), \(z\), listed in the X , Y , and Z arrays. |
Details
The 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 PMFT is defined as the negative algorithm of positional correlation function (PCF). A given set of reference points is given around which the PCF is computed and averaged in a sea of data points. The resulting values are accumulated in a PCF array listing the value of the PCF at a discrete set of points. The specific points are determined by the particular coordinate system used to represent the system.
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\).
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
).
- box (
-
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 angles 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 angles used in computation. Usesref_orientations
if not provided orNone
. - nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
- box (
-
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
).
- box (
-
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 angles 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 angles used in computation. Usesref_orientations
if not provided orNone
. - nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
- box (
-
reset
¶ Resets the values of the PCF histograms in memory.
- box (
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
).
- box (
-
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 angles 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 angles used in computation. Usesref_orientations
if not provided orNone
. - nlist (
freud.locality.NeighborList
, optional) – NeighborList used to find bonds (Default value =None
).
- box (
-
reset
¶ Resets the values of the PCF histograms in memory.
- box (
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 angles 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 angles 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
).
- box (
-
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 angles 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 angles 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
).
- box (
-
reset
¶ Resets the values of the PCF histograms in memory.