doped.generation module

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

class doped.generation.DefectsGenerator(structure: Structure | Atoms | PathLike, 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[str, int | float | bool] | None = None, interstitial_gen_kwargs: dict | bool | None = None, target_frac_coords: list | None = None, processes: int | None = None, **kwargs)

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) using the get_interstitial_sites function, which also generates adsorbate sites if the structure is determined to be a slab/layer/rod. This can be controlled using the interstitial_gen_kwargs argument. 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_ideal_supercell_matrix() function (see docstring), with default settings of min_image_distance = 10 (minimum distance between periodic images of 10 Å), min_atoms = 50 (minimum 50 atoms in the supercell) and ideal_threshold = 0.1 (allow up to 10% larger supercell if it is a diagonal expansion of the primitive or conventional cell). This uses a custom algorithm in doped to efficiently search over possible supercell transformations and identify that with the minimum number of atoms (hence computational cost) that satisfies the minimum image distance, number of atoms and ideal_threshold constraints. These settings can be controlled by specifying keyword arguments with supercell_gen_kwargs, which are passed to get_ideal_supercell_matrix() (e.g. for a minimum image distance of 15 Å with at least 100 atoms, supercell_gen_kwargs would be: {'min_image_distance': 15, 'min_atoms': 100}). If the input structure already satisfies these constraints (for the same number of atoms as the doped-generated supercell), then it will be used. 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 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). Large (absolute) charge states, low probability oxidation states and/or greater charge/oxidation state magnitudes than that of the host are disfavoured. This can be controlled using the probability_threshold (default = 0.0075) key in the charge_state_gen_kwargs parameter, which is passed to the guess_defect_charge_states() 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, and the charge_state_probability() docstring for more details on the charge state guessing algorithm. The doped algorithm was found to give optimal performance in terms of efficiency and completeness (see JOSS paper), but of course may not be perfect in all cases, so make sure to critically consider the estimated charge states for your system!

Note that Wyckoff letters can depend on the ordering of elements in the conventional standard structure, for which doped uses the spglib convention.

Parameters:

• structure (Structure) – Structure of the host material, either as a pymatgen Structure, ASE Atoms or path to a structure file (e.g. CONTCAR). If this is not the primitive unit cell, it will be reduced to the primitive cell for defect generation, before supercell generation.

• extrinsic (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_mult_and_equiv_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 the custom algorithm in doped which efficiently searches over possible supercell transformations and identifies that with the minimum number of atoms (hence computational cost) that satisfies the minimum image distance, number of atoms and ideal_threshold constraints – which can be controlled with supercell_gen_kwargs). If False, then the input structure is used as the defect & bulk supercell (note this may give a slightly different (but fully equivalent) set of coordinates). Default is True.

• charge_state_gen_kwargs (dict) – Keyword arguments to pass to the guess_defect_charge_states function (such as probability_threshold; default = 0.0075) to control defect charge state generation.

• supercell_gen_kwargs (dict) – Keyword arguments to pass to the get_ideal_supercell_matrix function (such as min_image_distance (default = 10), min_atoms (default = 50), ideal_threshold (default = 0.1), force_cubic – which enforces a (near-)cubic supercell output (default = False), or force_diagonal (default = False)).

• interstitial_gen_kwargs (dict, bool) – Keyword arguments for get_interstitial_sites() (such as min_dist (0.9 Å, or 0.5 Å for Hydrogen), clustering_tol (0.8 Å), symm_pref_dist_factor (0.85), stol (0.32), tight_stol (0.02), symprec (0.01), vacuum_radius (1.5 * bulk bond length), include_unique_wyckoffs (False) – see its docstring, parentheses indicate default values), or InterstitialGenerator (where only min_dist is used) 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] (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.

• **kwargs –

  Additional keyword arguments for defect generation. Options:

  • {defect}_elements where {defect} is vacancy, substitution, or interstitial, in which cases only those defects of the specified elements will be generated (where {defect}_elements is a list of element symbol strings). Setting {defect}_elements to an empty list will skip defect generation for that defect type entirely.

  • {defect}_charge_states to specify the charge states to use for all defects of that type (as a list of integers).

  • neutral_only to only generate neutral charge states.

  • symprec for get_sga_and_symprec(), get_primitive_structure, defect object initialisation etc. Default is 0.01.

  • Keyword arguments for get_all_equiv_sites, such as dist_tol_factor.

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 self.primitive_structure * self.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

prim_interstitial_coords_mult_and_equiv_coords

List of interstitial coordinates in the primitive cell, their multiplicity and the equivalent fractional coordinates, as a list of tuples.

Type:

list

|DefectsGenerator| input parameters are also set as attributes.

add_charge_states(defect_entry_name: str, charge_states: list | int)

Add additional DefectEntrys 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]), or a single charge state (e.g. -2).

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 | Path)

