Diffraction Module - freud 3.0.0 documentation (2024)

Overview

Details

The freud.diffraction module provides functions for computing thediffraction pattern of particles in systems with long range order.

Stability

freud.diffraction is unstable. When upgrading from version 2.x to2.y (y > x), existing freud scripts may need to be updated. The API will befinalized in a future release.

class freud.diffraction.DiffractionPattern(grid_size=512, output_size=None)#

Bases: _Compute

Computes a 2D diffraction pattern.

The diffraction image represents the scattering of incident radiation,and is useful for identifying translational and/or rotational symmetrypresent in the system. This class computes the static structure factor \(S(\vec{k})\) fora plane of wavevectors \(\vec{k}\) orthogonal to a view axis. Theview orientation \((1, 0, 0, 0)\) defaults to looking down the\(z\) axis (at the \(xy\) plane). The points in the system areconverted to fractional coordinates, then binned into a grid whoseresolution is given by grid_size. A higher grid_size will lead toa higher resolution. The points are convolved with a Gaussian of width\(\sigma\), given by peak_width. This convolution is performedas a multiplication in Fourier space. The computed diffraction patterncan 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 valueof \(S(\vec{k}=0) = N\), per common convention. Theremaining \(\vec{k}\) vectors are computed such that each peak in thediffraction pattern satisfies the relationship \(\vec{k} \cdot\vec{R} = 2 \pi N\) for some integer \(N\) and lattice vector ofthe system \(\vec{R}\). See the reciprocal lattice Wikipedia page for more information.

This method is based on the implementations in the open-sourceGIXStapose application and itspredecessor, diffractometer [JJ17].

Note

freud only supports diffraction patterns for cubic boxes.

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 ifnot provided or None (Default value = None).

property N_points#

Number of points used in the last computation.

Type:

int

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 tofreud.locality.NeighborQuery.from_system.

• view_orientation ((\(4\)) numpy.ndarray, optional) – View orientation. Uses \((1, 0, 0, 0)\) if not providedor None (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 addingthe new computations; if False, will accumulate data (Defaultvalue = True).

property diffraction#

(output_size, output_size) numpy.ndarray:Diffraction pattern.

grid_size#

Resolution of the diffraction grid.

Type:

int

property k_values#

k-values.

Type:

(output_size,) numpy.ndarray

property k_vectors#

k-vectors.

Type:

(output_size, output_size, 3) numpy.ndarray

output_size#

Resolution of the output diffraction image.

Type:

int

plot(self, ax=None, cmap='afmhot', vmin=None, vmax=None)#

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) – Minimum of the color scale. Uses 4e-6 * N_points ifnot provided or None (Default value = None).

  See Also

  Reading Simulation Data for freudBond Module — freud 0.9.0 documentationAbout this Collection | Sigmund Freud Papers | Digital Collections | Library of Congress

• vmax (float) – Maximum of the color scale. Uses 0.7 * N_points ifnot provided or None (Default value = None).

Returns:

Axis with the plot.

Return type:

(matplotlib.axes.Axes)

to_image(self, cmap='afmhot', vmin=None, vmax=None)#

Generates image of diffraction pattern.

Parameters:

• cmap (str, optional) – Colormap name to use (Default value = 'afmhot').

• vmin (float) – Minimum of the color scale. Uses 4e-6 * N_points ifnot provided or None (Default value = None).

• vmax (float) – Maximum of the color scale. Uses 0.7 * N_points ifnot provided or None (Default value = None).

Returns:

RGBA array of pixels.

Return type:

((output_size, output_size, 4) numpy.ndarray)

class freud.diffraction.StaticStructureFactorDebye#

Bases: _StaticStructureFactor

Computes a 1D static structure factor using theDebye scattering equation.

This computes the static structure factor \(S(k)\) at given\(k\) values by averaging over all \(\vec{k}\) vectors of the samemagnitude. 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 factorcalculation 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 isdefined as \(\sin x / x\) (no factor of \(\pi\) as in someconventions). For more information see this Wikipedia article. For a full derivationsee [FB09]. Note that the definition requires \(S(0) = N\).

Note

