qolossal package

Abstract Hamiltonian

Abstract Hamiltonian class for large systems.

class qolossal.abstractHamiltonian.Hamiltonian[source]

Bases: ABC

Abstract base class for a general Hamiltonian.

This class does not implement any Hamiltonian. Nonetheless it provides all methods for calculating the properties of systems. This is possible since, within the linear method based on the Chebyshev expansion, only the dot product of the Hamiltonian on a state is needed to compute observables.

Empty constructor.

The attributes defined below are of general character, i.e. will have definite values in all actual implementations of the Hamiltonian, and are needed for the various calculations performed by the methods defined in this class.

disDict: dictionary defining disorder. Will be translated to a HQSchema. disLocPot: local disorder potential. scaling: chebyshev scaling object. chebyshev: chebyshev expansion object. dim: number of sites in the system. Can double in spinful OR BCS cases. realDim: real number of sites. velocity_operator: velocity operator in the x-, y- and z- directions. total_volume: total volume of the system. is_complex: flag for complex Hamiltonians

__init__() → None[source]

Empty constructor.

The attributes defined below are of general character, i.e. will have definite values in all actual implementations of the Hamiltonian, and are needed for the various calculations performed by the methods defined in this class.

disDict: dictionary defining disorder. Will be translated to a HQSchema. disLocPot: local disorder potential. scaling: chebyshev scaling object. chebyshev: chebyshev expansion object. dim: number of sites in the system. Can double in spinful OR BCS cases. realDim: real number of sites. velocity_operator: velocity operator in the x-, y- and z- directions. total_volume: total volume of the system. is_complex: flag for complex Hamiltonians

property dtype: Type

Dtype convenience function.

Returns:: complex or float depending on the flag is_complex
Return type:: Type

abstract dot(v: ndarray, out: ndarray) → ndarray[source]

Empty dot product. Abstract method: it has to be overloaded.

Parameters:

v (np.ndarray) – Vector to dot.
out (np.ndarray) – preallocated output array.

Raises:

NotImplementedError – In any case, since this method HAS to be overwritten by children classes.

_dot_scaling(v: ndarray, out: ndarray) → ndarray[source]

Dot product including scaling.

This dot product is needed for evaluating moments of quantities that have not been yet implemented in the lattice solver.

Parameters:

v (np.ndarray) – Vector to dot.
out (np.ndarray) – preallocated output array.

Returns:

Dot product of H with v.

Return type:

np.ndarray

_set_scaling_and_cheby(lower_spectral_bound: float = -1, upper_spectral_bound: float = 1, delta: float = 0, force_complex: bool = False) → None[source]

Set the scaling and corresponding chebyshev objects.

Parameters:

lower_spectral_bound (float) – Lower bound of the spectral range. Defaults to -1.
upper_spectral_bound (float) – Upper bound of the spectral range. Defaults to 1.
delta (float) – Spectral buffer for Hamiltonian scaling.
force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

_set_cheby(force_complex: bool = False) → None[source]

Set the chebyshev object.

Parameters:: force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

generateSelector(what: str = 'all') → ndarray[source]

Trivial selector generator given a certain input configuration.

This method is just an empty placeholder, it will have to be specified for each Hamiltonian implementation.

Parameters:: what (str) – input configuration. Not used in this method.
Returns:: array of 1’s.
Return type:: np.ndarray

Warning

RuntimeWarning: warn all the time, since this function is always selecting everything.

getBoundsLanczos(Order: int, tolerance: float = 1e-11) → ndarray[source]

Get spectrum boundaries for the current Hamiltonian with the Lanczos method.

Parameters:

Order (int) – Order of the Lanczos expansion
tolerance (float) – Tolerance for the expansion. Defaults to 1e-11.

Returns:

Boundaries of the spectrum.

Return type:

np.ndarray

scaleH(delta: float = 0.1, LanczOrder: int | None = None, energyBounds: list | ndarray | None = None) → None[source]

Rescale Hamiltonian to have spectrum between -1 and 1.

Parameters:

delta (float) – Controls the extra compression of the band. This will be rescaled to be (-1 + delta/2, 1 - delta/2). Defaults to 0.1.
LanczOrder (Optional[int]) – Order of the Lanczos expansion used to determine the bandwidth. Cannot be set together with energyBounds.
energyBounds (Optional[Union[list, np.ndarray]]) – lower and upper energy boundaries to determine scaling. Cannot be set together with LanczOrder.

Raises:

ValueError – If delta is not in (0, 2).
ValueError – If both LanczOrder and energyBounds are set.

scaleH_inv() → None[source]: Rescale Hamiltonian to have original spectrum.

scale2real(x: fl_cmplx_or_ndarr) → fl_cmplx_or_ndarr[source]

Apply scaling to transform scaled frequencies to real ones.

Parameters:: x (qt.fl_cmplx_or_ndarr) – array of scaled energies within (-1, 1).
Returns:: Real energies array.
Return type:: qt.fl_cmplx_or_ndarr

scale2transformed(z: fl_cmplx_or_ndarr) → fl_cmplx_or_ndarr[source]

Apply scaling to transform real frequencies to scaled ones.

Parameters:: z (qt.fl_cmplx_or_ndarr) – real energies array.
Returns:: Scaled energies array.
Return type:: qt.fl_cmplx_or_ndarr

parseDisDict(parse_dict: dict) → None[source]

Parse disorder input dictionary.

The disorder dictionary specifies the properties of the disorder:

type: kind of disorder, e.g. onsite (only type implemented for now).

distribution: random distribution of disorder potential.

sigma: standard deviation of the disorder distribution.

avg: mean of distribution.

Note