Load a DefectsGenerator object from a json(.gz) file.

Note that .json.gz files can be loaded directly.

Parameters:

filename (PathLike) – Filename of json file to load DefectsGenerator object from.

Returns:

DefectsGenerator object

remove_charge_states(defect_entry_name: str, charge_states: list | int)

Remove DefectEntrys 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]), or a single charge state (e.g. -2).

to_json(filename: str | Path | None = None)

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

Note that file extensions with “.gz” will be automatically compressed (recommended to save space)!

Parameters:

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

doped.generation.charge_state_probability(charge_state: int, defect_el_oxi_state: int, defect_el_oxi_probability: float, max_host_oxi_magnitude: int, return_log: bool = False) → float | dict

Function to estimate the probability of a given defect charge state, 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).

Disfavours large (absolute) charge states, low probability oxidation states and greater charge/oxidation state magnitudes than that of the host. Specifically, the overall probability is given by the product of these probability factors:

• The probability of the corresponding oxidation state of the defect element (e.g. Na_i^+1 has Na in the +1 oxidation state), typically given by its prevalence in the ICSD (for substitutions & interstitials), or the vacancy oxidation state probability function (described in the guess_defect_charge_states() docstring; implemented in _get_vacancy_oxi_states).

• The magnitude of the charge state; with a probability function: 1/|charge_state|^(2/3)

• The magnitude of the charge state relative to the max host oxidation state (i.e. how ‘charged’ the host is); with a probability function: 1/(2*|charge_state - max_host_oxi_magnitude|)^(2/3) if charge_state > max_host_oxi_magnitude, otherwise 1.

• The magnitude of the defect element oxidation state relative to the max host oxidation state; with a probability function: 1/(2*|defect_el_oxi_state - max_host_oxi_magnitude|)^(2/3) if defect_el_oxi_state > max_host_oxi_magnitude, otherwise 1.

Note that neutral charge states are always included.

This probability function was found to give optimal performance in terms of efficiency and completeness when tested against other approaches (see the doped JOSS paper: https://doi.org/10.21105/joss.06433) but of course may not be perfect in all cases, so make sure to critically consider the estimated charge states for your system!

Parameters:

• charge_state (int) – Charge state of defect.

• defect_el_oxi_state (int) – Oxidation state of defect element.

• defect_el_oxi_probability (float) – Probability of oxidation state of defect element.

• max_host_oxi_magnitude (int) – Maximum host oxidation state magnitude.

• return_log (bool) – If true, returns a dictionary of input & computed values used to determine charge state probability. Default is False.

Returns:

Probability of the defect charge state (between 0 and 1) if return_log is False, otherwise a dictionary of input & computed values used to determine charge state probability.

doped.generation.closest_site_info(defect_entry_or_defect: DefectEntry | Defect, n: int = 1, element_list: list[str] | None = None)

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

If there are multiple elements with the same distance (to within ~0.01 Å), then the preference for which element to return is controlled by element_list. If element_list is not provided, then it is set to match the order of appearance in the structure composition.

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

Parameters:

• defect_entry_or_defect (DefectEntry | Defect) – DefectEntry or Defect object, to get neighbour info.

• n (int) – Return the element symbol and distance for the nth closest site. Default is 1, corresponding to the (1st) closest neighbour.

• element_list (list) – Sorted list of elements in the host structure to govern the preference of elemental symbols to return, when the distance to multiple neighbours with different elements is the same. Default is to use _get_element_list(), which follows the order of appearance of elements in the Structure composition.

Returns:

Element symbol and distance (rounded to 2 decimal places) of the nth closest site to the defect site.

Return type:

str

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+, sc_defect_frac_coords: ~numpy.ndarray | None = None)

