Scattering Kernels#

class elecboltz.kernel.AnisotropicGaussianScattering(C_0, C_1, sigma_0, sigma_1, m=1, nu_c=1.0, nu_s=1.0, phi_c=0.0, phi_s=0.0, delta=0.0)#

Bases: object

Scattering kernel based on a Gaussian of the difference of the angles of the wavevectors of the incoming and outgoing states in the x-y plane, with anisotropic parameters.

\[\]

C(phi, phi’) = left(C_0 + C_1 left|mathrm{cos}left(m: left[frac{phi+phi’}{2}-phi_cright]right) right|^{nu_c}right)mathrm{exp}left( -frac{(|\phi-\phi'|-delta)^2}{2left( sigma_0+sigma_1left|mathrm{cos}left( mleft[frac{phi+phi’}{2}-phi_sright]right) right|^{nu_s}right)^2}right)

Call the object like C(kx, ky, kz, kx_prime, ky_prime, kz_prime) to evaluate the kernel function at the given wavevectors.

Parameters:

C_0 (float) – The constant term in the amplitude of the Gaussian.
C_1 (float) – The coefficient for the anisotropic term in the amplitude of the Gaussian.
sigma_0 (float) – The constant term in the width of the Gaussian.
sigma_1 (float) – The coefficient for the anisotropic term in the width of the Gaussian.
m (int) – Sets the symmetry of the anisotropy over the angle in the x-y plane. For example, m=2 repeats the peak every 90 degrees.
nu_c (float) – Sets the sharpness of the anisotropy in the amplitude of the Gaussian.
nu_s (float) – Sets the sharpness of the anisotropy in the width of the Gaussian.
phi_c (float) – Sets the angle at which the peak of the amplitude of the anisotropy occurs. In units of degrees.
phi_s (float) – Sets the angle at which the width of the kernel is largest. In units of degrees.
delta (float) – The shift of the Gaussian from zero, in degrees. This can be used to model scattering that is peaked at a non-zero angle difference, such as forward scattering (delta=0) or backward scattering (delta=180).

class elecboltz.kernel.AzimuthalKernelFunction(C_1, m=1, nu=1.0, phi_0=0.0)#

Bases: object

Scattering kernel that is a function of the angle of the wavevector in the x-y plane, but not the magnitude.

\[\]

C(phi, phi’) = C_1left|mathrm{cos}left(m: left[frac{phi+phi’}{2}-phi_cright]right) right|^{nu_c}

Call the object like C(kx, ky, kz, kx_prime, ky_prime, kz_prime) to evaluate the kernel function at the given wavevectors.

Parameters:

C_1 (float) – The coefficient for the anisotropic term in the kernel function.
m (int) – Sets the symmetry of the anisotropy over the angle in the x-y plane. For example, m=2 repeats the peak every 90 degrees.
nu (float) – Sets the sharpness of the anisotropy in the kernel function.
phi_0 (float) – The phase shift of the anisotropy in the kernel function.

class elecboltz.kernel.CustomKernel(params: Mapping)#

Bases: ScatteringKernel

Scattering kernel expanded by the eigenvalue decomposition of a custom kernel function.

Parameters:

params (dict) –

A dictionary containing the following keys:

'kernel_func': A callable that takes in wavevector

components (kx, ky, kz, kx’, ky’, kz’) and returns the value

of the kernel function at that wavevector. The output should

be in units of angstrom^2 THz. The wavevector components

have units of 1/angstrom.
'rank': The number of eigenvalue and eigenvector pairs

to keep when decomposing the kernel function into basis

functions and coefficients. This would be the final rank of

the resulting scattering kernel. If not provided, set to 20

by default.
'low_res': The resolution of the approximate band object

used for a more managable eigenvalue decomposition

(nystrom method). If not provided, set to 21 by default.
'decomp_method': The method to use for the eigenvalue

decomposition. Should be one of ‘lanczos’ or ‘full’. If not

provided, set to ‘lanczos’ by default. ‘lanczos’ should be

more efficient for larger low-res approximations of

the kernel.

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.CylindricalKernel(params: Mapping)#

Bases: ScatteringKernel

Scattering kernel based on real cylindrical harmonics \(\cos(m\phi)\) and \(\sin(m\phi)\).

Parameters:: params (dict or np.ndarray) – A dictionary mapping (m, m') to the non-zero coefficients of the scattering kernel. For the cosine basis functions, m is non-negative, while for the sine basis functions, m is negative. Note that since the scattering kernel should be Hermitian, (real-symmetric in this case), you must only specify one coefficient for each pair of indices. The kernel will automatically fill in the other coefficient.

build_coeffs(params: Mapping)#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.GaussianScattering(C, sigma, delta=0.0, backward=False)#

Bases: object

Scattering kernel based on a Gaussian of the difference of the wavevectors of the incoming and outgoing states.

\[C(k, k') = C \mathrm{exp}( -(|\mathbf{k}\pm \mathbf{k'}|-delta)^2/2\sigma^2)\]

Call the object like C(kx, ky, kz, kx_prime, ky_prime, kz_prime) to evaluate the kernel function at the given wavevectors.

Parameters:

C (float) – The amplitude of the Gaussian.
sigma (float) – The width of the Gaussian.
backward (bool) – Whether the Gaussian is a function of |k+k'| (backward scattering) or |k-k'| (forward scattering). Default is False, which corresponds to forward scattering.
delta (float) – The shift of the Gaussian from zero. This can be used to model scattering that is peaked at a non-zero momentum transfer, such as forward scattering (delta = 0) or backward scattering (delta = 2|k|).

class elecboltz.kernel.HotspotScattering(m_h, dphi_h, C_h, sigma_h, phi_h0=0.0)#

Bases: object

Scattering kernel based on a Gaussian of the difference of the angles of the wavevectors of the incoming and outgoing states in the x-y plane with “hotspot” pairs.

\[\]

C(phi, phi’) = sum_i C_{hi}sum_j mathrm{exp}left(: -frac{(phi-phi_{hj})^2}{2sigma_{hi}^2}right) mathrm{exp}left(-frac{(phi-phi’_{hj})^2} {2sigma_{hi}^2}right)

The hotspots themselves are defined by a number of hotspots m_h and a shift phi_h0. The hotspots are then located at phi_h[i] = phi_h0 + i*2*pi/m_h, so that there are \(m_h\) hotspots evenly spaced around the circle. Their connecting angles are then defined by the array dphi_h, which is a sequence of angle differences between the hotspots that makes the pairs \(\phi_{hj}\) and \(\phi'_{hj}\). That is, when the hotspots are at angle dphi_h[j] apart, the kernel will have a peak at that angle difference.

Parameters:

m_h (int) – The number of hotspots.
phi_h0 (Sequence of float) – The shift of the hotspots from zero, in degrees. Each hotspot will then be at angle phi_h[i] = phi_h0 + i*2*pi/m_h (here, phi_h0 is converted into radians).
dphi_h (Sequence of float) – The connecting angles between the hotspots, in degrees. When the hotspots are at angle dphi_h[j] apart, the kernel will have a peak at that angle difference.
C_h (Sequence of float) – The amplitude of the Gaussian for each connecting angle between the hotspots.
sigma_h (Sequence of float) – The width of the Gaussian for each connecting angle between the hotspots.

class elecboltz.kernel.IsotropicKernelFunction(C)#

Bases: object

Scattering kernel that is just a constant function of the wavevectors of the incoming and outgoing states. This corresponds to isotropic scattering.

Call the object like C(kx, ky, kz, kx_prime, ky_prime, kz_prime) to evaluate the kernel function at the given wavevectors.

Parameters:: C (float) – The value of the kernel function at all wavevectors. Should be in units of angstrom^2 THz.

class elecboltz.kernel.LegendreKernel(params: Mapping)#

Bases: ScatteringKernel

Scattering kernel based on Legendre polynomials \(P_l(\cos \theta)\).

To preserve normalization, this kernel actually uses the spherical harmonics \(Y^{m=0}_l(\theta, \phi)\), which are proportional to the Legendre polynomials \(P_l(\cos \theta)\).

Parameters:: params (dict) – Either a dictionary mapping (l, l') to the non-zero coefficients of the scattering kernel, or a 2D array of coefficients where the entry at (l, l’) corresponds to the coefficient for the basis functions with indices l and l'. Note that since the scattering kernel should be Hermitian (real-symmetric in this case), if you use a dictionary, you must only specify one coefficient for each pair of indices. The kernel will automatically fill in the other coefficient.

build_coeffs(params: Mapping)#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.ScatteringKernel(params: Mapping)#

Bases: object

Base class for scattering kernels.

This class should contain the following attributes and methods:

is_explicit#

Whether the kernel already has explicit basis functions that can be evaluated at any wavevector. If False, the kernel should provide a method decompose(band) to decompose the kernel into the basis functions and coefficients (effectively building ceoffs and eval_basis from the kernel function).

Type:: bool

coeffs#

The coefficients of the scattering kernel. The entry at (i, j) corresponds to the coefficient for the basis functions with indices i and j.

Type:: np.ndarray

build_coeffs(params) → np.ndarray#: Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute. Only necessary if is_explicit is True.

eval_basis(index, kx, ky, kz) → np.ndarray#: Evaluate the basis function with the given index at the given wavevector. Only necessary if is_explicit is True. The output should be in units of angstrom^2 THz. The wavevector components have units of 1/angstrom.

decompose(band)#: Decompose the kernel into the basis functions and coefficients. Takes in a band object. Only necessary if is_explicit is False. This should set the coeffs attribute and provide the object with the parameters needed for eval_basis.

build_coeffs(params: Mapping) → ndarray#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz) → ndarray#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.SphericalKernel(params: Mapping)#

Bases: ScatteringKernel

Scattering kernel based on real-valued spherical harmonics \(\sqrt{2} \Re Y^{|m|}_l(\theta, \phi)\) and \(\sqrt{2} \Im Y^{|m|}_l(\theta, \phi)\). The first, cosine-like, basis function corresponds to positive m, while the second, sine-like, basis function corresponds to negative m.

Parameters:: params (dict) – A dictionary mapping tuples of tuples of integers, ((l, m), (l', m')), to the corresponding coefficients of the scattering kernel. Note that since the scattering kernel should be Hermitian (real-symmetric in this case), you must only specify one coefficient for each pair of indices. The kernel will automatically fill in the other coefficient.

build_coeffs(params: Mapping)#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.SumKernel(kernels: Collection[ScatteringKernel])#

Bases: ScatteringKernel

Scattering kernel that is a sum of other kernels.

The resulting basis is a direct sum of each basis for the individual kernels. This means that the vector of the basis functions is just a concatenation of the basis functions for each kernel, and the coefficient matrix would become a block-diagonal matrix with the coefficient matrices of the individual kernels as blocks.

Keep in mind that this creates many unused entries in the scattering matrix. So, always try finding a more general basis before simply adding multiple kernels with this method.

Parameters:: kernels (list of ScatteringKernel) – The kernels to sum together.

build_coeffs(kernels: Collection[ScatteringKernel])#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

class elecboltz.kernel.SumKernelFunction(kernels: Collection[Callable])#

Bases: object

Class for gathering multiple kernels together by adding their kernel functions.

Call the object like C(kx, ky, kz, kx_prime, ky_prime, kz_prime) to evaluate the combined kernel function at the given wavevectors.

Parameters:: kernels (list of Callable) – A list of kernel functions to add together.

class elecboltz.kernel.VonMisesKernel(params: Mapping)#

Bases: ScatteringKernel

Scattering kernel based on von Mises distributions in the angle of the wavevector in the x-y plane.

The basis consists of a constant term and one function of the form:

\[e^{\kappa \cos(m(\phi-\phi_0))}\]

So, the full kernel is:

\[C(\phi, \phi') = C_0 + C_1 ( e^{\kappa \cos(m(\phi-\phi_0))} e^{\kappa \cos(m(\phi'-\phi_0))})\]

Parameters:

params (dict) –

A dictionary containing the following keys:

c0: The constant term in the kernel.
c1: The coefficient for the von Mises distribution.
kappa: Controls the width of the distribution. Larger

kappa corresponds to a narrower distribution.
m: Sets the symmetry of the distribution over the

angle in the x-y plane. For example, m=4 repeats the

peak every 90 degrees.
phi_0: Sets the angle at which the peak of the

distribution occurs. Should be in degrees.

build_coeffs(params: Mapping)#

Build the coefficients of the scattering kernel from the given parameters and set the coeffs attribute.

Parameters:: params (dict) – A dictionary of parameters needed to construct the scattering kernel.
Returns:: The coefficients of the scattering kernel.
Return type:: np.ndarray

eval_basis(index, kx, ky, kz)#

Evaluate the basis function with the given index at the given wavevector.

Parameters:

index (int) – The index of the basis function to evaluate.
kx (float) – The components of the wavevector with units of 1/angstrom.
ky (float) – The components of the wavevector with units of 1/angstrom.
kz (float) – The components of the wavevector with units of 1/angstrom.

Returns:

The values of the basis functions at the given wavevector.

Return type:

np.ndarray

elecboltz.kernel.build_kernel(kernel, kernel_params)#

Build a scattering kernel based on the given kernel type and parameters.

Parameters:

kernel (str or list of str) –
The type(s) of kernel(s) to build. Kernels with explicit basis functions include:
- 'spherical': Spherical Harmonics. The parameters are
  
  indicated by a pair of tuples of integers,
  
  ((l, m), (l', m')), mapping to the corresponding
  
  coefficients of the (real-valued) spherical harmonics
  
  \(P_l^m(\theta, \phi)\)
  
  and \(P_{l'}^{m'}(\theta, \phi)\).
- 'cylindrical': Cylindrical Harmonics, which are just
  
  cosines and sines of the angle in the x-y plane. The
  
  parameter dictionary keys can be expressed in two ways;
  
  first, as a pair of integers (m, m'), where
  
  non-negative m corresponds to cosines and negative m
  
  corresponds to sines; second, as a string of the form
  
  '[cos/sin][m][cos/sin][m'], so for example (-2, 3)
  
  in the previous scheme would correspond to 'sin2cos3'.
  
  You can set single sines and cosines either by setting the
  
  other m to zero or by simply omitting it, so for
  
  example 'cos3'. You can set the constant term by having
  
  both m and m’ be zero, or just use '1' or 'constant'
  
  or 'const' or 'iso' as the key.
- 'legendre': Legendre polynomials. The parameters are
  
  indicated by a pair of integers, (l, l'), mapping to
  
  the corresponding coefficients of the Legendre polynomials
  
  \(P_l(\cos \theta)\)
  
  and \(P_{l'}(\cos \theta)\). Note that, to keep the
  
  normalization consistent, this kernel actually uses the
  
  spherical harmonics \(Y^{m=0}_l(\theta, \phi)\).
Kernels without explicit basis functions include:
- 'isotropic': Isotropic scattering, where the kernel is
  
  just a constant value 'C_0' at all wavevectors.
- 'azimuthal': A kernel that is a function of the angle
  
  of the wavevector in the x-y plane, but not the magnitude.
  
  The function has the form
  
  \(C(\phi, \phi') = C_1|\mathrm{cos}(m[\frac{\phi+\phi'}{2}-\phi])|^\nu\).
  
  The kernel parameters are 'C_1' (the aplitude),
  
  'm' (the symmetry), 'nu' (the sharpness of the
  
  anisotropy), and 'phi' (the angle at which the
  
  anisotropy peaks, in degrees).
- 'forward': Forward scattering expressed as a Gaussian
  
  \(C_f \mathrm{exp}(-|k-k'|^2/2\sigma_f^2)\). The
  
  kernel parameters are 'C_f', which sets the amplitude,
  
  and 'sigma_f', which sets the width.
- 'backward': Backward scattering expressed as a Gaussian
  
  \(C_b \mathrm{exp}(-|k+k'|^2/2\sigma_b^2)\). The
  
  kernel parameters are 'C_b', which sets the amplitude,
  
  and 'sigma_b', which sets the width.
- 'forward_phi': Like 'forward', but the Gaussian is
  
  in the angle of the wavevector in the x-y plane instead of
  
  the full wavevector. So,
  
  \(C_f \mathrm{exp}(-|\phi-\phi'|^2/(2\sigma_f^2))\).
- 'backward_phi': Like 'backward', but the Gaussian
  
  is in the angle of the wavevector in the x-y plane instead
  
  of the full wavevector. So,
  
  \(C_b \mathrm{exp}(-|\phi+\phi'|^2/(2\sigma_b^2))\).
- 'forward_anisotropic': Like 'forward_phi', but with
  
  anisotropic parameters for the Gaussian. This means,
  
  \(C_f = C_{f0} + C_{f1}|\mathrm{cos}(m[(\phi+\phi')/2-\phi_{fc}])|^{\nu_{fc}}\) and
  
  \(\sigma_f=\sigma_{f0}+\sigma_{f1}\left|\mathrm{cos}(m[(\phi+\phi')/2-\phi_{fs}])\right|^{\nu_{fs}}\).
  
  The kernel parameters are 'C_f0', 'C_f1',
  
  'sigma_f0', 'sigma_f1', 'm', \nu_{fc},
  
  \nu_{fs}, 'phi_fc', and 'phi_fs'.
  
  Any omitted parameters will be set to zero, except for 'm',
  
  which will be set to 1 by default.
- 'backward_anisotropic': Like 'backward_phi', but
  
  with anisotropic parameters for the Gaussian. This means,
  
  \(C_b = C_{b0} + C_{b1}|\mathrm{cos}(m[(\phi+\phi')/2-\phi_{bc}])|^{\nu_{bc}}\) and
  
  \(\sigma_b=\sigma_{b0}+\sigma_{b1}\left|\mathrm{cos}(m[(\phi+\phi')/2-\phi_{bs}])\right|^{\nu_{bs}}\).
  
  The kernel parameters are 'C_b0', 'C_b1',
  
  'sigma_b0', 'sigma_b1', 'm', \nu_{bc},
  
  \nu_{bs}, 'phi_bc', and 'phi_bs'.
  
  Any omitted parameters will be set to zero, except for 'm',
  
  which will be set to 1 by default.
- 'hotspot': See
  
  elecboltz.kernel.AzimuthalHotspotScattering for details.
  
  The parameters are 'm_h' (number of hotspots),
  
  'phi_h0' (shift of the hotspots from zero, in degrees.
  
  if omitted, set to 0 by default),
  
  dphi_h (array of connecting angles between
  
  the hotspots, in degrees),
  
  'C_h' (array of strengths for each connecting angle),
  
  and 'sigma_h' (array of widths for each
  
  connecting angle).
If a list of kernels is provided, the resulting kernel is the sum of all the kernels in the list. Note that you cannot mix kernels with explicit basis functions and kernels without explicit basis functions.
kernel_params (dict or list of dict) – The parameters for the kernel(s). If a list of explicit basis kernels is provided, a list of parameter dictionaries should be provided, where each dictionary corresponds to the parameters for the respective kernel. For non-explicit kernels, an extra dictionary can be provided at the end of the list to specify the parameters for the decomposition of the resulting kernel (see elecboltz.kernel.CustomKernel).