doped.core module

Core functions and classes for defects in doped.

class doped.core.Defect(structure: Structure, site: PeriodicSite, multiplicity: int | None = None, oxi_state: float | None = None, equivalent_sites: List[PeriodicSite] | None = None, symprec: float = 0.01, angle_tolerance: float = 5, user_charges: List[int] | None = None, **doped_kwargs)[source]

Bases: Defect

Doped Defect object.

Subclass of pymatgen.analysis.defects.core.Defect with additional attributes and methods used by doped.

Parameters:

  • structure – The structure in which to create the defect. Typically the primitive structure of the host crystal.

  • site – The defect site in the structure.

  • multiplicity – The multiplicity of the defect.

  • oxi_state – The oxidation state of the defect, if not specified, this will be determined automatically.

  • equivalent_sites – A list of equivalent sites for the defect in the structure.

  • symprec – Tolerance for symmetry finding.

  • angle_tolerance – Angle tolerance for symmetry finding.

  • user_charges – User specified charge states. If specified, get_charge_states will return this list. If None or empty list the charge states will be determined automatically.

  • **doped_kwargs – Additional keyword arguments to define doped-specific attributes (listed below), in the form doped_attribute_name=value. (e.g. wyckoff = "4a").

as_dict()[source]

JSON-serializable dict representation of Defect.

Needs to be redefined because attributes not explicitly specified in subclasses, which is required for monty functions.

classmethod from_json(filename: str)[source]

Load a Defect object from a json file.

Parameters:

filename (str) – Filename of json file to load Defect from.

Returns:

Defect object

get_supercell_structure(sc_mat: ndarray | None = None, min_atoms: int = 50, max_atoms: int = 500, min_length: float = 10.0, force_diagonal: bool = False, dummy_species: str | None = None, target_frac_coords: ndarray | None = None, return_sites: bool = False) → Structure[source]

Generate the supercell for a defect.

Redefined from the parent class to allow the use of target_frac_coords to place the defect at the closest equivalent site to the target fractional coordinates in the supercell, while keeping the supercell fixed (to avoid any issues with defect parsing). Also returns information about equivalent defect sites in the supercell.

Parameters:

  • sc_mat – Transformation matrix of self.structure to create the supercell. If None, then automatically determined by CubicSupercellAnalyzer.

  • target_frac_coords – If set, the defect will be placed at the closest equivalent site to these fractional coordinates (using self.equivalent_sites).

  • return_sites – If True, returns a tuple of the defect supercell, defect supercell site and list of equivalent supercell sites.

  • dummy_species – Dummy species to highlight the defect position (for visualizing vacancies).

  • max_atoms – Maximum number of atoms allowed in the generated supercell (if sc_mat is None).

  • min_atoms – Minimum number of atoms allowed in the generated supercell (if sc_mat is None).

  • min_length – Minimum length of the generated supercell lattice vectors (if sc_mat is None).

  • force_diagonal – If True, generate a supercell with a diagonal transformation matrix (if sc_mat is None).

Returns:

The defect supercell structure. If return_sites is True, also returns the defect supercell site and list of equivalent supercell sites.

to_json(filename: str | None = None)[source]

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

Parameters:

filename (str) – Filename to save json file as. If None, the filename will be set as “{Defect.name}.json”.

class doped.core.DefectEntry(defect: ~doped.core.Defect, charge_state: int, sc_entry: ~pymatgen.entries.computed_entries.ComputedStructureEntry, corrections: ~typing.Dict[str, float] = <factory>, corrections_metadata: ~typing.Dict[str, ~typing.Any] = <factory>, sc_defect_frac_coords: ~typing.Tuple[float, float, float] | None = None, bulk_entry: ~pymatgen.entries.computed_entries.ComputedStructureEntry | None = None, entry_id: str | None = None, name: str = '', calculation_metadata: ~typing.Dict = <factory>, conventional_structure: ~pymatgen.core.structure.Structure | None = None, conv_cell_frac_coords: ~numpy.ndarray | None = None, equiv_conv_cell_frac_coords: ~typing.List[~numpy.ndarray] = <factory>, _BilbaoCS_conv_cell_vector_mapping: ~typing.List[int] = <factory>, wyckoff: str | None = None, charge_state_guessing_log: ~typing.Dict = <factory>, defect_supercell: ~pymatgen.core.structure.Structure | None = None, defect_supercell_site: ~pymatgen.core.sites.PeriodicSite | None = None, equivalent_supercell_sites: ~typing.List[~pymatgen.core.sites.PeriodicSite] = <factory>, bulk_supercell: ~pymatgen.core.structure.Structure | None = None)[source]

Bases: DefectEntry

