doped.generation module

Code to generate Defect objects and supercell structures for ab-initio calculations.

class doped.generation.DefectsGenerator(structure: Structure, extrinsic: str | List | Dict | None = None, interstitial_coords: List | None = None, generate_supercell: bool = True, charge_state_gen_kwargs: Dict | None = None, supercell_gen_kwargs: Dict | None = None, interstitial_gen_kwargs: Dict | None = None, target_frac_coords: List | None = None, processes: int | None = None)

Bases: MSONable

Class for generating doped DefectEntry objects.

Generates doped DefectEntry objects for defects in the input host structure. By default, generates all intrinsic defects, but extrinsic defects (impurities) can also be created using the extrinsic argument.

Interstitial sites are generated using Voronoi tessellation by default (found to be the most reliable), which can be controlled using the interstitial_gen_kwargs argument (passed as keyword arguments to the VoronoiInterstitialGenerator class). Alternatively, a list of interstitial sites (or single interstitial site) can be manually specified using the interstitial_coords argument.

By default, supercells are generated for each defect using the doped get_supercell_structure() method, with default settings of min_length = 10 (minimum supercell length of 10 Å) and min_atoms = 50 (minimum 50 atoms in supercell). If a different supercell is desired, this can be controlled by specifying keyword arguments with supercell_gen_kwargs, which are passed to get_supercell_structure() (e.g. for a minimum supercell length of 15 Å, use: supercell_gen_kwargs = {‘min_length’: 15}). Alternatively if generate_supercell = False, then no supercell is generated and the input structure is used as the defect & bulk supercell. (Note this may give a slightly different (but fully equivalent) set of coordinates).

The algorithm for determining defect entry names is to use the pymatgen defect name (e.g. v_Cd, Cd_Te etc.) for vacancies/antisites/substitutions, unless there are multiple inequivalent sites for the defect, in which case the point group of the defect site is appended (e.g. v_Cd_Td, Cd_Te_Td etc.), and if this is still not unique, then element identity and distance to the nearest neighbour of the defect site is appended (e.g. v_Cd_Td_Te2.83, Cd_Te_Td_Cd2.83 etc.). For interstitials, the same naming scheme is used, but the point group is always appended to the pymatgen defect name.

Possible charge states for the defects are estimated using the probability of the corresponding defect element oxidation state, the magnitude of the charge state, and the maximum magnitude of the host oxidation states (i.e. how ‘charged’ the host is), with large (absolute) charge states, low probability oxidation states and/or greater charge/oxidation state magnitudes than that of the host being disfavoured. This can be controlled using the probability_threshold (default = 0.0075) or padding (default = 1) keys in the charge_state_gen_kwargs parameter, which are passed to the _charge_state_probability() function. The input and computed values used to guess charge state probabilities are provided in the DefectEntry.charge_state_guessing_log attributes. See docs for examples of modifying the generated charge states.

Parameters:

• structure (Structure) – Structure of the host material (as a pymatgen Structure object). If this is not the primitive unit cell, it will be reduced to the primitive cell for defect generation, before supercell generation.

• extrinsic (Union[str, List, Dict]) – List or dict of elements (or string for single element) to be used for extrinsic defect generation (i.e. dopants/impurities). If a list is provided, all possible substitutional defects for each extrinsic element will be generated. If a dict is provided, the keys should be the host elements to be substituted, and the values the extrinsic element(s) to substitute in; as a string or list. In both cases, all possible extrinsic interstitials are generated.

• interstitial_coords (List) – List of fractional coordinates (corresponding to the input structure), or a single set of fractional coordinates, to use as interstitial defect site(s). Default (when interstitial_coords not specified) is to automatically generate interstitial sites using Voronoi tessellation. The input interstitial_coords are converted to DefectsGenerator.prim_interstitial_coords, which are the corresponding fractional coordinates in DefectsGenerator.primitive_structure (which is used for defect generation), along with the multiplicity and equivalent coordinates, sorted according to the doped convention.

• generate_supercell (bool) – Whether to generate a supercell for the output defect entries (using pymatgen’s CubicSupercellTransformation and ASE’s find_optimal_cell_shape() functions) or not. If False, then the input structure is used as the defect & bulk supercell.

• charge_state_gen_kwargs (Dict) – Keyword arguments to be passed to the _charge_state_probability function (such as probability_threshold (default = 0.0075, used for substitutions and interstitials) and padding (default = 1, used for vacancies)) to control defect charge state generation.

• supercell_gen_kwargs (Dict) – Keyword arguments to be passed to the get_sc_fromstruct function in pymatgen.analysis.defects.supercells (such as min_atoms (default = 50), max_atoms (default = 500), min_length (default = 10), and force_diagonal (default = False)).

• interstitial_gen_kwargs (Dict, bool) – Keyword arguments to be passed to the VoronoiInterstitialGenerator class (such as clustering_tol, stol, min_dist etc), or to InterstitialGenerator if interstitial_coords is specified. If set to False, interstitial generation will be skipped entirely.

