# pymatgen.electronic_structure.dos module¶

class CompleteDos(structure, total_dos, pdoss)[source]

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}}}

as_dict()[source]

Json-serializable dict representation of CompleteDos.

classmethod from_dict(d)[source]

Returns CompleteDos object from dict representation.

get_element_dos()[source]

Get element projected Dos.

Returns: Dos} dict of {Element
get_element_spd_dos(el)[source]

Get element and spd projected Dos

Parameters: el – Element in Structure.composition associated with CompleteDos {“S”: densities, “P”: densities, “D”: densities}} 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. 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. 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. Dos}, e.g. {“s”: Dos object, …} 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. Dos, “t2g”: Dos} containing summed e_g and t2g DOS for the site. A dict {“e_g”
get_spd_dos()[source]

Get orbital projected Dos.

Returns: Dos}, e.g. {“s”: Dos object, …} 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 ill-defined (e.g. for insulator)

class DOS(energies, densities, efermi)[source]

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. float in eV corresponding to the gap (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. 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. Tuple of floats in eV corresponding to the gap, cbm and vbm. (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.
as_dict()[source]

Json-serializable dict representation of Dos.

classmethod from_dict(d)[source]

Returns Dos object from dict representation of Dos.

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. float in eV corresponding to the gap (cbm, vbm)
get_densities(spin=None)[source]

Returns the density of states for a particular spin.

Parameters: spin – Spin 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. 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. Tuple of floats in eV corresponding to the gap, cbm and vbm. (gap, cbm, vbm)
get_interpolated_value(energy)[source]

Returns interpolated density for a particular energy.

Parameters: energy – Energy to return the density for.
get_smeared_densities(sigma)[source]

Returns the Dict representation of the densities, {Spin: densities}, but with a Gaussian smearing of std dev sigma applied about the fermi level.

Parameters: sigma – Std dev of Gaussian smearing function. Dict of Gaussian-smeared densities.
class FermiDos(dos, structure=None, nelecs=None, bandgap=None)[source]

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 (n-type doping) and positive c represents holes or p-type 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 Fermi-Dirac 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 (n-type doping) and if positive holes/p-type
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 n-type doping and c>0 represents p-type 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.
add_densities(density1, density2)[source]

Method to sum two densities.

Parameters: density1 – First density. density2 – Second density. density}. Dict of {spin
f0(E, fermi, T)[source]

Returns the equilibrium fermi-dirac. :param E: energy in eV :type E: float :param fermi: the fermi level in eV :type fermi: float :param T: the temperature in kelvin :type T: float