doped.vasp module

Code to generate VASP defect calculation input files.

class doped.vasp.DefectDictSet(structure: Structure, charge_state: int = 0, user_incar_settings: dict | None = None, user_kpoints_settings: dict | Kpoints | None = None, user_potcar_functional: str = 'PBE', user_potcar_settings: dict | None = None, poscar_comment: str | None = None, **kwargs)[source]

Bases: DopedDictSet

Extension to pymatgen VaspInputSet object for VASP defect calculations.

Parameters:

structure (Structure) – pymatgen Structure object of the defect supercell.
charge_state (int) – Charge of the defect (to set NELECT – total number of electrons).
user_incar_settings (dict) – Dictionary of user INCAR settings (AEXX, NCORE etc.) to override default settings. Highly recommended to look at output INCARs or the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder, to see what the default INCAR settings are. Note that any flags that aren’t numbers or True/False need to be input as strings with quotation marks (e.g. {"ALGO": "All"}). (default: None)
user_kpoints_settings (dict or Kpoints) – Dictionary of user KPOINTS settings (in pymatgen VaspInputSet format) e.g., {"reciprocal_density": 123}, or a Kpoints object. Default is Gamma-centred, reciprocal_density = 100 [Å⁻³].
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.
poscar_comment (str) – Comment line to use for POSCAR files. Default is defect name, fractional coordinates of initial site and charge state.
**kwargs – Additional kwargs to pass to VaspInputSet.

property incar

Returns the Incar object generated from DopedDictSet, with NELECT and NUPDOWN set accordingly.

See https://doped.readthedocs.io/en/latest/Tips.html#spin for discussion about appropriate NUPDOWN/MAGMOM settings.

property nelect

Number of electrons (NELECT) for the given structure and charge state.

This is equal to the sum of valence electrons (ZVAL) of the POTCARs for each atom in the structure (supercell), minus the charge state.

write_input(output_path: str | Path, poscar: bool = True, rattle: bool = False, make_dir_if_not_present: bool = True, include_cif: bool = False, potcar_spec: bool = False, zip_output: bool = False, snb: bool = False, stdev: float | None = None, d_min: float | None = None)[source]

Writes out all input to a directory.

Refactored slightly from pymatgen VaspInputSet.write_input() to allow checking of user POTCAR setup, and generation of rattled structures.

Parameters:

output_path (PathLike) – Directory to output the VASP input files.
poscar (bool) – If True, write the POSCAR to the generated folder as well. If rattle=True, this will be a rattled structure, otherwise the unperturbed defect structure. (default: True)
rattle (bool) – If writing POSCAR, apply random displacements to all atomic positions in the structure using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: False)
make_dir_if_not_present (bool) – Set to True if you want the directory (and the whole path) to be created if it is not present. (default: True)
include_cif (bool) – Whether to write a CIF file in the output directory for easier opening by VESTA. (default: False)
potcar_spec (bool) – Instead of writing the POTCAR, write a “POTCAR.spec”. This is intended to help sharing an input set with people who might not have a license to specific Potcar files. Given a POTCAR.spec file, the specific POTCAR file can be re-generated using pymatgen with the generate_potcar function in the pymatgen CLI. (default: False)
zip_output (bool) – Whether to zip each VASP input file written to the output directory. (default: False)
snb (bool) – If input structures are from ShakeNBreak (so POSCARs aren’t ‘unperturbed’) – only really intended for internal use by ShakeNBreak. (default: False)
stdev (float) – Standard deviation for the Gaussian distribution of displacements for the ShakeNBreak rattling algorithm. If None (default) this is set to 10% of the nearest neighbour distance in the structure.
d_min (float) – Minimum interatomic distance (in Angstroms) in the rattled structure. Monte Carlo rattle moves that put atoms at distances less than this will be heavily penalised. Default is to set this to 80% of the nearest neighbour distance in the structure.

Bases: MSONable

Class for generating input files for VASP defect relaxation calculations for a single pymatgen DefectEntry or Structure object.

The supercell structure and charge state are taken from the DefectEntry attributes, or if a Structure is provided, then from the defect_supercell and charge_state input parameters.

Creates attributes:

DefectRelaxSet.vasp_gam:
DefectDictSet for Gamma-point only relaxation. Usually not needed if ShakeNBreak (or other) structure searching has been performed (recommended), unless only Γ-point k-point sampling is required (converged) for your system, and no vasp_std calculations with multiple k-points are required (determined from kpoint settings).
DefectRelaxSet.vasp_nkred_std:
DefectDictSet for relaxation with a kpoint mesh and using NKRED. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Gamma k-point sampling is required.
DefectRelaxSet.vasp_std:
DefectDictSet for relaxation with a kpoint mesh, not using NKRED. Not generated if only Gamma kpoint sampling is required.
DefectRelaxSet.vasp_ncl:
DefectDictSet for single-point (static) energy calculation with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).

where DefectDictSet is an extension of pymatgen’s VaspInputSet class for defect calculations, with incar, poscar, kpoints and potcar attributes for the corresponding VASP defect calculations (see docstring). Also creates the corresponding bulk_vasp_... attributes for single-point (static) energy calculations of the bulk (pristine, defect-free) supercell. This needs to be calculated once with the same settings as the defect calculations, for the later calculation of defect formation energies.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

