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 (in radians).

• sigma_1 (float) – The coefficient for the anisotropic term in the width of the Gaussian (in radians).

• 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.AzimuthalHotspotKernel(phi_h, dphi_h, C_h, sigma_h, tol=1e-05)

Bases: ScatteringKernel

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_h^2}right) mathrm{exp}left(-frac{(phi-phi’_{hj})^2} {2sigma_h^2}right)

Pairs of “hotspots” separated by a particular angle will contribute to the scattering kernel in the form of a double Gaussian peak.

Parameters:

• phi_h (Sequence of float) – The position of the hotspots by their angle in the x-y plane. In degrees, but converted to radians internally.

• dphi_h (float) – The connecting angle between the hotspots. In degrees, but converted to radians internally. Only pairs of hotspots with this particular connecting angle will contribute to the scattering kernel.

• C_h (float) – The amplitude of each Gaussian pair in the scattering kernel. In units of angstrom^2 THz.

• sigma_h (Sequence of float) – The width of the Gaussians (in radians).

• tol (float) – The tolerance for determining whether a pair of hotspots is connected by the given connecting angle. This is in absolute terms, in radians.

build_coeffs()

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.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(kernel_func: Callable, rank: int = 20, low_res: int = 21, **kwargs)

Bases: ScatteringKernel

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

Parameters:

• kernel_func – 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.

• 'low_res' – The resolution of the approximate band object used for a more managable eigenvalue decomposition.

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

Bases: object

Helper class to sum multiple custom kernel functions together into one unified function.

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 (in angstroms).

• 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.IsotropicKernel(C)

Bases: ScatteringKernel

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

Parameters:

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

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

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 building a kernel with explicit basis functions.

eval_basis(index, kx, ky, kz) → np.ndarray

Evaluate the basis function with the given index at the given wavevector. Only necessary if you want to use explicit basis functions.

decompose(band)

Decompose the kernel into the basis functions and coefficients. Takes in a band object. Only necessary if there is no explicit basis functions. This sets eval_basis and whatever is needed to build the transformation from the reduced basis to the full FEM 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], **decomp_params)

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.

Custom kernels will just be summed together in one unified function, and the basis obtained from the decomposition of the resulting kernel will be used.

Parameters:

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

• decomp_params (dict) – The parameters for the decomposition of the custom kernels.

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_phi': See

    elecboltz.kernel.AzimuthalHotspotScattering for details.

  If a list of kernels is provided, the resulting kernel is the sum of all the kernels in the list.

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