shakenbreak.energy_lowering_distortions module

Module to apply energy lowering distortions found for a certain defect species (charge state) to other charge states of that defect.

shakenbreak.energy_lowering_distortions.compare_struct_to_distortions(distorted_struct: Structure, defect_species: str, output_path: str = '.', code: str = 'vasp', structure_filename: str = 'CONTCAR', stol: float = 0.5, min_dist: float = 0.2, verbose: bool = False) → tuple

Compares the ground-state structure found for a certain defect charge state with all relaxed bond-distorted structures for defect_species, to avoid redundant work (testing this distorted structure for other charge states when it has already been found for them).

Parameters:

• distorted_struct (Structure) – Structure of ground-state distorted defect

• defect_species (str) – Defect name including charge (e.g. ‘vac_1_Cd_0’)

• output_path (str) – Path to directory with your distorted defect calculations (to calculate structure comparisons – needs code output/structure files to parse the structures). (Default is current directory = “./”)

• code (str, optional) – Code used for the geometry relaxations. Options include: “vasp”, “cp2k”, “espresso”, “castep”, “fhi-aims” (case insensitive). (Default: “vasp”)

• structure_filename (str, optional) – Name of the file containing the structure. (Default: CONTCAR)

• stol (float) – Site-matching tolerance for structure matching. Site tolerance defined as thefraction of the average free length per atom := ( V / Nsites ) ** (1/3). (Default: 0.5)

• min_dist (float) – Minimum atomic displacement threshold between structures, in orderto consider them not matching (in Å, default = 0.2 Å).

• verbose (bool) – Whether to print information message about structures being compared.

Returns:

(True/False/None, matching structure, energy difference of the matching structure compared to its unperturbed reference, bond distortion of the matching structure). True if a match is found between the input structure and the relaxed bond-distorted structures for defect_species, False if no match, None if no converged structures found for defect_species.

Return type:

tuple

shakenbreak.energy_lowering_distortions.get_energy_lowering_distortions(defect_charges_dict: dict | None = None, output_path: str = '.', code: str = 'vasp', structure_filename: str = 'CONTCAR', min_e_diff: float = 0.05, stol: float = 0.5, min_dist: float = 0.2, verbose: bool = False, write_input_files: bool = False, metastable: bool = False) → dict

Convenience function to identify defect species undergoing energy-lowering distortions. Useful for then testing these distorted structures for the other charge states of that defect. Considers all identified energy-lowering distortions for each defect in each charge state, and screens out duplicate distorted structures found for multiple charge states.

Parameters:

• defect_charges_dict (dict, optional) – Dictionary matching defect name(s) to list(s) of their charge states. (e.g {“Int_Sb_1”:[0,+1,+2]} etc). If not specified, all defects present in output_path will be parsed. (Default: None)

• output_path (str) – Path to directory with your distorted defect calculations (need code output/structure files for structure matching) and distortion_metadata.json. (Default is current directory = “./”)

• code (str, optional) – Code used for the geometry relaxations. Supported code names are: “vasp”, “espresso”, “cp2k” and “fhi-aims” (case insensitive). (Default: “vasp”)

• structure_filename (str, optional) – Name of the file containing the structure. (Default: CONTCAR)

• ( (min_e_diff) – obj: float): Minimum energy difference (in eV) between the ground-state defect structure, relative to the Unperturbed structure, to consider it as having found a new energy-lowering distortion. Default is 0.05 eV.

• stol (float) – Site-matching tolerance for structure matching. Site tolerance defined as the fraction of the average free length per atom := ( V / Nsites ) ** (1/3). (Default: 0.5)

• min_dist (float) – Minimum atomic displacement threshold between structures, in order to consider them not matching (in Å, default = 0.2 Å).

• verbose (bool) – Whether to print verbose information about parsed defect structures for energy-lowering distortions, if found. (Default: True)

• write_input_files (bool) – Whether to write input files for the identified distortions (Default: False)

• metastable (bool) – Whether to also store non-spontaneous _metastable_ energy-lowering distortions, as these can become ground-state distortions for other charge states. (Default: False)

Returns:

Dictionary of defects for which bond distortion found an energy-lowering distortion (which is missed with normal unperturbed relaxation), of the form {defect: [list of distortion dictionaries (with corresponding charge states, energy lowering, distortion factors, structures and charge states for which these structures weren’t found)]}.

Return type:

dict

shakenbreak.energy_lowering_distortions.read_defects_directories(output_path: str = './') → dict

Reads all defect folders in the output_path directory and stores defect names and charge states in a dictionary.

Parameters:

output_path (str) – Path to directory with your distorted defect calculations. (Default is current directory = “./”)

Returns:

Dictionary mapping defect names to a list of its charge states.

Return type:

dict

shakenbreak.energy_lowering_distortions.write_groundstate_structure(all: bool = True, output_path: str = '.', groundstate_folder: str | None = None, groundstate_filename: str = 'groundstate_POSCAR', structure_filename: str = 'CONTCAR', verbose: bool = False) → None

Writes the groundstate structure of each defect (if all=True, default) to the corresponding defect folder, with an optional name (default “groundstate_POSCAR”), to then run continuation calculations.

Parameters:

• all (bool) – Write groundstate structures for all defect folders in the (top-level) directory, specified by output_path. If False, output_path should be a single defect folder, for which the groundstate structure will be written.

• output_path (str) – Path to top-level directory with your distorted defect calculation folders (if all=True, else path to single defect folder)(need CONTCAR files for structure matching) and distortion_metadata.json. (Default: current directory = “./”)

• groundstate_folder (str) – Name of the directory to write the groundstate structure to. (Default: None (ground state structure is written to the root defect directory))

• groundstate_filename (str) – Name of the file to write the groundstate structure to. (Default: “groundstate_POSCAR”)

• structure_filename (str) – Name of the file to read the structure from. (Default: “CONTCAR”)

• verbose (bool) – Whether to print additional information about the generated folders.

Returns:

None

shakenbreak.energy_lowering_distortions.write_retest_inputs(low_energy_defects: dict, output_path: str = '.', code: str = 'vasp', input_filename: str | None = None) → None

Create folders with relaxation input files for testing the low-energy distorted defect structures found for other charge states of that defect, as identified with get_energy_lowering_distortions().

Parameters:

• low_energy_defects (dict) – Dictionary of defects for which bond distortion found an energy-lowering distortion which is missed with normal unperturbed relaxation), generated by get_energy_lowering_distortions(). Has the form {defect: [list of distortion dictionaries (with corresponding charge states, energy lowering, distortion factors, structures and charge states for which these structures weren’t found)]}.

• output_path (str) – Path to directory with your distorted defect calculations (to write input files for distorted defect structures to test). (Default is current directory = “./”)

• code (str) – Code used for the geometry relaxations. The supported codes include “vasp”, “cp2k”, “espresso”, “castep” and “fhi-aims” (case insensitive). (Default: “vasp”)

• input_filename (str) – Name of the code input file if different from ShakeNBreak default. Only applies to CP2K, Quantum Espresso, CASTEP and FHI-aims. If not specified, ShakeNBreak default name is assumed, that is: for Quantum Espresso: “espresso.pwi”, CP2K: “cp2k_input.inp”, CASTEP: “castep.param”, FHI-aims: “control.in” (Default: None)

Returns:

None