Parameters:

defect_entry (DefectEntry, Structure) – doped/pymatgen DefectEntry or Structure (defect supercell) for which to generate DefectDictSets for.
charge_state (int) – Charge state of the defect. Overrides DefectEntry.charge_state if DefectEntry is input.
soc (bool) – Whether to generate vasp_ncl DefectDictSet attribute for spin-orbit coupling single-point (static) energy calculations. If not set, then by default is set to True if the max atomic number (Z) in the structure is >= 31 (i.e. further down the periodic table than Zn), otherwise False.
user_incar_settings (dict) – Dictionary of user INCAR settings (AEXX, NCORE etc.) to override default settings. Highly recommended to look at output INCARs or the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder, to see what the default INCAR settings are. Note that any flags that aren’t numbers or True/False need to be input as strings with quotation marks (e.g. {"ALGO": "All"}). (default: None)
user_kpoints_settings (dict or Kpoints) – Dictionary of user KPOINTS settings (in pymatgen VaspInputSet format) e.g., {"reciprocal_density": 123}, or a Kpoints object, to use for the vasp_std, vasp_nkred_std and vasp_ncl DefectDictSets (Γ-only for vasp_gam). Default is Gamma-centred, reciprocal_density = 100 [Å⁻³].
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.
**kwargs – Additional kwargs to pass to DefectDictSet.

Key Attributes:

vasp_gam (DefectDictSet):: DefectDictSet for Gamma-point only relaxation. Usually not needed if ShakeNBreak (or other) structure searching has been performed (recommended), unless only Γ-point k-point sampling is required (converged) for your system, and no vasp_std calculations with multiple k-points are required (determined from kpoints settings).
vasp_nkred_std (DefectDictSet):: DefectDictSet for relaxation with a non-Γ-only kpoint mesh, using NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of the hybrid DFT calculation. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Gamma kpoint sampling is required.
vasp_std (DefectDictSet):: DefectDictSet for relaxation with a non-Γ-only kpoint mesh, not using NKRED. Not generated if only Gamma kpoint sampling is required.
vasp_ncl (DefectDictSet):: DefectDictSet for single-point (static) energy calculation with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).
defect_supercell (Structure):: Supercell structure for defect calculations, taken from defect_entry.defect_supercell (if defined), otherwise from defect_entry.sc_entry.structure if inputting a DefectEntry object, or the input structure if inputting a Structure object.
bulk_supercell (Structure):: Supercell structure of the bulk (pristine, defect-free) material, taken from defect_entry.bulk_supercell (if defined), otherwise from defect_entry.bulk_entry.structure if inputting a DefectEntry object, or None if inputting a Structure object.
poscar_comment (str):: Comment to write at the top of the POSCAR files. Default is the defect entry name, defect frac coords and charge state (if inputting a DefectEntry object), or the formula of the input structure and charge state (if inputting a Structure object), for defects. For the bulk supercell, it’s "{formula} - Bulk".
bulk_vasp_gam (DefectDictSet):: DefectDictSet for a bulk Γ-point-only single-point (static) supercell calculation. Often not used, as the bulk supercell only needs to be calculated once with the same settings as the final defect calculations, which may be with vasp_std or vasp_ncl.
bulk_vasp_nkred_std (DefectDictSet):: DefectDictSet for a single-point (static) bulk vasp_std supercell calculation (i.e. with a non-Γ-only kpoint mesh) and NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of the hybrid DFT calculation. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Gamma kpoint sampling is required.
bulk_vasp_std (DefectDictSet):: DefectDictSet for a single-point (static) bulk vasp_std supercell calculation with a non-Γ-only kpoint mesh, not using NKRED. Not generated if only Gamma kpoint sampling is required.
bulk_vasp_ncl (DefectDictSet):: DefectDictSet for single-point (static) energy calculation of the bulk supercell with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).

Input parameters are also set as attributes.

property bulk_vasp_gam: DefectDictSet | None

Returns a DefectDictSet object for a VASP bulk Γ-point-only (vasp_gam) single-point (static) supercell calculation. Often not used, as the bulk supercell only needs to be calculated once with the same settings as the final defect calculations, which is vasp_std if we have a non-Γ-only final k-point mesh, or vasp_ncl if SOC effects are being included. If the final converged k-point mesh is Γ-only, then bulk_vasp_gam should be used to calculate the single- point (static) bulk supercell reference energy. Can also sometimes be useful for the purpose of calculating defect formation energies at early stages of the typical vasp_gam -> vasp_nkred_std (if.

hybrid & non-Γ-only k-points) -> vasp_std (if non-Γ-only k-points) -> vasp_ncl (if SOC included) workflow, to obtain rough formation energy estimates and flag any potential issues with defect calculations early on.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property bulk_vasp_ncl: DefectDictSet | None

Returns a DefectDictSet object for VASP bulk supercell single- point calculations with spin-orbit coupling (SOC) included (i.e. LSORBIT = True), using vasp_ncl. If DefectRelaxSet.soc is False, then this returns None and a warning. If the soc parameter is not set when initializing DefectRelaxSet, then this is set to True for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn), otherwise False.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property bulk_vasp_nkred_std: DefectDictSet | None