This will become obsolete with the introduction of a Schema for the disDict.

Parameters:: parse_dict (dict) – Dictionary containing information about the disorder.
Raises:: ValueError – if the dictionary cannot be parsed

scrambleW() → None[source]: Function that scrambles the disorder vector.

getTrResolvent(NSamples: int, Order: int, rescale: bool = True, use_KPM: bool = True, verbose: int = 2, selector: ndarray | None = None) → Callable[source]

Returns a function evaluating the trace of the resolvent.

This method computes the Chebyshev moments for a given order and given number of stochastic samples to evaluate the trace. Can be used to evaluate the trace of the resolvent,

\[\mathrm{Tr} \left[ \frac{1}{z - \hat{H}} \right]\]

for a given ‘frequency’ \(z\) without the need to recompute the Chebyshev expansion. This is useful if it is not a priori clear on how many frequencies the trace of the resolvent needs to be evaluated.

The trace of the resolvent will be evaluated at the given frequencies. For real frequencies the retarded resolvent is chosen.

NOTE: The trace is estimated as the average over all (normalized) stochastic samples. Hence, multiply the result by the linear size of the Hamiltonian to get the “true” estimate for the trace.

NOTE: If the number of samples is larger that the size of the selected subspace, the trace is computed exactly (apart from the normalization, see above).

Parameters:

NSamples (int) – Number of stochastic samples to approximate the trace.
Order (int) – Order of the Chebyshev expanbsion to approximate the resolvent.
rescale (bool) – Whether generated function transforms input into interval (-1, 1). Defaults to True.
use_KPM (bool) – Flag controlling the use of KPM.
verbose (int) – Controls verbosity of output and warnings. Defaults to 2.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Returns:

Function evaluating the trace of the resolvent for a given frequency.

Return type:

Callable

_get_DOS_moments(NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray[source]

Calculates the moments of the Chebyshev expansion of the density of states.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

NSamples (int) – Number of stochastic samples for the calculation of the DoS.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the density of states

Return type:

np.ndarray

getDOS(NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None) → tuple[ndarray, ndarray][source]

Calculates DoS through stochastic averaging of Chebyshev expansion.

This density of states integrates to 1, i.e. it is defined as:

\[\rho(E) = \frac{1}{N} \sum\limits_i \delta(E - E_i) = \frac{1}{N} {\rm Tr} \left[ \delta(E - \hat{H}) \right]\]

with \(E_i\) the eigenvalues of the Hamiltonian and N the number of orbitals.

More details on the calculation are readily available in the literature. For example: https://doi.org/10.1016/j.physrep.2020.12.001

Parameters:

NSamples (int) – Number of stochastic samples for the calculation of the DoS.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of frequencies to evaluate the DoS at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

DoS and corresponding frequencies.

Return type:

tuple

Calculate the retarded Green’s Function in the real space basis.

This calculation is performed the same way as for the DOS, the only difference being the states used for evaluating the moments: in this case we directly use the real space basis.

Parameters:

selector (Union[str, ArrayLike]) – specifies what to compute (‘diag’, ‘full’, or array of row-column pairs)
Order (int) – Order of the Chebyshev expansion.
NOmegas (int) – Number of frequencies to evaluate.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

GF and corresponding frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

_get_conductivity_moments(tensor_element: str, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray[source]

Calculates the moments of the Chebyshev expansion of the conductivity.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Moments associated with the conductivity

Return type:

np.ndarray

getConductivity(tensor_element: str, T: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None) → tuple[ndarray, ndarray][source]

Calculates the conductivity of the system from the Kubo-Greenwood formula.

This routine follows the method presented in https://doi.org/10.1016/j.physrep.2020.12.001

In short: a Chebyshev expansion of the zero temperature Kubo formula is performed. This translates into the expansion of the function \(\delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H})\) \(\hat{V}_{\beta}\), where \(E\) is the energy, \(\hat{H}\) is the Hamiltonian and \(\hat{V}\) is the velocity operator in the direction \(\alpha\,{\rm and }\,\beta\). The conductivity reads

\[\sigma(E) = \frac{\pi \hbar e^2}{\Omega} {\rm Tr}\left[ \delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H}) \right]\]

The temperature dependent result is obtained by simply convolving the zero temperature result by a ‘Fermi window’, i.e. minus the derivative of the Fermi function with respect to the energy.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

getConductivityMu(tensor_element: str, NSamples: int, Order: int, mu: float | ndarray, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None) → float | complex | ndarray[source]

Calculates the conductivity of the system defined by H at a single chemical potential.

Given a Hamiltonian, the corresponding conductivity can be calculated as

\[\sigma(\mu) = \frac{\pi \Omega}{\Delta E^2} \braket{\phi^L|\phi^R}\]

where \(\Omega\) is the volume of the system, \(\Delta E\) is the scaling applied to the Hamiltonian to ensure the spectrum lies within (-1, 1) and the vectors \(\phi\) are

\[ \begin{align}\begin{aligned}\ket{\phi^L} = \sum_n Im[G^+_n(\mu)] T_n(\tilde{H}) V \ket{r}\\\ket{\phi^R} = \sum_n Im[G^+_n(\mu)] V T_n(\tilde{H}) \ket{r}\end{aligned}\end{align} \]

where \(\ket{r}\) is the random vector, \(V\) is the velocity operator, \(G^+_n\) is the n-th GF coefficient and \(T_n(\tilde{H})\) is the m-th Chebyshev polynomial.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
mu (Union[float, np.ndarray]) – Energy(ies) (as in chemical potential) at which to evaluate the conductivity.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the DOS.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Conductivity at the specified chemical potential(s).

