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(defects: Union[list, dict], oxidation_states: Optional[dict] = None, dict_number_electrons_user: Optional[dict] = None, distortion_increment: float = 0.1, bond_distortions: Optional[list] = None, local_rattle: bool = False, distorted_elements: Optional[dict] = None, **mc_rattle_kwargs)[source]#

Bases: object

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

Parameters:

  • defects (dict_or_list_or_DefectEntry) –

    List or dictionary of pymatgen.analysis.defects.thermo.DefectEntry() objects. The DefectEntry objects are initialised with a pymatgen.analysis.defects.core.Defect, a pymatgen.entries.computed_entries.ComputedStructureEntry (containing the defect supercell) and the defect charge state (e.g. DefectEntry(defect=Defect, sc_entry=ComputedStructureEntry, charge_state=+1)). E.g.: [DefectEntry(), DefectEntry(), …], or single DefectEntry(). In this case, generated defect folders will be named in the format: “{DefectEntry.defect.name}_m{DefectEntry.defect.multiplicity}” for interstitials and “{DefectEntry.defect.name}_s{DefectEntry.defect.defect_site_index}” for vacancies and substitutions. The labels “a”, “b”, “c”… will be appended for defects with multiple inequivalent sites.

    Alternatively, if specific defect folder names are desired, defects can be input as a dictionary in the format {“defect name”: DefectEntry()}. E.g.: {“vac_name”: DefectEntry(), “vac_2_name”: DefectEntry(), …, “int_name”: DefectEntry(), “sub_name”: DefectEntry(), …}.

    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 doped/PyCDT 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][source]#

Applies rattle and bond distortion to all defects in defects. 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: Optional[dict] = None, padding: int = 1, dict_number_electrons_user: Optional[dict] = None, distortion_increment: float = 0.1, bond_distortions: Optional[list] = None, local_rattle: bool = False, distorted_elements: Optional[dict] = None, **mc_rattle_kwargs) → Distortions[source]#

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

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

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[source]#

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

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

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(incar_settings: Optional[dict] = None, potcar_settings: Optional[dict] = None, output_path: str = '.', verbose: bool = False) → Tuple[dict, dict][source]#

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

Parameters:

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

  • potcar_settings (dict) – Dictionary of user VASP POTCAR settings, to overwrite/update the doped defaults. Using pymatgen syntax (e.g. {‘POTCAR’: {‘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)

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: Optional[float] = None, d_min: Optional[float] = None, distorted_element: Optional[str] = None, verbose: bool = False, **mc_rattle_kwargs) → dict[source]#

Applies rattle and bond distortions to num_nearest_neighbours of the unperturbed defect structure (in defect_dict).

Parameters:

  • defect_entry (DefectEntry) – pymatgen.analysis.defects.thermo.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: Optional[list] = None, verbose: bool = False) → Defect[source]#

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 defects 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.get_defect_site_idxs_and_unrelaxed_structure(bulk, defect, defect_type, composition_diff, unique_tolerance=1)[source]#

This code is pulled from doped. Will be replaced by importing from doped in future versions, once issues with pymatgen compatibility has been resolved. Get the defect site and unrelaxed structure. Contributed by Dr. Alex Ganose (@ Imperial Chemistry) and refactored for extrinsic species

shakenbreak.input.get_defect_type_and_composition_diff(bulk, defect)[source]#

This code is pulled from doped. Will be replaced by importing from doped in future versions, once issues with pymatgen compatibility has been resolved. Get the difference in composition between a bulk structure and a defect structure. Contributed by Dr. Alex Ganose (@ Imperial Chemistry) and refactored for extrinsic species

shakenbreak.input.identify_defect(defect_structure, bulk_structure, defect_coords=None, defect_index=None) → Defect[source]#

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