PMFT Module

Overview

freud.pmft.PMFTR12

Computes the PMFT [vAKA+14][vAAS+13] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\).

freud.pmft.PMFTXYT

Computes the PMFT [vAKA+14][vAAS+13] for systems described by coordinates \(x\), \(y\), \(\theta\).

freud.pmft.PMFTXY

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\).

freud.pmft.PMFTXYZ

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\), \(z\).

Details

The freud.pmft module allows for the calculation of the Potential of Mean Force and Torque (PMFT) [vAKA+14][vAAS+13] 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 query point’s neighboring points are assigned to bins, determined by the relative positions and/or orientations of the particles. Next, the pair correlation function (PCF) is computed by normalizing the binned histogram, by dividing out the number of accumulated frames, bin sizes (the Jacobian), and query 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 [vAKA+14].

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 PMFT will return nan.

class freud.pmft.PMFTR12

Bases: freud.pmft._PMFT

Computes the PMFT [vAKA+14][vAAS+13] 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].

Parameters
  • r_max (float) – Maximum distance at which to compute the PMFT.

  • bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(r\), \(\theta_1\), and \(\theta_2\). If a sequence of three integers, interpreted as (num_bins_r, num_bins_t1, num_bins_t2).

bin_centers

The centers of each bin in the histogram (has the same shape as the histogram itself).

Type

numpy.ndarray

property bin_counts

The bin counts in the histogram.

Type

numpy.ndarray

bin_edges

The edges of each bin in the histogram (is one element larger in each dimension than the histogram because each bin has a lower and upper bound).

Type

numpy.ndarray

bounds

A list of tuples indicating upper and lower bounds of each axis of the histogram.

Type

list (tuple)

property box

The box object used in the last computation.

Type

freud.box.Box

compute

Calculates the PMFT.

Parameters
  • system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

  • orientations ((\(N_{points}\), 4) or (\(N_{points}\),) numpy.ndarray) – Orientations associated with system points that are used to calculate bonds. If the array is one-dimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.

  • query_points ((\(N_{query\_points}\), 3) numpy.ndarray, optional) – Query points used to calculate the PMFT. Uses the system’s points if None (Default value = None).

  • query_orientations ((\(N_{query\_points}\), 4) numpy.ndarray, optional) – Query orientations associated with query points that are used to calculate bonds. If the array is one-dimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis. Uses orientations if None. (Default value = None).

  • neighbors (freud.locality.NeighborList or dict, optional) – Either a NeighborList of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).

  • reset (bool) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).

default_query_args

The default query arguments are {'mode': 'ball', 'r_max': self.r_max}.

nbins

The number of bins in each dimension of the histogram

Type

list

property pmft

The discrete potential of mean force and torque.

Type

np.ndarray

class freud.pmft.PMFTXY

Bases: freud.pmft._PMFT

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\).

Since there are 3 degrees of translational and rotational freedom in 2 dimensions, this class is implicitly integrating out one of them. Specifically, by comparison to PMFTXYT we see that the missing dimension is the relative orientation of the second particle. Note that this degree of freedom is still accounted for in the Jacobian of this calculation.

Note

2D: freud.pmft.PMFTXY is only defined for 2D systems. The points must be passed in as [x, y, 0].

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.

  • bins (unsigned int or sequence of length 2) – If an unsigned int, the number of bins in \(x\) and \(y\). If a sequence of two integers, interpreted as (num_bins_x, num_bins_y).

bin_centers

The centers of each bin in the histogram (has the same shape as the histogram itself).

Type

numpy.ndarray

property bin_counts

The bin counts in the histogram.

Type

numpy.ndarray

bin_edges

The edges of each bin in the histogram (is one element larger in each dimension than the histogram because each bin has a lower and upper bound).

Type

numpy.ndarray

bounds

A list of tuples indicating upper and lower bounds of each axis of the histogram.

Type

list (tuple)

property box

The box object used in the last computation.

Type

freud.box.Box

compute

Calculates the PMFT.

Note

The orientations of the system points are irrelevant for this calculation because that dimension is integrated out. The provided query_orientations are therefore always associated with query_points (which are equal to the system points if no query_points are explicitly provided).

Parameters
  • system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

  • query_orientations ((\(N_{query\_points}\), 4) or (\(N_{query\_points}\),) numpy.ndarray) – Query orientations associated with query points that are used to calculate bonds. If the array is one-dimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.

  • query_points ((\(N_{query\_points}\), 3) numpy.ndarray, optional) – Query points used to calculate the PMFT. Uses the system’s points if None (Default value = None).

  • neighbors (freud.locality.NeighborList or dict, optional) –

    Either a NeighborList of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).

  • reset (bool) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).

default_query_args

The default query arguments are {'mode': 'ball', 'r_max': self.r_max}.

nbins

The number of bins in each dimension of the histogram

Type

list

plot

Plot PMFTXY.

Parameters

ax (matplotlib.axes.Axes, optional) – 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)

property pmft

The discrete potential of mean force and torque.

Type

np.ndarray

class freud.pmft.PMFTXYT

Bases: freud.pmft._PMFT