• target_frac_coords (List) – Defects are placed at the closest equivalent site to these fractional coordinates in the generated supercells. Default is [0.5, 0.5, 0.5] if not set (i.e. the supercell centre, to aid visualisation).

• processes (int) – Number of processes to use for multiprocessing. If not set, defaults to one less than the number of CPUs available.

defect_entries

Dictionary of {defect_species: DefectEntry} for all defect entries (with charge state and supercell properties) generated.

Type:

Dict

defects

Dictionary of {defect_type: [Defect, …]} for all defect objects generated.

Type:

Dict

primitive_structure

Primitive cell structure of the host used to generate defects.

Type:

Structure

supercell_matrix

Matrix to generate defect/bulk supercells from the primitive cell structure.

Type:

Matrix

bulk_supercell

Supercell structure of the host (equal to primitive_structure * supercell_matrix).

Type:

Structure

conventional_structure

Conventional cell structure of the host according to the Bilbao Crystallographic Server (BCS) definition, used to determine defect site Wyckoff labels and multiplicities.

Type:

Structure

`DefectsGenerator` input parameters are also set as attributes.

add_charge_states(defect_entry_name: str, charge_states: list)

Add additional DefectEntry`s with the specified charge states to `self.defect_entries.

Parameters:

• defect_entry_name (str) – Name of defect entry to add charge states to. Doesn’t need to include the charge state.

• charge_states (list) – List of charge states to add to defect entry (e.g. [-2, -3]).

as_dict()

JSON-serializable dict representation of DefectsGenerator.

defect_generator_info()

Prints information about the defects that have been generated.

classmethod from_dict(d)

Reconstructs DefectsGenerator object from a dict representation created using DefectsGenerator.as_dict().

Parameters:

d (dict) – dict representation of DefectsGenerator.

Returns:

DefectsGenerator object

classmethod from_json(filename: str)

Load a DefectsGenerator object from a json file.

Parameters:

• filename (str) – Filename of json file to load DefectsGenerator

• from. (object) –

Returns:

DefectsGenerator object

remove_charge_states(defect_entry_name: str, charge_states: list)

Remove DefectEntry`s with the specified charge states from `self.defect_entries.

Parameters:

• defect_entry_name (str) – Name of defect entry to remove charge states from. Doesn’t need to include the charge state.

• charge_states (list) – List of charge states to add to defect entry (e.g. [-2, -3]).

to_json(filename: str | None = None)

Save the DefectsGenerator object as a json file, which can be reloaded with the DefectsGenerator.from_json() class method.

Parameters:

filename (str) – Filename to save json file as. If None, the filename will be set as “{Chemical Formula}_defects_generator.json” where {Chemical Formula} is the chemical formula of the host material.

doped.generation.closest_site_info(defect_entry_or_defect, n=1, element_list=None)

Return the element and distance (rounded to 2 decimal places) of the closest site to the defect in the input DefectEntry or Defect object.

If DefectEntry, uses defect_entry.defect_supercell_site if set, otherwise defect_entry.sc_defect_frac_coords, with defect_entry.sc_entry.structure. If Defect, uses defect.get_supercell_structure() with a 2x2x2 supercell to ensure none of the detected sites are periodic images of the defect site.

Requires distances > 0.01 (i.e. so not the site itself), and if there are multiple elements with the same distance, sort by order of appearance of elements in the composition, then alphabetically and return the first one.

If n is set, then it returns the nth closest site, where the nth site must be at least 0.02 Å further away than the n-1th site.

doped.generation.get_defect_entry_from_defect(defect: ~doped.core.Defect, defect_supercell: ~pymatgen.core.structure.Structure, charge_state: int, dummy_species: ~pymatgen.core.periodic_table.DummySpecies = DummySpecies X0+)

Generate doped DefectEntry object from a doped Defect object.

This is used to describe a Defect with a specified simulation cell.

Parameters:

• defect (Defect) – doped/pymatgen Defect object.

• defect_supercell (Structure) – Defect supercell structure.

• charge_state (int) – Charge state of the defect.

• dummy_species (DummySpecies) – Dummy species used to keep track of defect

Returns:

doped DefectEntry object.

Return type:

DefectEntry

doped.generation.get_defect_name_from_defect(defect, element_list=None, symm_ops=None, symprec=0.01)

Get the doped/SnB defect name from Defect object.

Parameters:

• defect (Defect) – Defect object.

• element_list (list) – Sorted list of elements in the host structure, so that closest_site_info returns deterministic results (in case two different elements located at the same distance from defect site). Default is None.

• symm_ops (list) – List of symmetry operations of defect.structure, to avoid re-calculating. Default is None (recalculates).

• symprec (float) – Symmetry tolerance for spglib. Default is 0.01.

Returns:

Defect name.

Return type:

str

