# PMFT Module¶

The PMFT Module allows for the calculation of the Potential of Mean Force and Torque (PMFT) [Cit2] in a number of different coordinate systems.

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$$):
• X, Y
• X, Y, $$\theta_2$$
• $$r$$, $$\theta_1$$, $$\theta_2$$
• 3D particle coordinates -> X, Y, Z

## Coordinate System: $$x$$, $$y$$, $$\theta_2$$¶

class freud.pmft.PMFTXYT(x_max, y_max, n_x, n_y, n_t)

Computes the PMFT [Cit2] for a given set of points.

A given set of reference points is given around which the PCF is computed and averaged in a sea of data points. Computing the PCF results in a PCF array listing the value of the PCF at each given $$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. x_max, y_max 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: This calculation is defined for 2D systems only. However particle positions are still required to be (x, y, 0)

Module author: Eric Harper <harperic@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
PCF

Get the positional correlation function.

PMFT

Get the positional correlation function.

T

Get the array of t-values for the PCF histogram

X

Get the array of x-values for the PCF histogram

Y

Get the array of y-values for the PCF 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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
bin_counts

Get the raw bin counts.

box

Get the box used in the calculation

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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
getBinCounts(self)

Get the raw bin counts.

Returns: Bin Counts numpy.ndarray, shape= $$\left(N_{\theta}, N_{y}, N_{x}\right)$$, dtype= numpy.uint32
getBox(self)

Get the box used in the calculation

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

Get the jacobian used in the pmft

Returns: Inverse Jacobian float
getNBinsT(self)

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

Returns: $$N_{\theta}$$ unsigned int
getNBinsX(self)

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

Returns: $$N_x$$ unsigned int
getNBinsY(self)

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

Returns: $$N_y$$ unsigned int
getPCF(self)

Get the positional correlation function.

Returns: PCF numpy.ndarray, shape= $$\left(N_{\theta}, N_{y}, N_{x}\right)$$, dtype= numpy.float32
getPMFT(self)

Get the Potential of Mean Force and Torque.

Returns: PMFT numpy.ndarray, shape= $$\left(N_{\theta}, N_{y}, N_{x}\right)$$, dtype= numpy.float32
getRCut(self)

Get the r_cut value used in the cell list

Returns: r_cut float
getT(self)

Get the array of t-values for the PCF histogram

Returns: bin centers of t-dimension of histogram numpy.ndarray, shape= $$\left(N_{\theta}\right)$$, dtype= numpy.float32
getX(self)

Get the array of x-values for the PCF histogram

Returns: bin centers of x-dimension of histogram numpy.ndarray, shape= $$\left(N_{x}\right)$$, dtype= numpy.float32
getY(self)

Get the array of y-values for the PCF histogram

Returns: bin centers of y-dimension of histogram numpy.ndarray, shape= $$\left(N_{y}\right)$$, dtype= numpy.float32
jacobian

Get the jacobian used in the pmft

n_bins_T

Get the number of bins in the T-dimension of histogram

n_bins_X

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

n_bins_Y

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

r_cut

Get the r_cut value used in the cell list

reducePCF(self)

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

resetPCF(self)

Resets the values of the pcf histograms in memory

## Coordinate System: $$x$$, $$y$$¶

class freud.pmft.PMFTXY2D(x_max, y_max, n_x, n_y)

Computes the PMFT [Cit2] for a given set of points.

A given set of reference points is given around which the PCF is computed and averaged in a sea of data points. Computing the PCF results in a PCF array listing the value of the PCF at each given $$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. x_max and y_max 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: This calculation is defined for 2D systems only.

Module author: Eric Harper <harperic@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
PCF

Get the positional correlation function.

PMFT

Get the positional correlation function.

X

Get the array of x-values for the PCF histogram

Y

Get the array of y-values for the PCF 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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – orientations of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – orientations of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
bin_counts

Get the raw bin counts.

box

Get the box used in the calculation

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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – orientations of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – orientations of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
getBinCounts(self)

Get the raw bin counts (non-normalized).

Returns: Bin Counts numpy.ndarray, shape= $$\left(N_{y}, N_{x}\right)$$, dtype= numpy.uint32
getBox(self)

Get the box used in the calculation

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

Get the jacobian

Returns: jacobian float
getNBinsX(self)

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

Returns: $$N_x$$ unsigned int
getNBinsY(self)

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

Returns: $$N_y$$ unsigned int
getPCF(self)

Get the positional correlation function.