Computes the PMFT [vAKA+14][vAAS+13] for systems described by coordinates \(x\), \(y\), \(\theta\).

Note

2D: freud.pmft.PMFTXYT is only defined for 2D systems. The points must be passed in as [x, y, 0].

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.

  • bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(x\), \(y\), and \(t\). If a sequence of three integers, interpreted as (num_bins_x, num_bins_y, num_bins_t).

bin_centers

The centers of each bin in the histogram (has the same shape as the histogram itself).

Type

numpy.ndarray

property bin_counts

The bin counts in the histogram.

Type

numpy.ndarray

bin_edges

The edges of each bin in the histogram (is one element larger in each dimension than the histogram because each bin has a lower and upper bound).

Type

numpy.ndarray

bounds

A list of tuples indicating upper and lower bounds of each axis of the histogram.

Type

list (tuple)

property box

The box object used in the last computation.

Type

freud.box.Box

compute

Calculates the PMFT.

Parameters
  • system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

  • orientations ((\(N_{points}\), 4) or (\(N_{points}\),) numpy.ndarray) – Orientations associated with system points that are used to calculate bonds. If the array is one-dimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis.

  • query_points ((\(N_{query\_points}\), 3) numpy.ndarray, optional) – Query points used to calculate the PMFT. Uses the system’s points if None (Default value = None).

  • query_orientations ((\(N_{query\_points}\), 4) numpy.ndarray, optional) – Query orientations associated with query points that are used to calculate bonds. If the array is one-dimensional, the values are treated as angles in radians corresponding to counterclockwise rotations about the z axis. Uses orientations if None. (Default value = None).

  • neighbors (freud.locality.NeighborList or dict, optional) –

    Either a NeighborList of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).

  • reset (bool) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).

default_query_args

The default query arguments are {'mode': 'ball', 'r_max': self.r_max}.

nbins

The number of bins in each dimension of the histogram

Type

list

property pmft

The discrete potential of mean force and torque.

Type

np.ndarray

class freud.pmft.PMFTXYZ

Bases: freud.pmft._PMFT

Computes the PMFT [vAKA+14][vAAS+13] in coordinates \(x\), \(y\), \(z\).

Since there are 6 degrees of translational and rotational freedom in 3 dimensions, this class is implicitly integrating out three of them. In particular, we are disregarding the orientational degrees of freedom in the system. The simplest parameterization of these degrees is using Euler angles. The total volume of orientations that are implicitly integrated out by this calculation can be computed by an explicit integral over the Euler angles:

\[\int_0^{2\pi} \int_0^\pi \int_0^{2\pi} \sin \theta d\phi d\theta d\psi = 8 \pi^2\]

For more information on this calculation, see [GMS63] (the equation is also reproduced without proof at https://en.wikipedia.org/wiki/3D_rotation_group#Spherical_harmonics). This prefactor of \(8 \pi^2\) is accounted for in the Jacobian used to compute the PMFTXYZ.

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.

  • bins (unsigned int or sequence of length 3) – If an unsigned int, the number of bins in \(x\), \(y\), and \(z\). If a sequence of three integers, interpreted as (num_bins_x, num_bins_y, num_bins_z).

  • shiftvec (list) – Vector pointing from [0, 0, 0] to the center of the PMFT.

bin_centers

The centers of each bin in the histogram (has the same shape as the histogram itself).

Type

numpy.ndarray

property bin_counts

The bin counts in the histogram.

Type

numpy.ndarray

bin_edges

The edges of each bin in the histogram (is one element larger in each dimension than the histogram because each bin has a lower and upper bound).

Type

numpy.ndarray

bounds

A list of tuples indicating upper and lower bounds of each axis of the histogram.

Type

list (tuple)

property box

The box object used in the last computation.

Type

freud.box.Box

compute

Calculates the PMFT.

Note

The orientations of the system points are irrelevant for this calculation because that dimension is integrated out. The provided query_orientations are therefore always associated with query_points (which are equal to the system points if no query_points are explicitly provided.

Parameters
  • system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

  • query_orientations ((\(N_{points}\), 4) numpy.ndarray) – Query orientations associated with query points that are used to calculate bonds.

  • query_points ((\(N_{query\_points}\), 3) numpy.ndarray, optional) – Query points used to calculate the PMFT. Uses the system’s points if None (Default value = None).

  • face_orientations ((\(N_{points}\), \(N_{faces}\), 4) numpy.ndarray, optional) – Orientations of particle faces to account for symmetry of the points. If not supplied by user or None, unit quaternions will be supplied. If a 2D array of shape (\(N_{faces}\), 4) or a 3D array of shape (1, \(N_{faces}\), 4) is supplied, the supplied quaternions will be broadcast for all points. (Default value = None).

  • neighbors (freud.locality.NeighborList or dict, optional) –

    Either a NeighborList of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).

  • reset (bool) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).

default_query_args

The default query arguments are {'mode': 'ball', 'r_max': self.r_max}.

nbins

The number of bins in each dimension of the histogram

Type

list

property pmft

The discrete potential of mean force and torque.

Type

np.ndarray