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 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. 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}\), 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).

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}\), 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).

plot

Plot PMFTXY2D.

Parameters

ax (matplotlib.axes.Axes) – Axis to plot on. If None, make a new figure and axis. (Default value = None)

Returns

Axis with the plot.

Return type

(matplotlib.axes.Axes)

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}\), 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).

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 quaternions 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 quaternions 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 quaternions 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 quaternions 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.