PMFT Module

Overview

freud.pmft.PMFTR12	Computes the PMFT [vAAS+13, vAKA+14] in a 2D system described by \(r\), \(\theta_1\), \(\theta_2\).
freud.pmft.PMFTXYT	Computes the PMFT [vAAS+13, vAKA+14] for systems described by coordinates \(x\), \(y\), \(\theta\).
freud.pmft.PMFTXY	Computes the PMFT [vAAS+13, vAKA+14] in coordinates \(x\), \(y\).
freud.pmft.PMFTXYZ	Computes the PMFT [vAAS+13, vAKA+14] in coordinates \(x\), \(y\), \(z\).

Details

The freud.pmft module allows for the calculation of the Potential of Mean Force and Torque (PMFT) [vAAS+13, vAKA+14] 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(r_max, bins)

Bases: _PMFT

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

property bin_centers

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

Type:

list (numpy.ndarray)

property bin_counts

The bin counts in the histogram.

Type:

\(\left(N_0, N_1 \right)\) numpy.ndarray

property 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:

list (numpy.ndarray)

property 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(system, orientations, query_points=None, query_orientations=None, neighbors=None, reset=True)

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

property default_query_args

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

property 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(x_max, y_max, bins)

Bases: _PMFT

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

There are 3 degrees of translational and rotational freedom in 2 dimensions, so this class implicitly integrates over the rotational degree of freedom of the second particle.

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

property bin_centers

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

Type:

list (numpy.ndarray)

property bin_counts

The bin counts in the histogram.

Type:

numpy.ndarray

property 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:

list (numpy.ndarray)

property 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(system, query_orientations, query_points=None, neighbors=None, reset=True)

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

property default_query_args

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

property nbins

The number of bins in each dimension of the histogram.

Type:

list

plot(ax=None, cmap='viridis')

Plot PMFTXY.

Parameters:

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

cmap (str):

String name of a Matplotlib colormap. (Default value = "viridis").

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(x_max, y_max, bins)

Bases: _PMFT

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

property bin_centers

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

Type:

list (numpy.ndarray)

property bin_counts

The bin counts in the histogram.

Type:

\(\left(N_0, N_1 \right)\) numpy.ndarray

property 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:

list (numpy.ndarray)

property 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(system, orientations, query_points=None, query_orientations=None, neighbors=None, reset=True)

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

property default_query_args

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

property 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(x_max, y_max, z_max, bins, shiftvec=None)

Bases: _PMFT

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

There are 6 degrees of translational and rotational freedom in 3 dimensions, so this class is implicitly integrates out the orientational degrees of freedom in the system associated with the points. All calculations are done in the reference from of the query points.

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.

property bin_centers

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

Type:

list (numpy.ndarray)

property bin_counts

The bin counts in the histogram.

Type:

\(\left(N_0, N_1 \right)\) numpy.ndarray

property 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:

list (numpy.ndarray)

property 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(system, query_orientations, query_points=None, equiv_orientations=None, neighbors=None, reset=True)

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

• equiv_orientations ((\(N_{faces}\), 4) numpy.ndarray, optional) – Orientations to be treated as equivalent to account for symmetry of the points. For instance, if the query_points are rectangular prisms with the long axis corresponding to the x-axis, then a point at \((1, 0, 0)\) and a point at \((-1, 0, 0)\) are symmetrically equivalent and can be counted towards both the positive and negative bins. If not supplied by user or None, a unit quaternion will be used (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).

property default_query_args

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

property 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