Returns a DefectDictSet object for a single-point (static) bulk vasp_std supercell calculation (i.e. with a non-Γ-only kpoint mesh) and NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of the hybrid DFT calculation. By default, sets NKRED(X,Y,Z) to 2 or 3 in the directions for which the k-point grid is divisible by this factor. Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case (bulk_)vasp_gam should be used) or for GGA calculations (if LHFCALC is set to False in user_incar_settings, in which case (bulk_)vasp_std should be used).

The bulk supercell only needs to be calculated once with the same settings as the final defect calculations, which is vasp_std if we have a non-Γ-only final k-point mesh, vasp_ncl if SOC effects are being included (in which case bulk_vasp_ncl should be used for the single-point bulk supercell reference calculation), or vasp_gam if the final converged k-point mesh is Γ-only (in which case bulk_vasp_gam should be used for the single-point bulk supercell reference calculation). Can also sometimes be useful for the purpose of calculating defect formation energies at midway stages of the typical vasp_gam -> vasp_nkred_std (if hybrid & non-Γ-only k-points) -> vasp_std (if non-Γ-only k-points) -> vasp_ncl (if SOC included) workflow, to obtain rough formation energy estimates and flag any potential issues with defect calculations early on.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property bulk_vasp_std: DefectDictSet | None

Returns a DefectDictSet object for a single-point (static) bulk vasp_std supercell calculation. Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case (bulk_)vasp_gam should be used).

The bulk supercell only needs to be calculated once with the same settings as the final defect calculations, which is vasp_std if we have a non-Γ-only final k-point mesh, vasp_ncl if SOC effects are being included (in which case bulk_vasp_ncl should be used for the single-point bulk supercell reference calculation), or vasp_gam if the final converged k-point mesh is Γ-only (in which case bulk_vasp_gam should be used for the single-point bulk supercell reference calculation). Can also sometimes be useful for the purpose of calculating defect formation energies at midway stages of the typical vasp_gam -> vasp_nkred_std (if hybrid & non-Γ-only k-points) -> vasp_std (if non-Γ-only k-points) -> vasp_ncl (if SOC included) workflow, to obtain rough formation energy estimates and flag any potential issues with defect calculations early on.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property vasp_gam: DefectDictSet

Returns a DefectDictSet object for a VASP Γ-point-only (vasp_gam) defect supercell relaxation. Typically not needed if ShakeNBreak (or other) structure searching has been performed (recommended), unless only Γ-point k-point sampling is required (converged) for your system, and no vasp_std calculations with multiple k-points are required (determined from kpoints settings).

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property vasp_ncl: DefectDictSet | None

Returns a DefectDictSet object for a VASP defect supercell single- point calculation with spin-orbit coupling (SOC) included (i.e. LSORBIT = True), using vasp_ncl. If DefectRelaxSet.soc is False, then this returns None and a warning. If the soc parameter is not set when initializing DefectRelaxSet, then this is set to True for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn), otherwise False.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property vasp_nkred_std: DefectDictSet | None

Returns a DefectDictSet object for a VASP defect supercell relaxation using vasp_std (i.e. with a non-Γ-only kpoint mesh) and NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of hybrid DFT calculations, following the doped recommended defect calculation workflow (see docs). By default, sets NKRED(X,Y,Z) to 2 or 3 in the directions for which the k-point grid is divisible by this factor. Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case vasp_gam should be used) or for GGA calculations (if LHFCALC is set to False in user_incar_settings, in which case vasp_std should be used).

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

property vasp_std: DefectDictSet | None

Returns a DefectDictSet object for a VASP defect supercell relaxation using vasp_std (i.e. with a non-Γ-only kpoint mesh). Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case vasp_gam should be used).

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

write_all(defect_dir: str | Path | None = None, poscar: bool = False, rattle: bool = True, vasp_gam: bool | None = None, bulk: bool | str = False, **kwargs)[source]

Write all VASP input files to subfolders in the defect_dir folder.

The following subfolders are generated:

vasp_nkred_std:
Defect relaxation with a kpoint mesh and using NKRED. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Γ-point sampling required.
vasp_std:
Defect relaxation with a kpoint mesh, not using NKRED. Not generated if only Γ-point sampling required.
vasp_ncl:
Singlepoint (static) energy calculation with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).

If vasp_gam=True (not recommended) or self.vasp_std = None (i.e. Γ-only k-point sampling converged for the kpoints settings used), then also outputs:

vasp_gam:
Γ-point only defect relaxation. Usually not needed if structure searching has been performed (e.g. with ShakeNBreak) (recommended).

By default, does not generate a vasp_gam folder unless self.vasp_std is None (i.e. only Γ-point sampling required for this system), as vasp_gam calculations should be performed with defect structure-searching (e.g. with ShakeNBreak) and initial relaxations. If vasp_gam files are desired, set vasp_gam=True.

By default, POSCAR files are not generated for the vasp_(nkred_)std (and vasp_ncl if self.soc is True) folders, as these should be taken from structure-searching calculations (e.g. snb-groundstate -d vasp_nkred_std) or, if not following the recommended structure-searching workflow, from the CONTCARs of vasp_gam calculations. If including SOC effects (i.e. self.soc = True), then the vasp_std CONTCARs should be used as the vasp_ncl POSCARs. If POSCAR files are desired for the vasp_(nkred_)std (and vasp_ncl) folders, set poscar=True.