Subclass of pymatgen.analysis.defects.thermo.DefectEntry with additional attributes used by doped.

Core Attributes:
defect:

doped/pymatgen defect object corresponding to the defect in the entry.

charge_state:

Charge state of the defect.

sc_entry:

pymatgen ComputedStructureEntry for the _defect_ supercell.

sc_defect_frac_coords:

The fractional coordinates of the defect in the supercell.

bulk_entry:

pymatgen ComputedEntry for the bulk supercell reference. Required for calculating the defect formation energy.

corrections:

A dictionary of energy corrections which are summed and added to the defect formation energy.

corrections_metadata:

A dictionary that acts as a generic container for storing information about how the corrections were calculated. Only used for debugging and plotting purposes.

Parsing Attributes:
calculation_metadata:

A dictionary of calculation parameters and data, used to perform charge corrections and compute formation energies.

Generation Attributes:
name:

The doped-generated name of the defect entry. See docstrings of DefectsGenerator for the doped naming algorithm.

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.

conv_cell_frac_coords:

Fractional coordinates of the defect in the conventional cell.

equiv_conv_cell_frac_coords:

Symmetry-equivalent defect positions in fractional coordinates of the conventional cell.

_BilbaoCS_conv_cell_vector_mapping:

A vector mapping the lattice vectors of the spglib-defined conventional cell to that of the Bilbao Crystallographic Server definition (for most space groups the definitions are the same).

wyckoff:

Wyckoff label of the defect site.

charge_state_guessing_log:

A log of the input & computed values used to determine charge state probabilities.

defect_supercell:

pymatgen Structure object of the defect supercell.

defect_supercell_site:

pymatgen PeriodicSite object of the defect in the defect supercell.

equivalent_supercell_sites:

List of pymatgen PeriodicSite objects of symmetry-equivalent defect sites in the defect supercell.

bulk_supercell:

pymatgen Structure object of the bulk (pristine, defect-free) supercell.

as_dict() → dict[source]

Returns a dictionary representation of the DefectEntry object.

bulk_entry: ComputedStructureEntry | None = None
bulk_supercell: Structure | None = None
calculation_metadata: Dict
charge_state: int
charge_state_guessing_log: Dict
conv_cell_frac_coords: ndarray | None = None
conventional_structure: Structure | None = None
property corrected_energy: float

The energy of the defect entry with _all_ corrections applied.

corrections: Dict[str, float]
corrections_metadata: Dict[str, Any]
defect: Defect
defect_supercell: Structure | None = None
defect_supercell_site: PeriodicSite | None = None
entry_id: str | None = None
equiv_conv_cell_frac_coords: List[ndarray]
equivalent_supercell_sites: List[PeriodicSite]
classmethod from_json(filename: str)[source]

Load a DefectEntry object from a json file.

Parameters:

filename (str) – Filename of json file to load DefectEntry from.

Returns:

DefectEntry object

get_freysoldt_correction(dielectric: float | int | ndarray | list | None = None, defect_locpot: str | Locpot | dict | None = None, bulk_locpot: str | Locpot | dict | None = None, plot: bool = False, filename: str | None = None, axis=None, return_correction_error: bool = False, error_tolerance: float = 0.05, **kwargs) → CorrectionResult[source]

Compute the _isotropic_ Freysoldt (FNV) correction for the defect_entry.

The correction is added to the defect_entry.corrections dictionary (to be used in following formation energy calculations). If this correction is used, please cite Freysoldt’s original paper; 10.1103/PhysRevLett.102.016402.

Parameters:

  • dielectric (float or int or 3x1 matrix or 3x3 matrix) – Total dielectric constant of the host compound (including both ionic and (high-frequency) electronic contributions). If None, then the dielectric constant is taken from the defect_entry calculation_metadata if available.

  • defect_locpot – Path to the output VASP LOCPOT file from the defect supercell calculation, or the corresponding pymatgen Locpot object, or a dictionary of the planar-averaged potential in the form: {i: Locpot.get_average_along_axis(i) for i in [0,1,2]}. If None, will try to use defect_locpot from the defect_entry calculation_metadata if available.

  • bulk_locpot – Path to the output VASP LOCPOT file from the bulk supercell calculation, or the corresponding pymatgen Locpot object, or a dictionary of the planar-averaged potential in the form: {i: Locpot.get_average_along_axis(i) for i in [0,1,2]}. If None, will try to use bulk_locpot from the defect_entry calculation_metadata if available.

  • plot (bool) – Whether to plot the FNV electrostatic potential plots (for manually checking the behaviour of the charge correction here).

  • filename (str) – Filename to save the FNV electrostatic potential plots to. If None, plots are not saved.

  • axis (int or None) – If int, then the FNV electrostatic potential plot along the specified axis (0, 1, 2 for a, b, c) will be plotted. Note that the output charge correction is still that for _all_ axes. If None, then all three axes are plotted.

  • return_correction_error (bool) – If True, also returns the average standard deviation of the planar-averaged potential difference times the defect charge (which gives an estimate of the error range of the correction energy). Default is False.

  • error_tolerance (float) – If the estimated error in the charge correction is greater than this value (in eV), then a warning is raised. (default: 0.05 eV)

  • **kwargs – Additional kwargs to pass to pymatgen.analysis.defects.corrections.freysoldt.get_freysoldt_correction (e.g. energy_cutoff, mad_tol, q_model, step).

