assyst package¶

Submodules¶

assyst.structures module¶

Crystal structure generation step of ASSYST.

class assyst.structures.Formulas(atoms: tuple[dict[str, int], ...])¶

Bases: Sequence

Simple helper to generate lists of structure compositions.

sample_space_groups() is the intended consumer and expects an iterable of dictionaries, where each dictionary maps an element name to the number of atoms of this type in one structure. Formulas behaves as if it were such a tuple, but extends the basic python arithmetic operations to make building the list a bit simpler.

The class can be initialized from any tuple of dictionaries.

>>> el_manual = Formulas(({'Cu': 1}, {'Cu': 2}))

unary_range() is a helper class method that initializes Formulas for a single element and takes the same arguments as the builtin range, except that it skips the zero.

>>> el = Formulas.unary_range('Cu', 3)
Formulas(atoms=({'Cu': 1}, {'Cu': 2}))
>>> el == el_manual
True

Addition is overloaded to the addition of the underlying tuples.

>>> Formulas.unary_range('Cu', 1, 5) == Formulas.unary_range('Cu', 1, 3) + Formulas.unary_range('Cu', 3, 5)

The bitwise or operation is akin to the inner product

>>> Formulas.unary_range('Cu', 3) | Formulas.unary_range('Ag', 3)
Formulas(atoms=({'Cu': 1, 'Ag': 1}, {'Cu': 2, 'Ag': 2}))

>>> Formulas.unary_range('Cu', 3) * Formulas.unary_range('Ag', 3)
Formulas(atoms=({'Cu': 1, 'Ag': 1}, {'Cu': 2, 'Ag': 1}, {'Cu': 1, 'Ag': 2}, {'Cu': 2, 'Ag': 2}))

atoms: tuple[dict[str, int], ...]¶

property elements: set[str]¶: Set of elements present in elements.

classmethod unary_range(element: str, *range_args) → Self¶: Creates

assyst.structures.sample_space_groups(formulas: Formulas | Iterable[dict[str, int]], spacegroups: list[int] | tuple[int, ...] | None = None, min_atoms: int = 1, max_atoms: int = 10, max_structures: int | None = None) → Iterator[Atoms]¶

Create symmetric random structures.

Parameters:

formulas (Formulas or iterable of dicts from str to int) – list of chemical formulas
spacegroups (list of int) – which space groups to generate
max_atoms (int) – do not generate structures larger than this
max_structures (int) – generate at most this many structures

Yields:

Atoms – random symmetric crystal structures

assyst.relax module¶

Relaxation step of ASSYST.

class assyst.relax.CellRelax(max_steps: int = 100, force_tolerance: float = 0.001, algorithm: Literal['LBFGS'] = 'LBFGS')¶

Bases: Relax

Minimize energy while keeping relative positions and volume constant.

apply_filter_and_constraints(structure: Atoms)¶: Hook to allow subclasses to add filters and constraints.

class assyst.relax.FullRelax(max_steps: int = 100, force_tolerance: float = 0.001, algorithm: Literal['LBFGS'] = 'LBFGS', pressure: float = 0.0)¶

Bases: Relax

Minimize energy with respect to internal positions and cell without constraints.

apply_filter_and_constraints(structure: Atoms)¶: Hook to allow subclasses to add filters and constraints.

pressure: float = 0.0¶

class assyst.relax.Relax(max_steps: int = 100, force_tolerance: float = 0.001, algorithm: Literal['LBFGS'] = 'LBFGS')¶

Bases: object

Minimize energy with respect to internal positions.

Also used as a base class for all other relaxation.

algorithm: Literal['LBFGS'] = 'LBFGS'¶

apply_filter_and_constraints(structure: Atoms)¶: Hook to allow subclasses to add filters and constraints.

force_tolerance: float = 0.001¶

max_steps: int = 100¶

relax(structure: Atoms) → Atoms¶

Relax a structure and return result.

Structure must have a calculator attached. Returned structure will have a SinglePointCalculator with the final energy, forces and stresses attached.

Parameters:: structure (ase.Atoms) – structure to relax
Returns:: relaxed structure with attached single point calculator.
Return type:: ase.Atoms

class assyst.relax.SymmetryRelax(max_steps: int = 100, force_tolerance: float = 0.001, algorithm: Literal['LBFGS'] = 'LBFGS', pressure: float = 0.0)¶

Bases: Relax

Minimize energy with respect to internal positions and cell, while keeping space group fixed.

apply_filter_and_constraints(structure: Atoms)¶: Hook to allow subclasses to add filters and constraints.

pressure: float = 0.0¶

class assyst.relax.VolumeRelax(max_steps: int = 100, force_tolerance: float = 0.001, algorithm: Literal['LBFGS'] = 'LBFGS', pressure: float = 0.0)¶

Bases: Relax

Minimize energy while keeping relative positions and cell shape constant.

