pymatgen.electronic_structure.dos module¶
This module defines classes to represent the density of states, etc.
-
class
CompleteDos(structure, total_dos, pdoss)[source]¶ Bases:
pymatgen.electronic_structure.dos.DosThis wrapper class defines a total dos, and also provides a list of PDos. Mainly used by pymatgen.io.vasp.Vasprun to create a complete Dos from a vasprun.xml file. You are unlikely to try to generate this object manually.
- Parameters
structure – Structure associated with this particular DOS.
total_dos – total Dos for structure
pdoss – The pdoss are supplied as an {Site:{Orbital:{ Spin:Densities}}}
-
get_element_spd_dos(el)[source]¶ Get element and spd projected Dos
- Parameters
el – Element in Structure.composition associated with CompleteDos
- Returns
{“S”: densities, “P”: densities, “D”: densities}}
- Return type
dict of {Element
-
get_site_dos(site)[source]¶ Get the total Dos for a site (all orbitals).
- Parameters
site – Site in Structure associated with CompleteDos.
- Returns
Dos containing summed orbital densities for site.
-
get_site_orbital_dos(site, orbital)[source]¶ Get the Dos for a particular orbital of a particular site.
- Parameters
site – Site in Structure associated with CompleteDos.
orbital – Orbital in the site.
- Returns
Dos containing densities for orbital of site.
-
get_site_spd_dos(site)[source]¶ Get orbital projected Dos of a particular site
- Parameters
site – Site in Structure associated with CompleteDos.
- Returns
Dos}, e.g. {“s”: Dos object, …}
- Return type
dict of {orbital
-
get_site_t2g_eg_resolved_dos(site)[source]¶ Get the t2g, eg projected DOS for a particular site.
- Parameters
site – Site in Structure associated with CompleteDos.
- Returns
Dos, “t2g”: Dos} containing summed e_g and t2g DOS for the site.
- Return type
A dict {“e_g”
-
class
DOS(energies, densities, efermi)[source]¶ Bases:
pymatgen.core.spectrum.SpectrumReplacement basic DOS object. All other DOS objects are extended versions of this object. Work in progress.
- Parameters
energies – A sequence of energies
densities (ndarray) – Either a Nx1 or a Nx2 array. If former, it is interpreted as a Spin.up only density. Otherwise, the first column is interpreted as Spin.up and the other is Spin.down.
efermi – Fermi level energy.
-
get_cbm_vbm(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the cbm and vbm.
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – An absolute tolerance (True) and a relative one (False)
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
float in eV corresponding to the gap
- Return type
(cbm, vbm)
-
get_gap(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the gap.
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – An absolute tolerance (True) and a relative one (False)
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
gap in eV
-
get_interpolated_gap(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the gap
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – Set to True for an absolute tolerance and False for a relative one.
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
Tuple of floats in eV corresponding to the gap, cbm and vbm.
- Return type
(gap, cbm, vbm)
-
class
Dos(efermi, energies, densities)[source]¶ Bases:
monty.json.MSONableBasic DOS object. All other DOS objects are extended versions of this object.
- Parameters
efermi – Fermi level energy
energies – A sequences of energies
({Spin (densities) – np.array}): representing the density of states for each Spin.
-
get_cbm_vbm(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the cbm and vbm.
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – An absolute tolerance (True) and a relative one (False)
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
float in eV corresponding to the gap
- Return type
(cbm, vbm)
-
get_densities(spin=None)[source]¶ Returns the density of states for a particular spin.
- Parameters
spin – Spin
- Returns
Returns the density of states for a particular spin. If Spin is None, the sum of all spins is returned.
-
get_gap(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the gap.
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – An absolute tolerance (True) and a relative one (False)
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
gap in eV
-
get_interpolated_gap(tol=0.001, abs_tol=False, spin=None)[source]¶ Expects a DOS object and finds the gap
- Parameters
tol – tolerance in occupations for determining the gap
abs_tol – Set to True for an absolute tolerance and False for a relative one.
spin – Possible values are None - finds the gap in the summed densities, Up - finds the gap in the up spin channel, Down - finds the gap in the down spin channel.
- Returns
Tuple of floats in eV corresponding to the gap, cbm and vbm.
- Return type
(gap, cbm, vbm)
-
class
FermiDos(dos: pymatgen.electronic_structure.dos.Dos, structure: pymatgen.core.structure.Structure = None, nelecs: float = None, bandgap: float = None)[source]¶ Bases:
pymatgen.electronic_structure.dos.Dos,monty.json.MSONableThis wrapper class helps relate the density of states, doping levels (i.e. carrier concentrations) and corresponding fermi levels. A negative doping concentration indicates the majority carriers are electrons (n-type doping); a positive doping concentration indicates holes are the majority carriers (p-type doping).
- Parameters
dos – Pymatgen Dos object.
structure – A structure. If not provided, the structure of the dos object will be used. If the dos does not have an associated structure object, an error will be thrown.
nelecs – The number of electrons included in the energy range of dos. It is used for normalizing the densities. Default is the total number of electrons in the structure.
bandgap – If set, the energy values are scissored so that the electronic band gap matches this value.
-
get_doping(fermi_level: float, temperature: float) → float[source]¶ Calculate the doping (majority carrier concentration) at a given fermi level and temperature. A simple Left Riemann sum is used for integrating the density of states over energy & equilibrium Fermi-Dirac distribution.
- Parameters
fermi_level – The fermi_level level in eV.
temperature – The temperature in Kelvin.
- Returns
The doping concentration in units of 1/cm^3. Negative values indicate that the majority carriers are electrons (n-type doping) whereas positivie values indicates the majority carriers are holes (p-type doping).
-
get_fermi(concentration: float, temperature: float, rtol: float = 0.01, nstep: int = 50, step: float = 0.1, precision: int = 8)[source]¶ Finds the fermi level at which the doping concentration at the given temperature (T) is equal to concentration. A greedy algorithm is used where the relative error is minimized by calculating the doping at a grid which continually becomes finer.
- Parameters
concentration – The doping concentration in 1/cm^3. Negative values represent n-type doping and positive values represent p-type doping.
temperature – The temperature in Kelvin.
rtol – The maximum acceptable relative error.
nstep – THe number of steps checked around a given fermi level.
step – Initial step in energy when searching for the Fermi level.
precision – Essentially the decimal places of calculated Fermi level.
- Returns
The fermi level in eV.. Note that this is different from the default dos.efermi.
-
get_fermi_interextrapolated(concentration: float, temperature: float, warn: bool = True, c_ref: float = 10000000000.0, **kwargs) → float[source]¶ Similar to get_fermi except that when get_fermi fails to converge, an interpolated or extrapolated fermi is returned with the assumption that the fermi level changes linearly with log(abs(concentration)).
- Parameters
concentration – The doping concentration in 1/cm^3. Negative values represent n-type doping and positive values represent p-type doping.
temperature – The temperature in Kelvin.
warn – Whether to give a warning the first time the fermi cannot be found.
c_ref – A doping concentration where get_fermi returns a value without error for both c_ref and -c_ref.
**kwargs – Keyword arguments passed to the get_fermi function.
- Returns
The Fermi level. Note, the value is possibly interpolated or extrapolated and must be used with caution.
-
class
LobsterCompleteDos(structure, total_dos, pdoss)[source]¶ Bases:
pymatgen.electronic_structure.dos.CompleteDosExtended CompleteDOS for Lobster
- Parameters
structure – Structure associated with this particular DOS.
total_dos – total Dos for structure
pdoss – The pdoss are supplied as an {Site:{Orbital:{ Spin:Densities}}}
-
get_element_spd_dos(el)[source]¶ Get element and spd projected Dos
- Parameters
el – Element in Structure.composition associated with LobsterCompleteDos
- Returns
{“S”: densities, “P”: densities, “D”: densities}}
- Return type
dict of {Element
-
get_site_orbital_dos(site, orbital)[source]¶ Get the Dos for a particular orbital of a particular site.
- Parameters
site – Site in Structure associated with CompleteDos.
orbital – principal quantum number and orbital in string format, e.g. “4s”. possible orbitals are: “s”, “p_y”, “p_z”, “p_x”, “d_xy”, “d_yz”, “d_z^2”, “d_xz”, “d_x^2-y^2”, “f_y(3x^2-y^2)”, “f_xyz”, “f_yz^2”, “f_z^3”, “f_xz^2”, “f_z(x^2-y^2)”, “f_x(x^2-3y^2)” In contrast to the Cohpcar and the Cohplist objects, the strings from the Lobster files are used
- Returns
Dos containing densities of an orbital of a specific site.