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, e_above_hull=0.1, api_key=None, full_phase_diagram=False)[source]

Bases: object

Class to generate the 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.1 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).

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

  • 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. Any 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.1 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()

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(system, extrinsic_species=None)[source]

Bases: object

Post-processing competing phases data to calculate chemical potentials.

Parameters:

  • system (str) – The ‘reduced formula’ of the bulk composition

  • extrinsic_species (str) – Extrinsic species - can only deal with one at a time (see tutorial on the docs for more complex cases).

bulk_composition

The bulk (host) composition

Type:

str

elemental

List of elemental species in the bulk composition

Type:

list

extrinsic_species

Extrinsic species, if present

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

calculate_chempots(csv_path=None, verbose=True, sort_by=None)[source]

Calculates chemical potential limits. For dopant species, it calculates the limiting potential based on the intrinsic chemical potentials (i.e. same as full_sub_approach=False in pycdt).

Parameters:

  • csv_path (str) – If set, will save chemical potential limits to csv

  • verbose (bool) – If True, will print out chemical potential limits.

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

Returns:

Pandas DataFrame, optionally saved to csv.

property chempots: dict

Returns the calculated chemical potential limits.

from_csv(csv_path)[source]

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

Parameters:

  • csv_path (str) – Path to csv file. Must have columns ‘Formula’,

  • Unit (and 'DFT Energy per Formula)

  • Atom ('DFT Energy per)

Returns:

None, sets self.data and self.elemental_energies.

from_vaspruns(path='competing_phases', folder='vasp_std', csv_path=None, verbose=True)[source]

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

Parameters:

  • path (list, str, pathlib Path) – 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.

  • folder (str) – The subfolder in which your vasprun.xml(.gz) output files are located (e.g. a file-structure like: formula_EaH_X/{folder}/vasprun.xml(.gz)). Default is to search for vasp_std subfolders, or directly in the formula_EaH_X folder.

  • csv_path (str) – 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.

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: dict

Returns the calculated intrinsic phase diagram.

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, sort_by_energy=False, prune_polymorphs=False)[source]

Write parsed competing phases data to csv. Can be re-loaded with CompetingPhasesAnalyzer.from_csv().

Parameters:

  • csv_path (str) – 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, extrinsic_species, e_above_hull=0.1, full_sub_approach=False, codoping=False, api_key=None)[source]

Bases: CompetingPhases

This class generates the competing phases that need to be calculated to obtain the chemical potential limits when doping with extrinsic species / impurities.

Ensures that only the necessary additional competing phases are generated.

Parameters:

  • composition (str, Composition) – Composition of host material (e.g. ‘LiFePO4’, or Composition(‘LiFePO4’), or Composition({“Li”:1, “Fe”:1, “P”:1, “O”:4}))

  • extrinsic_species (str, list) – Extrinsic dopant/impurity species (e.g. “Mg” or [“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. Default is 0.1 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 = False. Described in further detail below.

  • 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 = 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 This should correspond to the legacy MP API; from https://legacy.materialsproject.org/open.

This code uses the Materials Project (MP) phase diagram data along with the e_above_hull error range to generate potential competing phases.

NOTE on ‘full_sub_approach’:

The default approach for substitutional elements (full_sub_approach = False) is to only consider chemical potential limits with a maximum of 1 extrinsic phase (composition with extrinsic species present). 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.

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.

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_chempots_from_phase_diagram(bulk_ce, phase_diagram)[source]

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

Parameters:

  • bulk_ce – Pymatgen ComputedStructureEntry object for bulk entry / supercell

  • phase_diagram – Pymatgen PhaseDiagram object for the system of interest

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