doped.chemical_potentials module

Functions for setting up and parsing competing phase calculations in order to determine and analyse the elemental chemical potentials for defect formation energies.

class doped.chemical_potentials.ChemicalPotentialGrid(chempots: dict[str, Any], format_chempot_labels: bool = True)[source]

Bases: object

A class to represent a grid in chemical potential space and to perform operations such as generating a grid within the convex hull of given vertices (chemical potential limits).

This class provides methods for handling and manipulating chemical potential data, including the creation of a grid that spans a specified chemical potential space.

Initializes the ChemicalPotentialGrid with chemical potential data.

This constructor takes a dictionary of chemical potentials and sets up the initial vertices of the grid.

Parameters:

chempots (dict) –
Dictionary of chemical potentials for the grid. This can have the form of {"limits": [{'limit': [chempot_dict]}], ...} (the format generated by doped's chemical potential parsing functions), or alternatively can be a dictionary of the form {'limit': [chempot_dict, ...]} (i.e. matching the format of chempots["limits_wrt_el_refs"] from the doped chempots dict) where the keys are the limit names (e.g. “Cd-CdTe”, “Cd-rich” etc) and the values are dictionaries of a single chemical potential limit in the format: {element symbol: chemical potential}.

If chempots in the doped format is supplied, then the chemical potentials with respect to the elemental reference energies will be used (i.e. chempots["limits_wrt_el_refs"])!
format_chempot_labels (bool) – Whether to format the elemental chemical potential labels as “µ_{elt} (eV)” (default) or just “{elt}” (if False).

classmethod from_dataframe(vertices: DataFrame) → ChemicalPotentialGrid[source]

Create a ChemicalPotentialGrid object from a dataframe of the chemical potential limits (i.e. vertices).

Parameters:: vertices (pd.DataFrame) – A DataFrame of the chemical potential limits (i.e. vertices). The columns should be the chemical potentials of the elements, and the rows should be the limits.
Returns:: A ChemicalPotentialGrid object.
Return type:: ChemicalPotentialGrid

get_constrained_grid(fixed_elements: dict[str, float], n_points: int | None = None, cartesian: bool = False, decimal_places: int = 4, drop_duplicates: bool = True, include_vertices: bool = True) → DataFrame[source]

Generates a grid of points that spans the chemical potential space defined by the vertices, constrained by a set of fixed chemical potentials.

By default, the grid is generated in barycentric coordinates (i.e. in ‘relative’ coordinates, as weighted averages of the chemical potential limits). This is far more efficient than generating a Cartesian grid, but means that the grid is evenly spaced in barycentric (‘relative’) coordinates, and not necessarily in Cartesian coordinates. If cartesian is set to True, then a regular grid in Cartesian coordinates is generated (however this can be much slower).

Parameters:

fixed_elements (dict) – A dictionary of chemical potentials to fix (in the format: {column_name: value}; e.g. {"Li": -2}).
n_points (int | None) – Minimum number of grid points to generate, within the constrained subspace. The output grid will contain at least this many points (regularly spaced in barycentric or Cartesian space depending cartesian), in addition to the vertices of the constrained subspace (if include_vertices is True; default), then with any duplicate / overlapping points dropped. The default is 1000 when barycentric coordinates are used (cartesian=False), and 100 otherwise (as Cartesian grid generation and sub-selection to the stable polytope is much slower). Note that large values (>= 1e5) with multinary systems can explode, crashing system memory.
cartesian (bool) – Whether to generate the grid in Cartesian coordinates. If False (default), the grid is generated in barycentric coordinates, which is far more efficient, but means that the grid is evenly spaced in barycentric (‘relative’) coordinates, and not necessarily in Cartesian coordinates.
decimal_places (int) – The number of decimal places to round the grid coordinates to. Default is 4.
drop_duplicates (bool) – Whether to drop duplicate points in the generated grid. With barycentric coordinate generation, there can be duplicate points in the generated grid from overlapping simplices. If duplicates are acceptable (likely true for most downstream usages; e.g. plotting etc) then this can be set to False to speed up runtime. Default is True.
include_vertices (bool) – Whether to include the vertices themselves in the generated grid. Default is True.

Returns:

A DataFrame containing the points within the convex hull, constrained by the fixed chemical potentials. Each row represents a point in the grid.

Return type:

pd.DataFrame

get_grid(n_points: int | None = None, fixed_elements: dict[str, float] | None = None, cartesian: bool = False, decimal_places: int = 4, drop_duplicates: bool = True, include_vertices: bool = True) → DataFrame[source]

Generates a grid of points that spans the chemical potential space defined by the vertices. It ensures that the generated points lie within the convex hull of the provided vertices and interpolates the chemical potential values at these points.

By default, the grid is generated in barycentric coordinates (i.e. in ‘relative’ coordinates, as weighted averages of the chemical potential limits). This is far more efficient than generating a Cartesian grid, but means that the grid is evenly spaced in barycentric (‘relative’) coordinates, and not necessarily in Cartesian coordinates. If cartesian is set to True, then a regular grid in Cartesian coordinates is generated (however this can be much slower).

Parameters:

n_points (int | None) – Minimum number of grid points to generate. The output grid will contain at least this many points (regularly spaced in barycentric or Cartesian space depending cartesian), in addition to the vertices themselves (if include_vertices is True; default), then with any duplicate / overlapping points dropped. The default is 1000 when barycentric coordinates are used (cartesian=False), and 100 otherwise (as Cartesian grid generation and sub-selection to the stable polytope is much slower). Note that large values (>= 1e5) with multinary systems can explode, crashing system memory.
fixed_elements (dict | None) – A dictionary of chemical potentials to fix (in the format: {column_name: value}; e.g. {"Li": -2}), if a reduced / constrained chemical potential grid is desired. If provided, the get_constrained_grid method is used.
cartesian (bool) – Whether to generate the grid in Cartesian coordinates. If False (default), the grid is generated in barycentric coordinates, which is far more efficient, but means that the grid is evenly spaced in barycentric (‘relative’) coordinates, and not necessarily in Cartesian coordinates.
decimal_places (int) – The number of decimal places to round the grid coordinates to. Note that the tolerance for grid-point matching is 10^[-decimal_places]. Default is 4.
drop_duplicates (bool) – Whether to drop duplicate points in the generated grid. With barycentric coordinate generation, there can be duplicate points in the generated grid from overlapping simplices. If duplicates are acceptable (likely true for most downstream usages; e.g. plotting etc) then this can be set to False to speed up runtime. Default is True.
include_vertices (bool) – Whether to include the vertices themselves in the generated grid. Default is True.

Returns:

A DataFrame containing the points within the convex hull. Each row represents a point in the grid.

Return type:

pd.DataFrame

class doped.chemical_potentials.CompetingPhases(composition: str | Composition | Structure, energy_above_hull: float = 0.05, extrinsic: str | Iterable | None = None, full_phase_diagram: bool = False, MP_doc_dicts: bool = False, full_sub_approach: bool = False, codoping: bool = False, api_key: str | None = None)[source]

Bases: object

Class to generate VASP input files for competing phases on the phase diagram for the host material (and any extrinsic (dopant/impurity) elements), which determine the chemical potential limits for elements in that compound.

For this, the Materials Project (MP) database is queried using the MPRester API, and any calculated compounds which could border the host material within an error tolerance for the semi-local DFT database energies (energy_above_hull, 0.05 eV/atom by default) are generated, along with the elemental reference phases. Diatomic gaseous molecules are generated as molecules-in-a-box as appropriate (e.g. for O2, F2, H2 etc).

Often energy_above_hull can be lowered (e.g. to 0) to reduce the number of calculations while retaining good accuracy relative to the typical error of defect calculations.

The default energy_above_hull of 50 meV/atom works well in accounting for MP formation energy inaccuracies in most known cases. However, some critical thinking is key (as always!) and so if there are any obvious missing phases or known failures of the Materials Project energetics in your chemical space of interest, you should adjust this parameter to account for this (or alternatively manually include these known missing phases in your competing phase calculations, to be included in parsing and chemical potential analysis later on).

Particular attention should be paid for materials containing transition metals, (inter)metallic systems, mixed oxidation states, van der Waals (vdW) binding and/or large spin-orbit coupling (SOC) effects, for which the Materials Project energetics are typically less reliable.

Parameters:

composition (str, Composition, Structure) – Composition of the host material (e.g. 'LiFePO4', or Composition('LiFePO4'), or Composition({"Li":1, "Fe":1, "P":1, "O":4})). Alternatively a pymatgen Structure object for the host material can be supplied (recommended), in which case the primitive structure will be used as the only host composition phase, reducing the number of calculations.
energy_above_hull (float) – Maximum energy above hull (in eV/atom) of Materials Project entries to be considered as competing phases. This is an uncertainty range for the MP-calculated formation energies, which may not be accurate due to functional choice (GGA vs hybrid DFT / GGA+U / RPA etc.), lack of vdW corrections etc. All phases that would border the host material on the phase diagram, if their relative energy was downshifted by energy_above_hull, are included. Often energy_above_hull can be lowered (e.g. to 0) to reduce the number of calculations while retaining good accuracy relative to the typical error of defect calculations. (Default is 0.05 eV/atom).
extrinsic (str, Iterable) – Extrinsic dopant/impurity species to consider, to generate the relevant competing phases to additionally determine their chemical potential limits within the host. Can be a single element as a string (e.g. “Mg”) or an iterable of element strings (list, set, tuple, dict) (e.g. [“Mg”, “Na”]).
full_phase_diagram (bool) – If True, include all phases on the MP phase diagram (with energy above hull < energy_above_hull eV/atom) for the chemical system of the input composition and any extrinsic species. Typically not recommended. If False (default), only includes phases that would border the host material on the phase diagram (and thus set the chemical potential limits), if their relative energy was downshifted by energy_above_hull eV/atom. (Default is False).
full_sub_approach (bool) – Generate competing phases by considering the full phase diagram, including chemical potential limits with multiple extrinsic phases. Only recommended when looking at high (non-dilute) doping concentrations. The default approach (full_sub_approach = False) for extrinsic elements is to only consider chemical potential limits where the host composition borders a maximum of 1 extrinsic phase (composition with extrinsic element(s)). This is a valid approximation for the case of dilute dopant/impurity concentrations. For high (non-dilute) concentrations of extrinsic species, use full_sub_approach = True.
codoping (bool) – Whether to consider extrinsic competing phases containing multiple extrinsic species. Usually only relevant under high (non-dilute) co-doping concentrations. If set to True, then full_sub_approach is also set to True. Default is False.
api_key (str) – Materials Project (MP) API key, needed to access the MP database for competing phase generation. If not supplied, will attempt to read from environment variable PMG_MAPI_KEY (in ~/.pmgrc.yaml or ~/.config/.pmgrc.yaml) – see the doped Installation docs page: https://doped.readthedocs.io/en/latest/Installation.html
MP_doc_dicts (bool) – If True, also queries the Materials Project (MP) for summary doc dicts with MPRester.summary_search() for the competing phase entries, and stores them in CompetingPhases.MP_doc_dicts. Default is False.

convergence_setup(kpoints_metals=(40, 1000, 5), kpoints_nonmetals=(5, 120, 5), user_potcar_functional='PBE', user_potcar_settings=None, user_incar_settings=None, **kwargs)[source]

Generates VASP input files for k-points convergence testing for competing phases, using PBEsol (GGA) DFT by default. Automatically sets the ISMEAR INCAR tag to 2 (if metallic) or 0 if not. Recommended to use with https://github.com/kavanase/vaspup2.0.

Parameters:

kpoints_metals (tuple) – Kpoint density per inverse volume (Å^-3) to be tested in (min, max, step) format for metals
kpoints_nonmetals (tuple) – Kpoint density per inverse volume (Å^-3) to be tested in (min, max, step) format for nonmetals
user_potcar_functional (str) – POTCAR functional to use. Default is “PBE” and if this fails, tries “PBE_52”, then “PBE_54”.
user_potcar_settings (dict) – Override the default POTCARs, e.g. {“Li”: “Li_sv”}. See doped/VASP_sets/PotcarSet.yaml for the default POTCAR set.
user_incar_settings (dict) – Override the default INCAR settings e.g. {"EDIFF": 1e-5, "LDAU": False, "ALGO": "All"}. Note that any non-numerical or non-True/False flags need to be input as strings with quotation marks. See doped/VASP_sets/PBEsol_ConvergenceSet.yaml for the default settings.
**kwargs – Additional kwargs to pass to DictSet.write_input()

property metallic_entries: list[ComputedEntry]: Returns a list of entries in self.entries which are metallic (i.e. have a band gap = 0) according to the Materials Project database.

property molecular_entries: list[ComputedEntry]: Returns a list of entries in self.entries which are diatomic molecules generated by doped (i.e. O2, N2, H2, F2, or Cl2).

property nonmetallic_entries: list[ComputedEntry]

Returns a list of entries in self.entries which are non-metallic (i.e. have a band gap > 0, or no recorded band gap) according to the Materials Project database.

Note that the doped-generated diatomic molecule phases, which are insulators, are not included here.

vasp_std_setup(kpoints_metals=200, kpoints_nonmetals=64, user_potcar_functional='PBE', user_potcar_settings=None, user_incar_settings=None, **kwargs)[source]

Generates VASP input files for vasp_std relaxations of the competing phases, using HSE06 (hybrid DFT) DFT by default. Automatically sets the ISMEAR INCAR tag to 2 (if metallic) or 0 if not. Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for the defect supercell calculations.

Parameters:

kpoints_metals (int) – Kpoint density per inverse volume (Å^-3) for metals. Default is 200.
kpoints_nonmetals (int) – Kpoint density per inverse volume (Å^-3) for nonmetals (default is 64, the default for MPRelaxSet).
user_potcar_functional (str) – POTCAR functional to use. Default is “PBE” and if this fails, tries “PBE_52”, then “PBE_54”.
user_potcar_settings (dict) – Override the default POTCARs, e.g. {“Li”: “Li_sv”}. See doped/VASP_sets/PotcarSet.yaml for the default POTCAR set.
user_incar_settings (dict) – Override the default INCAR settings e.g. {"EDIFF": 1e-5, "LDAU": False, "ALGO": "All"}. Note that any non-numerical or non-True/False flags need to be input as strings with quotation marks. See doped/VASP_sets/RelaxSet.yaml and HSESet.yaml for the default settings.
**kwargs – Additional kwargs to pass to DictSet.write_input()

Bases: MSONable

Class for post-processing competing phases calculations, to determine the corresponding chemical potentials for the host composition.

This class can be initialised from VASP outputs (vasprun.xmls) by specifying the path to the directory containing the outputs (e.g. "CompetingPhases") or a list of directories, or from a list of of ComputedEntrys / ComputedStructureEntrys (e.g. for use with high-throughput computing architectures such as atomate2 or AiiDA).

Multiprocessing is used by default to speed up parsing of VASP outputs, which can be controlled with processes. If parsing hangs, this may be due to memory issues, in which case you should reduce processes (e.g. 4 or less).

Parameters:

composition (str, Composition) – Composition of the host material (e.g. 'LiFePO4', or Composition('LiFePO4'), or Composition({"Li":1, "Fe":1, "P":1, "O":4})).
entries (PathLike, list[PathLike], list[ComputedEntry], list[ComputedStructureEntry]) – Either a path to the base folder containing the VASP outputs (e.g. "CompetingPhases"; default; with subfolders like: formula_EaH_X/vasp_std/vasprun.xml(.gz), or formula_EaH_X/vasprun.xml(.gz)) or a list of paths to vasprun.xml(.gz) files. Alternatively, can be a list of ComputedEntrys / ComputedStructureEntrys.
subfolder (PathLike) – The subfolder in which your vasprun.xml(.gz) output files are located (e.g. a file-structure like: formula_EaH_X/{subfolder}/vasprun.xml(.gz)), if entries is a path to a base folder with VASP outputs. Default is to search for vasp_std subfolders, or directly in the formula_EaH_X folders.
verbose (bool) – Whether to print out information about directories that were skipped (due to no vasprun.xml(.gz) files being found), when parsing VASP outputs. Default is True.
processes (int) – Number of processes to use for multiprocessing for expedited parsing of VASP outputs. If None (default), then the parsing time with multiprocessing is estimated based on vasprun.xml(.gz) file sizes, and used if predicted to be faster than serial processing. Set to 1 to prevent multiprocessing.
check_compatibility (bool) – Whether to check the compatibility of the parsed entries, by comparing their INCAR and POTCAR settings (if available). Default is True.

Key attributes:

composition (str):: The bulk (host) composition.
chempots (dict):: Dictionary of the chemical potential limits for the host material, in the doped format (i.e. {"limits": [{'limit': [chempot_dict]}], ...}). This can be directly used with the DefectThermodynamics plotting & analysis methods, and saved to file with dumpfn from monty.serialization.
chempots_df (DataFrame):: DataFrame of the chemical potential limits for the host.
elements (list):: List of all elements in the chemical system (host + extrinsic), from all parsed calculations.
extrinsic_elements (str):: List of extrinsic elements in the chemical system (not present in composition).
intrinsic_elements (str):: List of intrinsic elements (i.e. those in composition).
bulk_entry (ComputedStructureEntry):: The lowest energy computed entry for the host material.
unstable_host (bool):: Whether the host material is unstable with respect to competing phases (i.e. has an energy above hull > 0).
entries (list[Union[ComputedEntry, ComputedStructureEntry]]):: List of all parsed ComputedEntrys / ComputedStructureEntrys.
phase_diagram (PhaseDiagram):: A pymatgen phase diagram generated from the parsed entries. Note that this phase diagram is likely not a full phase diagram for this chemical space, as we typically only generate the nearby competing phases for the host material to reduce the number of calculations.
intrinsic_phase_diagram (PhaseDiagram):: A pymatgen phase diagram containing only entries with elements from the host material (i.e. no extrinsic elements).
elemental_energies (dict):: Dictionary of the lowest energy elemental phases for each element in the chemical system.
parsed_folders (list):: List of folders from which VASP calculation outputs were parsed, if entries was given as a path / paths to directories.

as_dict() → dict[source]

Returns:: JSON-serializable dict representation of CompetingPhasesAnalyzer.

Calculates the chemical potential limits for the host composition (self.composition).

If extrinsic_species (i.e. dopant/impurity elements) is specified, then the limiting chemical potential for extrinsic_species at the intrinsic chemical potential limits is calculated and also returned (corresponds to full_sub_approach=False in pycdt). extrinsic_species is set to self.extrinsic_elements if not specified.

Parameters:

extrinsic_species (str, Element, list) – If set, will calculate the limiting chemical potential for the specified extrinsic species at the intrinsic chemical potential limits. Can be a single element (str or Element), or a list of elements. If None (default), uses self.extrinsic_elements.
sort_by (str) – If set, will sort the chemical potential limits in the output DataFrame according to the chemical potential of the specified element (from element-rich to element-poor conditions).
verbose (bool) – If True (default), will print the parsed chemical potential limits.

Returns:

pandas DataFrame, optionally saved to csv.

property chempot_grid: ChemicalPotentialGrid

ChemicalPotentialGrid object for the chemical potential limits of the host composition.

This object can be used for plotting and numerical analyses of chemical stability regions. See the ChemicalPotentialGrid class for more details.

classmethod from_dict(d: dict) → CompetingPhasesAnalyzer[source]

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

Parameters:: d (dict) – dict representation of CompetingPhasesAnalyzer.
Returns:: CompetingPhasesAnalyzer object

get_formation_energy_df(prune_polymorphs: bool = False, include_dft_energies: bool = False, skip_rounding: bool = False) → DataFrame[source]

Generate a DataFrame of the formation energies of parsed competing phases calculations.

Useful for quick summary and analysis of results, e.g. to include in the SI of journal articles or a thesis – to aid open-science and reproducibility, or for quick data sharing, or for use with other codes. Can be saved to file with formation_energy_df.to_csv() etc.

Rows are sorted according to CompetingPhasesAnalyzer.entries, which by default is sorted by energy above hull (with the host composition first), then by the number of elements in the formula, then by the position of elements in the periodic table (main group elements, then transition metals, sorted by row), then alphabetically.

Parameters:

prune_polymorphs (bool) – Whether to only write the lowest energy polymorphs for each composition. Doesn’t affect chemical potential limits (only the ground-state polymorphs matter for this). Default is False.
include_dft_energies (bool) – Whether to include the raw DFT energies in the output DataFrame. Default is False.
skip_rounding (bool) – Whether to skip rounding the energies to 3 decimal places (1 meV/atom or meV/fu) for cleanliness. Default is False.

Plot a heatmap of the chemical potentials for a multinary system, showing bordering secondary phases.

In this plot, the dependent_element chemical potential is plotted as a heatmap over the stability region of the host composition, as a function of two other elemental chemical potentials on the x and y axes.

3-D data is required to plot a 2-D heatmap, and so this function can be applied as-is for ternary systems, but for higher-dimensional systems a set of chemical potential constraints must be provided (as fixed_elements) to project the chemical stability region to 3-D; see the competing phases tutorial: https://doped.readthedocs.io/en/latest/chemical_potentials_tutorial.html#analysing-and-visualising-the-chemical-potential-limits

Note that due to an issue with matplotlib Stroke path effects, sometimes there can be odd holes in the whitespace around the chemical formula labels (see: https://github.com/matplotlib/matplotlib/issues/25669). This is only the case for png output, so saving to e.g. svg or pdf instead will avoid this issue.

If using the default colour map (batlow) in publications, please consider citing: https://zenodo.org/records/8409685

Tip: https://github.com/frssp/cplapy can be used to generate 3D plots of chemical stability regions, to show the bordering competing phases in quaternary systems.

Parameters:

dependent_element (str or Element) – The element for which the chemical potential is plotted as a heatmap. If None (default), the last element in the bulk composition formula is used (which corresponds to the most electronegative element present).
fixed_elements (dict) – A dictionary of chemical potentials to fix (in the format: {element: value}; e.g. {"Li": -2}) if the chemical system is >3-D. Constraining chemical potentials is required for multinary systems, in order to reduce the dimensionality to 3-D for plotting a 2-D heatmap. For a system with N elements, N-3 fixed chemical potentials should be specified. If None (default), the chemical potentials of the first N-3 elements in the bulk composition are fixed to their mean values in the stability region (i.e. the centroid of the stability region).
bordering_phases (bool) – Whether to plot the competing/secondary phases which border the host composition in the chemical potential diagram. Default is True.
xlim (tuple) – The x-axis limits for the plot. If None (default), the limits are set to the minimum and maximum values of the x-axis data, with padding equal to padding (default = 10% of the range).
ylim (tuple) – The y-axis limits for the plot. If None (default), the limits are set to the minimum and maximum values of the y-axis data, with padding equal to padding (default = 10% of the range).
cbar_range (tuple) – The range for the colourbar. If None (default), the range is set to the minimum and maximum values of the data.
colormap (str, matplotlib.colors.Colormap) –
Colormap to use for the heatmap, either as a string (which can be a colormap name from https://www.fabiocrameri.ch/colourmaps / https://matplotlib.org/stable/users/explain/colors/colormaps) or a Colormap / ListedColormap object. If None (default), uses batlow from https://www.fabiocrameri.ch/colourmaps.

Append “S” to the colormap name if using a sequential colormap from https://www.fabiocrameri.ch/colourmaps.
padding (float) – The padding to add to the x and y axis limits. If None (default), the padding is set to 10% of the range.
title (str or bool) – The title for the plot. If False (default), no title is added. If True, the title is set to the bulk composition formula, or if str, the title is set to the provided string.
label_positions (bool, dict or list) – The positions for the chemical formula line labels. If True (default), the labels are placed using a custom doped algorithm which attempts to find the best possible positions (minimising overlap). If False, no labels are added. Alternatively a dictionary can be provided, where the keys are the chemical formulae and the values are tuples of (x_coord, y-offset) at which to place the line labels (where y-offset is the offset from the line at x=x_coord). A list of tuples can also be provided, where the order is assumed to match the competing phase lines.
filename (PathLike) – The filename to save the plot to. If None (default), the plot is not saved.
style_file (PathLike) – Path to a mplstyle file to use for the plot. If None (default), uses the default doped style (from doped/utils/doped.mplstyle).
**kwargs – Additional keyword arguments to pass to ChemicalPotentialDiagram.get_grid(), such as n_points (default = 1000) and cartesian (default = False).

Returns:

The matplotlib Figure object.

Return type:

plt.Figure

to_LaTeX_table(splits=1, prune_polymorphs=True)[source]

A very simple function to print out the competing phase formation energies in a LaTeX table format, showing the formula, space group, energy above hull, kpoints (if present in the parsed data) and formation energy.

Needs the mhchem package to work and does not use the booktabs package; change hline to toprule, midrule and bottomrule if you want to use booktabs style.

Parameters:

splits (int) – Number of splits for the table; either 1 (default) or 2 (with two large columns, each with the formula, kpoints (if present) and formation energy (sub-)columns).
prune_polymorphs (bool) – Whether to only print out the lowest energy polymorphs for each composition. Default is True.

Returns:

LaTeX table string

Return type:

str

doped.chemical_potentials.combine_extrinsic(first: dict, second: dict, extrinsic_species: str) → dict[source]

Combines chemical potential limits for different extrinsic species.

Usage explained in the chemical potentials tutorial. To be removed in following versions.

Parameters:

first (dict) – First chemical potential dictionary, it can contain extrinsic species other than the set extrinsic species.
second (dict) – Second chemical potential dictionary, it must contain the extrinsic species.
extrinsic_species (str) – Extrinsic species in the second dictionary.

Returns:

Combined dictionary with limits for the extrinsic species.

Return type:

dict

doped.chemical_potentials.entries_from_chempot_limits(chempots_dict)[source]

Generate a list of ComputedEntry objects from a doped dictionary of chemical potential limits.

These entries will correspond to the ground-state phase for each chemically-stable composition in the chemical system, and can be used to generate a ChemicalPotentialDiagram object (used in chemical potential heatmap plotting).

Parameters:

chempots_dict (dict) –

doped chemical potential limits dictionary, as output by CompetingPhasesAnalyzer.chempots, having the keys:

”limits”: {“phaseA-phaseB-phaseC”:
{“Li”: mu_Li, “P”: mu_P, …}, … }

”elemental_refs”:
{“Li”: mu_Li_ref, “P”: mu_P_ref, …}

Returns:

List of ComputedEntry objects, with energies per formula unit.

Return type:

list[ComputedEntry]

doped.chemical_potentials.get_MP_summary_dicts(entries: list[ComputedEntry] | None = None, chemsys: str | list[str] | None = None, api_key: str | None = None, **kwargs) → dict[str, dict][source]

Get the corresponding Materials Project (MP) summary dictionaries for computed entries in the input entries list or chemsys chemical system.

If entries is provided (which should be a list of ComputedEntry``s from the Materials Project), then only summary dictionaries in this chemical system which match one of these entries (based on the MPIDs given in ``ComputedEntry.entry_id/ComputedEntry.data["material_id"] and summary_dict["material_id"]) are returned.

Parameters:

entries (list[ComputedEntry]) – Optional input; list of ComputedEntry objects for the input chemical system. If provided, only summary dictionaries which match one of these entries (based on the MPIDs given in ComputedEntry.entry_id/ComputedEntry.data["material_id"] and summary_dict["material_id"]) are returned.
chemsys (str, list[str]) – Optional input; chemical system to get entries for, in the format "A-B-C" or ["A", "B", "C"]. E.g. "Li-Fe-O" or ["Li", "Fe", "O"]. Either entries or chemsys must be provided!
api_key (str) – Materials Project (MP) API key, needed to access the MP database to obtain the corresponding summary dictionaries. If not supplied, will attempt to read from environment variable PMG_MAPI_KEY (in ~/.pmgrc.yaml or ~/.config/.pmgrc.yaml) – see the doped Installation docs: doped.readthedocs.io/en/latest/Installation.html#setup-potcars-and-materials-project-api
**kwargs – Additional keyword arguments to pass to the Materials Project API query, e.g. MPRester.summary_search().

Returns:

Dictionary of summary dictionaries for the input chemical system. The keys are the MPIDs (e.g. "mp-1234") and the values are the corresponding summary dictionaries.

Return type:

dict[str, dict]

doped.chemical_potentials.get_X_poor_limit(X: str, chempots: dict)[source]

Determine the chemical potential limit of the input chempots dict which corresponds to the most X-poor conditions.

Parameters:

X (str) – Elemental species (e.g. “Te”)
chempots (dict) – The chemical potential limits dict, as returned by CompetingPhasesAnalyzer.chempots

doped.chemical_potentials.get_X_rich_limit(X: str, chempots: dict)[source]

Determine the chemical potential limit of the input chempots dict which corresponds to the most X-rich conditions.

Parameters:

X (str) – Elemental species (e.g. “Te”)
chempots (dict) – The chemical potential limits dict, as returned by CompetingPhasesAnalyzer.chempots

doped.chemical_potentials.get_and_set_competing_phase_name(entry: ComputedStructureEntry | ComputedEntry, regenerate=False, ndigits=3) → str[source]

Get the doped name for a competing phase entry from the Materials Project (MP) database.

The default naming convention in doped for competing phases is: "{Chemical Formula}_{Space Group}_EaH_{MP Energy above Hull}". This is stored in the entry.data["doped_name"] key-value pair. If this value is already set, then this function just returns the previously-generated doped name, unless regenerate=True.

Parameters:

entry (ComputedStructureEntry, ComputedEntry) – pymatgen ComputedStructureEntry object for the competing phase.
regenerate (bool) – Whether to regenerate the doped name for the competing phase, if entry.data["doped_name"] already set. Default is False.
ndigits (int) – Number of digits to round the energy above hull value (in eV/atom) to. Default is 3.

Returns:

The doped name for the competing phase.

Return type:

doped_name (str)

doped.chemical_potentials.get_chempots_from_phase_diagram(bulk_computed_entry: ComputedEntry, phase_diagram: PhaseDiagram) → dict[source]

Get the chemical potential limits for the bulk computed entry in the supplied phase diagram.

Parameters:

bulk_computed_entry (ComputedEntry) – ComputedEntry/ComputedStructureEntry object for the host composition.
phase_diagram (PhaseDiagram) – PhaseDiagram object for the system of interest.

Returns:

Dictionary of the chemical potential limits for the bulk computed entry in the phase diagram.

Return type:

dict

doped.chemical_potentials.get_doped_chempots_from_entries(entries: Sequence[ComputedEntry | ComputedStructureEntry | PDEntry], composition: str | Composition | ComputedEntry, sort_by: str | None = None, single_chempot_limit: bool = False) → dict[source]

Given a list of ComputedEntrys / ComputedStructureEntrys / PDEntrys and the bulk composition, returns the chemical potential limits dictionary in the doped format (i.e. {"limits": [{'limit': [chempot_dict]}], ...}) for the host material.

Parameters:

entries (list[ComputedEntry]) – List of ComputedEntrys / ComputedStructureEntrys / PDEntrys for the chemical system, from which to determine the chemical potential limits for the host material (composition).
composition (str, Composition, ComputedEntry) – Composition of the host material either as a string (e.g. ‘LiFePO4’) a pymatgen Composition object (e.g. Composition('LiFePO4')), or a ComputedEntry object.
sort_by (str) – If set, will sort the chemical potential limits in the output DataFrame according to the chemical potential of the specified element (from element-rich to element-poor conditions).
single_chempot_limit (bool) – If set to True, only returns the first chemical potential limit in the calculated chemical potentials dictionary. Mainly intended for internal doped usage when the host material is calculated to be unstable with respect to the competing phases.

Returns:

Dictionary of chemical potential limits in the doped format.

Return type:

dict

doped.chemical_potentials.get_entries(chemsys_formula_id_criteria: str | dict[str, Any], api_key: str | None = None, bulk_composition: str | Composition | None = None, **kwargs)[source]

Convenience function to get a list of ComputedStructureEntrys for an input single composition/formula, chemical system, MPID or full criteria, using MPRester.get_entries().

The output entries list is sorted by energy per atom (equivalent sorting as energy above hull), then by the number of elements in the formula, then by the position of elements in the periodic table (main group elements, then transition metals, sorted by row).

Parameters:

chemsys_formula_id_criteria (str/dict) – A formula (e.g., Fe2O3), chemical system (e.g., Li-Fe-O) or MPID (e.g., mp-1234) or full Mongo-style dict criteria.
api_key (str) – Materials Project (MP) API key, needed to access the MP database to obtain the corresponding ComputedStructureEntry``s. If not supplied, will attempt to read from environment variable ``PMG_MAPI_KEY (in ~/.pmgrc.yaml or ~/.config/.pmgrc.yaml) – see the doped Installation docs: doped.readthedocs.io/en/latest/Installation.html#setup-potcars-and-materials-project-api
bulk_composition (str/Composition) – Optional input; formula of the bulk host material, to use for sorting the output entries (with all those matching the bulk composition first). Default is None.
**kwargs – Additional keyword arguments to pass to the Materials Project API get_entries() query.

Returns:

List of ComputedStructureEntry objects for the input chemical system.

Return type:

list[ComputedStructureEntry]

Convenience function to get a list of ComputedStructureEntrys for an input chemical system, using MPRester.get_entries_in_chemsys().

Automatically uses the appropriate format and syntax required for the (new) Materials Project (MP) API. chemsys = ["Li", "Fe", "O"] will return a list of all entries in the Li-Fe-O chemical system, i.e., all LixOy, FexOy, LixFey, LixFeyOz, Li, Fe and O phases. Extremely useful for creating phase diagrams of entire chemical systems.

If energy_above_hull is supplied, then only entries with energies above hull (according to the MP-computed phase diagram) less than this value (in eV/atom) will be returned.

The output entries list is sorted by energy above hull, then by the number of elements in the formula, then by the position of elements in the periodic table (main group elements, then transition metals, sorted by row).

Parameters:

chemsys (str, list[str]) – Chemical system to get entries for, in the format “A-B-C” or [“A”, “B”, “C”]. E.g. “Li-Fe-O” or [“Li”, “Fe”, “O”].
api_key (str) – Materials Project (MP) API key, needed to access the MP database to obtain the corresponding ComputedStructureEntry``s. If not supplied, will attempt to read from environment variable ``PMG_MAPI_KEY (in ~/.pmgrc.yaml or ~/.config/.pmgrc.yaml) – see the doped Installation docs: doped.readthedocs.io/en/latest/Installation.html#setup-potcars-and-materials-project-api
energy_above_hull (float) – If supplied, only entries with energies above hull (according to the MP-computed phase diagram) less than this value (in eV/atom) will be returned. Set to 0 to only return phases on the MP convex hull. Default is None (i.e. all entries are returned).
bulk_composition (str/Composition) – Optional input; formula of the bulk host material, to use for sorting the output entries (with all those matching the bulk composition first). Default is None.
**kwargs – Additional keyword arguments to pass to the Materials Project API get_entries_in_chemsys() query.

Returns:

List of ComputedStructureEntry objects for the input chemical system.

Return type:

list[ComputedStructureEntry], dict, list

doped.chemical_potentials.make_molecular_entry(computed_entry: ComputedEntry) → ComputedStructureEntry[source]

Generate a new ComputedStructureEntry for a molecule in a box, for the input elemental ComputedEntry.

The formula of the input computed_entry must be one of the supported diatomic molecules (O2, N2, H2, F2, Cl2).

Parameters:: computed_entry (ComputedEntry) – ComputedEntry object for the elemental entry.
Returns:: ComputedStructureEntry for the molecule in a box.
Return type:: ComputedStructureEntry

doped.chemical_potentials.make_molecule_in_a_box(element: str)[source]

Generate an X2 ‘molecule-in-a-box’ structure for the input element X, (i.e. a 30 Å cuboid supercell with a single X2 molecule in the centre).

This is the natural state of several elemental competing phases, such as O2, N2, H2, F2 and Cl2. Initial bond lengths are set to the experimental bond lengths of these gaseous molecules.

Parameters:

element (str) – Element symbol of the molecule to generate.

Returns:

structure (Structure):: pymatgen Structure object of the molecule in a box.
formula (str):: Chemical formula of the molecule in a box.
total_magnetization (int):: Total magnetization of the molecule in a box (0 for all X2 except O2 which has a triplet ground state (S = 1)).

Return type:

Structure, formula and total magnetization

Plot a heatmap of the chemical potentials (chempots) for a multinary system (composition), showing bordering secondary phases.

In this plot, the dependent_element chemical potential is plotted as a heatmap over the stability region of the host composition, as a function of two other elemental chemical potentials on the x and y axes.

3-D data is required to plot a 2-D heatmap, and so this function can be applied as-is for ternary systems, but for higher-dimensional systems a set of chemical potential constraints must be provided (as fixed_elements) to project the chemical stability region to 3-D; see the competing phases tutorial: https://doped.readthedocs.io/en/latest/chemical_potentials_tutorial.html#analysing-and-visualising-the-chemical-potential-limits

Note that due to an issue with matplotlib Stroke path effects, sometimes there can be odd holes in the whitespace around the chemical formula labels (see: https://github.com/matplotlib/matplotlib/issues/25669). This is only the case for png output, so saving to e.g. svg or pdf instead will avoid this issue.

If using the default colour map (batlow) in publications, please consider citing: https://zenodo.org/records/8409685

Tip: https://github.com/frssp/cplapy can be used to generate 3D plots of chemical stability regions, to show the bordering competing phases in quaternary systems.

Parameters:

chempots (dict) – Chemical potential limits dictionary in the doped format (i.e. {"limits": [{'limit': [chempot_dict]}], ...}) for the host material (composition).
composition (str or Composition or ComputedEntry) – Host material composition as a string, Composition object or ComputedEntry, for which to plot the chemical stability region (and for which chempots corresponds to).
dependent_element (str or Element) – The element for which the chemical potential is plotted as a heatmap. If None (default), the last element in the bulk composition formula is used (which corresponds to the most electronegative element present).
fixed_elements (dict) – A dictionary of chemical potentials to fix (in the format: {element: value}; e.g. {"Li": -2}) if the chemical system is >3-D. Constraining chemical potentials is required for multinary systems, in order to reduce the dimensionality to 3-D for plotting a 2-D heatmap. For a system with N elements, N-3 fixed chemical potentials should be specified. If None (default), the chemical potentials of the first N-3 elements in the bulk composition are fixed to their mean values in the stability region (i.e. the centroid of the stability region).
bordering_phases (bool) – Whether to plot the competing/secondary phases which border the host composition in the chemical potential diagram. Default is True.
xlim (tuple) – The x-axis limits for the plot. If None (default), the limits are set to the minimum and maximum values of the x-axis data, with padding equal to padding (default = 10% of the range).
ylim (tuple) – The y-axis limits for the plot. If None (default), the limits are set to the minimum and maximum values of the y-axis data, with padding equal to padding (default = 10% of the range).
cbar_range (tuple) – The range for the colourbar. If None (default), the range is set to the minimum and maximum values of the data.
colormap (str, matplotlib.colors.Colormap) –
Colormap to use for the heatmap, either as a string (which can be a colormap name from https://www.fabiocrameri.ch/colourmaps / https://matplotlib.org/stable/users/explain/colors/colormaps) or a Colormap / ListedColormap object. If None (default), uses batlow from https://www.fabiocrameri.ch/colourmaps.

Append “S” to the colormap name if using a sequential colormap from https://www.fabiocrameri.ch/colourmaps.
padding (float) – The padding to add to the x and y axis limits. If None (default), the padding is set to 10% of the range.
title (str or bool) – The title for the plot. If False (default), no title is added. If True, the title is set to the bulk composition formula, or if str, the title is set to the provided string.
label_positions (bool, dict or list) – The positions for the chemical formula line labels. If True (default), the labels are placed using a custom doped algorithm which attempts to find the best possible positions (minimising overlap). If False, no labels are added. Alternatively a dictionary can be provided, where the keys are the chemical formulae and the values are tuples of (x_coord, y-offset) at which to place the line labels (where y-offset is the offset from the line at x=x_coord). A list of tuples can also be provided, where the order is assumed to match the competing phase lines.
filename (PathLike) – The filename to save the plot to. If None (default), the plot is not saved.
style_file (PathLike) – Path to a mplstyle file to use for the plot. If None (default), uses the default doped style (from doped/utils/doped.mplstyle).
**kwargs – Additional keyword arguments to pass to ChemicalPotentialDiagram.get_grid(), such as n_points (default = 1000) and cartesian (default = False).

Returns:

The matplotlib Figure object.

Return type:

plt.Figure

doped.chemical_potentials.prune_entries_to_border_candidates(entries: list[ComputedEntry], bulk_computed_entry: ComputedEntry, phase_diagram: PhaseDiagram | None = None, energy_above_hull: float = 0.05)[source]

Given an input list of ComputedEntry/ComputedStructureEntry``s (``entries) and a single entry for the host material (bulk_computed_entry), returns the subset of entries which could border the host on the phase diagram (and therefore be a competing phase which determines the host chemical potential limits), allowing for an error tolerance for the semi-local DFT database energies (energy_above_hull, set to self.energy_above_hull – 0.05 eV/atom by default).

If phase_diagram is provided then this is used as the reference phase diagram, otherwise it is generated from entries and bulk_computed_entry.

Parameters:

entries (list[ComputedEntry]) – List of ComputedEntry objects to prune down to potential host border candidates on the phase diagram.
bulk_computed_entry (ComputedEntry) – ComputedEntry object for the host material.
phase_diagram (PhaseDiagram) – Optional input; PhaseDiagram object for the system of interest. If provided, this is used as the reference phase diagram from which to determine the (potential) chemical potential limits, otherwise it is generated from entries and bulk_computed_entry.
energy_above_hull (float) – Maximum energy above hull (in eV/atom) of Materials Project entries to be considered as competing phases. This is an uncertainty range for the MP-calculated formation energies, which may not be accurate due to functional choice (GGA vs hybrid DFT / GGA+U / RPA etc.), lack of vdW corrections etc. All phases that would border the host material on the phase diagram, if their relative energy was downshifted by energy_above_hull, are included. (Default is 0.05 eV/atom).

Returns:

List of all ComputedEntry objects in entries which could border the host material on the phase diagram (and thus set the chemical potential limits), if their relative energy was downshifted by energy_above_hull eV/atom.

Return type:

list[ComputedEntry]