Return type:

qt.fl_cmplx_or_ndarr

getConductivity_KB(tensor_element: str, T: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None, NOmegasInt: int | None = None) → tuple[ndarray, ndarray][source]

Calculates the conductivity of the system evaluating the Kubo-Bastin formula.

This routine follows the method presented in https://doi.org/10.1103/PhysRevLett.114.116602

In short: a Chebyshev expansion of the Kubo-Bastin formula is performed. This translates into the expansion of the function:

\[v_\alpha \delta(\varepsilon - \hat{H}) \hat{v}_\beta \frac{dG^+(\varepsilon)} {d\varepsilon} - \hat{v}_\alpha \frac{dG^-(\varepsilon)}{d\varepsilon} \hat{v}_\beta \delta(\varepsilon - \hat{H})\]

where \(\varepsilon\) is the energy, \(\hat{H}\) is the Hamiltonian, \(\hat{v}\) is the velocity operator and \(\alpha, \beta\) indicate the direction. The modus operandi is exactly the same as for the other conductivity calculations based on the Chebyshev expansion.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.
NOmegasInt (Optional[int]) – number of frequencies to use to calculate the E integral.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

_get_expectation_value_moments(A: Callable, expectation_value_dtype: type, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray[source]

Calculates the moments of the Chebyshev expansion of an operator’s expectation value.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

A (Callable) – Linear operator.
expectation_value_dtype (type) – dtype of the linear operator.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the expectation value of operator A.

Return type:

np.ndarray

getExpectationValue(A: Callable, dtype: type, T: float, mu: float, NSamples: int, Order: int, NPadeFreq: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None) → float | complex[source]

Calculates the expectation value of an operator through Chebyshev expansion.

This is done by performing the Chebyshev expansion of

\[\langle \hat{A} \rangle = {\rm Tr} \left[ \hat{A} f(\hat{H}) \right]\]

where \(\hat{A}\) is the operator, \(\hat{H}\) is the hamiltonian and f is the fermi function. This expression is expanded in terms of Chebyshev polynomials. The integral over the energies is performed via the resummation of the Fermi-Pade’ expansion of the Fermi function.

Parameters:

A (Callable) – Linear operator.
dtype (type) – dtype of the linear operator.
T (float) – temperature in Kelvins. Must be greater than 0.
mu (float) – chemical potential.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NPadeFreq (int) – Number of Pade frequencies to evaluate the approximation to the Fermi function.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if temperature is too small.

Returns:

expectation value of operator A.

Return type:

Union[float, complex]

getConductivityOptical(tensor_element: str, T: float, mu: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None, NOmegasInt: int | None = None) → tuple[ndarray, ndarray][source]

Calculates the complex optical conductivity of the system.

In short: a Chebyshev expansion of the Kubo formula is performed. The procedure is similar to the one presented in https://journals.aps.org/prb/abstract/10.1103/PhysRevB.94.235405

Details on the routine can be found in the internal notes. In particular, eq. 32 of the notes is implemented.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
mu (float) – Chemical potential.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.
NOmegasInt (Optional[int]) – number of frequencies to use to calculate the E integral.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

_abc_impl = <_abc._abc_data object>

Abstract Hamiltonian based on Lattice Builder

Abstract Hamiltonian class interfacing directly to the Lattice Builder.

class qolossal.abstractHamiltonian_LB.HamiltonianLB(input_dict: dict, disDict: dict | None = None)[source]

Bases: Hamiltonian

Abstract Hamiltonian class that takes care of the interface with the LatticeBuilder.

Initialization of the class.

This init takes care of validation and building of the system coresponding to the input dictionary and will extract the general information needed by most Hamiltonians. The Hamiltonian itself will have to be extracted by each the specific implementation. Note that this class is still abstract as no dot product is defined.

Parameters:

input_dict (dict) – Input dictionary for the Lattice Builder to construct the Hamiltonian
disDict (Optional[dict]) – dictionary specifying the disorder.

Raises:

ValueError – if the input_dict or dis dictionaries cannot be validated.

__init__(input_dict: dict, disDict: dict | None = None) → None[source]

Initialization of the class.

This init takes care of validation and building of the system coresponding to the input dictionary and will extract the general information needed by most Hamiltonians. The Hamiltonian itself will have to be extracted by each the specific implementation. Note that this class is still abstract as no dot product is defined.

Parameters:

input_dict (dict) – Input dictionary for the Lattice Builder to construct the Hamiltonian
disDict (Optional[dict]) – dictionary specifying the disorder.

Raises:

ValueError – if the input_dict or dis dictionaries cannot be validated.

is_complex: bool

realDim: int

dim: int

velocity_operator: tuple[Callable, Callable, Callable] | None

total_volume: float

abstract set_Hamiltonian(kpt: ndarray | None = None, mu: float = 0, Bz: float = 0) → None[source]

Hamiltonian setter method.

Parameters:

kpt (Optional[np.ndarray]) – Bloch vector determining phase-shift at periodic boundaries.
mu (float) – additional chemical potential.
Bz (float) – additional Bz field.

Raises:

NotImplementedError – If the method is not overloaded in the children classes.

getH() → csr_array[source]

Getter function for Hamiltonian in sparse format.

Returns:: Hamiltonian matrix in sparse row format.
Return type:: csr_array
Raises:: RuntimeError – if the Hamiltonian is not available.

todense() → ndarray[source]

Getter function for Hamiltonian in dense format.

Returns:: Hamiltonian matrix in dense format.
Return type:: np.ndarray

generateSelector(what: str = 'all') → ndarray[source]

Generate selector given a certain input configuration.

Parameters:: what (str) – input configuration.
Returns:: array composed of 1’s and 0’s selecting the correct sublattice.
Return type:: np.ndarray
Raises:: ValueError – if the argument ‘what’ is invalid.

Warning

RuntimeWarning: if the selection is inconsistent with the system and a default choice is made.

getSpectral(num_kpoints: float, Order: int, NOmegas: int, NSamplesDis: int = 1, verbose: int = 2, eWindow: list | ndarray | None = None) → tuple[source]

Calculate the spectral function.

This calculation is performed the same way as for the GF, the only difference being the states used for evaluating the moments: in this case we directly use the Bloch functions. The band structure is then simply \(-\operatorname{Im}[G_{kk}]/\pi\) for k’s along the correct k path.

Parameters:

num_kpoints (float) – number of kpoints for the spectral function calculation.
Order (int) – Order of the Chebyshev expansion.
NOmegas (int) – Number of frequencies to evaluate.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

spectral function, frequencies and corresponding k-path information.

Return type:

tuple

Calculate the chemical potential.

We calculate the chemical potential as the \(\mu\) which satisfies

\[N = \int\limits dE f(E-\mu) \rho(E)\]

where \(N\) is the number of particles in the system, f is the fermi function and \(\rho(E)\) is the density of states.

In the case of BCS systems, the DOS depends on the chemical potential. This is therefore calculated for every chemical potential and the corresponding number of particles is obtained. A bisection is used starting from the boundaries of the Hamiltonian and honing in on the chemical potential resulting in a number of particles closest to the desired one. Starting from the two values giving slightly more and slightly less particles than needed, a linear extrapolation is finally performed to approximate the energy that results in the occupation closest to the desired one.

TODO: it is probably better to split this calculation in the “one-shot” version and the self-consistent one, suitable for BCS systems.

Parameters:

T (float) – Temperature.
dos (Optional[np.ndarray]) – precoumputed DoS. Will be the 1st one to be used in the BCS case.
w (Optional[np.ndarray]) – frequencies of the precomputed DoS.
NSamples (Optional[int]) – Number of stochastic samples for the DoS calculation.
Order (Optional[int]) – Order of the Chebyshev expansion for the DoS calculation.
NOmegas (Optional[int]) – Number of frequencies for the DoS calculation.
NSamplesDis (int) – Number of disorder configurations for the DoS calculation.
verbose (int) – controls the verbosity of the method.

Raises:

ValueError – if the input is not consistent.

Returns:

Chemical potential.

Return type:

float

getCarrierDensity(dos: ndarray, w: ndarray, mu: float, T: float) → float[source]

Calculate the carrier density.

The calculation is performed by integrating the DoS time the occupation for frequencies larger than the chemical potential and normalizing this by the system’s volume. The formula reads:

\[n = \frac{1}{\Omega} \int\limits_{-\infty}^{\mu} f(E-\mu) \rho(E)\]

where \(\Omega\) is the total volume, \(\mu\) is the chemical potential, f is the fermi function and \(\rho(E)\) is the density of states.

Parameters:

dos (np.ndarray) – Density of states.
w (np.ndarray) – Energies for which the DOS is defined.
mu (float) – Chemical potential.
T (float) – Temperature.

Raises:

ValueError – If dos and w are not compatible.

Returns:

Carrier density in \(Å^{-D}\) with D the dimensionality of the system.

Return type:

float

Calculate the linear DC electric charge susceptibility.

This is equal to

\[\chi_e = \frac{2 \pi}{\Omega} \frac{\partial N}{\partial \mu}\]

where \(\Omega\) is the total volume, N is the number of particles and \(\mu\) the chemical potential.

The routine simply computes the numerical derivative of the number of particles with respect to the chemical potential as an average of energies close to it.

TODO: add possibility to select sublattices, if deemed useful

Parameters:

T (float) – Temperature.
mu (float) – Chemical potential.
dos (Optional[np.ndarray]) – precoumputed DoS.
w (Optional[np.ndarray]) – frequencies of the precomputed DoS.
NSamples (Optional[int]) – Number of stochastic samples for the DoS calculation.
Order (Optional[int]) – Order of the Chebyshev expansion for the DoS calculation.
NOmegas (Optional[int]) – Number of frequencies for the DoS calculation.
NSamplesDis (int) – Number of disorder configurations for the DoS calculation.

Raises:

ValueError – if the input is not consistent.

Returns:

static charge susceptibility of the system.

Return type:

float

Calculate the linear static magnetic susceptibility.

This is equal to

\[\chi_m = \frac{2 \pi}{\Omega} \frac{\partial S_z}{\partial B_z}\]

where \(\Omega\) is the total volume, \(S_z\) is the spin operator in the z direction and \(B_z\) the magnetic field.

The routine simply computes the numerical derivative of the spin expectation value with respect to the applied B field.

TODO: add possibility to select sublattices, if deemed useful

Parameters:

T (float) – Temperature.
mu (float) – Chemical potential.
dos_u (Optional[np.ndarray]) – precoumputed DoS of spin up electrons.
dos_d (Optional[np.ndarray]) – precoumputed DoS of spin down electrons.
w (Optional[np.ndarray]) – frequencies of the precomputed DoS.
NSamples (Optional[int]) – Number of stochastic samples for the DoS calculation.
Order (Optional[int]) – Order of the Chebyshev expansion for the DoS calculation.
NOmegas (Optional[int]) – Number of frequencies for the DoS calculation.
NSamplesDis (int) – Number of disorder configurations for the DoS calculation.

Raises:

ValueError – if the input is not consistent.

Returns:

static magnetic susceptibility of the system.

Return type:

float

getLinearResponse(A: Callable, P: Callable, dtype: type, T: float, mu: float, NSamples: int, Order: int, NPadeFreq: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None) → float | complex[source]

Calculates the static linear response of an observable to a perturbation.

This is done by expanding

\[\chi^A_P = \frac{2 \pi}{\Omega} \frac{\partial \langle \hat{A} \rangle}{\partial \varepsilon}\]

where \(\hat{A}\) is the observable, \(\hat{P}\) the perturbation and \(\varepsilon\) its strength, i.e. the perturbation enters the Hamiltonian as \(\hat{H}' = \varepsilon \hat{P}\) with \(\varepsilon << 1\).

Parameters:

A (Callable) – Linear operator associated with the observable.
P (Callable) – Perturbation in linear operator form.
dtype (type) – dtype of the linear operators.
T (float) – temperature in Kelvins. Must be greater than 0.
mu (float) – chemical potential.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NPadeFreq (int) – Number of Pade frequencies to evaluate the approximation to the Fermi function.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if temperature is too small.

Returns:

expectation value of operator A.

Return type:

Union[float, complex]

getOperator(operator: str) → tuple[Callable, type][source]

Provide basic operators.

Operators available:

±number operator and its left version
±spin operator and its left version
±position and its left version

Parameters:

operator (str) – operator to be returned.

Raises:

NotImplementedError – if the requested operator has not been implemented.

Returns:

tuple contining the operator as a callable acting on an input: array and the dtype of the operator.

Return type:

tuple[Callable, type]

_abc_impl = <_abc._abc_data object>

_dot_scaling(v: ndarray, out: ndarray) → ndarray

Dot product including scaling.

This dot product is needed for evaluating moments of quantities that have not been yet implemented in the lattice solver.

Parameters:

v (np.ndarray) – Vector to dot.
out (np.ndarray) – preallocated output array.

Returns:

Dot product of H with v.

Return type:

np.ndarray

_get_DOS_moments(NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of the density of states.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

NSamples (int) – Number of stochastic samples for the calculation of the DoS.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the density of states

Return type:

np.ndarray

_get_conductivity_moments(tensor_element: str, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of the conductivity.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Moments associated with the conductivity

Return type:

np.ndarray

_get_expectation_value_moments(A: Callable, expectation_value_dtype: type, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of an operator’s expectation value.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

A (Callable) – Linear operator.
expectation_value_dtype (type) – dtype of the linear operator.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the expectation value of operator A.

Return type:

np.ndarray

_set_cheby(force_complex: bool = False) → None

Set the chebyshev object.

Parameters:: force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

_set_scaling_and_cheby(lower_spectral_bound: float = -1, upper_spectral_bound: float = 1, delta: float = 0, force_complex: bool = False) → None

Set the scaling and corresponding chebyshev objects.

Parameters:

lower_spectral_bound (float) – Lower bound of the spectral range. Defaults to -1.
upper_spectral_bound (float) – Upper bound of the spectral range. Defaults to 1.
delta (float) – Spectral buffer for Hamiltonian scaling.
force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

abstract dot(v: ndarray, out: ndarray) → ndarray

Empty dot product. Abstract method: it has to be overloaded.

Parameters:

v (np.ndarray) – Vector to dot.
out (np.ndarray) – preallocated output array.

Raises:

NotImplementedError – In any case, since this method HAS to be overwritten by children classes.

property dtype: Type

Dtype convenience function.

Returns:: complex or float depending on the flag is_complex
Return type:: Type

getBoundsLanczos(Order: int, tolerance: float = 1e-11) → ndarray

Get spectrum boundaries for the current Hamiltonian with the Lanczos method.

Parameters:

Order (int) – Order of the Lanczos expansion
tolerance (float) – Tolerance for the expansion. Defaults to 1e-11.

Returns:

Boundaries of the spectrum.

Return type:

np.ndarray

getConductivity(tensor_element: str, T: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None) → tuple[ndarray, ndarray]

Calculates the conductivity of the system from the Kubo-Greenwood formula.

This routine follows the method presented in https://doi.org/10.1016/j.physrep.2020.12.001

In short: a Chebyshev expansion of the zero temperature Kubo formula is performed. This translates into the expansion of the function \(\delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H})\) \(\hat{V}_{\beta}\), where \(E\) is the energy, \(\hat{H}\) is the Hamiltonian and \(\hat{V}\) is the velocity operator in the direction \(\alpha\,{\rm and }\,\beta\). The conductivity reads

\[\sigma(E) = \frac{\pi \hbar e^2}{\Omega} {\rm Tr}\left[ \delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H}) \right]\]

The temperature dependent result is obtained by simply convolving the zero temperature result by a ‘Fermi window’, i.e. minus the derivative of the Fermi function with respect to the energy.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

getConductivityMu(tensor_element: str, NSamples: int, Order: int, mu: float | ndarray, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None) → float | complex | ndarray

Calculates the conductivity of the system defined by H at a single chemical potential.

Given a Hamiltonian, the corresponding conductivity can be calculated as

\[\sigma(\mu) = \frac{\pi \Omega}{\Delta E^2} \braket{\phi^L|\phi^R}\]

where \(\Omega\) is the volume of the system, \(\Delta E\) is the scaling applied to the Hamiltonian to ensure the spectrum lies within (-1, 1) and the vectors \(\phi\) are

\[ \begin{align}\begin{aligned}\ket{\phi^L} = \sum_n Im[G^+_n(\mu)] T_n(\tilde{H}) V \ket{r}\\\ket{\phi^R} = \sum_n Im[G^+_n(\mu)] V T_n(\tilde{H}) \ket{r}\end{aligned}\end{align} \]

where \(\ket{r}\) is the random vector, \(V\) is the velocity operator, \(G^+_n\) is the n-th GF coefficient and \(T_n(\tilde{H})\) is the m-th Chebyshev polynomial.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
mu (Union[float, np.ndarray]) – Energy(ies) (as in chemical potential) at which to evaluate the conductivity.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the DOS.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Conductivity at the specified chemical potential(s).

Return type:

qt.fl_cmplx_or_ndarr

getConductivityOptical(tensor_element: str, T: float, mu: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None, NOmegasInt: int | None = None) → tuple[ndarray, ndarray]

Calculates the complex optical conductivity of the system.

In short: a Chebyshev expansion of the Kubo formula is performed. The procedure is similar to the one presented in https://journals.aps.org/prb/abstract/10.1103/PhysRevB.94.235405

Details on the routine can be found in the internal notes. In particular, eq. 32 of the notes is implemented.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
mu (float) – Chemical potential.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.
NOmegasInt (Optional[int]) – number of frequencies to use to calculate the E integral.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

getConductivity_KB(tensor_element: str, T: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None, NOmegasInt: int | None = None) → tuple[ndarray, ndarray]

Calculates the conductivity of the system evaluating the Kubo-Bastin formula.

This routine follows the method presented in https://doi.org/10.1103/PhysRevLett.114.116602

In short: a Chebyshev expansion of the Kubo-Bastin formula is performed. This translates into the expansion of the function:

\[v_\alpha \delta(\varepsilon - \hat{H}) \hat{v}_\beta \frac{dG^+(\varepsilon)} {d\varepsilon} - \hat{v}_\alpha \frac{dG^-(\varepsilon)}{d\varepsilon} \hat{v}_\beta \delta(\varepsilon - \hat{H})\]

where \(\varepsilon\) is the energy, \(\hat{H}\) is the Hamiltonian, \(\hat{v}\) is the velocity operator and \(\alpha, \beta\) indicate the direction. The modus operandi is exactly the same as for the other conductivity calculations based on the Chebyshev expansion.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.
NOmegasInt (Optional[int]) – number of frequencies to use to calculate the E integral.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Conductivity and corresponding frequencies.

Return type:

tuple

getDOS(NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None) → tuple[ndarray, ndarray]

Calculates DoS through stochastic averaging of Chebyshev expansion.

This density of states integrates to 1, i.e. it is defined as:

\[\rho(E) = \frac{1}{N} \sum\limits_i \delta(E - E_i) = \frac{1}{N} {\rm Tr} \left[ \delta(E - \hat{H}) \right]\]

with \(E_i\) the eigenvalues of the Hamiltonian and N the number of orbitals.

More details on the calculation are readily available in the literature. For example: https://doi.org/10.1016/j.physrep.2020.12.001

Parameters:

NSamples (int) – Number of stochastic samples for the calculation of the DoS.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of frequencies to evaluate the DoS at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

DoS and corresponding frequencies.

Return type:

tuple

getExpectationValue(A: Callable, dtype: type, T: float, mu: float, NSamples: int, Order: int, NPadeFreq: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None) → float | complex

Calculates the expectation value of an operator through Chebyshev expansion.

This is done by performing the Chebyshev expansion of

\[\langle \hat{A} \rangle = {\rm Tr} \left[ \hat{A} f(\hat{H}) \right]\]

where \(\hat{A}\) is the operator, \(\hat{H}\) is the hamiltonian and f is the fermi function. This expression is expanded in terms of Chebyshev polynomials. The integral over the energies is performed via the resummation of the Fermi-Pade’ expansion of the Fermi function.

Parameters:

A (Callable) – Linear operator.
dtype (type) – dtype of the linear operator.
T (float) – temperature in Kelvins. Must be greater than 0.
mu (float) – chemical potential.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NPadeFreq (int) – Number of Pade frequencies to evaluate the approximation to the Fermi function.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if temperature is too small.

Returns:

expectation value of operator A.

Return type:

Union[float, complex]

Calculate the retarded Green’s Function in the real space basis.

This calculation is performed the same way as for the DOS, the only difference being the states used for evaluating the moments: in this case we directly use the real space basis.

Parameters:

selector (Union[str, ArrayLike]) – specifies what to compute (‘diag’, ‘full’, or array of row-column pairs)
Order (int) – Order of the Chebyshev expansion.
NOmegas (int) – Number of frequencies to evaluate.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.

Returns:

GF and corresponding frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

getTrResolvent(NSamples: int, Order: int, rescale: bool = True, use_KPM: bool = True, verbose: int = 2, selector: ndarray | None = None) → Callable

Returns a function evaluating the trace of the resolvent.

This method computes the Chebyshev moments for a given order and given number of stochastic samples to evaluate the trace. Can be used to evaluate the trace of the resolvent,

\[\mathrm{Tr} \left[ \frac{1}{z - \hat{H}} \right]\]

for a given ‘frequency’ \(z\) without the need to recompute the Chebyshev expansion. This is useful if it is not a priori clear on how many frequencies the trace of the resolvent needs to be evaluated.

The trace of the resolvent will be evaluated at the given frequencies. For real frequencies the retarded resolvent is chosen.

NOTE: The trace is estimated as the average over all (normalized) stochastic samples. Hence, multiply the result by the linear size of the Hamiltonian to get the “true” estimate for the trace.

NOTE: If the number of samples is larger that the size of the selected subspace, the trace is computed exactly (apart from the normalization, see above).

Parameters:

NSamples (int) – Number of stochastic samples to approximate the trace.
Order (int) – Order of the Chebyshev expanbsion to approximate the resolvent.
rescale (bool) – Whether generated function transforms input into interval (-1, 1). Defaults to True.
use_KPM (bool) – Flag controlling the use of KPM.
verbose (int) – Controls verbosity of output and warnings. Defaults to 2.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Returns:

Function evaluating the trace of the resolvent for a given frequency.

Return type:

Callable

parseDisDict(parse_dict: dict) → None

Parse disorder input dictionary.

The disorder dictionary specifies the properties of the disorder:

type: kind of disorder, e.g. onsite (only type implemented for now).

distribution: random distribution of disorder potential.

sigma: standard deviation of the disorder distribution.

avg: mean of distribution.

Note

This will become obsolete with the introduction of a Schema for the disDict.

Parameters:: parse_dict (dict) – Dictionary containing information about the disorder.
Raises:: ValueError – if the dictionary cannot be parsed

scale2real(x: fl_cmplx_or_ndarr) → fl_cmplx_or_ndarr

Apply scaling to transform scaled frequencies to real ones.

Parameters:: x (qt.fl_cmplx_or_ndarr) – array of scaled energies within (-1, 1).
Returns:: Real energies array.
Return type:: qt.fl_cmplx_or_ndarr

scale2transformed(z: fl_cmplx_or_ndarr) → fl_cmplx_or_ndarr

Apply scaling to transform real frequencies to scaled ones.

Parameters:: z (qt.fl_cmplx_or_ndarr) – real energies array.
Returns:: Scaled energies array.
Return type:: qt.fl_cmplx_or_ndarr

scaleH(delta: float = 0.1, LanczOrder: int | None = None, energyBounds: list | ndarray | None = None) → None

Rescale Hamiltonian to have spectrum between -1 and 1.

Parameters:

delta (float) – Controls the extra compression of the band. This will be rescaled to be (-1 + delta/2, 1 - delta/2). Defaults to 0.1.
LanczOrder (Optional[int]) – Order of the Lanczos expansion used to determine the bandwidth. Cannot be set together with energyBounds.
energyBounds (Optional[Union[list, np.ndarray]]) – lower and upper energy boundaries to determine scaling. Cannot be set together with LanczOrder.

Raises:

ValueError – If delta is not in (0, 2).
ValueError – If both LanczOrder and energyBounds are set.

scaleH_inv() → None: Rescale Hamiltonian to have original spectrum.

scrambleW() → None: Function that scrambles the disorder vector.

disDict: dict

disLocPot: np.ndarray

scaling: lsc.chebyshev_scaling

chebyshev: lsc.chebyshev

Hamiltonians

Hamiltonian classes implementation for large systems.

class qolossal.Hamiltonians.HamiltonianSparse(input_dict: dict, disDict: dict | None = None)[source]

Bases: HamiltonianLB

Hamiltonian implementation in full sparse matrix representation.

This implementation is based on the representation of the Hamiltonian in sparse matrix form.

The parent class takes care of the interface with the Lattice Builder, saving the lattice builder instance in the object, for easy access and extracting all the important properties of the system to be used within the package’s methods.

Initialization of the HamiltonianSparse class.

Parameters:

input_dict (dict) – Input dictionary for the Lattice Builder to construct the Hamiltonian
disDict (Optional[dict]) – dictionary specifying the disorder.

__init__(input_dict: dict, disDict: dict | None = None) → None[source]

Initialization of the HamiltonianSparse class.

Parameters:

input_dict (dict) – Input dictionary for the Lattice Builder to construct the Hamiltonian
disDict (Optional[dict]) – dictionary specifying the disorder.

set_Hamiltonian(kpt: ndarray | None = None, mu: float = 0, Bz: float = 0) → None[source]

Hamiltonian setter method.

Parameters:

kpt (Optional[np.ndarray]) – Bloch vector determining phase-shift at periodic boundaries.
mu (float) – additional chemical potential.
Bz (float) – additional Bz field.

dot(v: ndarray, out: ndarray) → ndarray[source]

Calculate the scalar product of H.

Parameters:

v (np.ndarray) – vector to dot the Hamiltonian into.
out (np.ndarray) – preallocated output array.

Returns:

Dot product of H with v

Return type:

np.ndarray

_abc_impl = <_abc._abc_data object>

_dot_scaling(v: ndarray, out: ndarray) → ndarray

Dot product including scaling.

This dot product is needed for evaluating moments of quantities that have not been yet implemented in the lattice solver.

Parameters:

v (np.ndarray) – Vector to dot.
out (np.ndarray) – preallocated output array.

Returns:

Dot product of H with v.

Return type:

np.ndarray

_get_DOS_moments(NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of the density of states.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

NSamples (int) – Number of stochastic samples for the calculation of the DoS.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the density of states

Return type:

np.ndarray

_get_conductivity_moments(tensor_element: str, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of the conductivity.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.

Raises:

ValueError – if the velocity operator is not set for the current object.

Returns:

Moments associated with the conductivity

Return type:

np.ndarray

_get_expectation_value_moments(A: Callable, expectation_value_dtype: type, NSamples: int, Order: int, NSamplesDis: int, verbose: int, selector: ndarray) → ndarray

Calculates the moments of the Chebyshev expansion of an operator’s expectation value.

Only meant for internal and expert usage. This method does not implement any failsafe mechanism or consistency checks.

Parameters:

A (Callable) – Linear operator.
expectation_value_dtype (type) – dtype of the linear operator.
NSamples (int) – Number of stochastic samples.
Order (int) – Order of the Chebyshev expansion used for the calculation
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – controls verbosity of output and warnings.
selector (np.ndarray) – selects a sublattice of interest for the calculation.

Returns:

Moments associated with the expectation value of operator A.

Return type:

np.ndarray

_set_cheby(force_complex: bool = False) → None

Set the chebyshev object.

Parameters:: force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

_set_scaling_and_cheby(lower_spectral_bound: float = -1, upper_spectral_bound: float = 1, delta: float = 0, force_complex: bool = False) → None

Set the scaling and corresponding chebyshev objects.

Parameters:

lower_spectral_bound (float) – Lower bound of the spectral range. Defaults to -1.
upper_spectral_bound (float) – Upper bound of the spectral range. Defaults to 1.
delta (float) – Spectral buffer for Hamiltonian scaling.
force_complex (bool) – Flag for forcing complex chebyshev objects. Defaults to False.

property dtype: Type

Dtype convenience function.

Returns:: complex or float depending on the flag is_complex
Return type:: Type

generateSelector(what: str = 'all') → ndarray

Generate selector given a certain input configuration.

Parameters:: what (str) – input configuration.
Returns:: array composed of 1’s and 0’s selecting the correct sublattice.
Return type:: np.ndarray
Raises:: ValueError – if the argument ‘what’ is invalid.

Warning

RuntimeWarning: if the selection is inconsistent with the system and a default choice is made.

getBoundsLanczos(Order: int, tolerance: float = 1e-11) → ndarray

Get spectrum boundaries for the current Hamiltonian with the Lanczos method.

Parameters:

Order (int) – Order of the Lanczos expansion
tolerance (float) – Tolerance for the expansion. Defaults to 1e-11.

Returns:

Boundaries of the spectrum.

Return type:

np.ndarray

getCarrierDensity(dos: ndarray, w: ndarray, mu: float, T: float) → float

Calculate the carrier density.

The calculation is performed by integrating the DoS time the occupation for frequencies larger than the chemical potential and normalizing this by the system’s volume. The formula reads:

\[n = \frac{1}{\Omega} \int\limits_{-\infty}^{\mu} f(E-\mu) \rho(E)\]

where \(\Omega\) is the total volume, \(\mu\) is the chemical potential, f is the fermi function and \(\rho(E)\) is the density of states.

Parameters:

dos (np.ndarray) – Density of states.
w (np.ndarray) – Energies for which the DOS is defined.
mu (float) – Chemical potential.
T (float) – Temperature.

Raises:

ValueError – If dos and w are not compatible.

Returns:

Carrier density in \(Å^{-D}\) with D the dimensionality of the system.

Return type:

float

Calculate the linear DC electric charge susceptibility.

This is equal to

\[\chi_e = \frac{2 \pi}{\Omega} \frac{\partial N}{\partial \mu}\]

where \(\Omega\) is the total volume, N is the number of particles and \(\mu\) the chemical potential.

The routine simply computes the numerical derivative of the number of particles with respect to the chemical potential as an average of energies close to it.

TODO: add possibility to select sublattices, if deemed useful

Parameters:

T (float) – Temperature.
mu (float) – Chemical potential.
dos (Optional[np.ndarray]) – precoumputed DoS.
w (Optional[np.ndarray]) – frequencies of the precomputed DoS.
NSamples (Optional[int]) – Number of stochastic samples for the DoS calculation.
Order (Optional[int]) – Order of the Chebyshev expansion for the DoS calculation.
NOmegas (Optional[int]) – Number of frequencies for the DoS calculation.
NSamplesDis (int) – Number of disorder configurations for the DoS calculation.

Raises:

ValueError – if the input is not consistent.

Returns:

static charge susceptibility of the system.

Return type:

float

getConductivity(tensor_element: str, T: float, NSamples: int, Order: int, NOmegas: int = 101, NSamplesDis: int = 1, verbose: int = 2, selector: ndarray | None = None, eWindow: list | ndarray | None = None) → tuple[ndarray, ndarray]

Calculates the conductivity of the system from the Kubo-Greenwood formula.

This routine follows the method presented in https://doi.org/10.1016/j.physrep.2020.12.001

In short: a Chebyshev expansion of the zero temperature Kubo formula is performed. This translates into the expansion of the function \(\delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H})\) \(\hat{V}_{\beta}\), where \(E\) is the energy, \(\hat{H}\) is the Hamiltonian and \(\hat{V}\) is the velocity operator in the direction \(\alpha\,{\rm and }\,\beta\). The conductivity reads

\[\sigma(E) = \frac{\pi \hbar e^2}{\Omega} {\rm Tr}\left[ \delta(E - \hat{H}) \hat{V}_{\alpha} \delta(E - \hat{H}) \right]\]

The temperature dependent result is obtained by simply convolving the zero temperature result by a ‘Fermi window’, i.e. minus the derivative of the Fermi function with respect to the energy.

NOTE: the output of this routine is in units of \(e^2/(h Å^{(D-2)})\) with D the dimensionality of the system and does NOT include any spin- degeneracy coefficients for spinless systems.

Parameters:

tensor_element (str) – specifies which element of the conductivity tensor to calculate, as literal, e.g. ‘xx’.
T (float) – Temperature in Kelvins.
NSamples (int) – Number of stochastic samples for the calculation of the conductivity.
Order (int) – Order of the Chebyshev expansion used for the calculation
NOmegas (int) – Number of energies to evaluate the conductivity at. Defaults to 101.
NSamplesDis (int) – Number of disorder configurations to average over.
verbose (int) – verbosity of routine. Defaults to 1.
selector (Optional[np.ndarray]) – selects a sublattice of interest for the calculation.
eWindow (Optional[Union[list, np.ndarray]]) – energy window for the result.