# pymatgen.analysis.defects.defect_compatibility module

This module implements DefectCompatibility analysis for consideration of defects

class DefectCompatibility(plnr_avg_var_tol=0.0001, plnr_avg_minmax_tol=0.1, atomic_site_var_tol=0.005, atomic_site_minmax_tol=0.1, tot_relax_tol=1.0, perc_relax_tol=50.0, defect_tot_relax_tol=2.0, preferred_cc='freysoldt', free_chg_cutoff=2.1, use_bandfilling=True, use_bandedgeshift=True)

  Bases: `monty.json.MSONable`

  The DefectCompatibility class evaluates corrections and delocalization metrics on a DefectEntry. It can only parse based on the available parameters that already exist in the parameters dict of the DefectEntry.

  required settings in defect_entry.parameters for various types of analysis/correction:
    freysoldt: [ “dielectric”, “axis_grid”, “bulk_planar_averages”, “defect_planar_averages”,

      “initial_defect_structure”, “defect_frac_sc_coords”]

    kumagai: [ “dielectric”, “bulk_atomic_site_averages”, “defect_atomic_site_averages”,

      “site_matching_indices”, “initial_defect_structure”, “defect_frac_sc_coords”]

    bandfilling: [“eigenvalues”, “kpoint_weights”, “potalign”, “vbm”, “cbm”, “run_metadata”] bandshifting: [“hybrid_cbm”, “hybrid_vbm”, “vbm”, “cbm”] defect relaxation/structure analysis: [“final_defect_structure”, “initial_defect_structure”,

    > “sampling_radius”, “defect_frac_sc_coords”]

  Initializes the DefectCompatibility class

  Each argument helps decide whether a DefectEntry is flagged as compatible or not :param plnr_avg_var_tol: compatibility tolerance for variance of the sampling region

  > in the planar averaged electrostatic potential (FreysoldtCorrection)

  Parameters

    - plnr_avg_minmax_tol (float) – compatibility tolerance for max/min difference of the sampling region in the planar averaged electrostatic potential (FreysoldtCorrection)

    - atomic_site_var_tol (float) – compatibility tolerance for variance of the sampling region in the atomic site averaged electrostatic potential (KumagaiCorrection)

    - atomic_site_minmax_tol (float) – compatibility tolerance for max/min difference of the sampling region in the atomic site averaged electrostatic potential (KumagaiCorrection)

    - tot_relax_tol (float) – compatibility tolerance for total integrated relaxation amount outside of a given radius from the defect (in Angstrom). Radius is supplied as ‘sampling_radius’ within parameters of DefectEntry.

    - perc_relax_tol (float) – compatibility tolerance for percentage of total relaxation outside of a given radius from the defect (percentage amount), assuming a total integration relaxation greater than 1 Angstrom. Radius is supplied as ‘sampling_radius’ within parameters of DefectEntry.

    - defect_tot_relax_tol (float) – compatibility tolerance for displacement of defect site itself (in Angstrom).

    - preferred_cc (str) – Charge correction that is preferred to be used. If only one is available based on metadata, then that charge correction will be used. Options are: ‘freysoldt’ and ‘kumagai’

    - free_chg_cutoff (float) – compatibility tolerance for total amount of host band occupation outside of band edges, given by eigenvalue data. Extra occupation in the CB would be free electrons, while lost occupation in VB would be free holes.

    - use_bandfilling (bool) – Whether to include BandFillingCorrection or not (assuming sufficient metadata is supplied to perform BandFillingCorrection).

    - use_bandedgeshift (bool) – Whether to perform a BandEdgeShiftingCorrection or not (assuming sufficient metadata is supplied to perform BandEdgeShiftingCorrection).

  check_final_relaxed_structure_delocalized(defect_entry)

    NOTE this assumes initial and final structures have sites indexed in same way

    Parameters

      defect_entry –

    Returns

  check_freysoldt_delocalized(defect_entry)

    Check for Freysoldt delocalization.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  check_kumagai_delocalized(defect_entry)

    Check for Kumagai delocalization.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  delocalization_analysis(defect_entry)
    Do delocalization analysis. To do this, one considers:

      1. sampling region of planar averaged electrostatic potential (freysoldt approach)

      2. sampling region of atomic site averaged potentials (kumagai approach)

      iii) structural relaxation amount outside of radius considered in kumagai approach (default is wigner seitz radius) iv) if defect is not a vacancy type -> track to see how much the defect has moved

    calculations that fail delocalization get “is_compatibile” set to False in parameters also parameters recieves a “delocalization_meta” with following dict:

    > plnr_avg = {‘is_compatible’: True/False, ‘metadata’: metadata used for determining this} atomic_site = {‘is_compatible’: True/False, ‘metadata’: metadata used for determining this} structure_relax = {‘is_compatible’: True/False, ‘metadata’: metadata used for determining this} defectsite_relax = {‘is_compatible’: True/False, ‘metadata’: metadata used for determing this}

  perform_all_corrections(defect_entry)

    Perform all corrections for a defect.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  static perform_band_edge_shifting(defect_entry)

    Perform band edge shifting correction.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  static perform_bandfilling(defect_entry)

    Perform bandfilling correction.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  static perform_freysoldt(defect_entry)

    Perform Freysoldt correction.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  static perform_kumagai(defect_entry)

    Perform Kumagai correction.

    Parameters

      defect_entry (DefectEntry) – Defect to correct.

    Returns

      Corrected DefectEntry

  process_entry(defect_entry, perform_corrections=True)

    Process a given DefectEntry with qualifiers given from initialization of class. Order of processing is:

    > 1. perform all possible defect corrections with information given

    > 2) consider delocalization analyses based on qualifier metrics given initialization of class. If delocalized, flag entry as delocalized 3) update corrections to defect entry and flag as delocalized

    Corrections are applied based on:
      1. if free charges are more than free_chg_cutoff then will not apply charge correction,

           because it no longer is applicable

      2. use charge correction set by preferred_cc

      3. only use BandFilling correction if use_bandfilling is set to True

      4. only use BandEdgeShift correction if use_bandedgeshift is set to True