Density Module¶

Overview

`freud.density.FloatCF`	Computes the pairwise correlation function \(\left< p*q \right> \left( r \right)\) between two sets of points with associated values \(p\) and \(q\).
`freud.density.ComplexCF`	Computes the pairwise correlation function \(\left< p*q \right> \left( r \right)\) between two sets of points with associated values \(p\) and \(q\).
`freud.density.GaussianDensity`	Computes the density of a system on a grid.
`freud.density.LocalDensity`	Computes the local density around a particle.
`freud.density.RDF`	Computes RDF for supplied data.

Details

The density module contains various classes relating to the density of the system. These functions allow evaluation of particle distributions with respect to other particles.

Correlation Functions¶

class freud.density.FloatCF(rmax, dr)¶

Computes the pairwise correlation function \(\left< p*q \right> \left( r \right)\) between two sets of points with associated values \(p\) and \(q\).

Two sets of points and two sets of real values associated with those points are given. Computing the correlation function results in an array of the expected (average) product of all values at a given radial distance.

The values of \(r\) where the correlation function is computed are controlled by the rmax and dr parameters to the constructor. rmax determines the maximum distance at which to compute the correlation function and dr is the step size for each bin.

Note

2D: freud.density.FloatCF properly handles 2D boxes. The points must be passed in as [x, y, 0]. Failing to set z=0 will lead to undefined behavior.

Self-correlation: It is often the case that we wish to compute the correlation function of a set of points with itself. If given the same arrays for both points and ref_points, we omit accumulating the self-correlation value in the first bin.

Module author: Matthew Spellings <mspells@umich.edu>

Parameters:	rmax (float) – Distance over which to calculate. dr (float) – Bin size.
Variables:	RDF ((\(N_{bins}\)) `numpy.ndarray`) – Expected (average) product of all values at a given radial distance. box (`freud.box.Box`) – Box used in the calculation. counts ((\(N_{bins}\)) `numpy.ndarray`) – The counts of each histogram bin. R ((\(N_{bins}\)) `numpy.ndarray`) – The values of bin centers.

accumulate(self, box, ref_points, refValues, points, values, nlist=None)¶

Calculates the correlation function and adds to the current histogram.

Parameters:

box (freud.box.Box) – Simulation box.
ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points to calculate the local density.
refValues ((\(N_{particles}\)) numpy.ndarray) – Values to use in computation.
points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the bonding.
values ((\(N_{particles}\)) – Values to use in computation.
nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).

compute(self, box, ref_points, refValues, points, values, nlist=None)¶

Calculates the 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 to calculate the local density.
refValues ((\(N_{particles}\)) numpy.ndarray) – Values to use in computation.
points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the local density.
values ((\(N_{particles}\)) – Values to use in computation.
nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).

getBox(self)¶

Get the box used in the calculation.

Returns:	freud Box.
Return type:	`freud.box.Box`

getCounts(self)¶

Get counts of each histogram bin.

Returns:	Counts of each histogram bin.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

getR(self)¶

Get bin centers.

Returns:	Values of bin centers.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

getRDF(self)¶

Returns the radial distribution function.

Returns:	Expected (average) product of all values at a given radial distance.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

reduceCorrelationFunction(self)¶: Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.density.FloatCF.getRDF(), freud.density.FloatCF.getCounts().

resetCorrelationFunction(self)¶: Resets the values of the correlation function histogram in memory.

class freud.density.ComplexCF(rmax, dr)¶

Computes the pairwise correlation function \(\left< p*q \right> \left( r \right)\) between two sets of points with associated values \(p\) and \(q\).

Two sets of points and two sets of complex values associated with those points are given. Computing the correlation function results in an array of the expected (average) product of all values at a given radial distance.

The values of \(r\) where the correlation function is computed are controlled by the rmax and dr parameters to the constructor. rmax determines the maximum distance at which to compute the correlation function and dr is the step size for each bin.

Note

2D: freud.density.ComplexCF properly handles 2D boxes. The points must be passed in as [x, y, 0]. Failing to set z=0 will lead to undefined behavior.

Self-correlation: It is often the case that we wish to compute the correlation function of a set of points with itself. If given the same arrays for both points and ref_points, we omit accumulating the self-correlation value in the first bin.

Module author: Matthew Spellings <mspells@umich.edu>

Parameters:	rmax (float) – Distance over which to calculate. dr (float) – Bin size.
Variables:	RDF ((\(N_{bins}\)) `numpy.ndarray`) – Expected (average) product of all values at a given radial distance. box (`freud.box.Box`) – Box used in the calculation. counts ((\(N_{bins}\)) `numpy.ndarray`) – The counts of each histogram bin. R ((\(N_{bins}\)) `numpy.ndarray`) – The values of bin centers.

