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.CompetingPhases(composition: str | Composition | Structure, e_above_hull: float = 0.05, api_key: str | None = None, full_phase_diagram: bool = False)[source]

Bases: object

Class to generate VASP input files for competing phases on the phase diagram for the host material, which determine the chemical potential limits for 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 (e_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 e_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 e_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.
e_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 e_above_hull, are included. Often e_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).
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
full_phase_diagram (bool) – If True, include all phases on the MP phase diagram (with energy above hull < e_above_hull eV/atom) for the chemical system of the input composition (not recommended). If False, 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 e_above_hull eV/atom. (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()

class doped.chemical_potentials.CompetingPhasesAnalyzer(composition: str | Composition)[source]

Bases: object

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

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

composition

The bulk (host) composition.

Type:: str

elements

List of all elements in the chemical system (host + extrinsic), from all parsed calculations.

Type:: list

extrinsic_elements

List of extrinsic elements in the chemical system (not present in composition).

Type:: str

data

List of dictionaries containing the parsed competing phases data.

Type:: list

formation_energy_df

DataFrame containing the parsed competing phases data.

Type:: pandas.DataFrame

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.
csv_path (PathLike) – If set, will save the calculated chemical potential limits to csv_path.
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 chempots: dict

Returns the calculated chemical potential limits.

If this is used with ExtrinsicCompetingPhases before calling calculate_chempots with a specified extrinsic_species, then the intrinsic chemical potential limits will be returned.

from_csv(csv_path: str | PathLike)[source]

Read in data from a previously parsed formation energies csv file.

Parameters:: csv_path (PathLike) – Path to csv file. Must have columns ‘Formula’, and ‘DFT Energy per Formula Unit (ev/fu)’ or ‘DFT Energy per Atom (ev/atom)’.
Returns:: None, sets self.data and self.elemental_energies.

Parses competing phase energies from vasprun.xml(.gz) outputs, computes the formation energies and generates the CompetingPhasesAnalyzer object.

By default, tries multiprocessing to speed up parsing, 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:

path (PathLike or list) – Either a path to the base folder in which you have your competing phase calculation outputs (e.g. formula_EaH_X/vasp_std/vasprun.xml(.gz), or formula_EaH_X/vasprun.xml(.gz)), or a list of strings/Paths to vasprun.xml(.gz) files.
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)). Default is to search for vasp_std subfolders, or directly in the formula_EaH_X folder.
csv_path (PathLike) – If set will save the parsed data to a csv at this filepath. Further customisation of the output csv can be achieved with the CompetingPhasesAnalyzer.to_csv() method.
verbose (bool) – Whether to print out information about directories that were skipped (due to no vasprun.xml files being found). Default is True.
processes (int) – Number of processes to use for multiprocessing for expedited parsing. If not set, defaults to one less than the number of CPUs available, or 1 if less than 10 phases to parse. Set to 1 for no multiprocessing.

Returns:

None, sets self.data, self.formation_energy_df and self.elemental_energies

property intrinsic_chempots: dict: Returns the calculated intrinsic chemical potential limits.

property intrinsic_phase_diagram: PhaseDiagram: Returns the calculated intrinsic phase diagram.

Plot a heatmap of the chemical potentials for a ternary system.

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 the other two elemental chemical potentials on the x and y axes.

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

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).
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 is 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 is 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 or 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 (list, dict or bool) – 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 the x positions at which to place the line labels. If a list of floats, the labels are placed at the provided x positions.
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).

Returns:

The matplotlib Figure object.

Return type:

plt.Figure

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

A very simple function to print out the competing phase formation energies in a LaTeX table format, showing the formula, 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).
sort_by_energy (bool) – If True, sorts the table by formation energy (highest to lowest). Default is False (sorting by formula).
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

to_csv(csv_path: str | PathLike, sort_by_energy: bool = False, prune_polymorphs: bool = False)[source]

Write parsed competing phases data to csv.

Can be re-loaded with CompetingPhasesAnalyzer.from_csv().

Parameters:

csv_path (Pathlike) – Path to csv file to write to.
sort_by_energy (bool) – If True, sorts the csv by formation energy (highest to lowest). Default is False (sorting by formula).
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.

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

Bases: CompetingPhases

Class to generate VASP input files for competing phases involving extrinsic (dopant/impurity) elements, which determine the chemical potential limits for those elements in the host compound.

Only extrinsic competing phases are contained in the: ExtrinsicCompetingPhases.entries list (used for input file generation), while the intrinsic competing phases for the host compound are stored in ExtrinsicCompetingPhases.intrinsic_entries.

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 (e_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 e_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 e_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.
extrinsic_species (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”]).
e_above_hull (float) –
Maximum energy-above-hull 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. Any phases that would border the host material on the phase diagram, if their relative energy was downshifted by e_above_hull, are included.

