pymatgen.analysis.defects.corrections module

Implementation of defect correction methods.

class BandEdgeShiftingCorrection

Bases: pymatgen.analysis.defects.core.DefectCorrection

A class for BandEdgeShiftingCorrection class. Largely adapted from PyCDT code

Initializes the BandEdgeShiftingCorrection class

get_correction(entry)

Gets the BandEdge correction for a defect entry :param entry: defect entry to compute BandFilling correction on.

Requires some parameters in the DefectEntry to properly function:

hybrid_cbm (float)

CBM of HYBRID bulk calculation one wishes to shift to

hybrid_vbm (float)

VBM of HYBRID bulk calculation one wishes to shift to

cbm (float)

CBM of bulk calculation (or band structure calculation of bulk); calculated on same level of theory as the defect (ex. GGA defects -> requires GGA cbm)

vbm (float)

VBM of bulk calculation (or band structure calculation of bulk); calculated on same level of theory as the defect (ex. GGA defects -> requires GGA vbm)

Returns

BandfillingCorrection value as a dictionary

class BandFillingCorrection(resolution=0.01)

Bases: pymatgen.analysis.defects.core.DefectCorrection

A class for BandFillingCorrection class. Largely adapted from PyCDT code

Initializes the Bandfilling correction

Parameters

resolution (float) – energy resolution to maintain for gap states

get_correction(entry)

Gets the BandFilling correction for a defect entry :param entry: defect entry to compute BandFilling correction on.

Requires following parameters in the DefectEntry to exist:

eigenvalues

dictionary of defect eigenvalues, as stored in a Vasprun object

kpoint_weights (list of floats)

kpoint weights corresponding to the dictionary of eigenvalues, as stored in a Vasprun object

potalign (float)

potential alignment for the defect calculation Only applies to non-zero charge, When using potential alignment correction (freysoldt or kumagai), need to divide by -q

cbm (float)

CBM of bulk calculation (or band structure calculation of bulk); calculated on same level of theory as the defect (ex. GGA defects -> requires GGA cbm)

vbm (float)

VBM of bulk calculation (or band structure calculation of bulk); calculated on same level of theory as the defect (ex. GGA defects -> requires GGA vbm)

run_metadata[“defect_incar”] (dict)

Dictionary of INCAR settings for the defect calculation, required to check if the calculation included spin-orbit coupling (to determine the spin factor for occupancies of the electron bands)

Returns

Bandfilling Correction value as a dictionary

perform_bandfill_corr(eigenvalues, kpoint_weights, potalign, vbm, cbm, soc_calc=False)

This calculates the band filling correction based on excess of electrons/holes in CB/VB…

Note that the total free holes and electrons may also be used for a “shallow donor/acceptor”

correction with specified band shifts:

+num_elec_cbm * Delta E_CBM (or -num_hole_vbm * Delta E_VBM)

class FreysoldtCorrection(dielectric_const, q_model=None, energy_cutoff=520, madetol=0.0001, axis=None)

Bases: pymatgen.analysis.defects.core.DefectCorrection

A class for FreysoldtCorrection class. Largely adapated from PyCDT code

If this correction is used, please reference Freysoldt’s original paper. doi: 10.1103/PhysRevLett.102.016402

Initializes the FreysoldtCorrection class :param dielectric_const: Dielectric constant for the structure :type dielectric_const: float or 3x3 matrix :param q_model: instantiated QModel object or None.

Uses default parameters to instantiate QModel if None supplied

Parameters

• energy_cutoff (int) – Maximum energy in eV in reciprocal space to perform integration for potential correction.

• madeltol (float) – Convergence criteria for the Madelung energy for potential correction

• axis (int) – Axis to calculate correction. If axis is None, then averages over all three axes is performed.

get_correction(entry)

Gets the Freysoldt correction for a defect entry :param entry: defect entry to compute Freysoldt correction on.

Requires following keys to exist in DefectEntry.parameters dict:

axis_grid (3 x NGX where NGX is the length of the NGX grid in the x,y and z axis directions. Same length as planar average lists):

A list of 3 numpy arrays which contain the cartesian axis values (in angstroms) that correspond to each planar avg potential supplied.

bulk_planar_averages (3 x NGX where NGX is the length of the NGX grid in the x,y and z axis directions.):

A list of 3 numpy arrays which contain the planar averaged electrostatic potential for the bulk supercell.

defect_planar_averages (3 x NGX where NGX is the length of the NGX grid in the x,y and z axis directions.):

A list of 3 numpy arrays which contain the planar averaged electrostatic potential for the defective supercell.

initial_defect_structure (Structure) structure corresponding to

initial defect supercell structure (uses Lattice for charge correction)

defect_frac_sc_coords (3 x 1 array) Fractional co-ordinates of

defect location in supercell structure

Returns

FreysoldtCorrection values as a dictionary

perform_es_corr(lattice, q, step=0.0001)

Peform Electrostatic Freysoldt Correction :param lattice: Pymatgen lattice object :param q: Charge of defect :type q: int :param step: step size for numerical integration :type step: float

Returns

Electrostatic Point Charge contribution to Freysoldt Correction (float)

perform_pot_corr(axis_grid, pureavg, defavg, lattice, q, defect_frac_position, axis, widthsample=1.0)

For performing planar averaging potential alignment :param axis_grid (1 x NGX where NGX is the length of the NGX grid:

in the axis direction. Same length as pureavg list):

