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\).
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 t1.
  • n_t2 (unsigned int) – Number of bins in t2.
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 T1-values for the PCF histogram.
  • T2 (\(\left(N_{\theta2}\right)\) numpy.ndarray) – The array of T2-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 histogram.
  • n_bins_T1 (unsigned int) – The number of bins in the T1-dimension of histogram.
  • n_bins_T2 (unsigned int) – The number of bins in the T2-dimension of histogram.
accumulate(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of reference points to use in the calculation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of particles to use in the calculation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
compute(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations as angles to use in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Orientations as angles to use in computation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
getBinCounts(self)

Get the raw bin counts.

Returns:Bin Counts.
Return type:\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\) numpy.ndarray
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getInverseJacobian(self)

Get the inverse Jacobian used in the PMFT.

Returns:Inverse Jacobian.
Return type:\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\) numpy.ndarray
getNBinsR(self)

Get the number of bins in the r-dimension of histogram.

Returns:\(N_r\).
Return type:unsigned int
getNBinsT1(self)

Get the number of bins in the T1-dimension of histogram.

Returns:\(N_{\theta_1}\).
Return type:unsigned int
getNBinsT2(self)

Get the number of bins in the T2-dimension of histogram.

Returns:\(N_{\theta_2}\).
Return type:unsigned int
getPCF(self)

Get the positional correlation function.

Returns:PCF.
Return type:\(\left(N_{r}, N_{\theta2}, N_{\theta1}\right)\) numpy.ndarray
getPMFT(self)

Get the potential of mean force and torque.

Returns:PMFT.
Return type:(matches PCF) numpy.ndarray
getR(self)

Get the array of r-values for the PCF histogram.

Returns:Bin centers of r-dimension of histogram.
Return type:\(\left(N_{r}\right)\) numpy.ndarray
getRCut(self)

Get the r_cut value used in the cell list.

Returns:r_cut.
Return type:float
getT1(self)

Get the array of T1-values for the PCF histogram.

Returns:Bin centers of T1-dimension of histogram.
Return type:\(\left(N_{\theta_1}\right)\) numpy.ndarray
getT2(self)

Get the array of T2-values for the PCF histogram.

Returns:Bin centers of T2-dimension of histogram.
Return type:\(\left(N_{\theta_2}\right)\) numpy.ndarray
reducePCF(self)

Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.pmft.PMFT.PCF().

resetPCF(self)

Resets the values of the PCF histograms in memory.

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, and t arrays.

The values of x, y, t to compute the PCF at are controlled by x_max, y_max and n_bins_x, n_bins_y, n_bins_t parameters to the constructor. The x_max and y_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 and n_bins_x, n_bins_y, n_bins_t is the number of bins in x, y, t.

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:
  • x_max (float) – Maximum x distance at which to compute the PMFT.
  • y_max (float) – Maximum y 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_t (unsigned int) – Number of bins in t.
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 T-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 histogram.
  • n_bins_y (unsigned int) – The number of bins in the y-dimension of histogram.
  • n_bins_T (unsigned int) – The number of bins in the T-dimension of histogram.
