# chebyshev¶

Computations based on Chebyshev polynomial expansion

The kernel polynomial method (KPM) can be used to approximate various functions by expanding them in a series of Chebyshev polynomials.

Classes

 KPM(impl) The common interface for various KPM implementations SpatialLDOS(data, energy, structure) Holds the results of KPM.calc_spatial_ldos()

Functions

 dirichlet_kernel() The Dirichlet kernel – returns raw moments, least favorable choice jackson_kernel() The Jackson kernel – a good general-purpose kernel, appropriate for most applications kpm(model[, energy_range, kernel, ...]) The default CPU implementation of the Kernel Polynomial Method kpm_cuda(model[, energy_range, kernel]) Same as kpm() except that it’s executed on the GPU using CUDA (if supported) lorentz_kernel([lambda_value]) The Lorentz kernel – best for Green’s function
class KPM(impl)

The common interface for various KPM implementations

It should not be created directly but via specific functions like kpm() or kpm_cuda().

All implementations are based on: https://doi.org/10.1103/RevModPhys.78.275

calc_conductivity(chemical_potential, broadening, temperature, direction='xx', volume=1.0, num_random=1, num_points=1000)

Calculate Kubo-Bastin electrical conductivity as a function of chemical potential

The return value is in units of the conductance quantum (e^2 / hbar) not taking into account spin or any other degeneracy.

The calculation is based on: https://doi.org/10.1103/PhysRevLett.114.116602.

Parameters: chemical_potential : array_like Values (in eV) for which the conductivity is calculated. broadening : float Width (in eV) of the smallest detail which can be resolved in the chemical potential. Lower values result in longer calculation time. temperature : float Value of temperature for the Fermi-Dirac distribution. direction : Optional[str] Direction in which the conductivity is calculated. E.g., “xx”, “xy”, “zz”, etc. volume : Optional[float] The volume of the system. num_random : int The number of random vectors to use for the stochastic calculation of KPM moments. Larger numbers improve the quality of the result but also increase calculation time linearly. Fortunately, result quality also improves with system size, so the DOS of very large systems can be calculated accurately with only a small number of random vectors. num_points : Optional[int] Number of points for integration. Series
calc_dos(energy, broadening, num_random=1)

Calculate the density of states as a function of energy

Parameters: energy : ndarray Values for which the DOS is calculated. broadening : float Width, in energy, of the smallest detail which can be resolved. Lower values result in longer calculation time. num_random : int The number of random vectors to use for the stochastic calculation of KPM moments. Larger numbers improve the quality of the result but also increase calculation time linearly. Fortunately, result quality also improves with system size, so the DOS of very large systems can be calculated accurately with only a small number of random vectors. Series
calc_greens(i, j, energy, broadening)

Calculate Green’s function of a single Hamiltonian element

Parameters: i, j : int Hamiltonian indices. energy : ndarray Energy value array. broadening : float Width, in energy, of the smallest detail which can be resolved. Lower values result in longer calculation time. ndarray Array of the same size as the input energy.
calc_ldos(energy, broadening, position, sublattice='', reduce=True)

Calculate the local density of states as a function of energy

Parameters: energy : ndarray Values for which the LDOS is calculated. broadening : float Width, in energy, of the smallest detail which can be resolved. Lower values result in longer calculation time. position : array_like Cartesian position of the lattice site for which the LDOS is calculated. Doesn’t need to be exact: the method will find the actual site which is closest to the given position. sublattice : str Only look for sites of a specific sublattice, closest to position. The default value considers any sublattice. reduce : bool This option is only relevant for multi-orbital models. If true, the resulting LDOS will summed over all the orbitals at the target site and the result will be a 1D array. If false, the individual orbital results will be preserved and the result will be a 2D array with shape == (energy.size, num_orbitals). Series
calc_spatial_ldos(energy, broadening, shape, sublattice='')

Calculate the LDOS as a function of energy and space (in the area of the given shape)

Parameters: energy : ndarray Values for which the LDOS is calculated. broadening : float Width, in energy, of the smallest detail which can be resolved. Lower values result in longer calculation time. shape : Shape Determines the site positions at which to do the calculation. sublattice : str Only look for sites of a specific sublattice, within the shape. The default value considers any sublattice. SpatialLDOS
deferred_ldos(energy, broadening, position, sublattice='')

Same as calc_ldos() but for parallel computation: see the parallel module