Generate a doped DefectEntry object from a doped Defect object.

This is used to describe a Defect with a specified simulation cell. To set the sc_defect_frac_coords attribute for DefectEntry (fractional coordinates of the defect in the defect_supercell), either dummy_species must be present in the defect_supercell (which is taken as the defect site), or sc_defect_frac_coords must be set.

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 present in the defect_supercell structure, used to determine sc_defect_frac_coords. If not found and sc_defect_frac_coords is not set, DefectEntry.sc_defect_frac_coords is set to None. Default is DummySpecies("X").

• sc_defect_frac_coords (np.ndarray) – Fractional coordinates of the defect in the defect supercell. If not set and dummy_species is not found in the defect_supercell, DefectEntry.sc_defect_frac_coords is set to None. Default is None.

Returns:

doped DefectEntry object.

Return type:

DefectEntry

doped.generation.get_defect_name_from_defect(defect: Defect, element_list: list[str] | None = None, symprec: float = 0.01)

Get the doped/SnB defect name from a 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.

• 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, symprec: float | None = None, relaxed: bool = True, **kwargs)

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

Note: If relaxed = True (default), then this uses the defect_entry.defect_supercell to determine the point symmetry of the (relaxed) defect structure, via direct isometry analysis of the local defect environment (see point_symmetry_from_defect_entry(); insensitive to periodicity-breaking supercell shapes, unlike global space-group analysis).

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.

• symprec (float) – Distance tolerance (in Å) for symmetry determination (see point_symmetry_from_defect_entry()). Default is 0.01 Å for unrelaxed structures, 0.1 Å 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).

• relaxed (bool) – If False, determines the site symmetry using the defect site in the unrelaxed bulk supercell, otherwise determines the point symmetry of the relaxed defect in the defect supercell. Default is True.

• **kwargs – Additional keyword arguments to pass to point_symmetry_from_defect_entry(), such as dist_tol_factor or verbose.

Returns:

Defect name.

Return type:

str

doped.generation.get_defect_site_orig_oxi_state(defect: Defect) → int

Get the oxidation state of the original (bulk) site at the defect position in the host structure.

This is the oxidation state of the original bulk site for vacancies and substitutions – for vacancies, taken as the negative of Vacancy.oxi_state (the fully-ionised vacancy charge state), to account for possible user-specified vacancy oxidation states – or 0 for interstitials (no original bulk site occupant).

Note that this requires oxidation states to be assigned to defect.structure for substitutions, and defect.oxi_state for vacancies).

Parameters:

defect (Defect) – A doped Defect object.

Returns:

Oxidation state of the original (bulk) site at the defect position, rounded to the nearest integer (for possible mixed-valence cases).

Return type:

int

doped.generation.get_ideal_supercell_matrix(structure: Structure, min_image_distance: float = 10.0, min_atoms: int = 50, force_cubic: bool = False, force_diagonal: bool = False, ideal_threshold: float = 0.1, verbose: bool = False, pbar: tqdm | None = None) → ndarray

Determine the ideal supercell matrix for a given structure, based on the minimum image distance, minimum number of atoms and ideal_threshold for further expanding if a diagonal expansion of the primitive/conventional cell is possible.

The ideal supercell is the smallest possible supercell which has a minimum image distance (i.e. minimum distance between periodic images of atoms/sites in a lattice) greater than min_image_distance (default = 10 Å – which is a typical threshold value used in QM/DFT defect supercell calculations) and a number of atoms greater than min_atoms (default = 50). Once these criteria have been reached, doped will then continue searching up to supercell sizes (numbers of atoms) 1 + ideal_threshold times larger (rounded up) to see if they return a diagonal expansion of the primitive/conventional cell (which can make later visualisation and analysis much easier) – if so, this larger supercell will be returned.

