shakenbreak.input module

Module containing functions to generate rattled and bond-distorted structures, as well as input files to run Gamma point relaxations with VASP, CP2K, Quantum-Espresso, FHI-aims and CASTEP.

class shakenbreak.input.Distortions(defect_entries: DefectsGenerator | list | dict | DefectEntry, oxidation_states: dict | None = None, dict_number_electrons_user: dict | None = None, distortion_increment: float = 0.1, bond_distortions: list | None = None, local_rattle: bool = False, distorted_elements: dict | None = None, distorted_atoms: list | None = None, dimer_bond_length: float | None = None, **mc_rattle_kwargs)

Bases: object

Class to apply rattle and bond distortion to all defects in defect_entries (each defect as a doped or pymatgen DefectEntry object).

Initialises the relevant information for generating ShakeNBreak distorted structures for defect entries in defect_entries.

The default distortions generated have the bond lengths of X nearest neighbours distorted by -60% to +60% (bond_distortions) in increments of 10% (distortion_increment), where X is equal to the excess charge for that defect species (e.g. 2 for v_Cd_0; see SnB tutorial: https://shakenbreak.readthedocs.io/en/latest/ShakeNBreak_Example_Workflow.html or npj theory paper: https://doi.org/10.1038/s41524-023-00973-1 for more info). Additionally, a dimer distortion will be included by default for each vacancy defect (see distortions.apply_dimer_distortion for more info), and distortions which result in inter-atomic distances less than 1 Å are excluded (unless Hydrogen is present).

Rattling is then performed by applying random displacements to atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev, using a Monte Carlo algorithm which disfavours moves that bring atoms closer than d_min. Rattling behaviour can be controlled with mc_rattle_kwargs, see the distortions.rattle() docstring for more info. Note that by default, rattling is not applied to the defect site or distorted neighbours, but to all other atoms in the supercell, however this can be controlled with the active_atoms kwarg (in mc_rattle_kwargs).

The nearest neighbours to distort are chosen by taking all sites (or those matching distorted_element / distorted_atoms, if provided), then sorting by distance to the defect site (rounded to 2 decimal places) and site index, and then taking the first num_nearest_neighbours of these. If there are multiple non-degenerate combinations of (nearly) equidistant NNs to distort (e.g. cis vs trans when distorting 2 NNs in a 4 NN square coordination), then the combination with distorted NNs closest to each other is chosen.

The bond distortion and rattling approaches are highly customisable via kwargs to this class and its methods, so see the argument descriptions for more info.

Parameters:

• defect_entries (Union[DefectsGenerator, list, dict, DefectEntry]) –

  Either a DefectsGenerator object from doped, or a list/dictionary of, or single, DefectEntry object(s). E.g.: [DefectEntry(), DefectEntry(), ...], or single DefectEntry. If a DefectsGenerator object or a dictionary (-> {defect_species: DefectEntry}), the defect folder names will be set equal to defect_species (with charge states included). 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 for all input DefectEntrys, otherwise generated according to the doped convention (see: https://doped.readthedocs.io/en/latest/generation_tutorial.html).

  Defect charge states (from which bond distortions are determined) are taken from the DefectEntry.charge_state property.

  Alternatively, a defects dict generated by ChargedDefectStructures from PyCDT/doped<2.0 can also be used as input, and the defect names and charge states generated by these codes will be used E.g.: {"bulk": {..}, "vacancies": [{...}, {...},], ...}

• oxidation_states (dict) – Dictionary of oxidation states for species in your material, used to determine the number of defect neighbours to distort (e.g {“Cd”: +2, “Te”: -2}). If none is provided, the oxidation states will be guessed based on the bulk composition and most common oxidation states of any extrinsic species.

• dict_number_electrons_user (dict) – Optional argument to set the number of extra/missing charge (negative of electron count change) for the input defects in their neutral state, as a dictionary with format {‘defect_name’: charge_change} where charge_change is the negative of the number of extra/missing electrons. (Default: None)

• distortion_increment (float) – Bond distortion increment. Distortion factors will range from 0 to +/-0.6, in increments of distortion_increment. Recommended values: 0.1-0.3 (Default: 0.1)

• bond_distortions (list) – List of bond distortions to apply to nearest neighbours, instead of the default set described above (e.g. [-0.5, 0.5]). (Default: None)

• local_rattle (bool) – Whether to apply random displacements that tail off as we move away from the defect site. Not recommended as typically worsens performance. If False (default), all supercell sites are rattled with the same amplitude (full rattle). (Default: False)

• distorted_elements (dict) – Optional argument to specify the neighbouring elements to distort for each defect, in the form of a dictionary with format {‘defect_name’: [‘element1’, ‘element2’, …]} (e.g {‘vac_1_Cd’: [‘Te’]}). If None, the closest neighbours to the defect are chosen. (Default: None)

• distorted_atoms (list) – Optional argument to specify the indices of the neighbouring atoms to distort for each defect (with indices starting from 0, matching python / pymatgen 0-indexing) for each defect, in the form of a dictionary with format: {'defect_name': [index_1, index_2, ...]} (e.g {'vac_1_Cd': [0, 2]}). If None (default), the closest neighbours to the defect are chosen.

• dimer_bond_length (float) – The bond length to set generated dimers in dimer distortions to, in Å. If None (default), uses distortions.get_dimer_bond_length to estimate the dimer bond length in each case.

• **mc_rattle_kwargs (dict) –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include:

  • stdev (float):

    Standard deviation (in Å) of the Gaussian distribution from which random atomic displacement distances are drawn during rattling. Default is set to 10% of the nearest neighbour distance in the bulk supercell.

  • d_min (float):

    Minimum interatomic distance (in Å) 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 bulk supercell.

  • max_disp (float):

    Maximum atomic displacement (in Å) during Monte Carlo rattling. Rarely occurs and is used primarily as a safety net. (Default: 2.0)

  • max_attempts (int):

    Limit for how many attempted rattle moves are allowed a single atom.

  • active_atoms (list):

    List of the atomic indices which should undergo Monte Carlo rattling. By default, all atoms are rattled. (Default: None)

  • seed (int):

    Seed from which rattle random displacements are generated. Default is to set seed = int(distortion_factor*100) (i.e. +40% distortion -> distortion_factor = 1.4 -> seed = 140, Rattled -> distortion_factor = 1 (no bond distortion) -> seed = 100)

apply_distortions(verbose: bool | None = None) → tuple[dict, dict]

Applies a range of bond distortions (given by self.bond_distortions) and rattling to the unperturbed defect supercell structures of all defects in self.defect_entries, using apply_snb_distortions().

Returns a dictionary with the distorted (and undistorted) structures for each charge state of each defect. If file generation is desired, instead use the methods write_<code>_files().

Note that by default, rattling is not applied to the defect site or distorted neighbours, but to all other atoms in the supercell, however this can be controlled with the active_atoms kwarg (in mc_rattle_kwargs). Rattling is performed by applying random displacements to atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev, using a Monte Carlo algorithm which disfavours moves that bring atoms closer than d_min. Rattling behaviour can be controlled with mc_rattle_kwargs, see the distortions.rattle() docstring for more info.

The nearest neighbours to distort are chosen by taking all sites (or those matching distorted_element / distorted_atoms, if provided), then sorting by distance to the defect site (rounded to 2 decimal places) and site index, and then taking the first num_nearest_neighbours of these. If there are multiple non-degenerate combinations of (nearly) equidistant NNs to distort (e.g. cis vs trans when distorting 2 NNs in a 4 NN square coordination), then the combination with distorted NNs closest to each other is chosen.

The bond distortion and rattling approaches are highly customisable via kwargs to this class and its methods, so see the argument descriptions for more info.

Parameters:

verbose (bool) – Whether to print distortion information (bond atoms and distances) for each charged defect. (Default: None – medium level verbosity)

Returns:

Tuple of a dictionary with the distorted and undistorted structures for each charge state of each defect, in the format: ``` {‘defect_name’: {

’charges’: {

{charge_state}: {

‘structures’: {…},

},

},

and dictionary with distortion parameters for each defect.

Return type:

tuple

classmethod from_structures(defects: list, bulk: Structure, oxidation_states: dict | None = None, padding: int = 1, dict_number_electrons_user: dict | None = None, distortion_increment: float = 0.1, bond_distortions: list | None = None, local_rattle: bool = False, distorted_elements: dict | None = None, distorted_atoms: list | None = None, **mc_rattle_kwargs) → Distortions

Initialise Distortions from defect and bulk structures.

See the Distortions docstring for information on behaviour and arguments.

Parameters:

• defects (list_or_Structure) –

  List of defect structures, or a single defect structure for which to generate distorted structures. If auto site-matching fails, the fractional coordinates or index of the defect site (in defect_structure for interstitials/substitutions, in bulk_structure for vacancies) can be provided in the format: [(defect Structure, frac_coords/index), ...] to aid site-matching.

  Defect charge states (from which bond distortions are determined) are set to the range: 0 - {Defect oxidation state}, with a padding (default = 1) on either side of this range.

• bulk (pymatgen.core.structure.Structure) – Bulk supercell structure, matching defect supercells.

• oxidation_states (dict) – Dictionary of oxidation states for species in your material, used to determine the number of defect neighbours to distort (e.g {“Cd”: +2, “Te”: -2}). If none is provided, the oxidation states will be guessed based on the bulk composition and most common oxidation states of any extrinsic species.

• padding (int) – Defect charge states are set to the range: 0 - {Defect oxidation state}, with a padding (default = 1) on either side of this range.

• dict_number_electrons_user (dict) – Optional argument to set the number of extra/missing charge (negative of electron count change) for the input defects in their neutral state, as a dictionary with format {‘defect_name’: charge_change} where charge_change is the negative of the number of extra/missing electrons. (Default: None)

• distortion_increment (float) – Bond distortion increment. Distortion factors will range from 0 to +/-0.6, in increments of distortion_increment. Recommended values: 0.1-0.3 (Default: 0.1)

• bond_distortions (list) – List of bond distortions to apply to nearest neighbours, instead of the default set (e.g. [-0.5, 0.5]). (Default: None)

• local_rattle (bool) – Whether to apply random displacements that tail off as we move away from the defect site. Not recommended as typically worsens performance. If False (default), all supercell sites are rattled with the same amplitude (full rattle). (Default: False)

• distorted_elements (dict) – Optional argument to specify the neighbouring elements to distort for each defect, in the form of a dictionary with format {‘defect_name’: [‘element1’, ‘element2’, …]} (e.g {‘vac_1_Cd’: [‘Te’]}). If None, the closest neighbours to the defect are chosen. (Default: None)

• distorted_atoms (list) – Optional argument to specify the indices of the neighbouring atoms to distort for each defect (with indices starting from 0, matching python / pymatgen 0-indexing), in the form of a dictionary with format: {'defect_name': [atom1, atom2, ...]} (e.g {'vac_1_Cd': [0, 1]}). If None, the closest neighbours to the defect are chosen. (Default: None)

• **mc_rattle_kwargs (dict) –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include:

  • stdev (float):

    Standard deviation (in Å) of the Gaussian distribution from which random atomic displacement distances are drawn during rattling. Default is set to 10% of the nearest neighbour distance in the bulk supercell.

  • d_min (float):

    Minimum interatomic distance (in Å) 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 bulk supercell.

  • max_disp (float):

    Maximum atomic displacement (in Å) during Monte Carlo rattling. Rarely occurs and is used primarily as a safety net. (Default: 2.0)

  • max_attempts (int):

    Limit for how many attempted rattle moves are allowed a single atom.

  • active_atoms (list):

    List of the atomic indices which should undergo Monte Carlo rattling. By default, all atoms are rattled. (Default: None)

  • seed (int):

    Seed from which rattle random displacements are generated. Default is to set seed = int(distortion_factor*100) (i.e. +40% distortion -> distortion_factor = 1.4 -> seed = 140, Rattled -> distortion_factor = 1 (no bond distortion) -> seed = 100)

write_castep_files(input_file: str | None = '/home/docs/checkouts/readthedocs.org/user_builds/shakenbreak/checkouts/latest/shakenbreak/SnB_input_files/castep.param', write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = None) → tuple[dict, dict]

Generates input .cell and .param files for CASTEP relaxations of all output structures from Distortions.apply_distortions().

See the Distortions.apply_distortions() docstring for info on the distortion generation approach.

Parameters:

• input_file (str, optional) – Path to CASTEP input (.param) file. If not set, default input file will be used (see shakenbreak/SnB_input_files/castep.param).

• write_structures_only (bool, optional) – Whether to only write the structure files (in CIF format) (without calculation inputs). (Default: False)

• output_path (str, optional) – Path to directory in which to write distorted defect structures and calculation inputs. (Default is current directory: “.”)

• verbose (bool, optional) – Whether to print distortion information (bond atoms and distances). (Default: None – medium level verbosity)

Returns:

Tuple of dictionaries with new defects_dict (containing the distorted structures) and defect distortion parameters.

Return type:

tuple

write_cp2k_files(input_file: str | None = None, write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = None) → tuple[dict, dict]

Generates input files for CP2K relaxations of all output structures from Distortions.apply_distortions().

See the Distortions.apply_distortions() docstring for info on the distortion generation approach.

Parameters:

• input_file (str, optional) – Path to CP2K input file. If not set, default input file will be used (see shakenbreak/SnB_input_files/cp2k_input.inp).

• write_structures_only (bool, optional) – Whether to only write the structure files (in CIF format) (without calculation inputs). (Default: False)

• output_path (str, optional) – Path to directory in which to write distorted defect structures and calculation inputs. (Default is current directory: “.”)

• verbose (bool, optional) – Whether to print distortion information (bond atoms and distances). (Default: None – medium level verbosity)

Returns:

Tuple of dictionaries with new defects_dict (containing the distorted structures) and defect distortion parameters.

Return type:

tuple

write_distortion_metadata(output_path: str = '.', defect: str | None = None, charge: int | None = None) → None

Write distortion metadata to file.

If the file already exists then the previous metadata will be renamed to distortion_metadata_<datetime>.json (if it differs from the current metadata), and also combined with the current metadata if compatible (i.e. if they are using similar distortion parameters and only differ in the set of defects / charge states / distortions used), before writing this combined metadata to file.

If defect and/or charge are specified, then only distortion metadata for that defect and/or charge state will be written.

Parameters:

• output_path (str) – Path to directory where the metadata file will be written.

• defect (str) – Name of the defect for which to write the metadata. If None, the metadata for all defects will be written. (Default: None)

• charge (int) – Charge state of the defect for which to write the metadata. If None, the metadata for all charge states of the defect will be written. (Default: None)

Returns:

None

write_espresso_files(pseudopotentials: dict | None = None, input_parameters: str | None = None, input_file: str | None = None, write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = None, profile=None) → tuple[dict, dict]

Generates input files for Quantum Espresso relaxations of all output structures from Distortions.apply_distortions().

See the Distortions.apply_distortions() docstring for info on the distortion generation approach.

Parameters:

• pseudopotentials (dict, optional) – Dictionary matching element to pseudopotential name. (Defaults: None)

• input_parameters (dict, optional) – Dictionary of user Quantum Espresso input parameters, to overwrite/update ShakeNBreak defaults (see shakenbreak/SnB_input_files/qe_input.yaml). (Default: None)

• input_file (str, optional) – Path to Quantum Espresso input file, to overwrite/update ShakeNBreak defaults (see shakenbreak/SnB_input_files/qe_input.yaml). If both input_parameters and input_file are provided, the input_parameters will be used. (Default: None)

• write_structures_only (bool, optional) – Whether to only write the structure files (in CIF format) (without calculation inputs). (Default: False)

• output_path (str, optional) – Path to directory in which to write distorted defect structures and calculation inputs. (Default is current directory: “.”)

• verbose (bool) – Whether to print distortion information (bond atoms and distances). (Default: None – medium level verbosity)

• profile (BaseProfile, optional) – ASE profile object to use for the Espresso() calculator class, if using ase>=3.23. If None (default), set to EspressoProfile(command="pw.x", pseudo_dir=".").

Returns:

Tuple of dictionaries with new defects_dict (containing the distorted structures) and defect distortion parameters.

Return type:

tuple

write_fhi_aims_files(input_file: str | None = None, ase_calculator=None, write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = None, profile=None) → tuple[dict, dict]

Generates input geometry and control files for FHI-aims relaxations of all output structures from Distortions.apply_distortions().

See the Distortions.apply_distortions() docstring for info on the distortion generation approach.

Note that if using ASE >= 3.23 and not write_structures_only, the $AIMS_SPECIES_DIR environment variable must be set.

Parameters:

• input_file (str, optional) – Path to FHI-aims input file, to overwrite/update shakenbreak default ones. If both input_file and ase_calculator are provided, the ase_calculator will be used.

• ase_calculator (Aims, AimsTemplate, optional) – Either an Aims (ASE calculator) or AimsTemplate object to obtain parameters from, for FHI-aims calculations. If not set, ShakeNBreak default values will be used. Recommended to check these! (Default: None)

• write_structures_only (bool, optional) – Whether to only write the structure files (in geometry.in format), without the control.in file.

• output_path (str, optional) – Path to directory in which to write distorted defect structures and calculation inputs. (Default is current directory: “.”)

• verbose (bool, optional) – Whether to print distortion information (bond atoms and distances). (Default: None – medium level verbosity)

• profile (BaseProfile, optional) – ASE profile object to use for the Aims() calculator class, if using ase>=3.23. If None (default), set to AimsProfile(command="fhiaims.x").

Returns:

Tuple of dictionaries with new defects_dict (containing the distorted structures) and defect distortion parameters.

Return type:

tuple

write_vasp_files(user_incar_settings: dict | None = None, user_potcar_functional: str | None = 'PBE', user_potcar_settings: dict | None = None, output_path: str = '.', verbose: bool | None = None, **kwargs) → tuple[dict, dict]

Generates the input files for vasp_gam relaxations of all output structures from Distortions.apply_distortions().

See the Distortions.apply_distortions() docstring for info on the distortion generation approach.

Parameters:

• user_incar_settings (dict) – Dictionary of user VASP INCAR settings (e.g. {“ENCUT”: 300, …}), to overwrite the ShakenBreak defaults for those tags. Highly recommended to look at output INCARs, or shakenbreak/SnB_input_files/incar.yaml 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_potcar_functional (str) – POTCAR functional to use. Default is “PBE” and if this fails, tries “PBE_52”, then “PBE_54”.

• user_potcar_settings (dict) – Dictionary of user VASP POTCAR settings, to overwrite/update the doped defaults (e.g. {‘Fe’: ‘Fe_pv’, ‘O’: ‘O’}}). Highly recommended to look at output POTCARs, or shakenbreak/SnB_input_files/default_POTCARs.yaml, to see what the default POTCAR settings are. (Default: None)

• write_files (bool) – Whether to write output files (Default: True)

• output_path (str) – Path to directory in which to write distorted defect structures and calculation inputs. (Default is current directory = “.”)

• verbose (bool) – Whether to print distortion information (bond atoms and distances). (Default: None – medium level verbosity)

• kwargs – Additional keyword arguments to pass to _create_vasp_input() (Mainly for testing purposes).

Returns:

tuple of dictionaries with new defects_dict (containing the distorted structures) and defect distortion parameters.

Return type:

tuple

shakenbreak.input.apply_snb_distortions(defect_entry: DefectEntry, num_nearest_neighbours: int, bond_distortions: list, local_rattle: bool = False, stdev: float | None = None, d_min: float | None = None, distorted_element: str | None = None, distorted_atoms: list | None = None, oxidation_states: dict | None = None, verbose: bool = False, dimer_bond_length: float | None = None, **mc_rattle_kwargs) → dict

Applies a range of bond distortions (given by bond_distortions) and rattling to num_nearest_neighbours of the unperturbed defect supercell structure of defect_entry, generating a range of distorted structures, using distort_and_rattle_defect_entry().

Note that by default, rattling is not applied to the defect site or distorted neighbours, but to all other atoms in the supercell, however this can be controlled with the active_atoms kwarg. Rattling is performed by applying random displacements to atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev, using a Monte Carlo algorithm which disfavours moves that bring atoms closer than d_min. Rattling behaviour can be controlled with mc_rattle_kwargs, see the distortions.rattle() docstring for more info. Note that dimer distortions can be generated by including "Dimer" in the bond_distortions list; see distortions.apply_dimer_distortion() for more info.

The nearest neighbours to distort are chosen by taking all sites (or those matching distorted_element / distorted_atoms, if provided), then sorting by distance to the defect site (rounded to 2 decimal places) and site index, and then taking the first num_nearest_neighbours of these. If there are multiple non-degenerate combinations of (nearly) equidistant NNs to distort (e.g. cis vs trans when distorting 2 NNs in a 4 NN square coordination), then the combination with distorted NNs closest to each other is chosen.

Parameters:

• defect_entry (DefectEntry) – The defect to distort, as a doped/pymatgen DefectEntry.

• num_nearest_neighbours (int) – Number of defect nearest neighbours to apply bond distortions to.

• bond_distortions (list) – List of specific distortions to apply to defect nearest neighbours (e.g. [-0.5, 0.5]). If “Dimer” is included, then a dimer distortion is also generated.

• local_rattle (bool) – Whether to apply random displacements that tail off as we move away from the defect site. If False, all supercell sites are rattled with the same amplitude. (Default: False)

• stdev (float) – Standard deviation (in Angstroms) of the Gaussian distribution from which random atomic displacement distances are drawn during rattling. Default is set to 10% of the bulk nearest neighbour distance.

• d_min (float, optional) – 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 bulk supercell.

• distorted_element (str, optional) – Neighbouring element to distort. If None, the closest neighbours to the defect will be chosen. (Default: None)

• distorted_atoms (list, optional) – List of atomic indices which should undergo bond distortions, using 0-indexing (i.e. python / pymatgen indexing). If None, the closest neighbours to the defect will be chosen. (Default: None)

• oxidation_states (dict) – Dictionary with oxidation states of the atoms in the material (e.g. {“Cd”: +2, “Te”: -2}).

• verbose (bool) – Whether to print distortion information. (Default: False)

• dimer_bond_length (float) – The bond length to set generated dimers in dimer distortions to, in Å. If None (default), uses distortions.get_dimer_bond_length to estimate the dimer bond length in each case.

• **mc_rattle_kwargs (dict) –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include:

  • max_disp (float):

    Maximum atomic displacement (in Å) during Monte Carlo rattling. Rarely occurs and is used primarily as a safety net. (Default: 2.0)

  • max_attempts (int):

    Limit for how many attempted rattle moves are allowed a single atom.

  • active_atoms (list):

    List of the atomic indices which should undergo Monte Carlo rattling. By default, all atoms are rattled. (Default: None)

  • seed (int):

    Seed from which rattle random displacements are generated. Default is to set seed = int(distortion_factor*100) (i.e. +40% distortion -> distortion_factor = 1.4 -> seed = 140, Rattled -> distortion_factor = 1 (no bond distortion) -> seed = 100)

Returns:

Dictionary with distorted defect structure and the distortion parameters.

Return type:

dict

shakenbreak.input.bold_print(string: str) → None

Prints the input string in bold.

Parameters:

string (str) – String to print in bold.

shakenbreak.input.distort_and_rattle_defect_entry(defect_entry: DefectEntry, num_nearest_neighbours: int, distortion_factor: float | str, local_rattle: bool = False, stdev: float | None = None, d_min: float | None = None, active_atoms: list | None = None, distorted_element: str | None = None, distorted_atoms: list | None = None, oxidation_states: dict | None = None, verbose: bool = False, dimer_bond_length: float | None = None, **mc_rattle_kwargs) → dict

Applies bond distortions and rattling to num_nearest_neighbours of the unperturbed defect supercell structure of defect_entry using the distort_and_rattle() function from shakenbreak.distortions.

The defect site is specified by either:

• fractional coordinates (for vacancies), or

• defect site index (for substitutions/interstitials).

Note that by default, rattling is not applied to the defect site or distorted neighbours, but to all other atoms in the supercell, however this can be controlled with the active_atoms kwarg. Rattling is performed by applying random displacements to atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev, using a Monte Carlo algorithm which disfavours moves that bring atoms closer than d_min. Rattling behaviour can be controlled with mc_rattle_kwargs, see the distortions.rattle() docstring for more info. Note that dimer distortions can be generated by setting distortion_factor to “Dimer”; see distortions.apply_dimer_distortion() for more info.

The nearest neighbours to distort are chosen by taking all sites (or those matching distorted_element / distorted_atoms, if provided), then sorting by distance to the defect site (rounded to 2 decimal places) and site index, and then taking the first num_nearest_neighbours of these. If there are multiple non-degenerate combinations of (nearly) equidistant NNs to distort (e.g. cis vs trans when distorting 2 NNs in a 4 NN square coordination), then the combination with distorted NNs closest to each other is chosen.

Parameters:

• defect_entry (DefectEntry) – The defect to distort, as a doped/pymatgen DefectEntry.

• num_nearest_neighbours (int) – Number of defect nearest neighbours to apply bond distortions to.

• distortion_factor (float) – The distortion factor or distortion name (“Dimer”) to apply to the bond distance between the defect and nearest neighbours. Typical choice is between 0.4 (-60%) and 1.6 (+60%).

• local_rattle (bool) – Whether to apply random displacements that tail off as we move away from the defect site. If False, all supercell sites are rattled with the same amplitude. (Default: False)

• stdev (float) – Standard deviation (in Angstroms) of the Gaussian distribution from which random atomic displacement distances are drawn during rattling. Default is set to 10% of the bulk nearest neighbour distance.

• 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 defect supercell (ignoring interstitials).

• active_atoms (list, optional) – List (or array) of which atomic indices should undergo Monte Carlo rattling. Default is to apply rattle to all atoms except the defect and the bond-distorted neighbours.

• distorted_element (str, optional) – Neighbouring element to distort. If None, the closest neighbours to the defect will be chosen. (Default: None)

• distorted_atoms (list, optional) – List of atomic indices which should undergo bond distortions, using 0-indexing (i.e. python / pymatgen indexing). If None, the closest neighbours to the defect will be chosen. (Default: None)

• oxidation_states (dict) – Dictionary with oxidation states of the atoms in the material (e.g. {“Cd”: +2, “Te”: -2}).

• verbose (bool) – Whether to print distortion information. (Default: False)

• dimer_bond_length (float) – The bond length to set generated dimers in dimer distortions to, in Å. If None (default), uses distortions.get_dimer_bond_length to estimate the dimer bond length.

• **mc_rattle_kwargs (dict) –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include:

  • max_disp (float):

    Maximum atomic displacement (in Å) during Monte Carlo rattling. Rarely occurs and is used primarily as a safety net. (Default: 2.0)

  • max_attempts (int):

    Limit for how many attempted rattle moves are allowed a single atom.

  • active_atoms (list):

    List of the atomic indices which should undergo Monte Carlo rattling. By default, all atoms are rattled. (Default: None)

  • seed (int):

    Seed for setting up NumPy random state from which rattle random displacements are generated.

Returns:

Dictionary with distorted defect structure and the distortion parameters.

Return type:

dict

shakenbreak.input.generate_defect_object(single_defect_dict: dict, bulk_dict: dict, charges: list | None = None, verbose: bool = False) → Defect

Create Defect object from a doped/PyCDT single_defect_dict.

Parameters:

• single_defect_dict (dict) – doped/PyCDT defect dictionary.

• bulk_dict (dict) – doped/PyCDT entry for bulk in the defect_entries dictionary, (e.g. {"vacancies": {}, "interstitials": {}, "bulk": {},})

• charges (list) – List of charge states for the defect.

• verbose (bool) – Whether to print information about the defect object being parsed. (Default is False).

Returns: Defect

shakenbreak.input.identify_defect(defect_structure, bulk_structure, defect_coords=None, defect_index=None, oxi_state=None) → Defect

By comparing the defect and bulk structures, identify the defect present and its site in the supercell, and generate a doped Defect object from this.

Parameters:

• defect_structure (Structure) – Defect structure

• bulk_structure (Structure) – Bulk structure

• defect_coords (list) – Fractional coordinates of the defect site in the supercell.

• defect_index (int) – Index of the defect site in the supercell. For vacancies, this should be the site index in the bulk structure, while for substitutions and interstitials it should be the site index in the defect structure.

• oxi_state (int, float, str) – Oxidation state of the defect site. If not provided, will be automatically determined from the defect structure.

Returns: Defect