For 2D systems freud uses the Bessel function \(J_0\) instead of the\(\text{sinc}\) function in the equation above. See[Wie12] for more information. For users wishing to calculatethe structure factor of quasi 2D systems (i.e. a 2D simulation is usedto model a real system such as particles on a 2D interface or similar)the 3D formula should be used. In these cases users should use a 3D boxwith its longest dimension being in the z-direction and particlepositions of the form \((x, y, 0)\).

This implementation uses an evenly spaced number of \(k\) points betweenk_min` and k_max. If k_min is set to 0 (the default behavior), thecomputed structure factor will show \(S(0) = N\).

The Debye implementation provides a much faster algorithm, but gives worseresults than freud.diffraction.StaticStructureFactorDirectat 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 ofquery_points and the total number of points in the system N_total tothe compute() method. The normalization criterion is based on theFaber-Ziman formalism. For particle types \(\alpha\) and \(\beta\),we compute the total scattering function as a sum of the partial scatteringfunctions as:

\[S(k) - 1 = \sum_{\alpha}\sum_{\beta} \frac{N_{\alpha}N_{\beta}}{N_{total}^2} \left(S_{\alpha \beta}(k) - 1\right)\]

Parameters:

• num_k_values (unsigned int) – Number of values to use 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 thereare practical restrictions on the validity of the calculation in thelong wavelength regime, see min_valid_k (Default value =0).

property S_k#

Staticstructure factor \(S(k)\) values.

Type:

(\(N_{bins}\),) numpy.ndarray

bounds#

A tuple indicating the smallest and largest \(k\) valuesused.

Type:

tuple

compute(self, system, query_points=None, N_total=None, reset=True)#

Computes static structure factor.

Example for a single component system:

>>> box, points = freud.data.make_random_system(10, 100, seed=0)>>> sf = freud.diffraction.StaticStructureFactorDebye(...  num_k_values=100, k_max=10, k_min=0... )>>> sf.compute((box, points))freud.diffraction.StaticStructureFactorDebye(...)

Example for partial mixed structure factor for a multiple componentsystem with types A and B:

>>> N_particles = 100>>> box, points = freud.data.make_random_system(...  10, N_particles, seed=0... )>>> A_points = points[:N_particles//2]>>> B_points = points[N_particles//2:]>>> sf = freud.diffraction.StaticStructureFactorDebye(...  num_k_values=100, k_max=10, k_min=0... )>>> sf.compute(...  system=(box, A_points),...  query_points=B_points,...  N_total=N_particles... )freud.diffraction.StaticStructureFactorDebye(...)

Parameters:

• system – Any object that is a valid argument tofreud.locality.NeighborQuery.from_system.Note that box is allowed to change when accumulatingaverage 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 if None. See classdocumentation for information about the normalization of partialstructure factors. If None, the full scattering iscomputed. (Default value = None).

• N_total (int, optional) – Total number of points in the system. This is required ifquery_points are provided. See class documentation forinformation about the normalization of partial structurefactors.

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

k_max#

Maximum value of k at which to calculate the structurefactor.

Type:

float

k_min#

Minimum value of k at which to calculate the structurefactor.

Type:

float

k_values#

The \(k\) values for the calculation.

Type:

numpy.ndarray

property min_valid_k#

Minimum valid value of k for the computed system box, equalto \(2\pi/(L/2)=4\pi/L\) where \(L\) is the minimum side length.For more information see [LP16].

Type:

float

num_k_values#

The number of k values used.

Type:

int

plot(self, ax=None, **kwargs)#

Plot static structure factor.

Note

This function plots \(S(k)\) for values abovemin_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:

(matplotlib.axes.Axes)

class freud.diffraction.StaticStructureFactorDirect#

Bases: _StaticStructureFactor

Computes a 1D static structure factor by operating on a\(k\) space grid.

This computes the static structure factor \(S(k)\) at given\(k\) values by averaging over all \(\vec{k}\) vectors directions ofthe same magnitude. Note that freud employs the physics convention in which\(k\) is used, as opposed to the crystallographic one where \(q\) isused. The relation is \(k=2 \pi q\). This is implemented using thefollowing formula:

\[S(\vec{k}) = \frac{1}{N} \sum_{i=0}^{N} \sum_{j=0}^N e^{i\vec{k} \cdot\vec{r}_{ij}}\]

where \(N\) is the number of particles. Note that the definitionrequires \(S(0) = N\).

This implementation provides a much slower algorithm, but gives betterresults than the freud.diffraction.StaticStructureFactorDebyemethod at low k values.

The \(\vec{k}\) vectors are sampled isotropically from a grid defined bythe box’s reciprocal lattice vectors. This sampling of reciprocal space isbased on the MIT licensed Dynasor library, modified to useparallelized C++ and to support larger ranges of \(k\) values.For more information see [FSEW21].

Note

Currently 2D boxes are not supported for this method. Use Debye instead.

Note

This code assumes all particles have a form factor \(f\) of 1.

Partial structure factors can be computed by providing query_points andtotal number of points in the system N_total to the compute()method. The normalization criterion is based on the Faber-Ziman formalism.For particle types \(\alpha\) and \(\beta\), we compute the totalscattering 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 thatthere are practical restrictions on the validity of thecalculation in the long wavelength regime, see min_valid_k(Default value = 0).

• num_sampled_k_points (unsigned int, optional) – The desired number of \(\vec{k}\) vectors to sample from thereciprocal lattice grid. If set to 0, all \(\vec{k}\) vectorsare used. If greater than 0, the \(\vec{k}\) vectors are sampledfrom the full grid with uniform radial density, resulting in asample of num_sampled_k_points vectors on average (Defaultvalue = 0).

property S_k#

Staticstructure factor \(S(k)\) values.

Type:

(\(N_{bins}\),) numpy.ndarray

bin_centers#

The centers of each bin of \(k\).

Type:

numpy.ndarray

bin_edges#

The edges of each bin of \(k\).

Type:

numpy.ndarray

bounds#

A tuple indicating upper and lower bounds of thehistogram.

Type:

tuple

compute(self, system, query_points=None, N_total=None, reset=True)#

Computes static structure factor.

Example for a single component system:

>>> box, points = freud.data.make_random_system(10, 100, seed=0)>>> sf = freud.diffraction.StaticStructureFactorDirect(...  bins=100, k_max=10, k_min=0... )>>> sf.compute((box, points))freud.diffraction.StaticStructureFactorDirect(...)

Example for partial mixed structure factor for multiple componentsystem with types A and B:

>>> N_particles = 100>>> box, points = freud.data.make_random_system(...  10, N_particles, seed=0... )>>> A_points = points[:N_particles//2]>>> B_points = points[N_particles//2:]>>> sf = freud.diffraction.StaticStructureFactorDirect(...  bins=100, k_max=10, k_min=0... )>>> sf.compute(...  (box, A_points),...  query_points=B_points,...  N_total=N_particles... )freud.diffraction.StaticStructureFactorDirect(...)

Parameters:

• system – Any object that is a valid argument tofreud.locality.NeighborQuery.from_system. Note that box isallowed to change when accumulating average static structure factor.For non-orthorhombic boxes the points are wrapped into a orthorhombicbox.

• query_points ((\(N_{query\_points}\), 3) numpy.ndarray, optional) – Query points used to calculate the partial structure factor.Uses the system’s points if None. See classdocumentation for information about the normalization of partialstructure factors. If None, the full scattering iscomputed. (Default value = None).

• N_total (int, optional) – Total number of points in the system. This is required ifquery_points are provided. See class documentation forinformation about the normalization of partial structurefactors.

• reset (bool, optional) – Whether to erase the previously computed values before addingthe new computation; if False, will accumulate data (Defaultvalue = True).

k_max#

Maximum value of k at which to calculate the structurefactor.

Type:

float

k_min#

Minimum value of k at which to calculate the structurefactor.

Type:

float

property k_points#

The \(\vec{k}\) points used in thecalculation.

Type:

numpy.ndarray

property min_valid_k#

Minimum valid value of k for the computed system box, equalto \(2\pi/L\) where \(L\) is the minimum side length.For more information see [LP16].

Type:

float

nbins#

Number of bins in the histogram.

Type:

float

num_sampled_k_points#

The target number of \(\vec{k}\) points to use whenconstructing \(k\) space grid.

Type:

int

plot(self, ax=None, **kwargs)#

Plot static structure factor.

Note

This function plots \(S(k)\) for values abovemin_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:

(matplotlib.axes.Axes)