accumulate(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations as angles to use in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – orientations as angles to use in computation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
compute(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Reference orientations as angles to use in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – orientations as angles to use in computation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
getBinCounts(self)

Get the raw bin counts.

Returns:Bin Counts.
Return type:\(\left(N_{\theta}, N_{y}, N_{x}\right)\) numpy.ndarray
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getJacobian(self)

Get the Jacobian used in the PMFT.

Returns:Jacobian.
Return type:float
getNBinsT(self)

Get the number of bins in the t-dimension of histogram.

Returns:\(N_{\theta}\).
Return type:unsigned int
getNBinsX(self)

Get the number of bins in the x-dimension of histogram.

Returns:\(N_x\).
Return type:unsigned int
getNBinsY(self)

Get the number of bins in the y-dimension of histogram.

Returns:\(N_y\).
Return type:unsigned int
getPCF(self)

Get the positional correlation function.

Returns:PCF.
Return type:\(\left(N_{\theta}, N_{y}, N_{x}\right)\) numpy.ndarray
getPMFT(self)

Get the potential of mean force and torque.

Returns:PMFT.
Return type:(matches PCF) numpy.ndarray
getRCut(self)

Get the r_cut value used in the cell list.

Returns:r_cut.
Return type:float
getT(self)

Get the array of t-values for the PCF histogram.

Returns:Bin centers of t-dimension of histogram.
Return type:\(\left(N_{\theta}\right)\) numpy.ndarray
getX(self)

Get the array of x-values for the PCF histogram.

Returns:Bin centers of x-dimension of histogram.
Return type:\(\left(N_{x}\right)\) numpy.ndarray
getY(self)

Get the array of y-values for the PCF histogram.

Returns:Bin centers of y-dimension of histogram.
Return type:\(\left(N_{y}\right)\) numpy.ndarray
reducePCF(self)

Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.pmft.PMFT.PCF().

resetPCF(self)

Resets the values of the PCF histograms in memory.

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 and y arrays.

The values of x and y to compute the PCF at are controlled by x_max, y_max, n_x, and n_y parameters to the constructor. The x_max and y_max parameters determine the minimum/maximum distance at which to compute the PCF and n_x and n_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:
  • x_max (float) – Maximum x distance at which to compute the PMFT.
  • y_max (float) – Maximum y 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.
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 histogram.
  • n_bins_y (unsigned int) – The number of bins in the y-dimension of histogram.
accumulate(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of reference points to use in the calculation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of particles to use in the calculation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
compute(self, box, ref_points, ref_orientations, points, orientations, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of reference points to use in the calculation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of particles to use in the calculation.
  • nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).
getBinCounts(self)

Get the raw bin counts (non-normalized).

Returns:Bin Counts.
Return type:\(\left(N_{y}, N_{x}\right)\) numpy.ndarray
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getJacobian(self)

Get the Jacobian.

Returns:Jacobian.
Return type:float
getNBinsX(self)

Get the number of bins in the x-dimension of histogram.

Returns:\(N_x\).
Return type:unsigned int
getNBinsY(self)

Get the number of bins in the y-dimension of histogram.

Returns:\(N_y\).
Return type:unsigned int
getPCF(self)

Get the positional correlation function.

Returns:PCF.
Return type:\(\left(N_{y}, N_{x}\right)\) numpy.ndarray
getPMFT(self)

Get the potential of mean force and torque.

Returns:PMFT.
Return type:(matches PCF) numpy.ndarray
getRCut(self)

Get the r_cut value used in the cell list.

Returns:r_cut.
Return type:float
getX(self)

Get the array of x-values for the PCF histogram.

Returns:Bin centers of x-dimension of histogram.
Return type:\(\left(N_{x}\right)\) numpy.ndarray
getY(self)

Get the array of y-values for the PCF histogram.

Returns:Bin centers of y-dimension of histogram.
Return type:\(\left(N_{y}\right)\) numpy.ndarray
reducePCF(self)

Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.pmft.PMFT.PCF().

resetPCF(self)

Resets the values of the PCF histograms in memory.

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, and z arrays.

The values of x, y, z to compute the PCF at are controlled by x_max, y_max, z_max, n_x, n_y, and n_z parameters to the constructor. The x_max, y_max, and z_max parameters determine the minimum/maximum distance at which to compute the PCF and n_x, n_y, and n_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 histogram.
  • n_bins_y (unsigned int) – The number of bins in the y-dimension of histogram.
  • n_bins_z (unsigned int) – The number of bins in the z-dimension of histogram.
accumulate(self, box, ref_points, ref_orientations, points, orientations, face_orientations=None, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of reference points to use in the calculation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of particles to use in the calculation.
  • 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 to use to find bonds (Default value = None).
compute(self, box, ref_points, ref_orientations, points, orientations, face_orientations=None, nlist=None)

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 to calculate the local density.
  • ref_orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of reference points to use in the calculation.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray) – Angles of particles to use in the calculation.
  • 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 to use to find bonds (Default value = None).
getBinCounts(self)

Get the raw bin counts.

Returns:Bin Counts.
Return type:\(\left(N_{z}, N_{y}, N_{x}\right)\) numpy.ndarray
getBox(self)

Get the box used in the calculation.

Returns:freud Box.
Return type:freud.box.Box
getJacobian(self)

Get the Jacobian.

Returns:Jacobian.
Return type:float
getNBinsX(self)

Get the number of bins in the x-dimension of histogram.

Returns:\(N_x\).
Return type:unsigned int
getNBinsY(self)

Get the number of bins in the y-dimension of histogram.

Returns:\(N_y\).
Return type:unsigned int
getNBinsZ(self)

Get the number of bins in the z-dimension of histogram.

Returns:\(N_z\).
Return type:unsigned int
getPCF(self)

Get the positional correlation function.

Returns:PCF.
Return type:\(\left(N_{z}, N_{y}, N_{x}\right)\) numpy.ndarray
getPMFT(self)

Get the potential of mean force and torque.

Returns:PMFT.
Return type:\(\left(N_{z}, N_{y}, N_{x}\right)\) numpy.ndarray
getRCut(self)

Get the r_cut value used in the cell list.

Returns:r_cut.
Return type:float
getX(self)

Get the array of x-values for the PCF histogram.

Returns:Bin centers of x-dimension of histogram.
Return type:\(\left(N_{x}\right)\) numpy.ndarray
getY(self)

Get the array of y-values for the PCF histogram.

Returns:Bin centers of y-dimension of histogram.
Return type:\(\left(N_{y}\right)\) numpy.ndarray
getZ(self)

Get the array of z-values for the PCF histogram.

Returns:Bin centers of z-dimension of histogram.
Return type:\(\left(N_{z}\right)\) numpy.ndarray
reducePCF(self)

Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.pmft.PMFTXYZ.PCF().

resetPCF(self)

Resets the values of the PCF histograms in memory.