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

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

Returns:

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.

Returns:

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.

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

Returns:

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.

Returns:

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.

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

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 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]

Returns:

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.

Returns:

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.

Returns:

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

Returns:

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.