Input files for the single-point (static) bulk supercell reference calculation are also written to "{formula}_bulk/{subfolder}" if bulk is True (False by default), where subfolder corresponds to the final (highest accuracy) VASP calculation in the workflow (i.e. vasp_ncl if self.soc=True, otherwise vasp_std or vasp_gam if only Γ-point reciprocal space sampling is required). If bulk = "all", then the input files for all VASP calculations in the workflow are written to the bulk supercell folder.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

The DefectEntry object is also written to a json.gz file in defect_dir to aid calculation provenance – can be reloaded directly with loadfn() from monty.serialization, or DefectEntry.from_json().

Parameters:

defect_dir (PathLike) – Folder in which to create the VASP defect calculation inputs. Default is to use the DefectEntry name (e.g. "Y_i_C4v_O1.92_+2" etc.), from self.defect_entry.name. If this attribute is not set, it is automatically generated according to the doped convention (using get_defect_name_from_entry()). Output folder structure is <defect_dir>/<subfolder> where subfolder is the name of the corresponding VASP program to run (e.g. vasp_std).
poscar (bool) – If True, writes the defect POSCAR to the generated folders as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching using ShakeNBreak (https://shakenbreak.readthedocs.io) or another approach, then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)), first with NKRED if using hybrid DFT, then without NKRED. (default: False)
rattle (bool) – If writing POSCARs, apply random displacements to all atomic positions in the structures using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
vasp_gam (Optional[bool]) – If True, writes the vasp_gam input files, with defect POSCAR. Not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching (e.g. using ShakeNBreak; https://shakenbreak.readthedocs.io), then continue the vasp_std relaxations from the ground-state structures. Default is None, where vasp_gam folders are written if self.vasp_std is None (i.e. only Γ-point reciprocal space sampling is required).
bulk (bool, str) – If True, the input files for a single-point calculation of the bulk supercell are also written to "{formula}_bulk/{subfolder}", where subfolder corresponds to the final (highest accuracy) VASP calculation in the workflow (i.e. vasp_ncl if self.soc=True, otherwise vasp_std or vasp_gam if only Γ-point reciprocal space sampling is required). If bulk = "all" then the input files for all VASP calculations in the workflow (vasp_gam, vasp_nkred_std, vasp_std, vasp_ncl (if applicable)) are written to the bulk supercell folder. (Default: False)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

write_gam(defect_dir: str | Path | None = None, subfolder: str | Path | None = 'vasp_gam', poscar: bool = True, rattle: bool = True, bulk: bool = False, **kwargs)[source]

Write the input files for VASP Γ-point-only (vasp_gam) defect supercell relaxation. Typically not recommended for use, as the recommended workflow is to perform vasp_gam calculations using ShakeNBreak (or other approaches) for defect structure-searching and initial relaxations, but should be used if the final, converged k-point mesh is Γ-point-only. If bulk is True, the input files for a single-point calculation of the bulk supercell are also written to "{formula}_bulk/{subfolder}".

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

The DefectEntry object is also written to a json.gz file in defect_dir to aid calculation provenance – can be reloaded directly with loadfn() from monty.serialization, or DefectEntry.from_json().

Parameters:

defect_dir (PathLike) – Folder in which to create the VASP defect calculation inputs. Default is to use the DefectEntry name (e.g. "Y_i_C4v_O1.92_+2" etc.), from self.defect_entry.name. If this attribute is not set, it is automatically generated according to the doped convention (using get_defect_name_from_entry()).
subfolder (PathLike) – Output folder structure is <defect_dir>/<subfolder> where subfolder = ‘vasp_gam’ by default. Setting subfolder to None will write the vasp_gam input files directly to the <defect_dir> folder, with no subfolders created.
poscar (bool) – If True (default), writes the defect POSCAR to the generated folder as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching using ShakeNBreak (https://shakenbreak.readthedocs.io) or another approach, then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)). (default: True)
rattle (bool) – If writing POSCAR, apply random displacements to all atomic positions in the structure using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
bulk (bool) – If True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”. (Default: False)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

write_ncl(defect_dir: str | Path | None = None, subfolder: str | Path | None = 'vasp_ncl', poscar: bool = False, rattle: bool = True, bulk: bool = False, **kwargs)[source]

Write the input files for VASP defect supercell single-point calculations with spin-orbit coupling (SOC) (LSORBIT = True) included, using vasp_ncl.

By default, does not generate POSCAR (input structure) files, as these should be taken from the CONTCARs of vasp_std relaxations (originally from structure-searching relaxations), or directly from ShakeNBreak calculations (via snb-groundstate -d vasp_ncl) if only Γ-point reciprocal space sampling is required. If POSCAR files are desired, set poscar=True.

If DefectRelaxSet.soc is False, then this returns None and a warning. If the soc parameter is not set when initializing DefectRelaxSet, then it is set to True for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn), otherwise False. If bulk is True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

The DefectEntry object is also written to a json.gz file in defect_dir to aid calculation provenance – can be reloaded directly with loadfn() from monty.serialization, or DefectEntry.from_json().

Parameters:

defect_dir (PathLike) – Folder in which to create the VASP defect calculation inputs. Default is to use the DefectEntry name (e.g. "Y_i_C4v_O1.92_+2" etc.), from self.defect_entry.name. If this attribute is not set, it is automatically generated according to the doped convention (using get_defect_name_from_entry()).
subfolder (PathLike) – Output folder structure is <defect_dir>/<subfolder> where subfolder = ‘vasp_ncl’ by default. Setting subfolder to None will write the vasp_ncl input files directly to the <defect_dir> folder, with no subfolders created.
poscar (bool) – If True, writes the defect POSCAR to the generated folder as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching (e.g. using ShakeNBreak (https://shakenbreak.readthedocs.io)), then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)), first with NKRED if using hybrid DFT, then without, then use the vasp_std CONTCARs as the input structures for final vasp_ncl single-point calculations. (default: False)
rattle (bool) – If writing POSCAR, apply random displacements to all atomic positions in the structure using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
bulk (bool) – If True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”. (Default: False)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

write_nkred_std(defect_dir: str | Path | None = None, subfolder: str | Path | None = 'vasp_nkred_std', poscar: bool = False, rattle: bool = True, bulk: bool = False, **kwargs)[source]

Write the input files for defect calculations using vasp_std (i.e. with a non-Γ-only kpoint mesh) and NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of hybrid DFT calculations, following the doped recommended defect calculation workflow (see docs). By default, sets NKRED(X,Y,Z) to 2 or 3 in the directions for which the k-point grid is divisible by this factor.

By default, does not generate POSCAR (input structure) files, as these should be taken from the CONTCARs of structure-searching calculations (e.g. via snb-groundstate -d vasp_nkred_std) or, if not following the recommended structure-searching workflow, from the CONTCARs of vasp_gam calculations. If POSCAR files are desired, set poscar=True. If bulk is True, the input files for a single-point calculation of the bulk supercell are also written to "{formula}_bulk/{subfolder}".

Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case vasp_gam should be used) or for GGA calculations (if LHFCALC is set to False in user_incar_settings, in which case vasp_std should be used).

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

The DefectEntry object is also written to a json.gz file in defect_dir to aid calculation provenance – can be reloaded directly with loadfn() from monty.serialization, or DefectEntry.from_json().

Parameters:

defect_dir (PathLike) – Folder in which to create the VASP defect calculation inputs. Default is to use the DefectEntry name (e.g. "Y_i_C4v_O1.92_+2" etc.), from self.defect_entry.name. If this attribute is not set, it is automatically generated according to the doped convention (using get_defect_name_from_entry()).
subfolder (PathLike) – Output folder structure is <defect_dir>/<subfolder> where subfolder = ‘vasp_nkred_std’ by default. Setting subfolder to None will write the vasp_nkred_std input files directly to the <defect_dir> folder, with no subfolders created.
poscar (bool) – If True, writes the defect POSCAR to the generated folder as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching using ShakeNBreak (https://shakenbreak.readthedocs.io) or another approach, then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)). (default: False)
rattle (bool) – If writing POSCAR, apply random displacements to all atomic positions in the structure using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
bulk (bool) – If True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”. (Default: False)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

write_std(defect_dir: str | Path | None = None, subfolder: str | Path | None = 'vasp_std', poscar: bool = False, rattle: bool = True, bulk: bool = False, **kwargs)[source]

Write the input files for a VASP defect supercell calculation using vasp_std (i.e. with a non-Γ-only kpoint mesh).

By default, does not generate POSCAR (input structure) files, as these should be taken from the CONTCARs of vasp_std relaxations using NKRED(X,Y,Z) (originally from structure-searching relaxations) if using hybrid DFT, or from ShakeNBreak calculations (via snb-groundstate -d vasp_std) if using GGA, or, if not following the recommended structure-searching workflow, from the CONTCARs of vasp_gam calculations. If POSCAR files are desired, set poscar=True. If bulk is True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”.

Returns None and a warning if the input kpoint settings correspond to a Γ-only kpoint mesh (in which case vasp_gam should be used).

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

The DefectEntry object is also written to a json.gz file in defect_dir to aid calculation provenance – can be reloaded directly with loadfn() from monty.serialization, or DefectEntry.from_json().

Parameters:

defect_dir (PathLike) – Folder in which to create the VASP defect calculation inputs. Default is to use the DefectEntry name (e.g. "Y_i_C4v_O1.92_+2" etc.), from self.defect_entry.name. If this attribute is not set, it is automatically generated according to the doped convention (using get_defect_name_from_entry()).
subfolder (PathLike) – Output folder structure is <defect_dir>/<subfolder> where subfolder = ‘vasp_std’ by default. Setting subfolder to None will write the vasp_std input files directly to the <defect_dir> folder, with no subfolders created.
poscar (bool) – If True, writes the defect POSCAR to the generated folder as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching using ShakeNBreak (https://shakenbreak.readthedocs.io) or another approach, then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)). (default: False)
rattle (bool) – If writing POSCAR, apply random displacements to all atomic positions in the structure using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
bulk (bool) – If True, the input files for a single-point calculation of the bulk supercell are also written to “{formula}_bulk/{subfolder}”. (Default: False)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

Bases: MSONable

Class for generating input files for VASP defect calculations for a set of doped/pymatgen DefectEntry objects.

Creates a dictionary of: {defect name: DefectRelaxSet}.

DefectRelaxSet has the attributes:

DefectRelaxSet.vasp_gam:
DefectDictSet for Gamma-point only relaxation. Usually not needed if structure searching (e.g. ShakeNBreak) has been performed (recommended), unless only Γ-point k-point sampling is required (converged) for your system, and no vasp_std calculations with multiple k-points are required (determined from kpoint settings).
DefectRelaxSet.vasp_nkred_std:
DefectDictSet for relaxation with a kpoint mesh and using NKRED. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Gamma k-point sampling is required.
DefectRelaxSet.vasp_std:
DefectDictSet for relaxation with a kpoint mesh, not using NKRED. Not generated if only Gamma kpoint sampling is required.
DefectRelaxSet.vasp_ncl:
DefectDictSet for single-point (static) energy calculation with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).

where DefectDictSet is an extension of pymatgen’s VaspInputSet class for defect calculations, with incar, poscar, kpoints and potcar attributes for the corresponding VASP defect calculations (see docstring). Also creates the corresponding bulk_vasp_... attributes for single-point (static) energy calculations of the bulk (pristine, defect-free) supercell. This needs to be calculated once with the same settings as the final defect calculations, for the later calculation of defect formation energies.

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR settings, and PotcarSet.yaml for the default POTCAR settings.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

Parameters:

defect_entries (DefectsGenerator, dict/list of DefectEntrys, or DefectEntry) – Either a DefectsGenerator object, or a dictionary/list of DefectEntrys, or a single DefectEntry object, for which to generate VASP input files. If a DefectsGenerator object or a dictionary (-> {defect name: DefectEntry}), the defect folder names will be set equal to defect name. If a list or single DefectEntry object is provided, the defect folder names will be set equal to DefectEntry.name if the name attribute is set, otherwise generated according to the doped convention (see doped.generation). Defect charge states are taken from DefectEntry.charge_state.
soc (bool) – Whether to generate vasp_ncl DefectDictSet attribute for spin-orbit coupling single-point (static) energy calculations. If not set, then by default is set to True if the max atomic number (Z) in the structure is >= 31 (i.e. further down the periodic table than Zn).
user_incar_settings (dict) – Dictionary of user INCAR settings (AEXX, NCORE etc.) to override default settings. Highly recommended to look at output INCARs or the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder, to see what the default INCAR settings are. Note that any flags that aren’t numbers or True/False need to be input as strings with quotation marks (e.g. {"ALGO": "All"}). (default: None)
user_kpoints_settings (dict or Kpoints) – Dictionary of user KPOINTS settings (in pymatgen VaspInputSet format) e.g., {"reciprocal_density": 123}, or a Kpoints object, to use for the vasp_std, vasp_nkred_std and vasp_ncl DefectDictSets (Γ-only for vasp_gam). Default is Gamma-centred, reciprocal_density = 100 [Å⁻³].
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.
**kwargs – Additional kwargs to pass to each DefectRelaxSet().

Key Attributes:

defect_sets (Dict):: Dictionary of {defect name: DefectRelaxSet}.
defect_entries (Dict):: Dictionary of {defect name: DefectEntry} for the input defect species, for which to generate VASP input files.
bulk_vasp_gam (DefectDictSet):: DefectDictSet for a bulk Γ-point-only single-point (static) supercell calculation. Often not used, as the bulk supercell only needs to be calculated once with the same settings as the final defect calculations, which may be with vasp_std or vasp_ncl.
bulk_vasp_nkred_std (DefectDictSet):: DefectDictSet for a single-point (static) bulk vasp_std supercell calculation (i.e. with a non-Γ-only kpoint mesh) and NKRED(X,Y,Z) INCAR tag(s) to downsample kpoints for the HF exchange part of the hybrid DFT calculation. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Gamma kpoint sampling is required.
bulk_vasp_std (DefectDictSet):: DefectDictSet for a single-point (static) bulk vasp_std supercell calculation with a non-Γ-only kpoint mesh, not using NKRED. Not generated if only Gamma kpoint sampling is required.
bulk_vasp_ncl (DefectDictSet):: DefectDictSet for single-point (static) energy calculation of the bulk supercell with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).
bulk_supercell (Structure):: Supercell structure of the bulk (pristine) material.
json_obj (Union[Dict, DefectsGenerator]):: Either the DefectsGenerator object if input defect_entries is a DefectsGenerator object, otherwise the defect_entries dictionary, which will be written to file when write_files() is called, to aid calculation provenance.
json_name (PathLike):: Name of the JSON file to save the json_obj to.

Input parameters are also set as attributes.

write_files(output_path: str | Path = '.', poscar: bool = False, rattle: bool = True, vasp_gam: bool | None = None, bulk: bool | str = True, processes: int | None = None, **kwargs)[source]

Write VASP input files to folders for all defects in self.defect_entries. Folder names are set to the key of the DefectRelaxSet in self.defect_sets (same as self.defect_entries keys, see DefectsSet docstring).

For each defect folder, the following subfolders are generated:

vasp_nkred_std:
Defect relaxation with a kpoint mesh and using NKRED. Not generated for GGA calculations (if LHFCALC is set to False in user_incar_settings) or if only Γ-point sampling required.
vasp_std:
Defect relaxation with a kpoint mesh, not using NKRED. Not generated if only Γ-point sampling required.
vasp_ncl:
Singlepoint (static) energy calculation with SOC included. Generated if soc=True. If soc is not set, then by default is only generated for systems with a max atomic number (Z) >= 31 (i.e. further down the periodic table than Zn).

If vasp_gam=True (not recommended) or self.vasp_std = None (i.e. Γ-only k-point sampling converged for the kpoints settings used), then also outputs:

vasp_gam:
Γ-point only defect relaxation. Usually not needed if structure searching has been performed (e.g. with ShakeNBreak) (recommended).

By default, does not generate a vasp_gam folder unless DefectRelaxSet.vasp_std is None (i.e. only Γ-point sampling required for this system), as vasp_gam calculations should be performed with defect structure-searching (e.g. with ShakeNBreak) and initial relaxations. If vasp_gam files are desired, set vasp_gam=True.

By default, POSCAR files are not generated for the vasp_(nkred_)std (and vasp_ncl if self.soc is True) folders, as these should be taken from structure-searching calculations (e.g. snb-groundstate -d vasp_nkred_std) or, if not following the recommended structure-searching workflow, from the CONTCARs of vasp_gam calculations. If including SOC effects (i.e. self.soc = True), then the vasp_std CONTCARs should be used as the vasp_ncl POSCARs. If POSCAR files are desired for the vasp_(nkred_)std (and vasp_ncl) folders, set poscar=True.

Input files for the single-point (static) bulk supercell reference calculation are also written to "{formula}_bulk/{subfolder}" if bulk is True (default), where subfolder corresponds to the final (highest accuracy) VASP calculation in the workflow (i.e. vasp_ncl if self.soc=True, otherwise vasp_std or vasp_gam if only Γ-point reciprocal space sampling is required). If bulk = "all", then the input files for all VASP calculations (gam/std/ncl) are written to the bulk supercell folder, or if bulk = False, then no bulk folder is created.

The DefectEntry objects are also written to json.gz files in the defect folders, as well as self.defect_entries (self.json_obj) in the top folder, to aid calculation provenance – these can be reloaded directly with loadfn() from monty.serialization, or individually with DefectEntry.from_json().

See the RelaxSet.yaml and DefectSet.yaml files in the doped/VASP_sets folder for the default INCAR and KPOINT settings, and PotcarSet.yaml for the default POTCAR settings. These are reasonable defaults that `roughly` match the typical values needed for accurate defect calculations, but usually will need to be modified for your specific system, such as converged ENCUT and KPOINTS, and NCORE / KPAR matching your HPC setup.

Note that any changes to the default INCAR/POTCAR settings should be consistent with those used for all defect and competing phase (chemical potential) calculations – this will be automatically checked upon defect & competing phases parsing in doped.

Parameters:

output_path (PathLike) – Folder in which to create the VASP defect calculation folders. Default is the current directory (“.”). Output folder structure is <output_path>/<defect name>/<subfolder> where defect name is the key of the DefectRelaxSet in self.defect_sets (same as self.defect_entries keys, see DefectsSet docstring) and subfolder is the name of the corresponding VASP program to run (e.g. vasp_std).
poscar (bool) – If True, writes the defect POSCAR to the generated folders as well. Typically not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching using ShakeNBreak (https://shakenbreak.readthedocs.io) or another approach, then continue the vasp(_nkred)_std relaxations from the ground-state structures (e.g. using -d vasp_nkred_std with snb-groundstate (CLI) or groundstate_folder="vasp_nkred_std" with write_groundstate_structure (Python API)), first with NKRED if using hybrid DFT, then without NKRED. (default: False)
rattle (bool) – If writing POSCARs, apply random displacements to all atomic positions in the structures using the ShakeNBreak algorithm; i.e. with the displacement distances randomly drawn from a Gaussian distribution of standard deviation equal to 10% of the bulk nearest neighbour distance and using a Monte Carlo algorithm to penalise displacements that bring atoms closer than 80% of the bulk nearest neighbour distance. stdev and d_min can also be given as input kwargs. This is intended to be used as a fallback option for breaking symmetry to partially aid location of global minimum defect geometries, if ShakeNBreak structure-searching is being skipped. However, rattling still only finds the ground-state structure for <~30% of known cases of energy-lowering reconstructions relative to an unperturbed defect structure. (default: True)
vasp_gam (Optional[bool]) – If True, writes the vasp_gam input files, with defect POSCARs. Not recommended, as the recommended workflow is to initially perform vasp_gam ground-state structure searching (e.g. using ShakeNBreak; https://shakenbreak.readthedocs.io), then continue the vasp_std relaxations from the ground-state structures. Default is None, where vasp_gam folders are written if self.vasp_std is None (i.e. only Γ-point reciprocal space sampling is required).
bulk (bool, str) – If True, the input files for a single-point calculation of the bulk supercell are also written to "{formula}_bulk/{subfolder}", where subfolder corresponds to the final (highest accuracy) VASP calculation in the workflow (i.e. vasp_ncl if self.soc=True, otherwise vasp_std or vasp_gam if only Γ-point reciprocal space sampling is required). If bulk = "all" then the input files for all VASP calculations in the workflow (vasp_gam, vasp_nkred_std, vasp_std, vasp_ncl (if applicable)) are written to the bulk supercell folder. (Default: False)
processes (int) – Number of processes to use for multiprocessing for file writing. If None (default), then is dynamically set to the optimal value for the number of folders to write. (Default: None)
**kwargs – Keyword arguments to pass to DefectDictSet.write_input().

class doped.vasp.DopedDictSet(structure: Structure, user_incar_settings: dict | None = None, user_kpoints_settings: dict | Kpoints | None = None, user_potcar_functional: str = 'PBE', user_potcar_settings: dict | None = None, auto_kpar: bool = True, poscar_comment: str | None = None, **kwargs)[source]

Bases: VaspInputSet

Modified version of pymatgen VaspInputSet, to have more robust POTCAR handling, expedited I/O (particularly for POTCAR generation, which can be slow when generating many folders), ensure POSCAR atom sorting, avoid encoding issues with KPOINTS comments etc.

Parameters:

structure (Structure) – pymatgen Structure object for the input structure file.
user_incar_settings (dict) – Dictionary of user INCAR settings (AEXX, NCORE etc.) to override default INCAR settings. Note that any flags that aren’t numbers or True/False need to be input as strings with quotation marks (e.g. {"ALGO": "All"}). (default: None)
user_kpoints_settings (dict or Kpoints) – Dictionary of user KPOINTS settings (in pymatgen VaspInputSet format) e.g., {"reciprocal_density": 123}, or a Kpoints object. Default is Gamma-only.
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.
auto_kpar (bool) – If True, and KPAR is not set in user_incar_settings, attempts to set KPAR to a reasonable value based on the k-point grid. Specifically, sets KPAR to 2 if there are 2 or >=4 k-points in any direction, or 4 if there are at least 2 directions with 2 or >=4 k-points (otherwise remains as the default of 1). Default is True.
poscar_comment (str) – Comment line to use for POSCAR file. Default is structure formula.
**kwargs – Additional kwargs to pass to VaspInputSet.

property incar: Returns the Incar object generated from the VaspInputSet config, with a warning if KPAR > 1 and only one k-point.

property kpoints: Return kpoints object with comment.

property poscar: Poscar: Return Poscar object with comment, ensuring atom sorting.

property potcar: Potcar

Potcar object.

Redefined to intelligently handle pymatgen POTCAR issues.

class doped.vasp.DopedKpoints(comment: str = 'Default gamma', num_kpts: int = 0, style: KpointsSupportedModes = KpointsSupportedModes.Gamma, kpts: Sequence[Kpoint] = ((1, 1, 1),), kpts_shift: tuple[float, float, float] = (0, 0, 0), kpts_weights: list[float] | None = None, coord_type: Literal['Reciprocal', 'Cartesian'] | None = None, labels: list[str] | None = None, tet_number: int = 0, tet_weight: float = 0, tet_connections: list[tuple] | None = None)[source]

Bases: Kpoints

Custom implementation of Kpoints to handle encoding errors that can happen on some old HPCs/Linux systems.

If an encoding error occurs upon file writing, then changes Γ to Gamma and Å to Angstrom in the KPOINTS comment.

Highly flexible constructor for Kpoints object. The flexibility comes at the cost of usability and in general, it is recommended that you use the default constructor only if you know exactly what you are doing and requires the flexibility. For most usage cases, the three automatic schemes can be constructed far more easily using the convenience static constructors (automatic, gamma_automatic, monkhorst_automatic) and it is recommended that you use those.

The default behavior of the constructor is for a Gamma-centered, 1x1x1 KPOINTS with no shift.

Parameters:

comment (str) – String comment for Kpoints. Defaults to “Default gamma”.
num_kpts – Following VASP method of defining the KPOINTS file, this parameter is the number of kpoints specified. If set to 0 (or negative), VASP automatically generates the KPOINTS.
style – Style for generating KPOINTS. Use one of the Kpoints.supported_modes enum types.
kpts (2D array) – Array of kpoints. Even when only a single specification is required, e.g. in the automatic scheme, the kpts should still be specified as a 2D array. e.g. [(20,),] or [(2, 2, 2),].
kpts_shift (3x1 array) – Shift for kpoints.
kpts_weights (list[float]) – Optional weights for explicit kpoints.
coord_type – In line-mode, this variable specifies whether the Kpoints were given in Cartesian or Reciprocal coordinates.
labels – In line-mode, this should provide a list of labels for each kpt. It is optional in explicit kpoint mode as comments for k-points.
tet_number – For explicit kpoints, specifies the number of tetrahedrons for the tetrahedron method.
tet_weight – For explicit kpoints, specifies the weight for each tetrahedron for the tetrahedron method.
tet_connections – For explicit kpoints, specifies the connections of the tetrahedrons for the tetrahedron method. Format is a list of tuples, [ (sym_weight, [tet_vertices]), …]

doped.vasp.deep_dict_update(d: dict, u: dict) → dict[source]: Recursively update nested dictionaries without overwriting existing keys.

doped.vasp.scaled_ediff(natoms: int, ediff_per_atom: float = 2e-07, max_ediff: float = 0.0001) → float[source]

Returns a scaled EDIFF value for VASP calculations, based on the number of atoms in the structure.

Parameters:

natoms (int) – Number of atoms in the structure.
ediff_per_atom (float) – Per-atom EDIFF in eV. Default is 2e-7 (1e-5 per 50 atoms).
max_ediff (float) – Maximum EDIFF value. Default is 1e-4 eV.

Returns:

Scaled EDIFF value.

Return type:

float