Returns: PCF numpy.ndarray, shape= $$\left(N_{y}, N_{y}\right)$$, dtype= numpy.float32
getPMFT(self)

Get the Potential of Mean Force and Torque.

Returns: PMFT numpy.ndarray, shape= $$\left(N_{y}, N_{x}\right)$$, dtype= numpy.float32
getRCut(self)

Get the r_cut value used in the cell list

Returns: r_cut float
getX(self)

Get the array of x-values for the PCF histogram

Returns: bin centers of x-dimension of histogram numpy.ndarray, shape= $$\left(N_{x}\right)$$, dtype= numpy.float32
getY(self)

Get the array of y-values for the PCF histogram

Returns: bin centers of y-dimension of histogram numpy.ndarray, shape= $$\left(N_{y}\right)$$, dtype= numpy.float32
jacobian

Get the jacobian used in the pmft

n_bins_X

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

n_bins_Y

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

r_cut

Get the r_cut value used in the cell list

reducePCF(self)

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

resetPCF(self)

Resets the values of the pcf histograms in memory

## Coordinate System: $$r$$, $$\theta_1$$, $$\theta_2$$¶

class freud.pmft.PMFTR12(r_max, n_r, n_t1, n_t2)

Computes the PMFT [Cit2] for a given set of points.

A given set of reference points is given around which the PCF is computed and averaged in a sea of data points. Computing the PCF results in a pcf array listing the value of the PCF at each given $$r$$, $$\theta_1$$, $$\theta_2$$ listed in the r, t1, and t2 arrays.

The values of r, t1, t2 to compute the pcf at are controlled by r_max and nbins_r, nbins_t1, nbins_t2 parameters to the constructor. rmax determines the minimum/maximum r ($$\min \left( \theta_1 \right) = \min \left( \theta_2 \right) = 0$$, ($$\max \left( \theta_1 \right) = \max \left( \theta_2 \right) = 2\pi$$) at which to compute the pcf and nbins_r, nbins_t1, nbins_t2 is the number of bins in r, t1, t2.

Note

2D: This calculation is defined for 2D systems only. However particle positions are still required to be (x, y, 0)

Module author: Eric Harper <harperic@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
PCF

Get the positional correlation function.

PMFT

Get the positional correlation function.

R

Get the array of r-values for the PCF histogram

Returns: bin centers of r-dimension of histogram numpy.ndarray, shape= $$\left(N_{r}\right)$$, dtype= numpy.float32
T1

Get the array of T1-values for the PCF histogram

T2

Get the array of T2-values for the PCF histogram

Returns: bin centers of T2-dimension of histogram numpy.ndarray, shape= $$\left(N_{\theta1}\right)$$, dtype= numpy.float32
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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
bin_counts

Get the raw bin counts.

box

Get the box used in the calculation

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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}\right)$$, dtype= numpy.float32) – angles of particles to use in calculation nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
getBinCounts(self)

Get the raw bin counts.

Returns: Bin Counts numpy.ndarray, shape= $$\left(N_{r}, N_{\theta1}, N_{\theta2}\right)$$, dtype= numpy.uint32
getBox(self)

Get the box used in the calculation

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

Get the inverse jacobian used in the pmft

Returns: Inverse Jacobian numpy.ndarray, shape= $$\left(N_{r}, N_{\theta1}, N_{\theta2}\right)$$, dtype= numpy.float32
getNBinsR(self)

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

Returns: $$N_r$$ unsigned int
getNBinsT1(self)

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

Returns: $$N_{\theta_1}$$ unsigned int
getNBinsT2(self)

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

Returns: $$N_{\theta_2}$$ unsigned int
getPCF(self)

Get the positional correlation function.

Returns: PCF numpy.ndarray, shape= $$\left(N_{r}, N_{\theta1}, N_{\theta2}\right)$$, dtype= numpy.float32
getPMFT(self)

Get the Potential of Mean Force and Torque.

Returns: PMFT numpy.ndarray, shape= $$\left(N_{r}, N_{\theta1}, N_{\theta2}\right)$$, dtype= numpy.float32
getR(self)

Get the array of r-values for the PCF histogram

Returns: bin centers of r-dimension of histogram numpy.ndarray, shape= $$\left(N_{r}\right)$$, dtype= numpy.float32
getRCut(self)

Get the r_cut value used in the cell list

Returns: r_cut float
getT1(self)

Get the array of T1-values for the PCF histogram

