shakenbreak.distortions module

shakenbreak.distortions module#

Module containing functions for applying distortions to defect structures.

shakenbreak.distortions.apply_dimer_distortion(structure: Structure, site_index: int | None = None, frac_coords: array | None = None) dict[source]#

Apply a dimer distortion to a defect structure. The defect nearest neighbours are determined, from them the two closest in distance are selected, which are pushed towards each other so that their distance is 2.0 A.

Parameters:
  • structure (Structure) – Defect structure.

  • site_index (Optional[int], optional) – Index of defect site (for non vacancy defects). Defaults to None.

  • frac_coords (Optional[np.array], optional) – Fractional coordinates of the defect site in the structure (for vacancies). Defaults to None.

Returns:

Structure:

Distorted dimer structure

Return type:

obj

shakenbreak.distortions.distort(structure: Structure, num_nearest_neighbours: int, distortion_factor: float, site_index: int | None = None, frac_coords: array | None = None, distorted_element: str | None = None, distorted_atoms: list | None = None, verbose: bool | None = False) dict[source]#

Applies bond distortions to num_nearest_neighbours of the defect (specified by site_index (for substitutions or interstitials) or frac_coords (for vacancies)).

Parameters:
  • structure (Structure) – Defect structure as a pymatgen object

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

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

  • site_index (int, optional) – Index of defect site in structure (for substitutions or interstitials), counting from 1.

  • frac_coords (numpy.ndarray, optional) – Fractional coordinates of the defect site in the structure (for vacancies).

  • 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 atom indices to distort. If None, the closest neighbours to the defect will be chosen. (Default: None)

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

Returns:

Dictionary with distorted defect structure and the distortion parameters.

Return type:

dict

shakenbreak.distortions.local_mc_rattle(structure: Structure, site_index: int | None = None, frac_coords: array | None = None, stdev: float | None = None, d_min: float | None = None, verbose: bool | None = False, n_iter: int = 1, active_atoms: list | None = None, nbr_cutoff: float = 5, width: float = 0.1, max_attempts: int = 5000, max_disp: float = 2.0, seed: int = 42) Structure[source]#

Given a pymatgen Structure object, apply random displacements to all atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev. The random displacements tail off as we move away from the defect site.

Parameters:
  • structure (Structure) – Structure as a pymatgen object

  • site_index (int, optional) – Index of defect site in structure (for substitutions or interstitials), counting from 1.

  • frac_coords (numpy.ndarray, optional) – Fractional coordinates of the defect site in the structure (for vacancies).

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

  • verbose (bool) – Whether to print out information about the rattling process.

  • n_iter (int) – Number of Monte Carlo cycles to perform. (Default: 1)

  • active_atoms (list, optional) – List of which atomic indices should undergo Monte Carlo rattling. (Default: None)

  • nbr_cutoff (float) – The radial cutoff distance (in Angstroms) used to construct the list of atomic neighbours for checking interatomic distances. (Default: 5)

  • width (float) – Width of the Monte Carlo rattling error function, in Angstroms. (Default: 0.1)

  • 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) – Maximum Monte Carlo rattle move attempts allowed for a single atom; if this limit is reached an Exception is raised. (Default: 5000)

  • seed (int) – Seed for NumPy random state from which random rattle displacements are generated. (Default: 42)

Returns:

Rattled pymatgen Structure object

Return type:

Structure

shakenbreak.distortions.rattle(structure: Structure, stdev: float | None = None, d_min: float | None = None, verbose: bool = False, n_iter: int = 1, active_atoms: list | None = None, nbr_cutoff: float = 5, width: float = 0.1, max_attempts: int = 5000, max_disp: float = 2.0, seed: int = 42) Structure[source]#

Given a pymatgen Structure object, apply random displacements to all atomic positions, with the displacement distances randomly drawn from a Gaussian distribution of standard deviation stdev.

Parameters:
  • structure (Structure) – Structure as a pymatgen object

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

  • verbose (bool) – Whether to print information about the rattling process.

  • n_iter (int) – Number of Monte Carlo cycles to perform. (Default: 1)

  • active_atoms (list, optional) – List of which atomic indices should undergo Monte Carlo rattling. If not set, rattles all atoms in the structure. (Default: None)

  • nbr_cutoff (float) – The radial cutoff distance (in Angstroms) used to construct the list of atomic neighbours for checking interatomic distances. (Default: 5)

  • width (float) – Width of the Monte Carlo rattling error function, in Angstroms. (Default: 0.1)

  • 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) – Maximum Monte Carlo rattle move attempts allowed for a single atom; if this limit is reached an Exception is raised. (Default: 5000)

  • seed (int) – Seed for NumPy random state from which random rattle displacements are generated. (Default: 42)

Returns:

Rattled pymatgen Structure object

Return type:

Structure