LocalDensityOfStates¶

class LocalDensityOfStates(configuration, kpoints=None, energies=None, energy_zero_parameter=None, band_indices=None, spectrum_method=None, density_mesh_cutoff=None)¶

Class for calculating the partial electron density.

Parameters:

configuration (BulkConfiguration | MoleculeConfiguration) – The configuration with an attached calculator for which to calculate the partial electron density.
kpoints – The k-points for which to perform the calculation. This can either be given as a k-point grid or a list of fractional k-points, e.g., [[0.0, 0.0, 0.0], [0.0, 0.0, 0.1], ...].
Default: The Monkhorst-Pack grid used for the self-consistent calculation.
energies (PhysicalQuantity of type energy) – The energies for which to calculate the projected density of states. The energies are relative to the zero of energy specified in energy_zero_parameter.
Default: numpy.arange(-1.0, 1.0, 0.01) * eV
energy_zero_parameter (FermiLevel | AbsoluteEnergy) – Specifies the choice for the energy zero.
Default: FermiLevel
band_indices (list of int) – The band indices of the Bloch states to include in the partial density.
Default: All occupied bands
spectrum_method (GaussianBroadening) – The method to use for calculating the partial electron density.
Default: GaussianBroadening(0.1*eV)
density_mesh_cutoff (PhysicalQuantity of type energy | GridSampling | OptimizedFFTGridSampling) – The mesh cutoff to be used to determine the grid sampling. The mesh cutoff must be a positive energy or a GridSampling object.
Default: Specific for each calculator.

bandIndices()¶

Returns:: The band indicies to include in the partial electron density.
Return type:: list of int.

energies()¶

Returns:: The energies.
Return type:: PhysicalQuantity of type energy

energyZero()¶

Returns:: The energy zero.
Return type:: PhysicalQuantity of type energy.

evaluate(x, y, z, spin=None)¶

Evaluate in the point (x, y, z).

Parameters:

x (PhysicalQuantity with type length) – The Cartesian x coordinate.
y (PhysicalQuantity with type length) – The Cartesian y coordinate.
z (PhysicalQuantity with type length) – The Cartesian z coordinate.
spin (Spin.All | Spin.Sum | Spin.Up | Spin.Down | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
Default: Spin.All

Returns:

The values for each energy at the specified point for the given spin. For Spin.All, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned.

Return type:

PhysicalQuantity of type length^-3 * energy ^-1

fermiLevel(spin=None)¶

Parameters:: spin (Spin.Up | Spin.Down | Spin.All) – The spin the Fermi level should be returned for. Must be either Spin.Up, Spin.Down, or Spin.All. Only when the band structure is calculated with a fixed spin moment will the Fermi level depend on spin.
Default: Spin.Up
Returns:: The Fermi level in absolute energy.
Return type:: PhysicalQuantity of type energy

kpoints()¶

Returns:: The kpoints given as input.
Return type:: MonkhorstPackGrid | RegularKpointGrid | numpy.ndarray

localDensityOfStateAtEnergyIndex(energy_index=None)¶

Return the local density of states for a particular energy index.

Parameters:: enegy_index (int) – The index of the energy for which to return the local density of states.
Returns:: A GridValues object with the local dos at a particular energy.
Return type:: GridValues

metatext()¶

Returns:: The metatext of the object or None if no metatext is present.
Return type:: str | None

nlprint(stream=None)¶

Print a string containing an ASCII table useful for plotting the AnalysisSpin object.

Parameters:: stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger()

setMetatext(metatext)¶

Set a given metatext string on the object.

Parameters:: metatext (str | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.

spectrumMethod()¶

Returns:: The method used for calculating the partial electron density.
Return type:: GaussianBroadening

uniqueString()¶: Return a unique string representing the state of the object.

Usage Examples¶

Analyze the local density of states of a silver (111) surface. This structure is characterized by a surface state around the \(\Gamma\)-point. In the example, the kpoint sampling is specified with a RegularKpointGrid in a kpoint region around the \(\Gamma\)-point.

# -*- coding: utf-8 -*-
setVerbosity(MinimalLog)

# -------------------------------------------------------------
# Bulk Configuration
# -------------------------------------------------------------

# Set up lattice
vector_a = [2.88903, 0.0, 0.0]*Angstrom
vector_b = [-1.44451, 2.50197, 0.0]*Angstrom
vector_c = [0.0, 0.0, 40.0]*Angstrom
lattice = UnitCell(vector_a, vector_b, vector_c)

# Define elements
elements = [Silver, Silver, Silver, Silver, Silver, Silver, Silver, Silver,
            Silver, Silver, Silver, Silver]

# Define coordinates
fractional_coordinates = [[ 0.749999669084,  0.5           ,  0.175654000711],
                          [ 0.749999669084,  0.5           ,  0.352570000323],
                          [ 0.749999669084,  0.5           ,  0.529485999935],
                          [ 0.749999669084,  0.5           ,  0.706401999547],
                          [ 0.416666424719,  0.833333341397,  0.234626000582],
                          [ 0.416666424719,  0.833333341397,  0.411542000194],
                          [ 0.416666424719,  0.833333341397,  0.588457999806],
                          [ 0.416666424719,  0.833333341397,  0.765373999418],
                          [ 0.083334237113,  0.166666658603,  0.293598000453],
                          [ 0.083334237113,  0.166666658603,  0.470514000065],
                          [ 0.083334237113,  0.166666658603,  0.647429999677],
                          [ 0.083334237113,  0.166666658603,  0.824345999289]]

# Set up configuration
bulk_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=elements,
    fractional_coordinates=fractional_coordinates
    )

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
#----------------------------------------
# Exchange-Correlation
#----------------------------------------
exchange_correlation = LDA.PZ

k_point_sampling = MonkhorstPackGrid(
    na=11,
    nb=11,
    )
numerical_accuracy_parameters = NumericalAccuracyParameters(
    density_mesh_cutoff=45.0*Hartree,
    k_point_sampling=k_point_sampling,
    )

calculator = LCAOCalculator(
    exchange_correlation=exchange_correlation,
    numerical_accuracy_parameters=numerical_accuracy_parameters,
    )

bulk_configuration.setCalculator(calculator)
nlprint(bulk_configuration)
bulk_configuration.update()
nlsave('local-density-of-states.hdf5', bulk_configuration)

# -------------------------------------------------------------
# Local Density Of States
# -------------------------------------------------------------
kpoints = RegularKpointGrid(
    ka_range=[-0.05, 0.05],
    kb_range=[-0.05, 0.05],
    kc_range=[0.0, 0.0],
    na=5,
    nb=5,
    nc=1,
    )

local_density_of_states = LocalDensityOfStates(
    configuration=bulk_configuration,
    kpoints=kpoints,
    energies=numpy.linspace(-1, 1, 101)*eV,
    band_indices=All,
    energy_zero_parameter=FermiLevel,
    spectrum_method=GaussianBroadening(0.1*eV),
    )
nlsave('local-density-of-states.hdf5', local_density_of_states)

local_density_of_states.py

Notes¶

The LocalDensityOfStates can be calculated by specifying the

energies. The local density of states will be calculated at the specified energies.

band_indices. Only states from the specified band indices will contribute to the partial electron density. By default, all bands are taken into account and the selection is determined by the energy range.

kpoints. The partial electron density is calculated from the eigenstates at the specified k-points.

spectrum_method. The method used to integrate the density of states. Currently only GaussianBroadening is supported. Each electronic state is assigned a gaussian weight determined by the eigenvalue and gaussian broadening.

The local density of states is defined as:

\[\begin{split}\begin{align*} D(E, \mathbf{r}) &= \sum_{i}\sum_\mathbf{k} w_{\mathbf{k}} |\psi_{i,\mathbf{k}}(\mathbf{r})|^2 \delta(E - \epsilon_{i,\mathbf{k}}) , \\ &\approx \sum_{i}\sum_\mathbf{k} w_{\mathbf{k}} |\psi_{i,\mathbf{k}}(\mathbf{r})|^2 w(E, \epsilon_{i,\mathbf{k}}) , \end{align*}\end{split}\]

where the sum over band indices \(i\) includes only the specified bands (by default all bands). The weights \(w_{\mathbf{k}}\) and \(w(E, \epsilon_{i,\mathbf{k}})\) are the k-point weights and the Gaussian weights, respectively. The energy dependent Gaussian weight is computed with a normalized Gaussian centered at \(\epsilon_{i,\mathbf{k}}\) with standard deviation \(\sigma\) over the specified energy range, i.e.

\[\begin{align*} w(\epsilon_{i,\mathbf{k}}) &= \frac{1}{\sqrt{2 \pi \sigma^2}} \exp\left(-\frac{\left(E - \epsilon_{i,\mathbf{k}}\right)^2}{2 \sigma^2}\right) \end{align*}\]

Tersoff-Hamann approximation of simulated STM¶

The LocalDensityOfStates can be used to simulate scanning tunneling microscopy (STM) images within the Tersoff-Hamann approximation [1] assuming that the tip wave function has s-orbital character. When simulating an STM image, the energy can be interpreted as the bias difference applied between the tip and the surface and the LocalDensityOfStates represents the STM \(dI/dV\) measurement.

Notice that the Tersoff-Hamann approximation is the simplest approach to simulated STM images and it is not always applicable. Also bare in mind that far away from a surface the partial density will be zero for an LCAO calculation since the basis orbitals have a finite range.