Returns: bin centers of T1-dimension of histogram numpy.ndarray, shape= $$\left(N_{\theta1}\right)$$, dtype= numpy.float32
getT2(self)

Get the array of T2-values for the PCF histogram

Returns: bin centers of T2-dimension of histogram numpy.ndarray, shape= $$\left(N_{\theta2}\right)$$, dtype= numpy.float32
inverse_jacobian

Get the array of T2-values for the PCF histogram

n_bins_T1

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

n_bins_T2

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

n_bins_r

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

r_cut

Get the r_cut value used in the cell list

reducePCF(self)

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

resetPCF(self)

Resets the values of the pcf histograms in memory

## Coordinate System: $$x$$, $$y$$, $$z$$¶

class freud.pmft.PMFTXYZ(x_max, y_max, z_max, n_x, n_y, n_z)

Computes the PMFT [Cit2] for a given set of points.

A given set of reference points is given around which the PCF is computed and averaged in a sea of data points. Computing the PCF results in a PCF array listing the value of the PCF at each given $$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. x_max, y_max, and z_max determine the minimum/maximum distance at which to compute the PCF and n_x, n_y, n_z is the number of bins in x, y, z.

Note

3D: This calculation is defined for 3D systems only.

Module author: Eric Harper <harperic@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
PCF

Get the positional correlation function.

PMFT

Get the Potential of Mean Force and Torque.

X

Get the array of x-values for the PCF histogram

Y

Get the array of y-values for the PCF histogram

Z

Get the array of z-values for the PCF 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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}, 4\right)$$, dtype= numpy.float32) – orientations of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}, 4\right)$$, dtype= numpy.float32) – orientations of particles to use in calculation face_orientations (numpy.ndarray, shape= $$\left( \left(N_{particles}, \right), N_{faces}, 4\right)$$, dtype= numpy.float32) – 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.
bin_counts

Get the raw bin counts.

box

Get the box used in the calculation

compute(self, box, ref_points, ref_orientations, points, orientations, face_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 (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – reference points to calculate the local density ref_orientations (numpy.ndarray, shape= $$\left(N_{particles}, 4\right)$$, dtype= numpy.float32) – orientations of reference points to use in calculation points (numpy.ndarray, shape= $$\left(N_{particles}, 3\right)$$, dtype= numpy.float32) – points to calculate the local density orientations (numpy.ndarray, shape= $$\left(N_{particles}, 4\right)$$, dtype= numpy.float32) – orientations of particles to use in calculation face_orientations (numpy.ndarray, shape= $$\left( \left(N_{particles}, \right), N_{faces}, 4\right)$$, dtype= numpy.float32) – orientations of particle faces to account for particle symmetry nlist (freud.locality.NeighborList) – freud.locality.NeighborList object to use to find bonds
getBinCounts(self)

Get the raw bin counts.

Returns: Bin Counts numpy.ndarray, shape= $$\left(N_{z}, N_{y}, N_{x}\right)$$, dtype= numpy.uint32
getBox(self)

Get the box used in the calculation

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

Get the jacobian

Returns: jacobian float
getNBinsX(self)

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

Returns: $$N_x$$ unsigned int
getNBinsY(self)

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

Returns: $$N_y$$ unsigned int
getNBinsZ(self)

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

Returns: $$N_z$$ unsigned int
getPCF(self)

Get the positional correlation function.

Returns: PCF numpy.ndarray, shape= $$\left(N_{z}, N_{y}, N_{x}\right)$$, dtype= numpy.float32
getPMFT(self)

Get the Potential of Mean Force and Torque.

Returns: PMFT numpy.ndarray, shape= $$\left(N_{z}, N_{y}, N_{x}\right)$$, dtype= numpy.float32
getX(self)

Get the array of x-values for the PCF histogram

Returns: bin centers of x-dimension of histogram numpy.ndarray, shape= $$\left(N_{x}\right)$$, dtype= numpy.float32
getY(self)

Get the array of y-values for the PCF histogram

Returns: bin centers of y-dimension of histogram numpy.ndarray, shape= $$\left(N_{y}\right)$$, dtype= numpy.float32
getZ(self)

Get the array of z-values for the PCF histogram

Returns: bin centers of z-dimension of histogram numpy.ndarray, shape= $$\left(N_{z}\right)$$, dtype= numpy.float32
jacobian

Get the jacobian used in the pmft

n_bins_X

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

n_bins_Y

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

n_bins_Z

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

reducePCF(self)

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

resetPCF(self)

Resets the values of the pcf histograms in memory