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 generalpurpose 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()
orkpm_cuda()
.All implementations are based on: https://doi.org/10.1103/RevModPhys.78.275

__call__
(*args, **kwargs)¶ Call self as a function.

calc_conductivity
(chemical_potential, broadening, temperature, direction='xx', volume=1.0, num_random=1, num_points=1000)¶ Calculate KuboBastin 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 FermiDirac 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.
Returns:

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

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.
Returns:  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 multiorbital 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)
.
Returns:

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

deferred_ldos
(energy, broadening, position, sublattice='')¶ Same as
calc_ldos()
but for parallel computation: see theparallel
moduleParameters:  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.
Returns:  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 = <\betaop \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 = <\betaT_n(H)\alpha>\).
Returns:  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 tightbinding model holding the Hamiltonian

scaling_factors
¶ A tuple of KPM scaling factors
a
andb

system
¶ The tightbinding 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 aStructureMap
.
ldos
(position, sublattice='')¶ Return the LDOS as a function of energy at a specific position
Parameters:  position : array_like
 sublattice : Optional[str]
Returns:

structure_map
(energy)¶ Return a
StructureMap
of the spatial LDOS at the given energyParameters:  energy : float
Produce a structure map for LDOS data closest to this energy value.
Returns:


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 produceNaN
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()
orlorentz_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.
Returns:

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

jackson_kernel
()¶ The Jackson kernel – a good generalpurpose kernel, appropriate for most applications
Imposes Gaussian broadening
sigma = pi / N
whereN
is the number of moments. The broadening value is userdefined 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
whereN
is the number of moments.Parameters:  lambda_value : float
May be used to finetune 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()
returnsN = pi / sigma
for compatibility with the Jackson kernel, but there is no actual broadening associated with the Dirichlet kernel.