apply_filter_and_constraints(structure: Atoms)¶: Hook to allow subclasses to add filters and constraints.

pressure: float = 0.0¶

assyst.relax.relax(settings: Relax, calculator: AseCalculatorConfig | Calculator, structure: Iterable[Atoms]) → Iterator[Atoms]¶

Relax structures according the given relaxation settings.

Output structures have the final energy and force attached as ase’s SinglePointCalculator.

Parameters:

settings (Relax) – the kind of relaxation to perform (position, volume, etc.)
calculator (AseCalculatorConfig or ase.calculators.calculator.Calculator) – the energy/force engine to use
structure (iterable of ase.Atoms) – the structures to minimize

Yields:

ase.Atoms – the corresponding relaxed configuration to each input structure

assyst.random module¶

Nodes to randomly rattle and shake structures.

class assyst.random.ModifyABC¶

Bases: ABC

Apply some modification to a given structure.

class assyst.random.RandomChoice(choice_a: Callable[[Atoms], Atoms] | ModifyABC, choice_b: Callable[[Atoms], Atoms] | ModifyABC, chance: float)¶

Bases: ModifyABC

Apply either of two alternatives randomly.

chance: float¶

choice_a: Callable[[Atoms], Atoms] | ModifyABC¶

choice_b: Callable[[Atoms], Atoms] | ModifyABC¶

class assyst.random.Rattle(sigma: float, create_supercells: bool = False)¶

Bases: ModifyABC

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.

sigma: float¶

class assyst.random.Series(modifications: tuple[Callable[[Atoms], Atoms] | ModifyABC, ...])¶

Bases: ModifyABC

Apply some modifications in sequence.

modifications: tuple[Callable[[Atoms], Atoms] | ModifyABC, ...]¶

class assyst.random.Stretch(hydro: float, shear: float, minimum_strain: float = 0.001)¶

Bases: ModifyABC

Apply random cell modification.

hydro: float¶

minimum_strain: float = 0.001¶

shear: float¶

assyst.random.apply_modifications(structures: Iterable[Atoms], modifications: Iterable[Callable[[Atoms], Atoms] | ModifyABC], filters: Iterable[Callable[[Atoms], bool]] | Callable[[Atoms], bool] | None = None) → Iterator[Atoms]¶: Apply a list of modifications to each structure and yield the result of each modification separately.

assyst.random.rattle(structure: Atoms, sigma: float) → Atoms¶

Randomly displace positions with gaussian noise.

Operates INPLACE.

assyst.random.stretch(structure: Atoms, hydro: float, shear: float, minimum_strain=0.001) → 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.

assyst.filters module¶

Classes that filter structures according to some criteria.

The code in the other modules that uses them is set up such that simple functions can always be passed as well and that the classes here are just for convenience.

class assyst.filters.AspectFilter(maximum_aspect_ratio: float = 6)¶

Bases: object

Filters structures with high aspect ratios.

maximum_aspect_ratio: float = 6¶

class assyst.filters.DistanceFilter(radii: dict[str, float])¶

Bases: object

Filter structures that contain too close atoms.

Setting a radius to NaN allows all bonds involving this atom.

radii: dict[str, float]¶

class assyst.filters.VolumeFilter(maximum_volume_per_atom: float)¶

Bases: object

Filters structures by volume.

maximum_volume_per_atom: float¶

assyst.calculators module¶

Convenience shorts to create ASE calculators to be used inside ASSYST.

Exists mostly to avoid passing around potentially large and unpickle-able calculator objects.

class assyst.calculators.AseCalculatorConfig¶

Bases: ABC

Base class to keep calculator configurations.

abstractmethod get_calculator() → Calculator¶

Return the actual calculator object.

Returns:: the actually usable calculator
Return type:: ase.calculators.calculator.Calculator

class assyst.calculators.Grace(model: str = 'GRACE-FS-OAM')¶

Bases: AseCalculatorConfig

Universal Graph Atomic Cluster Expansion models.

Attention

This class needs additional dependencies! Install tensorpotential from PyPI.

get_calculator() → Calculator¶

Return the actual calculator object.

Returns:: the actually usable calculator
Return type:: ase.calculators.calculator.Calculator

model: str = 'GRACE-FS-OAM'¶

class assyst.calculators.Morse(epsilon: float = 1.0, r0: float = 1.0, rho0: float = 1.0)¶

Bases: AseCalculatorConfig

Morse potential for testing. Parameters as in ASE.

epsilon: float = 1.0¶

get_calculator() → Calculator¶

Return the actual calculator object.

Returns:: the actually usable calculator
Return type:: ase.calculators.calculator.Calculator

r0: float = 1.0¶

rho0: float = 1.0¶

assyst package¶

Submodules¶

assyst.structures module¶

assyst.relax module¶

assyst.random module¶

assyst.filters module¶

assyst.calculators module¶

Module contents¶