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)

Bases: object

Class to generate the input files for competing phases on the phase diagram for the host material (determining the chemical potential limits). Materials Project (MP) data is used, along with an uncertainty range specified by e_above_hull, to determine the relevant competing phases. Diatomic gaseous molecules are generated as molecules-in-a-box as appropriate.

Parameters:

• composition (str, Composition) – Composition of 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 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) - 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) 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. (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)

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)

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

• kpoints_nonmetals (int) – Kpoint density per inverse volume (Å^-3) 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/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)

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)

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.

cplap_input(dependent_variable=None, filename='input.dat')

For completeness’ sake, automatically saves to input.dat for cplap :param dependent_variable: chosen from the composition if this isn’t set :type dependent_variable: str :param filename: filename, should end in .dat :type filename: str

Returns

None, writes input.dat file.

from_csv(csv_path)

Read in data from csv.

Parameters:

csv_path (str) – Path to csv file. Must have columns ‘formula’, ‘energy_per_fu’, ‘energy’ and ‘formation_energy’

Returns:

None, sets self.data and self.elemental_energies.

from_vaspruns(path='competing_phases', folder='vasp_std', csv_path=None)

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.

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)

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)

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)

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)

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)

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)

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)

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)

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:

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