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. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or 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 angles used in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Points used in computation. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or None.
  • 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 and Y arrays.

The values of \(x\) and \(y\) at which to compute the PCF 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 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. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or 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 angles used in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Points used in computation. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or None.
  • 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, \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, and T arrays.

The values of \(x, y, \theta\) at which to compute the PCF are controlled by x_max, y_max, and n_x, n_y, n_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_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:
  • 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 \(\theta\).
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. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 1) or (\(N_{particles}\),) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or 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 angles used in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Points used in computation. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or None.
  • 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, and Z 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, 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 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. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or None.
  • 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 angles used in computation.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Points used in computation. Uses ref_points if not provided or None.
  • orientations ((\(N_{particles}\), 4) numpy.ndarray, optional) – Orientations as angles used in computation. Uses ref_orientations if not provided or None.
  • 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.