This search for the ideal supercell transformation matrix is performed using the find_ideal_supercell function from doped.utils.supercells (see its docstring for more details), which efficiently scans over possible supercell matrices and identifies that with the minimum image distance and most cubic-like supercell shape. The advantage of this over that in pymatgen-analysis-defects is that it avoids the find_optimal_cell_shape function from ASE (which currently does not work for rotated matrices, is inefficient, and optimises based on cubic- like shape rather than minimum image distance), giving greatly reduced supercell sizes for a given minimum image distance.

If force_cubic or force_diagonal are True, then the CubicSupercellTransformation from pymatgen is used to identify any simple near-cubic supercell transformations which satisfy the minimum image distance and atom number criteria.

Parameters:

• structure (Structure) – Primitive unit cell structure to generate supercell for.

• min_image_distance (float) – Minimum image distance in Å of the supercell (i.e. minimum distance between periodic images of atoms/sites in the lattice). (Default = 10.0)

• min_atoms (int) – Minimum number of atoms allowed in the supercell. (Default = 50)

• force_cubic (bool) – Enforce usage of CubicSupercellTransformation from pymatgen for supercell generation. (Default = False)

• force_diagonal (bool) – If True, return a transformation with a diagonal transformation matrix. (Default = False)

• ideal_threshold (float) – Threshold for increasing supercell size (beyond that which satisfies min_image_distance and min_atoms`) to achieve an ideal supercell matrix (i.e. a diagonal expansion of the primitive or conventional cell). Supercells up to 1 + perfect_cell_threshold times larger (rounded up) are trialled, and will instead be returned if they yield an ideal transformation matrix. (Default = 0.1; i.e. 10% larger than the minimum size)

• verbose (bool) – Whether to print out extra information about the supercell search. (Default = False)

• pbar (tqdm) – tqdm progress bar object to update (for internal doped usage). Default is None.

Returns:

Ideal supercell matrix (np.ndarray).

doped.generation.get_interstitial_sites(host_structure: Structure, min_dist: float = 0.9, clustering_tol: float = 0.8, symm_pref_dist_factor: float = 0.85, stol: float = 0.32, tight_stol: float = 0.02, symprec: float = 0.01, vacuum_radius: float | None = None, include_unique_wyckoffs: bool = False) → list

Generate candidate interstitial sites using Voronoi analysis.

This function uses a similar approach to that in VoronoiInterstitialGenerator from pymatgen-analysis-defects, but with modifications to make interstitial generation much faster, fix bugs with interstitial grouping (which could lead to undesired dropping of candidate sites) and achieve better control over site placement in order to favour sites which are higher-symmetry and furthest from the host lattice atoms (typically the most favourable interstitial sites).

If the structure is detected to have a significant vacuum volume (determined using vacuum_radius), thus corresponding to a slab/layer/line structure, then the pymatgen adsorbate finder will be used to generate further candidate interstitial sites.

The logic for picking interstitial sites is as follows:

• Generate all candidate sites using (efficient) Voronoi analysis

• If vacuum volume present, include adsorbate sites as candidate sites

• Remove any sites which are within min_dist of any host atoms

• Cluster the remaining sites using a tolerance of clustering_tol and symmetry-preference of symm_pref_dist_factor (see doped_cluster_frac_coords)

• Determine the multiplicities and symmetry-equivalent coordinates of the clustered sites using doped symmetry functions.

• Group the clustered sites by symmetry using (looser) site matching as controlled by stol.

• From each group, pick the site with the highest symmetry and furthest distance from the host atoms, if its min_dist is no more than no more than symm_pref_dist_factor (0.85 by default) times the largest possible min_dist (distanceto the host atoms).

(Parameters mentioned here can be supplied via interstitial_gen_kwargs as noted in the args section below.)

The motivation for favouring high symmetry interstitial sites and then distance to host atoms is because higher symmetry interstitial sites are typically the more intuitive sites for placement, cleaner, easier for analysis etc., and interstitials are often lowest-energy when furthest from host atoms (i.e. in the largest interstitial voids – particularly for fully-ionised charge states), and so this approach tries to strike a balance between these two goals.

One caveat to this preference for high symmetry interstitial sites, is that they can also be slightly more prone to being stuck in local minima on the PES, and so as always it is highly recommended to use ShakeNBreak or another structure-searching technique to account for symmetry-breaking when performing defect relaxations!

You can see what Cartesian distance the chosen stol corresponds to using the get_stol_equiv_dist function. Note that you will likely want to reduce min_dist for hydrogen interstitials! (This is done by default with DefectsGenerator, reducing it to 0.5 Å for Hydrogen.)

Parameters:

• host_structure (Structure) – Host structure.

• min_dist (float) – Minimum distance from host atoms for interstitial sites. Defaults to 0.9 Å.

• clustering_tol (float) – Tolerance for clustering interstitial sites. Defaults to 0.8 Å.

• symm_pref_dist_factor (float) – Minimum acceptable ratio of distance to host atoms for symmetry-favoured sites vs distance-to-host-favoured sites, for which to prefer symmetry-favoured sites. Defaults to 0.85.

• stol (float) – Structure matcher tolerance for looser site matching. Defaults to 0.32.

• tight_stol (float) – Structure matcher tolerance for tighter site matching. Defaults to 0.02.

• symprec (float) – Symmetry precision for (symmetry-)equivalent site determination. Defaults to 0.01.

• vacuum_radius (float) – Tolerance radius for determining if a significant vacuum volume is present in the structure (if any Voronoi node has a minimum distance to a host atom greater than this value), in which case adsorbate sites will also be included for interstitial generation. Defaults to None, in which case it is set to 1.5 times the minimum bulk bond length.

• include_unique_wyckoffs (bool) – Include unique Wyckoff positions (those with no free variables) in the set of candidate interstitial sites. This can help ensure that expected canonical interstitial sites (e.g. distorted tetrahedral and octahedral in BCC crystals) are included, but will increase the number of candidate interstitials and is not expected to locate lower-energy sites compared to the default Voronoi approach in most cases. Defaults to False.

Returns:

List of interstitial sites as fractional coordinates

Return type:

list

doped.generation.get_neighbour_distances_and_symbols(site: PeriodicSite, structure: Structure, n: int = 1, element_list: list[str] | None = None, dist_tol_prefactor: float = 3.0, min_dist: float = 0.02)

Get a list of sorted tuples of (distance, element) for the nth closest sites to the input site in structure, where each consecutive neighbour in the list must be at least 0.02 Å further away than the previous neighbour.

If there are multiple elements with the same distance (to within ~0.01 Å), then the preference for which element to return is controlled by element_list. If element_list is not provided, then it is set to match the order of appearance in the structure composition.

For efficiency, this function dynamically increases the radius when searching for nearest neighbours as necessary, using the input dist_tol_prefactor and n to estimate a reasonable starting range.

Parameters:

• site (PeriodicSite) – Site to get neighbour info.

• structure (Structure) – Structure containing the site and neighbours.

• n (int) – Return the element symbol and distance tuples for the nth closest neighbours. Default is 1, corresponding to only the nearest neighbour.

• element_list (list) – Sorted list of elements in the host structure to govern the preference of elemental symbols to return, when the distance to multiple neighbours with different elements is the same. Default is to use the order of appearance of elements in the Structure composition.

• dist_tol_prefactor (float) – Initial distance tolerance prefactor to use when searching for neighbours, where the initial search radius is set to dist_tol_prefactor * sqrt(n) Å. This value is dynamically updated as needed, and so should only be adjusted if providing odd systems with very small/large bond lengths for which efficiency improvements are possible. Default is 3.0.

• min_dist (float) – Minimum distance in Å of neighbours from site. Intended as a distance tolerance to exclude the site itself from the neighbour list, for which the default value (0.02 Å) should be perfectly fine in most cases. Set to 0 to include the site itself in the output list (in which case it counts toward n).

Returns:

Sorted list of tuples of (distance, element) for the nth closest neighbours to the input site.

Return type:

list

doped.generation.get_stol_equiv_dist(stol: float, structure: Structure) → float

Get the equivalent Cartesian distance of a given stol value for a given Structure.

stol is a site tolerance parameter used in pymatgen StructureMatcher functions, defined as the fraction of the average free length per atom := ( V / Nsites ) ** (1/3).

Parameters:

• stol (float) – Site tolerance parameter.

• structure (Structure) – Structure to get equivalent distance for.

Returns:

Equivalent Cartesian distance for the given stol value.

Return type:

float

doped.generation.guess_defect_charge_states(defect: Defect, probability_threshold: float = 0.0075, return_log: bool = False) → list[int] | tuple[list[int], list[dict]]

Guess the possible stable charge states of a defect.

This function estimates the probabilities of the charge states of a defect, using the probability of the corresponding defect element oxidation states, the magnitudes of the charge states, and the maximum magnitude of the host oxidation states (i.e. how ‘charged’ the host is), and returns a list of charge states that have an estimated probability greater than the probability_threshold.

Disfavours large (absolute) charge states, low probability oxidation states and greater charge/oxidation state magnitudes than that of the host. The neutral charge state is always included, as well as the fully-ionised charge state (a.k.a. the natural charge state / ‘defect oxidation state’, i.e. the simple oxidation state difference) for intrinsic defects. If no charge states have probabilities above probability_threshold, the most probable charge state is included, and if the resulting charge state range is only {0} (e.g. for elemental systems) or the defect is a homovalent substitution then (-1, 0, +1) at minimum is included.

For substitutions and interstitials, the oxidation state probabilities are those of the corresponding defect element (as given by their prevalence in the ICSD), while for vacancies, effective ‘oxidation states’ of the vacant site are used, with 100% probability for oxidation states between that of the original site (i.e. the neutral vacancy) and zero (i.e. the fully-ionised vacancy), and Gaussian-decaying probabilities (corresponding to Boltzmann-weighted quadratic energy cost of additional charge; ∝exp(-Δq²)) of (1/4)^(Δ²) (= exp(-Δ²·ln4)) where Δ is the difference to the closest oxidation state in the 100% probability range, +1 if sign-reversed with respect to the original site oxidation state (i.e. effectively anionic on a cation site or vice versa; beyond ‘fully-ionised’). For specific details on the probability functions employed, see the charge_state_probability() function.

These probability functions were found to give optimal performance in terms of efficiency and completeness when tested against other approaches (see the doped JOSS paper: https://doi.org/10.21105/joss.06433) but of course may not be perfect in all cases, so make sure to critically consider the estimated charge states for your system!

Parameters:

• defect (Defect) – doped Defect object. Note that defect.structure must have oxidation states assigned (e.g. with add_oxidation_state_by_element()) for charge state guessing; this is handled automatically when generating defects with DefectsGenerator.

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

• 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 probabilities, including near-miss charge states (with probabilities above 10% of probability_threshold). 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.name_defect_entries(defect_entries: list[DefectEntry | Defect], element_list: list[str] | None = 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 or Defect 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.

Returns:

Dictionary of {name: DefectEntry} objects.

Return type:

dict

doped.generation.sort_defect_entries(defect_entries: dict | list, element_list: list | None = None)

Sort defect entries for deterministic behaviour; for output and when reloading DefectsGenerator objects, with DefectThermodynamics entries (particularly for deterministic plotting behaviour), and with DefectsParser objects.

Sorts defect entries by defect type (vacancies, substitutions, interstitials), then by order of appearance of elements in the host composition, then by periodic group (main groups 1, 2, 13-18 first, then TMs), then by atomic number, then (for defect entries of the same type) sort by name and charge state (from positive to negative).

Parameters:

• defect_entries (dict or list) – Dictionary (in the format: {defect_entry_name: defect_entry}) or list of defect entries to sort.

• element_list (list, optional) – List of elements present, used to determine preferential ordering. If None, determined by _get_element_list(), which orders by appearance of elements in the host composition, then by periodic group (main groups 1, 2, 13-18 first, then TMs), then by atomic number.

Returns:

Sorted dictionary or list of defect entries.