Diffraction Module
Overview
Computes a 2D diffraction pattern. 

Computes a 1D static structure factor using the Debye scattering equation. 
Details
The freud.diffraction
module provides functions for computing the
diffraction pattern of particles in systems with long range order.
Stability
freud.diffraction
is unstable. When upgrading from version 2.x to
2.y (y > x), existing freud scripts may need to be updated. The API will be
finalized in a future release.
 class freud.diffraction.DiffractionPattern(grid_size=512, output_size=None)
Bases:
freud.util._Compute
Computes a 2D diffraction pattern.
The diffraction image represents the scattering of incident radiation, and is useful for identifying translational and/or rotational symmetry present in the system. This class computes the static structure factor \(S(\vec{k})\) for a plane of wavevectors \(\vec{k}\) orthogonal to a view axis. The view orientation \((1, 0, 0, 0)\) defaults to looking down the \(z\) axis (at the \(xy\) plane). The points in the system are converted to fractional coordinates, then binned into a grid whose resolution is given by
grid_size
. A highergrid_size
will lead to a higher resolution. The points are convolved with a Gaussian of width \(\sigma\), given bypeak_width
. This convolution is performed as a multiplication in Fourier space. The computed diffraction pattern can be accessed as a square array of shape(output_size, output_size)
.The \(\vec{k}=0\) peak is always located at index
(output_size // 2, output_size // 2)
and is normalized to have a value of \(S(\vec{k}=0) = 1\) (not \(N\), a common convention). The remaining \(\vec{k}\) vectors are computed such that each peak in the diffraction pattern satisfies the relationship \(\vec{k} \cdot \vec{R} = 2 \pi N\) for some integer \(N\) and lattice vector of the system \(\vec{R}\). See the reciprocal lattice Wikipedia page for more information.This method is based on the implementations in the opensource GIXStapose application and its predecessor, diffractometer [JJ17].
 Parameters
grid_size (unsigned int) – Resolution of the diffraction grid (Default value = 512).
output_size (unsigned int) – Resolution of the output diffraction image, uses
grid_size
if not provided orNone
(Default value =None
).
 compute(self, system, view_orientation=None, zoom=4, peak_width=1, reset=True)
Computes diffraction pattern.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.view_orientation ((\(4\))
numpy.ndarray
, optional) – View orientation. Uses \((1, 0, 0, 0)\) if not provided orNone
(Default value =None
).zoom (float, optional) – Scaling factor for incident wavevectors (Default value = 4).
peak_width (float, optional) – Width of Gaussian convolved with points, in system length units (Default value = 1).
reset (bool, optional) – Whether to erase the previously computed values before adding the new computations; if False, will accumulate data (Default value = True).
 property diffraction
(
output_size
,output_size
)numpy.ndarray
: Diffraction pattern.
 property k_values
kvalues.
 Type
(
output_size
, )numpy.ndarray
 property k_vectors
(
output_size
,output_size
, 3)numpy.ndarray
: kvectors.
 plot(self, ax=None, cmap='afmhot', vmin=4e6, vmax=0.7)
Plot Diffraction Pattern.
 Parameters
ax (
matplotlib.axes.Axes
, optional) – Axis to plot on. IfNone
, make a new figure and axis. (Default value =None
)cmap (str, optional) – Colormap name to use (Default value =
'afmhot'
).vmin (float, optional) – Minimum of the color scale (Default value = 4e6).
vmax (float, optional) – Maximum of the color scale (Default value = 0.7).
 Returns
Axis with the plot.
 Return type
 to_image(self, cmap='afmhot', vmin=4e6, vmax=0.7)
Generates image of diffraction pattern.
 Parameters
 Returns
RGBA array of pixels.
 Return type
((output_size, output_size, 4)
numpy.ndarray
)
 class freud.diffraction.StaticStructureFactorDebye
Bases:
freud.util._Compute
Computes a 1D static structure factor using the Debye scattering equation.
This computes the static structure factor \(S(k)\) at given \(k\) values by averaging over all \(\vec{k}\) vectors of the same magnitude. Note that freud employs the physics convention in which \(k\) is used, as opposed to the crystallographic one where \(q\) is used. The relation is \(k=2 \pi q\). The static structure factor calculation is implemented using the Debye scattering equation:
\[S(k) = \frac{1}{N} \sum_{i=0}^{N} \sum_{j=0}^{N} \text{sinc}(k r_{ij})\]where \(N\) is the number of particles, \(\text{sinc}\) function is defined as \(\sin x / x\) (no factor of \(\pi\) as in some conventions). For more information see this Wikipedia article. For a full derivation see [FB09]. Note that the definition requires \(S(0) = N\).
The Debye implementation provides a much faster algorithm, but gives worse results than
freud.diffraction.StaticStructureFactorDirect
at low k values.Note
This code assumes all particles have a form factor \(f\) of 1.
Partial structure factors can be computed by providing a set of
query_points
and the total number of points in the systemN_total
to thecompute()
method. The normalization criterion is based on the FaberZiman formalism. For particle types \(\alpha\) and \(\beta\), we compute the total scattering function as a sum of the partial scattering functions as:\[S(k)  1 = \sum_{\alpha}\sum_{\beta} \frac{N_{\alpha} N_{\beta}}{N_{total}^2} \left(S_{\alpha \beta}(k)  1\right)\] Parameters
bins (unsigned int) – Number of bins in \(k\) space.
k_max (float) – Maximum \(k\) value to include in the calculation.
k_min (float, optional) – Minimum \(k\) value included in the calculation. Note that there are practical restrictions on the validity of the calculation in the long wavelength regime, see
min_valid_k
(Default value = 0).
 property S_k
Static structure factor \(S(k)\) values.
 Type
(\(N_{bins}\),)
numpy.ndarray
 bin_centers
The centers of each bin of \(k\).
 Type
 bin_edges
The edges of each bin of \(k\).
 Type
 compute(self, system, query_points=None, N_total=None, reset=True)
Computes static structure factor.
Example for a single component system:
>>> sf = freud.diffraction.StaticStructureFactorDebye( ... bins=100, k_max=10, k_min=0 ... ) >>> sf.compute((box, points))
Example for partial mixed structure factor for a multiple component system with types A and B:
>>> sf = freud.diffraction.StaticStructureFactorDebye( ... bins=100, k_max=10, k_min=0 ... ) >>> sf.compute( ... system=(box, A_points), ... query_points=B_points, ... N_total=N_particles ... )
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
. Note that box is allowed to change when calculating trajectory average static structure factor.query_points ((\(N_{query\_points}\), 3)
numpy.ndarray
, optional) – Query points used to calculate the partial structure factor. Uses the system’s points ifNone
. See class documentation for information about the normalization of partial structure factors. IfNone
, the full scattering is computed. (Default value =None
).N_total (int, optional) – Total number of points in the system. This is required if
query_points
are provided. See class documentation for information about the normalization of partial structure factors.reset (bool, optional) – Whether to erase the previously computed values before adding the new computation; if False, will accumulate data (Default value: True).
 property min_valid_k
Minimum valid value of k for the computed system box, equal to \(2\pi/(L/2)=4\pi/L\) where \(L\) is the minimum side length. For more information see [LP16].
 Type
 plot(self, ax=None, **kwargs)
Plot static structure factor.
Note
This function plots \(S(k)\) for values above
min_valid_k
. Parameters
ax (
matplotlib.axes.Axes
, optional) – Axis to plot on. IfNone
, make a new figure and axis. (Default value =None
) Returns
Axis with the plot.
 Return type