assyst.perturbations

Classes to apply (random) perturbations to structures.

class assyst.perturbations.ElementScaledRattle(sigma: float, reference: dict[str, float], create_supercells: bool = False, rng: int | Generator | None = None)

Bases: RngMixin, PerturbationABC

Displace atoms by some amount from a normal distribution.

Operates like Rattle but uses a standard deviation derived from the relative sigma and the reference, where this reference is given by element.

create_supercells: bool = False

Create minimal 2x2x2 super cells when applied to structures of only one atom.

reference: dict[str, float]

rng: int | Generator | None = None

sigma: float

class assyst.perturbations.PerturbationABC

Bases: ABC

Apply some perturbation to a given structure.

class assyst.perturbations.RandomChoice(choice_a: Callable[[Atoms], Atoms] | PerturbationABC, choice_b: Callable[[Atoms], Atoms] | PerturbationABC, chance: float, rng: int | Generator | None = None)

Bases: RngMixin, PerturbationABC

Apply either of two alternatives randomly.

chance: float

Probability to pick choice b

choice_a: Callable[[Atoms], Atoms] | PerturbationABC

choice_b: Callable[[Atoms], Atoms] | PerturbationABC

rng: int | Generator | None = None

class assyst.perturbations.Rattle(sigma: float, create_supercells: bool = False, rng: int | Generator | None = None)

Bases: RngMixin, PerturbationABC

Displace atoms by some absolute amount from a normal distribution.

create_supercells: bool = False

Create minimal 2x2x2 super cells when applied to structures of only one atom.

rng: int | Generator | None = None

sigma: float

class assyst.perturbations.Series(perturbations: tuple[Callable[[Atoms], Atoms] | PerturbationABC, ...])

Bases: PerturbationABC

Apply some perturbations in sequence.

perturbations: tuple[Callable[[Atoms], Atoms] | PerturbationABC, ...]

class assyst.perturbations.Stretch(hydro: float, shear: float, minimum_strain: float = 0.001, rng: int | Generator | None = None)

Bases: RngMixin, PerturbationABC

Apply random cell perturbation.

hydro: float

minimum_strain: float = 0.001

rng: int | Generator | None = None

shear: float

assyst.perturbations.element_scaled_rattle(structure: Atoms, sigma: float, reference: dict[str, float], rng: int | Generator | None = None) → Atoms

Randomly displace positions with gaussian noise relative to an elemental reference length.

Operates like rattle() but uses a standard deviation derived from the relative sigma and the reference, where this reference is given by element.

Operates IN PLACE!

Parameters:

• structure (ase.Atoms) – structure to perturb

• sigma (float) – relative standard deviation

• reference (dict of str to float) – reference length per element

• rng (int, numpy.random.Generator) – seed or random number generator

Raises:

• ValueError – if len(structure) == 1, create a super cell first before calling again

• ValueError – if reference values are not positive

• ValueError – if reference does not contain all elements in given structure

assyst.perturbations.perturb(structures: Iterable[Atoms], perturbations: Iterable[Callable[[Atoms], Atoms] | PerturbationABC], filters: Iterable[Callable[[Atoms], bool] | FilterBase] | Callable[[Atoms], bool] | FilterBase | None = None, retries: int = 10) → Iterator[Atoms]

Apply a list of perturbations to each structure and yield the result of each perturbation separately.

If a perturbation raises ValueError it is ignored.

Parameters:

• structures – collections.abc.Iterable of ase.Atoms to perturb.

• perturbations – collections.abc.Iterable of Perturbation that modify structures.

• filters – collections.abc.Iterable of Filter to filter valid results (optional).

• retries – int, max attempts per perturbation (default: 10).

Yields:

ase.Atoms – perturbed structure that passes all filters.

assyst.perturbations.rattle(structure: Atoms, sigma: float, rng: int | Generator | None = None) → Atoms

Randomly displace positions with gaussian noise.

Operates INPLACE.

Parameters:

• structure (ase.Atoms) – structure to perturb

• sigma (float) – standard deviation of the gaussian noise

• rng (int, numpy.random.Generator) – seed or random number generator

assyst.perturbations.stretch(structure: Atoms, hydro: float, shear: float, minimum_strain=0.001, rng: int | Generator | None = None) → Atoms

Randomly stretch cell with uniform noise.

Ensures at least minimum_strain strain to avoid structures very close to their original structures. These don’t offer a lot of new information and can also confuse VASP’s symmetry analyzer.

Operates INPLACE.

Parameters:

• structure (ase.Atoms) – structure to perturb

• hydro (float) – maximum hydrostatic (diagonal) strain magnitude

• shear (float) – maximum shear (off-diagonal) strain magnitude

• minimum_strain (float) – minimum strain magnitude to ensure structures differ from the original

• rng (int, numpy.random.Generator) – seed or random number generator