pymatgen.electronic_structure.dos module¶

class
CompleteDos
(structure, total_dos, pdoss)[source]¶ Bases:
pymatgen.electronic_structure.dos.Dos
This 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}}}

structure
¶ Structure associated with the CompleteDos.

pdos
¶ Dict of partial densities of the form {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”

get_spd_dos
()[source]¶ Get orbital projected Dos.
 Returns
Dos}, e.g. {“s”: Dos object, …}
 Return type
dict of {orbital

spin_polarization
¶ Calculates spin polarization at Fermi level.
See Sanvito et al., doi: 10.1126/sciadv.1602241 for an example usage.
 Return (float)
spin polarization in range [0, 1],
will also return NaN if spin polarization illdefined (e.g. for insulator)

class
DOS
(energies, densities, efermi)[source]¶ Bases:
pymatgen.core.spectrum.Spectrum
Replacement 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.

XLABEL
= 'Energy'¶

YLABEL
= 'Density'¶

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.MSONable
Basic 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, structure=None, nelecs=None, bandgap=None)[source]¶ Bases:
pymatgen.electronic_structure.dos.Dos
This wrapper class helps relates the density of states, doping levels (i.e. carrier concentrations) and corresponding fermi levels. A negative doping concentration (c) means that the majority carriers are electrons (ntype doping) and positive c represents holes or ptype doping.
 Parameters
dos (pymatgen Dos class) – density of states at corresponding energy levels
structure (pymatgen Structure class) – provided either as input or inside Dos (e.g. if CompleteDos used)
nelecs (float) – 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 (float) – if set, the energy values are scissored so that the electronic band gap matches this value.

get_doping
(fermi, T)[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 FermiDirac distribution
 Parameters
fermi (float) – the fermi level in eV
T (float) – the temperature in Kelvin
 Returns (float): in units 1/cm3. If negative it means that the majority
carriers are electrons (ntype doping) and if positive holes/ptype

get_fermi
(c, T, rtol=0.01, nstep=50, step=0.1, precision=8)[source]¶ Finds the fermi level at which the doping concentration at the given temperature (T) is equal to c. A greedy algorithm is used where the relative error is minimized by calculating the doping at a grid which is continuously become finer.
 Parameters
c (float) – doping concentration. c<0 represents ntype doping and c>0 represents ptype doping (i.e. majority carriers are holes)
T (float) – absolute temperature in Kelvin
rtol (float) – maximum acceptable relative error
nstep (int) – number of steps checked around a given fermi level
step (float) – initial step in fermi level when searching
precision (int) – essentially the decimal places of calculated fermi
 Returns (float): the fermi level. Note that this is different from the
default dos.efermi.

get_fermi_interextrapolated
(c, T, warn=True, c_ref=10000000000.0, **kwargs)[source]¶ Similar to get_fermi except that when get_fermi fails to converge, an interpolated or extrapolated fermi (depending on c) is returned with the assumption that the fermi level changes linearly with log(abs(c)).
 Parameters
c (float) – doping concentration in 1/cm3. c<0 represents ntype doping and c>0 ptype doping (i.e. majority carriers are holes)
T (float) – absolute temperature in Kelvin
warn (bool) – whether to warn for the first time when no fermi can be found.
c_ref (float) – a doping concentration where get_fermi returns a value without error for both c_ref and c_ref
**kwargs – see keyword arguments of the get_fermi function
 Returns (float): the fermi level that is possibly interapolated or
extrapolated and must be used with caution.

class
LobsterCompleteDos
(structure, total_dos, pdoss)[source]¶ Bases:
pymatgen.electronic_structure.dos.CompleteDos
Extended CompleteDOS for Lobster

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^2y^2”, “f_y(3x^2y^2)”, “f_xyz”, “f_yz^2”, “f_z^3”, “f_xz^2”, “f_z(x^2y^2)”, “f_x(x^23y^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.
