KSpace Module¶
Modules for calculating quantities in reciprocal space, including Fourier transforms of shapes and diffraction pattern generation.
Meshgrid¶
-
freud.kspace.
meshgrid2
(*arrs)[source]¶ Computes an n-dimensional meshgrid.
source: http://stackoverflow.com/questions/1827489/numpy-meshgrid-in-3d
Parameters: arrs – Arrays to meshgrid Returns: tuple of arrays Return type: tuple
Structure Factor¶
Methods for calculating the structure factor of different systems.
-
class
freud.kspace.
SFactor3DPoints
(box, g)[source]¶ Compute the full 3D structure factor of a given set of points.
Given a set of points \(\vec{r}_i\), SFactor3DPoints computes the static structure factor \(S \left( \vec{q} \right) = C_0 \left| {\sum_{m=1}^{N} \exp{\mathit{i}\vec{q}\cdot\vec{r_i}}} \right|^2\).
In this expression, \(C_0\) is a scaling constant chosen so that \(S\left(0\right) = 1\), and \(N\) is the number of particles.
\(S\) is evaluated on a grid of \(q\)-values \(\vec{q} = h \frac{2\pi}{L_x} \hat{i} + k \frac{2\pi}{L_y} \hat{j} + l \frac{2\pi}{L_z} \hat{k}\) for integer \(h,k,l: \left[-g,g\right]\) and \(L_x, L_y, L_z\) are the box lengths in each direction.
After calling
compute()
, access the \(q\) values withgetQ()
, the static structure factor values withgetS()
, and (if needed) the un-squared complex version of \(S\) withgetSComplex()
. All values are stored in 3Dnumpy.ndarray
structures. They are indexed by \(a, b, c\) where \(a=h+g, b=k+g, c=l+g\).Note
Due to the way that numpy arrays are indexed, access the returned S array as
S[c,b,a]
to get the value at \(q = \left(qx\left[a\right], qy\left[b\right], qz\left[c\right]\right)\).-
compute
(points)[source]¶ Compute the static structure factor of a given set of points.
After calling
compute()
, you can access the results withgetS()
,getSComplex()
, and the grid withgetQ()
.Parameters: points ( numpy.ndarray
, shape=(\(N_{particles}\), 3), dtype=numpy.float32
) – points used to compute the static structure factor
-
getQ
()[source]¶ Get the \(q\) values at each point.
The structure factor
S[c,b,a]
is evaluated at the vector \(q = \left(qx\left[a\right], qy\left[b\right], qz\left[c\right]\right)\).Returns: (qx, qy, qz) Return type: tuple
-
getS
()[source]¶ Get the computed static structure factor.
Returns: The computed static structure factor as a copy Return type: numpy.ndarray
, shape=(X,Y), dtype=numpy.float32
-
getSComplex
()[source]¶ Get the computed complex structure factor (if you need the phase information).
Returns: The computed static structure factor, as a copy, without taking the magnitude squared Return type: numpy.ndarray
, shape=(X,Y), dtype=numpy.complex64
-
-
class
freud.kspace.
AnalyzeSFactor3D
(S)[source]¶ Analyze the peaks in a 3D structure factor.
Given a structure factor \(S\left(q\right)\) computed by classes such as
SFactor3DPoints
,AnalyzeSFactor3D
performs a variety of analysis tasks.- Identifies peaks
- Provides a list of peaks and the vector \(\vec{q}\) positions at which they occur
- Provides a list of peaks grouped by \(q^2\)
- Provides a full list of \(S\left(\left|q\right|\right)\) values vs \(q^2\) suitable for plotting the 1D analog of the structure factor
- Scans through the full 3D peaks and reconstructs the Bravais lattice
Note
All of these operations work in an indexed integer \(q\)-space \(h,k,l\). Any peak position values returned must be multiplied by \(2\pi/L\) to get to real \(q\) values in simulation units.
-
getPeakDegeneracy
(cut)[source]¶ Get a dictionary of peaks indexed by \(q^2\).
Parameters: cut ( numpy.ndarray
) – All \(S\left(q\right)\) values greater than cut will be counted as peaksReturns: a dictionary with keys \(q^2\) and a list of peaks for the corresponding values Return type: dict
-
getPeakList
(cut)[source]¶ Get a list of peaks in the structure factor.
Parameters: cut – All \(S\left(q\right)\) values greater than cut will be counted as peaks Returns: peaks, \(q\) as lists Return type: list
-
getSvsQ
()[source]¶ Get a list of all \(S\left(\left|q\right|\right)\) values vs \(q^2\).
Returns: S, qsquared Return type: numpy.ndarray
-
class
freud.kspace.
SingleCell3D
(k, ndiv, dK, boxMatrix)[source]¶ SingleCell3D objects manage data structures necessary to call the Fourier Transform functions that evaluate FTs for given form factors at a list of \(K\) points. SingleCell3D provides an interface to helper functions to calculate \(K\) points for a desired grid from the reciprocal lattice vectors calculated from an input boxMatrix. State is maintained as set_ and update_ functions invalidate internal data structures and as fresh data is restored with update_ function calls. This should facilitate management with a higher-level UI such as a GUI with an event queue.
I’m not sure what sort of error checking would be most useful, so I’m mostly allowing ValueErrors and such exceptions to just occur and then propagate up through the calling functions to be dealt with by the user.
-
add_ptype
(name)[source]¶ Create internal data structures for new particle type by name.
Particle type is inactive when added because parameters must be set before FT can be performed.
Parameters: name (str) – particle name
-
calculate
(*args, **kwargs)[source]¶ Calculate FT. The details and arguments will vary depending on the form factor chosen for the particles.
For any particle type-dependent parameters passed as keyword arguments, the parameter must be passed as a list of length
max(p_type)+1
with indices corresponding to the particle types defined. In other words, type-dependent parameters are optional (depending on the set of form factors being calculated), but if included must be defined for all particle types.Parameters: - position (
numpy.ndarray
, shape=(\(N_{particles}\), 3), dtype=numpy.float32
) – array of particle positions in nm - orientation (
numpy.ndarray
, shape=(\(N_{particles}\), 4), dtype=numpy.float32
) – array of orientation quaternions - kwargs – additional keyword arguments passed on to form-factor-specific FT calculator
- position (
-
get_form_factors
()[source]¶ Get form factor names and indices.
Returns: list of factor names and indices Return type: list
-
get_ptypes
()[source]¶ Get ordered list of particle names.
Returns: list of particle names Return type: list
-
remove_ptype
(name)[source]¶ Remove internal data structures associated with ptype
name
.Parameters: name (str) – particle name Note
This shouldn’t usually be necessary, since particle types may be set inactive or have any of their properties updated through set_ methods.
-
set_box
(boxMatrix)[source]¶ Set box matrix.
Parameters: boxMatrix ( numpy.ndarray
, shape=(3, 3), dtype=numpy.float32
) – unit cell box matrix
-
set_dK
(dK)[source]¶ Set grid spacing in diffraction image.
Parameters: dK (float) – difference in \(K\) vector between two adjacent diffraction image grid points
-
set_form_factor
(name, ff)[source]¶ Set scattering form factor.
Parameters: - name (str) – particle type name
- ff (
list
) – scattering form factor named inget_form_factors()
-
set_k
(k)[source]¶ Set angular wave number of plane wave probe.
Parameters: k (float) – \(\left|k_0\right|\)
-
set_ndiv
(ndiv)[source]¶ Set number of grid divisions in diffraction image.
Parameters: ndiv (int) – define diffraction image as ndiv x ndiv grid
-
set_rq
(name, position, orientation)[source]¶ Set positions and orientations for a particle type.
To best maintain valid state in the event of changing numbers of particles, position and orientation are updated in a single method.
Parameters: - name (str) – particle type name
- position (
numpy.ndarray
, shape=(\(N_{particles}\), 3), dtype=numpy.float32
) – (N,3) array of particle positions - orientation (
numpy.ndarray
, shape=(\(N_{particles}\), 4), dtype=numpy.float32
) – (N,4) array of particle quaternions
-
set_scale
(scale)[source]¶ Set scale factor. Store global value and set for each particle type.
Parameters: scale (float) – nm per unit for input file coordinates
-
update_K_constraint
()[source]¶ Recalculate constraint used to select \(K\) values.
The constraint used is a slab of epsilon thickness in a plane perpendicular to the \(k_0\) propagation, intended to provide easy emulation of TEM or relatively high-energy scattering.
-
-
class
freud.kspace.
FTfactory
[source]¶ Factory to return an FT object of the requested type.
-
getFTlist
()[source]¶ Get an ordered list of named FT types.
Returns: list of FT names Return type: list
-
getFTobject
(i, args=None)[source]¶ Get a new instance of an FT type from list returned by
getFTlist()
.Parameters: - i (int) – index into list returned by
getFTlist()
- args (
list
) – argument object used to initialize FT, overriding default set ataddFT()
- i (int) – index into list returned by
-
-
class
freud.kspace.
FTbase
[source]¶ Base class for FT calculation classes.
-
getFT
()[source]¶ Return Fourier Transform.
Returns: Fourier Transform Return type: numpy.ndarray
-
get_parambyname
(name)[source]¶ Get named parameter for object.
Parameters: name (str) – parameter name. Must exist in list returned by get_params()
Returns: parameter value Return type: float
-
get_params
()[source]¶ Get the parameter names accessible with
set_parambyname()
.Returns: parameter names Return type: list
-
set_K
(K)[source]¶ Set \(K\) points to be evaluated.
Parameters: K ( numpy.ndarray
) – list of \(K\) vectors at which to evaluate FT
-
set_parambyname
(name, value)[source]¶ Set named parameter for object.
Parameters: - name (str) – parameter name. Must exist in list returned by
get_params()
- value (float) – parameter value to set
- name (str) – parameter name. Must exist in list returned by
-
set_rq
(r, q)[source]¶ Set \(r\), \(q\) values.
Parameters: - r (
numpy.ndarray
) – \(r\) - q (
numpy.ndarray
) – \(q\)
- r (
-
-
class
freud.kspace.
FTdelta
[source]¶ Fourier transform a list of delta functions.
-
compute
(*args, **kwargs)[source]¶ Compute FT.
Calculate \(S = \sum_{\alpha} \exp^{-i \mathbf{K} \cdot \mathbf{r}_{\alpha}}\)
-
set_K
(K)[source]¶ Set \(K\) points to be evaluated.
Parameters: K ( numpy.ndarray
) – list of \(K\) vectors at which to evaluate FT
-
set_rq
(r, q)[source]¶ Set \(r\), \(q\) values.
Parameters: - r (
numpy.ndarray
) – \(r\) - q (
numpy.ndarray
) – \(q\)
- r (
-
-
class
freud.kspace.
FTsphere
[source]¶ Fourier transform for sphere.
Calculate \(S = \sum_{\alpha} \exp^{-i \mathbf{K} \cdot \mathbf{r}_{\alpha}}\)
-
class
freud.kspace.
FTpolyhedron
[source]¶ Fourier Transform for polyhedra.
-
compute
(*args, **kwargs)[source]¶ Compute FT.
Calculate \(S = \sum_{\alpha} \exp^{-i \mathbf{K} \cdot \mathbf{r}_{\alpha}}\)
-
get_radius
()[source]¶ Get radius parameter.
If appropriate, return value should be scaled by
get_parambyname('scale')
for interpretation.Returns: unscaled radius Return type: float
-
set_K
(K)[source]¶ Set \(K\) points to be evaluated.
Parameters: K ( numpy.ndarray
) – list of \(K\) vectors at which to evaluate FT
-
set_params
(verts, facets, norms, d, areas, volume)[source]¶ Construct list of facet offsets.
Parameters: - verts (
numpy.ndarray
, shape=(\(N_{verts}\), 3), dtype=numpy.float32
) – list of vertices - facets (
numpy.ndarray
, shape=(\(N_{facets}\), \(N_{verts}\)), dtype=numpy.float32
) – list of facets - norms (
numpy.ndarray
, shape=(\(N_{facets}\), 3), dtype=numpy.float32
) – list of norms - d (
numpy.ndarray
, shape=(\(N_{facets}\)), dtype=numpy.float32
) – list of d values - areas (
numpy.ndarray
, shape=(\(N_{facets}\)), dtype=numpy.float32
) – list of areas - volumes (
numpy.ndarray
) – list of volumes
- verts (
-
set_radius
(radius)[source]¶ Set radius of in-sphere.
Parameters: radius (float) – radius inscribed sphere radius without scale applied
-
set_rq
(r, q)[source]¶ Set \(r\), \(q\) values.
Parameters: - r (
numpy.ndarray
) – \(r\) - q (
numpy.ndarray
) – \(q\)
- r (
-
-
class
freud.kspace.
FTconvexPolyhedron
[source]¶ Fourier Transform for convex polyhedra.
-
Spoly3D
(k)[source]¶ Calculate Fourier transform of polyhedron.
Parameters: k (int) – angular wave vector at which to calculate \(S\left(i\right)\)
-
compute_py
(*args, **kwargs)[source]¶ Compute FT.
Calculate \(P = F * S\):
- \(S = \sum_{\alpha} \exp^{-i \mathbf{K} \cdot \mathbf{r}_{\alpha}}\)
- F is the analytical form factor for a polyhedron,
computed with
Spoly3D()
-
Diffraction Patterns¶
Methods for calculating diffraction patterns of various systems.
-
class
freud.kspace.
DeltaSpot
[source]¶ Base class for drawing diffraction spots on a 2D grid.
Based on the dimensions of a grid, determines which grid points need to be modified to represent a diffraction spot and generates the values in that subgrid. Spot is a single pixel at the closest grid point.
-
get_gridPoints
()[source]¶ Get indices of sub-grid.
Based on the type of spot and its center, return the grid mask of points containing the spot
-
-
class
freud.kspace.
GaussianSpot
[source]¶ Draw diffraction spot as a Gaussian blur.
Grid points filled according to Gaussian at spot center.
Utilities¶
Classes and methods used by other kspace modules.
-
class
freud.kspace.
Constraint
[source]¶ Constraint base class.
Base class for constraints on vectors to define the API. All constraints should have a ‘radius’ defining a bounding sphere and a ‘satisfies’ method to determine whether an input vector satisfies the constraint.
-
satisfies
(v)[source]¶ Constraint test.
Parameters: v ( numpy.ndarray
, shape=(3), dtype=numpy.float32
) – vector to test against constraint
-
-
class
freud.kspace.
AlignedBoxConstraint
[source]¶ Axis-aligned Box constraint.
Tetragonal box aligned with the coordinate system. Consider using a small z dimension to serve as a plane plus or minus some epsilon. Set R < L for a cylinder
-
satisfies
(v)[source]¶ Constraint test.
Parameters: v ( numpy.ndarray
, shape=(3), dtype=numpy.float32
) – vector to test against constraint
-
-
freud.kspace.
constrainedLatticePoints
()[source]¶ Generate a list of points satisfying a constraint.
Parameters: - v1 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – lattice vector 1 along which to test points - v2 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – lattice vector 2 along which to test points - v3 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – lattice vector 3 along which to test points - constraint (
Constraint
) – constraint object to test lattice points against
- v1 (
-
freud.kspace.
reciprocalLattice3D
()[source]¶ Calculate reciprocal lattice vectors.
3D reciprocal lattice vectors with magnitude equal to angular wave number.
Parameters: - a1 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – real space lattice vector 1 - a2 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – real space lattice vector 2 - a3 (
numpy.ndarray
, shape=(3), dtype=numpy.float32
) – real space lattice vector 3
Returns: list of reciprocal lattice vectors
Return type: Note
For unit test,
dot(g[i], a[j]) = 2 * pi * diracDelta(i, j)
- a1 (