Parameters: energy : ndarray Values for which the LDOS is calculated. broadening : float Width, in energy, of the smallest detail which can be resolved. Lower values result in longer calculation time. position : array_like Cartesian position of the lattice site for which the LDOS is calculated. Doesn’t need to be exact: the method will find the actual site which is closest to the given position. sublattice : str Only look for sites of a specific sublattice, closest to position. The default value considers any sublattice. Deferred
moments(num_moments, alpha, beta=None, op=None)

Calculate KPM moments in the form of expectation values

The result is an array of moments where each value is equal to:

$\mu_n = <\beta|op \cdot T_n(H)|\alpha>$
Parameters: num_moments : int The number of moments to calculate. alpha : array_like The starting state vector of the KPM iteration. beta : Optional[array_like] If not given, defaults to $$\beta = \alpha$$. op : Optional[csr_matrix] Operator in the form of a sparse matrix. If omitted, an identity matrix is assumed: $$\mu_n = <\beta|T_n(H)|\alpha>$$. ndarray
report(shortform=False)

Return a report of the last computation

Parameters: shortform : bool, optional Return a short one line version of the report
kernel

The damping kernel

model

The tight-binding model holding the Hamiltonian

scaling_factors

A tuple of KPM scaling factors a and b

system

The tight-binding system (shortcut for KPM.model.system)

class SpatialLDOS(data, energy, structure)

Holds the results of KPM.calc_spatial_ldos()

It behaves like a product of a Series and a StructureMap.

ldos(position, sublattice='')

Return the LDOS as a function of energy at a specific position

Parameters: position : array_like sublattice : Optional[str] Series
structure_map(energy)

Return a StructureMap of the spatial LDOS at the given energy

Parameters: energy : float Produce a structure map for LDOS data closest to this energy value. StructureMap
kpm(model, energy_range=None, kernel='default', num_threads='auto', silent=False, **kwargs)

The default CPU implementation of the Kernel Polynomial Method

This implementation works on any system and is well optimized.

Parameters: model : Model Model which will provide the Hamiltonian matrix. energy_range : Optional[Tuple[float, float]] KPM needs to know the lowest and highest eigenvalue of the Hamiltonian, before computing the expansion moments. By default, this is determined automatically using a quick Lanczos procedure. To override the automatic boundaries pass a (min_value, max_value) tuple here. The values can be overestimated, but note that performance drops as the energy range becomes wider. On the other hand, underestimating the range will produce NaN values in the results. kernel : Kernel The kernel in the Kernel Polynomial Method. Used to improve the quality of the function reconstructed from the Chebyshev series. Possible values are jackson_kernel() or lorentz_kernel(). The Jackson kernel is used by default. num_threads : int The number of CPU threads to use for calculations. This is automatically set to the number of logical cores available on the current machine. silent : bool Don’t show any progress messages. KPM
kpm_cuda(model, energy_range=None, kernel='default', **kwargs)

Same as kpm() except that it’s executed on the GPU using CUDA (if supported)

See kpm() for detailed parameter documentation. This method is only available if the C++ extension module was compiled with CUDA.

Parameters: model : Model energy_range : Optional[Tuple[float, float]] kernel : Kernel KPM
jackson_kernel()

The Jackson kernel – a good general-purpose kernel, appropriate for most applications

Imposes Gaussian broadening sigma = pi / N where N is the number of moments. The broadening value is user-defined for each function calculation (LDOS, Green’s, etc.). The number of moments is then determined based on the broadening – it’s not directly set by the user.

lorentz_kernel(lambda_value=4.0)

The Lorentz kernel – best for Green’s function

This kernel is most appropriate for the expansion of the Green’s function because it most closely mimics the divergences near the true eigenvalues of the Hamiltonian. The Lorentzian broadening is given by epsilon = lambda / N where N is the number of moments.

Parameters: lambda_value : float May be used to fine-tune the smoothness of the convergence. Usual values are between 3 and 5. Lower values will speed up the calculation at the cost of accuracy. If in doubt, leave it at the default value of 4.
dirichlet_kernel()

The Dirichlet kernel – returns raw moments, least favorable choice

This kernel doesn’t modify the moments at all. The resulting moments represent just a truncated series which results in lots of oscillation in the reconstructed function. Therefore, this kernel should almost never be used. It’s only here in case the raw moment values are needed for some other purpose. Note that required_num_moments() returns N = pi / sigma for compatibility with the Jackson kernel, but there is no actual broadening associated with the Dirichlet kernel.