ProjectedDensityOfStates¶

class ProjectedDensityOfStates(configuration, kpoints=None, projections=None, energies=None, energy_zero_parameter=None, bands_above_fermi_level=None, spectrum_method=None)¶

Class for calculating the projected density of states for a configuration.

Parameters:

configuration (BulkConfiguration | MoleculeConfiguration) – The configuration with an attached calculator for which to calculate the projected density of states.
kpoints – The k-points for which to calculate the projected density of states.
Default: The Monkhorst-Pack grid used for the self-consistent calculation.
projections (list of Projection | Projection | ProjectionGenerator) – The projections used for the calculating the weights.
Default: [Projection(spin=Spin.Up), Projection(spin=Spin.Down)].
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(-2.0, 2.0, 0.01) * eV
energy_zero_parameter (FermiLevel | AbsoluteEnergy) – Specifies the choice for the energy zero.
Default: FermiLevel
bands_above_fermi_level (int | All) – The number of bands above the Fermi level per principal spin channel. Must be a non-negative integer.
Default: All (All bands are included).
spectrum_method (GaussianBroadening | TetrahedronMethod | Automatic) – The method to use for calculating the projected density of states. If Automatic is set then the tetrahedron method is used if there are more than 10 k-points in any direction, else the Gaussian broadening method is used.
Default: TetrahedronMethod for BulkConfigurations and GaussianBroadening for MoleculeConfigurations.

bandsAboveFermiLevel()¶

Returns:: The number of bands above the Fermi level per principal spin channel.
Return type:: int

densityOfStates(normalization=None)¶

Returns the possible normalized density of states.

Parameters:: normalization (False` | NormalizeByVolume() | NormalizeByNumberOfAtoms()) – Normalization scheme to use for the DOS.
Default: False
Returns:: The full density of states as a vector of the length of the number of energies.
Return type:: PhysicalQuantity of type reciprocal energy

directBandGap()¶

Returns:: The direct band gap.
Return type:: PhysicalQuantity of type energy

energies()¶

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

energyZero()¶

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

evaluate(projection_index=None, normalization=None)¶

The projected density of states for a given projection.

Parameters:

projection_index (int) – The index of the projection to query the projected density of states for. Negative indexing can be used such that e.g. projection_index=-1 will return the projected density of states for the last projection.
Default: The projected density of states for each projection is returned.
normalization (False` | NormalizeByVolume() | NormalizeByNumberOfAtoms()) – Normalization scheme to use for the DOS.
Default: False

Returns:

The projected density of states as a vector of the length of the number of energies, e. If projection_index is not specified, an array of shape (p, e) is returned, where p is the number of projections.

Return type:

PhysicalQuantity of type reciprocal energy

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

indirectBandGap()¶

Returns:: The indirect band gap.
Return type:: PhysicalQuantity of type energy

kpoints()¶

Returns:: The k-point sampling used for calculating the projected density of states.
Return type:: MonkhorstPackGrid | RegularKpointGrid

metatext()¶

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

nlinfo()¶

Returns:: Structured information about the PDOS.
Return type:: dict

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

projections()¶

Returns:: The projections used for the calculated projected density of states.
Return type:: list of class:~.Projection | class:~.Projection

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.

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

Usage Example¶

Calculate the Projected Density of States for bulk gallium arsenide, by projecting on each shell per each element

lattice = FaceCenteredCubic(5.6537*Angstrom)
elements = [Gallium, Arsenic]
fractional_coordinates = [[ 0.  ,  0.  ,  0.  ],
                                  [ 0.25,  0.25,  0.25]]

bulk_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=elements,
    fractional_coordinates=fractional_coordinates
    )

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
k_point_sampling = MonkhorstPackGrid(7, 7, 7)

numerical_accuracy_parameters = NumericalAccuracyParameters(
            k_point_sampling=k_point_sampling,
                )

calculator = LCAOCalculator(
            numerical_accuracy_parameters=numerical_accuracy_parameters,
                )

bulk_configuration.setCalculator(calculator)
bulk_configuration.update()

# -------------------------------------------------------------
# ProjectedDensityOfStates
# -------------------------------------------------------------
pdos = ProjectedDensityOfStates(
    configuration=bulk_configuration,
    projections=ProjectOnShellsByElement,
    kpoints=MonkhorstPackGrid(11, 11, 11),
    energies=numpy.arange(-4.0, 4.0, 0.01) * eV
    )

gaas_pdos.py

The same resuls can be obtained by defining explicitely the list of projections:

# -------------------------------------------------------------
# ProjectedDensityOfStates
# -------------------------------------------------------------
projections = [Projection(l_quantum_numbers=[0], atoms=[Gallium]),
               Projection(l_quantum_numbers=[1], atoms=[Gallium]),
               Projection(l_quantum_numbers=[2], atoms=[Gallium]),
               Projection(l_quantum_numbers=[0], atoms=[Arsenic]),
               Projection(l_quantum_numbers=[1], atoms=[Arsenic]),
               Projection(l_quantum_numbers=[2], atoms=[Arsenic]),]

pdos = ProjectedDensityOfStates(
    configuration=bulk_configuration,
    projections=projections,
    kpoints=MonkhorstPackGrid(11, 11, 11),
    energies=numpy.arange(-4.0, 4.0, 0.01) * eV)

More flexible projections can be achieved with algebraic operations, refer to the the documentation of Projection.

Notes¶

The ProjectedDensityOfStates is used to visualize the contribution of different orbitals to the density of states.

Recalling that the density of states can be written as

\[D(\epsilon) = \sum_{n} \delta \left(\epsilon - \epsilon _{n} \right)\]

where \(n\) includes all the quantum numbers of the system, we can define the Projected Density of States associated to a given projection M as

\[D _{M}(\epsilon) = \sum_{n} \delta \left(\epsilon - \epsilon _{n} \right) \langle \psi_{n} | \hat{\bf P}_M | \psi_{n } \rangle\]

\(\psi_{n }\) are the eigenstates and \(\hat{\bf P}_M\) is a projection operator defined according to the description contained in the documentation of Projection.

Note

The ProjectedDensityOfStates will always be positive (in units of \(\mathrm{eV}^{-1}\)) for projections on up/down spin, but might be both positive and negative (in units of \(\frac{\hbar}{2} \mathrm{eV}^{-1}\)) for projections involving the Pauli spin matrices. See the Usage Example in Projection for some more information.