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, **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).

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 DefectEntry`s, otherwise generated according to the `doped convention (see: https://doped.readthedocs.io/en/latest/dope_workflow_example.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 (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)

• **mc_rattle_kwargs –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include: - 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 nearest neighbour distance in the bulk supercell.

  • 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 bulk supercell.

  • max_disp (float):

    Maximum atomic displacement (in Angstroms) 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 = False) → Tuple[dict, dict]

Applies rattle and bond distortion to all defects in defect_entries. 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().

Parameters:

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

Returns:

Tuple of: 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, **mc_rattle_kwargs) → Distortions

Initialise Distortions() class from defect and bulk structures.

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)

• **mc_rattle_kwargs –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include: - 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 nearest neighbour distance in the bulk supercell.

  • 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 bulk supercell.

  • max_disp (float):

    Maximum atomic displacement (in Angstroms) 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 = False) → Tuple[dict, dict]

Generates input .cell and .param files for CASTEP relaxations of all output structures.

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: False)

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 = '/home/docs/checkouts/readthedocs.org/user_builds/shakenbreak/checkouts/latest/shakenbreak/../SnB_input_files/cp2k_input.inp', write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = False) → Tuple[dict, dict]

Generates input files for CP2K relaxations of all output structures.

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: False)

Returns:

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

Return type:

tuple

write_distortion_metadata(output_path='.') → None

Write metadata to file. If the file already exists, it will be renamed to distortion_metadata_<datetime>.json and updated with new metadata.

Parameters:

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

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 = False) → Tuple[dict, dict]

Generates input files for Quantum Espresso relaxations of all output structures.

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 default ones (see SnB_input_files/qe_input.yaml). (Default: None)

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

• 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: False)

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: Aims | None = None, write_structures_only: bool | None = False, output_path: str = '.', verbose: bool | None = False) → Tuple[dict, dict]

Generates input geometry and control files for FHI-aims relaxations of all output structures.

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 (ase.calculators.aims.Aims, optional) – ASE calculator object to use 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 contro-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: False)

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: Literal['PBE', 'PBE_52', 'PBE_54', 'LDA', 'LDA_52', 'LDA_54', 'PW91', 'LDA_US', 'PW91_US'] | None = 'PBE', user_potcar_settings: dict | None = None, output_path: str = '.', verbose: bool = False, **kwargs) → Tuple[dict, dict]

Generates the input files for vasp_gam relaxations of all output structures.

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 INCAR`s, or `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 POTCAR`s, 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: False)

• 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, verbose: bool = False, **mc_rattle_kwargs) → dict

Applies rattle and bond distortions to num_nearest_neighbours of the unperturbed defect structure of defect_entry.

Parameters:

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

• 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])

• 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)

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

• **mc_rattle_kwargs –

  Additional keyword arguments to pass to hiphive’s mc_rattle function. These include: - max_disp (float):

  Maximum atomic displacement (in Angstroms) 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.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.

Returns: Defect

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

By comparing the defect and bulk structures, identify the defect present and its site in the supercell, and generate a pymatgen defect object (doped.core.Defect) 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.

Returns: Defect