doped.generation.get_defect_name_from_entry(defect_entry: DefectEntry, element_list: list | None = None, symm_ops: list | None = None, symprec: float | None = None, unrelaxed: bool = False)

Get the doped/SnB defect name from a DefectEntry object.

Note: If unrelaxed=False (default), then this tries to use the defect_entry.defect_supercell to determine the site symmetry. This will thus give the _relaxed_ defect point symmetry if this is a DefectEntry created from parsed defect calculations. However, it should be noted that this is not guaranteed to work in all cases; namely for non-diagonal supercell expansions, or sometimes for non-scalar supercell expansion matrices (e.g. a 2x1x2 expansion)(particularly with high-symmetry materials) which can mess up the periodicity of the cell. doped tries to automatically check if this is the case, and will warn you if so.

This can also be checked by using this function on your doped _generated_ defects:

from doped.generation import get_defect_name_from_entry for defect_name, defect_entry in defect_gen.items():

print(defect_name, get_defect_name_from_entry(defect_entry, unrelaxed=True),

get_defect_name_from_entry(defect_entry), “n”)

And if the point symmetries match in each case, then using this function on your parsed _relaxed_ DefectEntry objects should correctly determine the final relaxed defect symmetry (and closest site info) - otherwise periodicity-breaking prevents this.

Parameters:

• defect_entry (DefectEntry) – DefectEntry object.

• element_list (list) – Sorted list of elements in the host structure, so that closest_site_info returns deterministic results (in case two different elements located at the same distance from defect site). Default is None.

• symm_ops (list) – List of symmetry operations of the defect_entry.bulk_supercell structure, to avoid re-calculating. Default is None (recalculates).

• symprec (float) – Symmetry tolerance for spglib. Default is 0.01 for unrelaxed structures, 0.2 for relaxed (to account for residual structural noise). You may want to adjust for your system (e.g. if there are very slight octahedral distortions etc).

• unrelaxed (bool) – If True, determines the site symmetry using the defect site _in the unrelaxed bulk supercell_, otherwise uses the defect supercell to determine the site symmetry (i.e. try determine the point symmetry of a relaxed defect in the defect supercell). Default is False.

Returns:

Defect name.

Return type:

str

doped.generation.get_oxi_probabilities(element_symbol: str) → dict

Get a dictionary of oxidation states and their probabilities for an element.

Tries to get the probabilities from the pymatgen tabulated ICSD oxidation state probabilities, and if not available, uses the common oxidation states of the element.

Parameters:

element_symbol (str) – Element symbol.

Returns:

Dictionary of oxidation states (ints) and their probabilities (floats).

Return type:

dict

doped.generation.guess_defect_charge_states(defect: Defect, probability_threshold: float = 0.0075, padding: int = 1, return_log: bool = False) → List[int] | Tuple[List[int], List[Dict]]

Guess the possible charge states of a defect.

Parameters:

• defect (Defect) – doped Defect object.

• probability_threshold (float) – Probability threshold for including defect charge states (for substitutions and interstitials). Default is 0.0075.

• padding (int) – Padding for vacancy charge states, such that the vacancy charge states are set to range(vacancy oxi state, padding), if vacancy oxidation state is negative, or to range(-padding, vacancy oxi state), if positive. Default is 1.

• return_log (bool) – If true, returns a tuple of the defect charge states and a list of dictionaries of input & computed values used to determine charge state probability. Default is False.

Returns:

List of defect charge states (int) or a tuple of the defect charge states (list) and a list of dictionaries of input & computed values used to determine charge state probability.

doped.generation.herm2sch(herm_symbol)

Convert from Hermann-Mauguin to Schoenflies.

doped.generation.name_defect_entries(defect_entries, element_list=None, symm_ops=None)

Create a dictionary of {Name: DefectEntry} from a list of DefectEntry objects, where the names are set according to the default doped algorithm; which is to use the pymatgen defect name (e.g. v_Cd, Cd_Te etc.) for vacancies/antisites/substitutions, unless there are multiple inequivalent sites for the defect, in which case the point group of the defect site is appended (e.g. v_Cd_Td, Cd_Te_Td etc.), and if this is still not unique, then element identity and distance to the nearest neighbour of the defect site is appended (e.g. v_Cd_Td_Te2.83, Cd_Te_Td_Cd2.83 etc.). Names do not yet have charge states included.

For interstitials, the same naming scheme is used, but the point group is always appended to the pymatgen defect name.

If still not unique after the 3rd nearest neighbour info, then “a, b, c” etc is appended to the name of different defects to distinguish.

Parameters:

• defect_entries (list) – List of DefectEntry objects to name.

• element_list (list) – Sorted list of elements in the host structure, so that closest_site_info returns deterministic results (in case two different elements located at the same distance from defect site). Default is None.

• symm_ops (list) – List of symmetry operations of defect.structure (i.e. the primitive structure), to avoid re-calculating. Default is None (recalculates).

Returns:

Dictionary of {Name: DefectEntry} objects.

Return type:

dict