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.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 31 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.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.
  • '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'.
  • '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'.

  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).