doped.plotting module

Code to analyse VASP defect calculations.

These functions are built from a combination of useful modules from pymatgen and AIDE (by Adam Jackson and Alex Ganose), alongside substantial modification, in the efforts of making an efficient, user-friendly package for managing and analysing defect calculations, with publication-quality outputs.

doped.plotting.formation_energy_plot(defect_phase_diagram, chempots: Dict | None = None, facets: List | str | None = None, el_refs: Dict | None = None, chempot_table: bool = True, all_entries: bool | str = False, style_file: str | None = None, xlim: Tuple | None = None, ylim: Tuple | None = None, fermi_level: float | None = None, colormap: str | Colormap = 'Dark2', auto_labels: bool = False, filename: str | None = None)[source]

Produce a defect formation energy vs Fermi level plot (a.k.a. a defect formation energy / transition level diagram). Returns the Matplotlib Figure object to allow further plot customisation.

Parameters:

  • defect_phase_diagram (DefectPhaseDiagram) – DefectPhaseDiagram for which to plot defect formation energies (typically created from analysis.dpd_from_defect_dict).

  • chempots (dict) – Dictionary of chemical potentials to use for calculating the defect formation energies. This can have the form of {“facets”: [{‘facet’: [chempot_dict]}]} (the format generated by doped’s chemical potential parsing functions (see tutorials)) and facet(s) (chemical potential limit(s)) to plot can be chosen using facets, or a dictionary of DFT/absolute chemical potentials (not formal chemical potentials!), in the format: {element symbol: chemical potential} - if manually specifying chemical potentials this way, you can set the el_refs option with the DFT reference energies of the elemental phases in order to show the formal (relative) chemical potentials above the plot. (Default: None)

  • facets (list, str) – A string or list of facet(s) (chemical potential limit(s)) for which to plot the defect formation energies, corresponding to ‘facet’ in {“facets”: [{‘facet’: [chempot_dict]}]} (the format generated by doped’s chemical potential parsing functions (see tutorials)). If not specified, will plot for each facet in chempots. (Default: None)

  • el_refs (dict) – Dictionary of elemental reference energies for the chemical potentials in the format: {element symbol: reference energy} (to determine the formal chemical potentials, when chempots has been manually specified as {element symbol: chemical potential}). Unnecessary if chempots is provided in format generated by doped (see tutorials). (Default: None)

  • chempot_table (bool) – Whether to print the chemical potential table above the plot. (Default: True)

  • all_entries (bool, str) – Whether to plot the formation energy lines of _all_ defect entries, rather than the default of showing only the equilibrium states at each Fermi level position (traditional). If instead set to “faded”, will plot the equilibrium states in bold, and all unstable states in faded grey (Default: False)

  • style_file (str) – Path to a mplstyle file to use for the plot. If None (default), uses the default doped style (from doped/utils/doped.mplstyle).

  • xlim – Tuple (min,max) giving the range of the x-axis (Fermi level). May want to set manually when including transition level labels, to avoid crossing the axes. Default is to plot from -0.3 to +0.3 eV above the band gap.

  • ylim – Tuple (min,max) giving the range for the y-axis (formation energy). May want to set manually when including transition level labels, to avoid crossing the axes. Default is from 0 to just above the maximum formation energy value in the band gap.

  • fermi_level (float) – If set, plots a dashed vertical line at this Fermi level value, typically used to indicate the equilibrium Fermi level position (e.g. calculated with py-sc-fermi). (Default: None)

  • colormap (str, matplotlib.colors.Colormap) – Colormap to use for the formation energy lines, either as a string (i.e. name from https://matplotlib.org/stable/users/explain/colors/colormaps.html) or a Colormap / ListedColormap object. (default: “Dark2”)

  • auto_labels (bool) – Whether to automatically label the transition levels with their charge states. If there are many transition levels, this can be quite ugly. (Default: False)

  • filename (str) – Filename to save the plot to. (Default: None (not saved))

Returns:

Matplotlib Figure object, or list of Figure objects if multiple facets chosen.