accumulate(self, box, ref_points, refValues, points, values, nlist=None)¶

Calculates the correlation function and adds to the current histogram.

Parameters:

box (freud.box.Box) – Simulation box.
ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points to calculate the local density.
refValues ((\(N_{particles}\)) numpy.ndarray) – Values to use in computation.
points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the bonding.
values ((\(N_{particles}\)) – Values to use in computation.
nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None).

compute(self, box, ref_points, refValues, points, values, nlist=None)¶

Calculates the 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 to calculate the local density.
refValues ((\(N_{particles}\)) numpy.ndarray) – Values to use in computation.
points ((\(N_{particles}\), 3) numpy.ndarray) – Points to calculate the bonding.
values ((\(N_{particles}\)) – Values to use in computation.
nlist (freud.locality.NeighborList, optional) – NeighborList to use to find bonds (Default value = None)

getBox(self)¶

Get the box used in the calculations.

Returns:	freud Box.
Return type:	`freud.box.Box`

getCounts(self)¶

Get the counts of each histogram bin.

Returns:	Counts of each histogram bin.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

getR(self)¶

Get The value of bin centers.

Returns:	Values of bin centers.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

getRDF(self)¶

Get the RDF.

Returns:	Expected (average) product of all values at a given radial distance.
Return type:	(\(N_{bins}\)) `numpy.ndarray`

reduceCorrelationFunction(self)¶: Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.density.ComplexCF.getRDF(), freud.density.ComplexCF.getCounts().

resetCorrelationFunction(self)¶: Resets the values of the correlation function histogram in memory.

Gaussian Density¶

class freud.density.GaussianDensity(*args)¶

Computes the density of a system on a grid.

Replaces particle positions with a Gaussian blur and calculates the contribution from the grid based upon the distance of the grid cell from the center of the Gaussian. The dimensions of the image (grid) are set in the constructor, and can either be set equally for all dimensions or for each dimension independently.

Constructor Calls:

Initialize with all dimensions identical:
freud.density.GaussianDensity(width, r_cut, dr)
Initialize with each dimension specified:
freud.density.GaussianDensity(width_x, width_y, width_z, r_cut, dr)

Module author: Joshua Anderson <joaander@umich.edu>

Parameters:

width (unsigned int) – Number of pixels to make the image.
width_x (unsigned int) – Number of pixels to make the image in x.
width_y (unsigned int) – Number of pixels to make the image in y.
width_z (unsigned int) – Number of pixels to make the image in z.
r_cut (float) – Distance over which to blur.
sigma (float) – Sigma parameter for Gaussian.

Variables:

box (freud.box.Box) – Box used in the calculation.
gaussian_density ((\(w_x\), \(w_y\), \(w_z\)) numpy.ndarray) – The image grid with the Gaussian density.
counts ((\(N_{bins}\)) numpy.ndarray) – The counts of each histogram bin.
R ((\(N_{bins}\)) numpy.ndarray) – The values of bin centers.

compute(self, box, points)¶

Calculates the Gaussian blur for the specified points. Does not accumulate (will overwrite current image).

Parameters:	box (`freud.box.Box`) – Simulation box. points ((\(N_{particles}\), 3) `numpy.ndarray`) – Points to calculate the local density.

getBox(self)¶

Get the box used in the calculation.

Returns:	freud Box.
Return type:	`freud.box.Box`

getGaussianDensity(self)¶

Get the image grid with the Gaussian density.

Returns:	Image (grid) with values of Gaussian.
Return type:	(\(w_x\), \(w_y\), \(w_z\)) `numpy.ndarray`

resetDensity(self)¶: Resets the values of GaussianDensity in memory.

Local Density¶

class freud.density.LocalDensity(r_cut, volume, diameter)¶

Computes the local density around a particle.

The density of the local environment is computed and averaged for a given set of reference points in a sea of data points. Providing the same points calculates them against themselves. Computing the local density results in an array listing the value of the local density around each reference point. Also available is the number of neighbors for each reference point, giving the user the ability to count the number of particles in that region.

The values to compute the local density are set in the constructor. r_cut sets the maximum distance at which to calculate the local density. volume is the volume of a single particle. diameter is the diameter of the circumsphere of an individual particle.

Note

2D: freud.density.LocalDensity properly handles 2D boxes. The points must be passed in as [x, y, 0]. Failing to set z=0 will lead to undefined behavior.

Module author: Joshua Anderson <joaander@umich.edu>

Parameters:	r_cut (float) – Maximum distance over which to calculate the density. volume (float) – Volume of a single particle. diameter (float) – Diameter of particle circumsphere.
Variables:	box (`freud.box.Box`) – Box used in the calculation. density ((\(N_{particles}\)) `numpy.ndarray`) – Density per particle. num_neighbors ((\(N_{particles}\)) `numpy.ndarray`) – Number of neighbors for each particle..

compute(self, box, ref_points, points=None, nlist=None)¶

Calculates the local density for the specified points. Does not accumulate (will overwrite current data).

Parameters:	box (`freud.box.Box`) – Simulation box. ref_points ((\(N_{particles}\), 3) `numpy.ndarray`) – Reference points to calculate the local density. points ((\(N_{particles}\), 3) `numpy.ndarray`) – Points to calculate the local density. nlist (`freud.locality.NeighborList`, optional) – NeighborList to use to find bonds (Default value = None).

getBox(self)¶

Get the box used in the calculation.

Returns:	freud Box.
Return type:	`freud.box.Box`

getDensity(self)¶

Get the density array for each particle.

Returns:	Density array for each particle.
Return type:	(\(N_{particles}\)) `numpy.ndarray`

getNumNeighbors(self)¶

Return the number of neighbors for each particle.

Returns:	Number of neighbors for each particle.
Return type:	(\(N_{particles}\)) `numpy.ndarray`

Radial Distribution Function¶

class freud.density.RDF(rmax, dr, rmin=0)¶

Computes RDF for supplied data.

The RDF (\(g \left( r \right)\)) is computed and averaged for a given set of reference points in a sea of data points. Providing the same points calculates them against themselves. Computing the RDF results in an RDF array listing the value of the RDF at each given \(r\), listed in the r array.

The values of \(r\) to compute the RDF are set by the values of rmin, rmax, dr in the constructor. rmax sets the maximum distance at which to calculate the \(g \left( r \right)\), rmin sets the minimum distance at which to calculate the \(g \left( r \right)\), and dr determines the step size for each bin.

Module author: Eric Harper <harperic@umich.edu>

Note

2D: freud.density.RDF properly handles 2D boxes. The points must be passed in as [x, y, 0]. Failing to set z=0 will lead to undefined behavior.

Parameters:	rmax (float) – Maximum distance to calculate. dr (float) – Distance between histogram bins. rmin (float) – Minimum distance to calculate, default 0.
Variables:	box (`freud.box.Box`) – Box used in the calculation. RDF ((\(N_{bins}\)) `numpy.ndarray`) – Histogram of RDF values. R ((\(N_{bins}\), 3) `numpy.ndarray`) – The values of bin centers. n_r ((\(N_{bins}\), 3) `numpy.ndarray`) – Histogram of cumulative RDF values.

Changed in version 0.7.0: Added optional rmin argument.

accumulate(self, box, ref_points, points, nlist=None)¶

Calculates the RDF and adds to the current RDF histogram.

Parameters:	box (`freud.box.Box`) – Simulation box. ref_points ((\(N_{particles}\), 3) `numpy.ndarray`) – Reference points to calculate the local density. points ((\(N_{particles}\), 3) `numpy.ndarray`) – Points to calculate the bonding. nlist (`freud.locality.NeighborList`, optional) – NeighborList to use to find bonds (Default value = None).

compute(self, box, ref_points, points, nlist=None)¶

Calculates the RDF for the specified points. Will overwrite the current histogram.

Parameters:	box (`freud.box.Box`) – Simulation box. ref_points ((\(N_{particles}\), 3) `numpy.ndarray`) – Reference points to calculate the local density. points ((\(N_{particles}\), 3) `numpy.ndarray`) – Points to calculate the bonding. nlist (`freud.locality.NeighborList`) – NeighborList to use to find bonds (Default value = None)

getBox(self)¶

Get the box used in the calculation.

Returns:	freud Box.
Return type:	`freud.box.Box`

getNr(self)¶

Get the histogram of cumulative RDF values.

Returns:	Histogram of cumulative RDF values.
Return type:	(\(N_{bins}\), 3) `numpy.ndarray`

getR(self)¶

Get values of the histogram bin centers.

Returns:	Values of the histogram bin centers.
Return type:	(\(N_{bins}\), 3) `numpy.ndarray`

getRDF(self)¶

Histogram of RDF values.

Returns:	Histogram of RDF values.
Return type:	(\(N_{bins}\), 3) `numpy.ndarray`

reduceRDF(self)¶: Reduces the histogram in the values over N processors to a single histogram. This is called automatically by freud.density.RDF.getRDF(), freud.density.RDF.getNr().

resetRDF(self)¶: Resets the values of RDF in memory.