Returns:

CorrectionResults (summary of the corrections applied and metadata), and the matplotlib figure object (or axis object if axis specified) if plot is True, and the estimated charge correction error if return_correction_error is True.

get_kumagai_correction(dielectric: float | int | ndarray | list | None = None, defect_outcar: str | Outcar | None = None, bulk_outcar: str | Outcar | None = None, plot: bool = False, filename: str | None = None, return_correction_error: bool = False, error_tolerance: float = 0.05, **kwargs)[source]

Compute the Kumagai (eFNV) finite-size charge correction for the defect_entry. Compatible with both isotropic/cubic and anisotropic systems.

The correction is added to the defect_entry.corrections dictionary (to be used in following formation energy calculations). If this correction is used, please cite the Kumagai & Oba paper: 10.1103/PhysRevB.89.195205

Parameters:

  • dielectric (float or int or 3x1 matrix or 3x3 matrix) – Total dielectric constant of the host compound (including both ionic and (high-frequency) electronic contributions). If None, then the dielectric constant is taken from the defect_entry calculation_metadata if available.

  • defect_outcar – Path to the output VASP OUTCAR file from the defect supercell calculation, or the corresponding pymatgen Outcar object. If None, will try to use the defect_supercell_site_potentials from the defect_entry calculation_metadata if available.

  • bulk_outcar – Path to the output VASP OUTCAR file from the bulk supercell calculation, or the corresponding pymatgen Outcar object. If None, will try to use the bulk_supercell_site_potentials from the defect_entry calculation_metadata if available.

  • plot (bool) – Whether to plot the Kumagai site potential plots (for manually checking the behaviour of the charge correction here).

  • filename (str) – Filename to save the Kumagai site potential plots to. If None, plots are not saved.

  • return_correction_error (bool) – If True, also returns the standard error of the mean of the sampled site potential differences times the defect charge (which gives an estimate of the error range of the correction energy). Default is False.

  • error_tolerance (float) – If the estimated error in the charge correction is greater than this value (in eV), then a warning is raised. (default: 0.05 eV)

  • **kwargs – Additional kwargs to pass to pydefect.corrections.efnv_correction.ExtendedFnvCorrection (e.g. charge, defect_region_radius, defect_coords).

Returns:

CorrectionResults (summary of the corrections applied and metadata), and the matplotlib figure object if plot is True, and the estimated charge correction error if return_correction_error is True.

name: str = ''
sc_defect_frac_coords: Tuple[float, float, float] | None = None
sc_entry: ComputedStructureEntry
to_json(filename: str | None = None)[source]

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

Parameters:

filename (str) – Filename to save json file as. If None, the filename will be set as “{DefectEntry.name}.json”.

wyckoff: str | None = None
class doped.core.Interstitial(*args, **kwargs)[source]

Bases: Interstitial, Defect

Subclass of pymatgen.analysis.defects.core.Interstitial with additional attributes and methods used by doped.

class doped.core.Substitution(*args, **kwargs)[source]

Bases: Substitution, Defect

Subclass of pymatgen.analysis.defects.core.Substitution with additional attributes and methods used by doped.

class doped.core.Vacancy(*args, **kwargs)[source]

Bases: Vacancy, Defect

Subclass of pymatgen.analysis.defects.core.Vacancy with additional attributes and methods used by doped.

doped.core.doped_defect_from_pmg_defect(defect: Defect, bulk_oxi_states=False, **doped_kwargs)[source]

Create the corresponding doped Defect (Vacancy, Interstitial, Substitution) from an input pymatgen Defect object.

Parameters:

  • defect – pymatgen Defect object.

  • bulk_oxi_states – Either a dict of bulk oxidation states to use, or a boolean. If True, re-guesses the oxidation state of the defect (ignoring the pymatgen Defect oxi_state attribute), otherwise uses the already-set oxi_state (default = 0). Used in doped defect generation to make defect setup more robust and efficient (particularly for odd input structures, such as defect supercells etc).

  • **doped_kwargs – Additional keyword arguments to define doped-specific attributes (see class docstring).