A numpy array which contain the cartesian axis values (in angstroms) that correspond to each planar avg potential supplied.

Parameters

• (1 x NGX where NGX is the length of the NGX grid in (defavg) –

  the axis direction.):

  A numpy array for the planar averaged electrostatic potential of the bulk supercell.

• (1 x NGX where NGX is the length of the NGX grid in –

  the axis direction.):

  A numpy array for the planar averaged electrostatic potential of the defect supercell.

• lattice – Pymatgen Lattice object of the defect supercell

• q (float or int) – charge of the defect

• defect_frac_position – Fracitional Coordinates of the defect in the supercell

• axis (int) – axis for performing the freysoldt correction on

• widthsample (float) – width (in Angstroms) of the region in between defects where the potential alignment correction is averaged. Default is 1 Angstrom.

Returns

Potential Alignment contribution to Freysoldt Correction (float)

plot(axis, title=None, saved=False)

Plots the planar average electrostatic potential against the Long range and short range models from Freysoldt. Must run perform_pot_corr or get_correction (to load metadata) before this can be used. :param axis: axis to plot :type axis: int :param title: Title to be given to plot. Default is no title. :type title: str :param saved: Whether to save file or not. If False then returns plot

object. If True then saves plot as str(title) + “FreyplnravgPlot.pdf”

class KumagaiCorrection(dielectric_tensor, sampling_radius=None, gamma=None)

Bases: pymatgen.analysis.defects.core.DefectCorrection

A class for KumagaiCorrection class. Largely adapated from PyCDT code

If this correction is used, please reference Kumagai and Oba’s original paper (doi: 10.1103/PhysRevB.89.195205) as well as Freysoldt’s original paper (doi: 10.1103/PhysRevLett.102.016402)

NOTE that equations 8 and 9 from Kumagai et al. reference are divided by (4 pi) to get SI units

Initializes the Kumagai Correction :param dielectric_tensor: Dielectric constant for the structure :type dielectric_tensor: float or 3x3 matrix :param optional data that can be tuned:

sampling_radius (float): radius (in Angstrom) which sites must be outside

of to be included in the correction. Publication by Kumagai advises to use Wigner-Seitz radius of defect supercell, so this is default value.

gamma (float): convergence parameter for gamma function.

Code will automatically determine this if set to None.

get_correction(entry)

Gets the Kumagai correction for a defect entry :param entry: defect entry to compute Kumagai correction on.

Requires following parameters in the DefectEntry to exist:

bulk_atomic_site_averages (list): list of bulk structure”s atomic site averaged ESPs * charge,

in same order as indices of bulk structure note this is list given by VASP’s OUTCAR (so it is multiplied by a test charge of -1)

defect_atomic_site_averages (list): list of defect structure”s atomic site averaged ESPs * charge,

in same order as indices of defect structure note this is list given by VASP’s OUTCAR (so it is multiplied by a test charge of -1)

site_matching_indices (list): list of corresponding site index values for

bulk and defect site structures EXCLUDING the defect site itself (ex. [[bulk structure site index, defect structure”s corresponding site index], … ]

initial_defect_structure (Structure): Pymatgen Structure object representing un-relaxed defect

structure

defect_frac_sc_coords (array): Defect Position in fractional coordinates of the supercell

given in bulk_structure

Returns

KumagaiCorrection values as a dictionary

static get_potential_shift(gamma, volume)

Parameters

• gamma (float) – Gamma

• volume (float) – Volume.

Returns

Potential shift for defect.

get_real_summation(gamma, real_vectors)

Get real summation term from list of real-space vectors

get_recip_summation(gamma, recip_vectors, volume, r=[0.0, 0.0, 0.0])

Get Reciprocal summation term from list of reciprocal-space vectors

get_self_interaction(gamma)

Parameters

() (gamma) –

Returns

Self-interaction energy of defect.

perform_es_corr(gamma, prec, lattice, charge)

Peform Electrostatic Kumagai Correction :param gamma: Ewald parameter :type gamma: float :param prec: Precision parameter for reciprical/real lattice vector generation :type prec: int :param lattice: Pymatgen Lattice object corresponding to defect supercell :param charge: Defect charge :type charge: int

Returns

Electrostatic Point Charge contribution to Kumagai Correction (float)

perform_pot_corr(defect_structure, defect_frac_coords, site_list, sampling_radius, q, r_vecs, g_vecs, gamma)

For performing potential alignment in manner described by Kumagai et al. :param defect_structure: Pymatgen Structure object corrsponding to the defect supercell :param defect_frac_coords: Defect Position in fractional coordinates of the supercell

given in bulk_structure

Parameters

• site_list – list of corresponding site index values for bulk and defect site structures EXCLUDING the defect site itself (ex. [[bulk structure site index, defect structure”s corresponding site index], … ]

• sampling_radius (float) – radius (in Angstrom) which sites must be outside of to be included in the correction. Publication by Kumagai advises to use Wigner-Seitz radius of defect supercell, so this is default value.

• q (int) – Defect charge

• r_vecs – List of real lattice vectors to use in summation

• g_vecs – List of reciprocal lattice vectors to use in summation

• gamma (float) – Ewald parameter

Returns

Potential alignment contribution to Kumagai Correction (float)

plot(title=None, saved=False)

Plots the AtomicSite electrostatic potential against the Long range and short range models from Kumagai and Oba (doi: 10.1103/PhysRevB.89.195205)