# 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

Parameters: arrs – Arrays to meshgrid tuple of arrays 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$$ where $$C_0$$ is a scaling constant chosen so that $$S\left(0\right) = 1$$, $$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 used q values with getQ(), the static structure factor with getS(), and (if needed) the un-squared complex version of S with getSComplex(). All values are stored in 3D numpy arrays. They are indexed by $$a,b,c$$ where $$a=h+g, b=k+g, c=l+g$$.

Note that 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 with getS(), getSComplex(), and the grid with getQ().

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,c] is evaluated at the vector q = (qx[a], qy[b], qz[c])

Returns: (qx, qy, qz) tuple
getS()[source]

Get the computed static structure factor

Returns: The computed static structure factor as a copy 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 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 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 peaks a dictionary with key $$q^2$$ and each element being a list of peaks 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 peaks, q as lists list
getSvsQ()[source]

Get a list of all $$S\left(\left|q\right|\right)$$ values vs $$q^2$$

Returns: S, qsquared 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
get_form_factors()[source]

Get form factor names and indices

Returns: list of factor names and indices list
get_ptypes()[source]

Get ordered list of particle names

Returns: list of particle names 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_active(name)[source]

Set particle type active

Parameters: name (str) – particle name
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 in get_form_factors()
set_inactive(name)[source]

Set particle type inactive

Parameters: name (str) – particle name
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_param(particle, param, value)[source]

Set named parameter for named particle

Parameters: particle (str) – particle name param (str) – parameter name value (float) – parameter value
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.

update_Kpoints()[source]

Update K points at which to evaluate FT

Note

If the diffraction image dimensions change relative to the reciprocal lattice, the K points need to be recalculated.

update_bases()[source]

Update the direct and reciprocal space lattice vectors

Note

If scale or boxMatrix is updated, the lattice vectors in direct and reciprocal space need to be recalculated.

class freud.kspace.FTfactory[source]

Factory to return an FT object of the requested type

addFT(name, constructor, args=None)[source]

Add an FT class to the factory

Parameters: name (str) – identifying string to be returned by getFTlist() constructor (object) – class / function name to be used to create new FT objects args (list) – set default argument object to be used to construct FT objects
getFTlist()[source]

Get an ordered list of named FT types

Returns: list of FT names 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 at addFT()
class freud.kspace.FTbase[source]

Base class for FT calculation classes

getFT()[source]

Return Fourier Transform

Returns: Fourier Transform numpy.ndarray
get_density(density)[source]

Get density

Returns: density numpy.complex64
get_parambyname(name)[source]

Get named parameter for object

Parameters: name (str) – parameter name. Must exist in list returned by get_params() parameter value float
get_params()[source]

Get the parameter names accessible with set_parambyname()

Returns: parameter names list
get_scale()[source]

Get scale

Returns: scale 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_density(density)[source]

set density

Parameters: density (numpy.complex64) – density
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
set_rq(r, q)[source]

Set r, q values

Parameters: r (numpy.ndarray) – r q (numpy.ndarray) – q
set_scale(scale)[source]

Set scale

Parameters: scale (float) – scale
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_density(density)[source]

set density

Parameters: density (numpy.complex64) – density
set_rq(r, q)[source]

Set r, q values

Parameters: r (numpy.ndarray) – r q (numpy.ndarray) – q
set_scale(scale)[source]

Set scale

Parameters: scale (float) – scale

Note

For a scale factor, $$\lambda$$, affecting the scattering density $$\rho\left(r\right)$$, $$S_{lambda}\left (k\right) == \lambda^3 * S\left(\lambda * k\right)$$

class freud.kspace.FTsphere[source]

Fourier transform for sphere

Calculate $$S = \sum_{\alpha} \exp^{-i \mathbf{K} \cdot \mathbf{r}_{\alpha}}$$

get_radius()[source]

If appropriate, return value should be scaled by get_parambyname(‘scale’) for interpretation.

set_radius(radius)[source]

Parameters: radius (float) – sphere radius will be stored as given, but scaled by scale parameter when used by methods
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]

If appropriate, return value should be scaled by get_parambyname(‘scale’) for interpretation.

set_K(K)[source]

Set K points to be evaluated

Parameters: K (numpy.ndarray) – list of K vectors at which to evaluate FT
set_density(density)[source]

set density

Parameters: density (numpy.complex64) – density
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
set_radius(radius)[source]

set_rq(r, q)[source]

Set r, q values

Parameters: r (numpy.ndarray) – r q (numpy.ndarray) – q
class freud.kspace.FTconvexPolyhedron[source]

Fourier Transform for convex polyhedra

Spoly2D(i, k)[source]

Calculate Fourier transform of polygon

Parameters: i (int) – face index into self.hull simplex list k (int) – angular wave vector at which to calcular $$S\left(i\right)$$
Spoly3D(k)[source]

Calculate Fourier transform of polyhedron

Parameters: k (int) – angular wave vector at which to calcular $$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
get_radius()[source]

If appropriate, return value should be scaled by get_parambyname(‘scale’) for interpretation.

set_radius(radius)[source]

## 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

makeSpot(cval)[source]

Generate intensity value(s) at sub-grid points

Parameters: cval (numpy.complex64) – complex valued amplitude used to generate spot intensity
set_xy(x, y)[source]

Set x,y values of spot center

Parameters: x (float) – x value of spot center y (float) – y value of spot center
class freud.kspace.GaussianSpot[source]

Draw diffraction spot as a Gaussian blur

grid points filled according to gaussian at spot center

makeSpot(cval)[source]

Generate intensity value(s) at sub-grid points

Parameters: cval (numpy.complex64) – complex valued amplitude used to generate spot intensity
set_sigma(sigma)[source]

Define Gaussian

Parameters: sigma (float) – width of the Guassian spot
set_xy(x, y)[source]

Set x,y values of spot center

Parameters: x (float) – x value of spot center y (float) – y value of 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
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 list of reciprocal lattice vectors list

Note

For unit test, dot(g[i], a[j]) = 2 * pi * diracDelta(i, j)