Often e_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.
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. Default is False.

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. Only relevant to 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) - see the doped Installation docs page: https://doped.readthedocs.io/en/latest/Installation.html. MP API key is available at https://next-gen.materialsproject.org/api#api-key
full_phase_diagram (bool) – If True, include all phases on the MP phase diagram (with energy above hull < e_above_hull eV/atom) for the chemical system of the input composition and extrinsic species (not recommended). If False, 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 e_above_hull eV/atom. Default is False.

doped.chemical_potentials.combine_extrinsic(first, second, extrinsic_species)[source]

Combines chemical limits for different extrinsic species using chemical limits json file from ChemicalPotentialAnalysis.

Usage explained in the example jupyter notebook :param first: First chemical potential dictionary, it can contain extrinsic species other :type first: dict :param than the set extrinsic species: :param second: Second chemical potential dictionary, it must contain the extrinsic species :type second: dict :param extrinsic_species: Extrinsic species in the second dictionary :type extrinsic_species: str

Returns:: dict.

Get the corresponding Materials Project (MP) SummaryDoc documents 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 ``SummaryDocs in this chemical system which match one of these entries (based on the MPIDs given in ComputedEntry.entry_id/ComputedEntry.data["material_id"] and SummaryDoc.material_id) are returned. Moreover, all data fields listed in data_fields (set to "band_gap", "total_magnetization" and "database_IDs" by default) will be copied from the corresponding SummaryDoc attribute to ComputedEntry.data for the matching ComputedEntry in entries

Note that this function can only be used with the new Materials Project API, as the legacy API does not have the SummaryDoc functionality (but most of the same data is available through the property_data arguments for the legacy-API-compatible functions).

Parameters:

entries (list[ComputedEntry]) – Optional input; list of ComputedEntry objects for the input chemical system. If provided, only SummaryDocs which match one of these entries (based on the MPIDs given in ComputedEntry.entry_id/ ComputedEntry.data["material_id"] and SummaryDoc.material_id) are returned. Moreover, all data fields listed in data_fields will be copied from the corresponding SummaryDoc attribute to ComputedEntry.data for the matching ComputedEntry in entries.
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 SummaryDoc documents. Must be a new (not legacy) MP API key! 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#setup-potcars-and-materials -project-api
data_fields (list[str]) – List of data fields to copy from the corresponding SummaryDoc attributes to the ComputedEntry.data objects, if entries is supplied. If not set, defaults to ["band_gap", "total_magnetization", "database_IDs"].
**kwargs – Additional keyword arguments to pass to the Materials Project API query, e.g. mpr.materials.summary.search().

Returns:

Dictionary of SummaryDoc documents with MPIDs as keys.

Return type:

dict[str, SummaryDoc]

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, phase_diagram)[source]

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

Parameters:

bulk_computed_entry – ComputedStructureEntry object for the host composition.
phase_diagram – PhaseDiagram object for the system of interest

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().

Automatically uses the appropriate format and syntax required for the new or legacy Materials Project (MP) APIs, depending on the type of API key supplied/present.

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 page: https://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 or legacy Materials Project (MP) APIs, depending on the type of API key supplied/present. 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 e_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 page: https://doped.readthedocs.io/en/latest/Installation.html#setup-potcars-and-materials -project-api
e_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).
return_all_info (bool) – If True, also returns the property_key_dict and property_data_fields objects, which list the appropriate keys and data field names for the new or legacy Materials Project API (corresponding to the current API key). Mainly intended for internal doped usage for provenance tracking. Default is False.
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. If return_all_info is True, also returns the property_key_dict and property_data_fields objects, which list the appropriate keys and data field names for the new or legacy Materials Project API (corresponding to the current API key).

Return type:

list[ComputedStructureEntry], dict, list

doped.chemical_potentials.make_molecular_entry(computed_entry, legacy_MP=False)[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.
legacy_MP (bool) – If True, use the legacy Materials Project property data fields (i.e. "e_above_hull", "pretty_formula" etc.), rather than the new Materials Project API format ("energy_above_hull", "formula_pretty" etc.). Default is False.

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

doped.chemical_potentials.prune_entries_to_border_candidates(entries: list[ComputedEntry], bulk_computed_entry: ComputedEntry, phase_diagram: PhaseDiagram | None = None, e_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 (e_above_hull, set to self.e_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.
e_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 e_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 e_above_hull eV/atom.

Return type:

list[ComputedEntry]