pymatgen.analysis.defects.thermodynamics module

Defect thermodynamics, such as defect phase diagrams, etc.

class DefectPhaseDiagram(entries, vbm, band_gap, filter_compatible=True, metadata=None)[source]

Bases: monty.json.MSONable

This is similar to a PhaseDiagram object in pymatgen, but has ability to do quick analysis of defect formation energies when fed DefectEntry objects.

uses many of the capabilities from PyCDT’s DefectsAnalyzer class…

This class is able to get:
  1. stability of charge states for a given defect,

  2. list of all formation ens

  3. transition levels in the gap

  • dentries ([DefectEntry]) – A list of DefectEntry objects

  • vbm (float) – Valence Band energy to use for all defect entries. NOTE if using band shifting-type correction then this VBM should still be that of the GGA calculation (the bandedgeshifting_correction accounts for shift’s contribution to formation energy).

  • band_gap (float) – Band gap to use for all defect entries. NOTE if using band shifting-type correction then this gap should still be that of the Hybrid calculation you are shifting to.

  • filter_compatible (bool) –

    Whether to consider entries which were ruled incompatible by the DefectComaptibility class. Note this must be set to False if you desire a suggestion for larger supercell sizes. Default is True (to omit calculations which have “is_compatible”=False in


  • metadata (dict) – Dictionary of metadata to store with the PhaseDiagram. Has no impact on calculations

property all_stable_entries[source]

List all stable entries (defect+charge) in the DefectPhaseDiagram

property all_unstable_entries[source]

List all unstable entries (defect+charge) in the DefectPhaseDiagram


JSON-serializable dict representation of DefectPhaseDiagram

defect_concentrations(chemical_potentials, temperature=300, fermi_level=0.0)[source]

Give list of all concentrations at specified efermi in the DefectPhaseDiagram :param chemical_potentials = {Element: number} is dict of chemical potentials to provide formation energies for :param temperature = temperature to produce concentrations from: :param fermi_level: (float) is fermi level relative to valence band maximum

Default efermi = 0 = VBM energy


list of dictionaries of defect concentrations

property defect_types[source]

List types of defects existing in the DefectPhaseDiagram


Sets the stable charges and transition states for a series of defect entries. This function uses scipy’s HalfspaceInterection to oncstruct the polygons corresponding to defect stability as a function of the Fermi-level. The Halfspace Intersection constructs N-dimensional hyperplanes, in this case N=2, based on the equation of defect formation energy with considering chemical potentials:

E_form = E_0^{Corrected} + Q_{defect}*(E_{VBM} + E_{Fermi})

Extra hyperplanes are constructed to bound this space so that the algorithm can actually find enclosed region.

This code was modeled after the Halfspace Intersection code for the Pourbaix Diagram

classmethod from_dict(d)[source]

Reconstitute a DefectPhaseDiagram object from a dict representation created using as_dict().


d (dict) – dict representation of DefectPhaseDiagram.


DefectPhaseDiagram object


Find Dopability limits for a given chemical potential. This is defined by the defect formation energies which first cross zero in formation energies. This determine bounds on the fermi level.

Does this by computing formation energy for every stable defect with non-zero charge. If the formation energy value changes sign on either side of the band gap, then compute the fermi level value where the formation energy is zero (formation energies are lines and basic algebra shows: x_crossing = x1 - (y1 / q) for fermi level, x1, producing formation energy y1)


chemical_potentials – dict of chemical potentials to use for calculation fermi level


lower dopability limit, upper dopability limit

(returns None if no limit exists for upper or lower i.e. no negative defect crossing before +/- 20 of band edges OR defect formation energies are entirely zero)

plot(mu_elts=None, xlim=None, ylim=None, ax_fontsize=1.3, lg_fontsize=1.0, lg_position=None, fermi_level=None, title=None, saved=False)[source]

Produce defect Formation energy vs Fermi energy plot :param mu_elts: a dictionary of {Element:value} giving the chemical

potential of each element

  • xlim – Tuple (min,max) giving the range of the x (fermi energy) axis

  • ylim – Tuple (min,max) giving the range for the formation energy axis

  • ax_fontsize – float multiplier to change axis label fontsize

  • lg_fontsize – float multiplier to change legend label fontsize

  • lg_position – Tuple (horizontal-position, vertical-position) giving the position to place the legend. Example: (0.5,-0.75) will likely put it below the x-axis.

  • saved


a matplotlib object

solve_for_fermi_energy(temperature, chemical_potentials, bulk_dos)[source]

Solve for the Fermi energy self-consistently as a function of T Observations are Defect concentrations, electron and hole conc :param temperature: Temperature to equilibrate fermi energies for :param chemical_potentials: dict of chemical potentials to use for calculation fermi level :param bulk_dos: bulk system dos (pymatgen Dos object)


Fermi energy dictated by charge neutrality

solve_for_non_equilibrium_fermi_energy(temperature, quench_temperature, chemical_potentials, bulk_dos)[source]

Solve for the Fermi energy after quenching in the defect concentrations at a higher temperature (the quench temperature), as outlined in P. Canepa et al (2017) Chemistry of Materials (doi: 10.1021/acs.chemmater.7b02909)

  • temperature – Temperature to equilibrate fermi energy at after quenching in defects

  • quench_temperature – Temperature to equilibrate defect concentrations at (higher temperature)

  • chemical_potentials – dict of chemical potentials to use for calculation fermi level

  • bulk_dos – bulk system dos (pymatgen Dos object)


Fermi energy dictated by charge neutrality with respect to frozen in defect concentrations


Suggest possible charges for defects to compute based on proximity of known transitions from entries to VBM and CBM


tolerance (float) – tolerance with respect to the VBM and CBM to ` continue to compute new charges


Suggest larger supercells for different defect+chg combinations based on use of compatibility analysis. Does this for any charged defects which have is_compatible = False, and the defect+chg formation energy is stable at fermi levels within the band gap.

NOTE: Requires self.filter_compatible = False :param tolerance: tolerance with respect to the VBM and CBM for considering

larger supercells for a given charge