assyst.crystals

Crystal structure generation step of ASSYST.

class assyst.crystals.Formulas(atoms: tuple[dict[str, int], ...])[source]

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

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.range('Cu', 3)
Formulas(atoms=({'Cu': 1}, {'Cu': 2}))
>>> el == el_manual
True

Addition is overloaded to the addition of the underlying tuples.

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

The bitwise or operation is akin to the inner product

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

>>> Formulas.range('Cu', 3) * Formulas.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 range(elements: str | Iterable[str], *range_args) → Self[source]

Creates formulas with number of atoms as given by the builtin range.

Multiple elements are combined as the outer product.

trim(min_atoms: int = 1, max_atoms: int | None = None) → Self[source]

Returns a copy of itself with formulas with lesser or more atoms than given limits removed.

assyst.crystals.pyxtal(group: int | list[int], species: tuple[str], num_ions: tuple[int], dim: Literal[0, 1, 2, 3] = 3, repeat: int = 1, allow_exceptions: bool = True, rng: int | Generator | None = None, **kwargs) → Atoms | list[dict][source]

Generate random crystal structures with PyXtal.

group must be between 1 and the largest possible value for the given dimensionality:

dim=3 => 1 - 230 (space groups) dim=2 => 1 - 80 (layer groups) dim=1 => 1 - 75 (rod groups) dim=0 => 1 - 58 (point groups)

When group is passed as a list of int or repeat>1, generate multiple structures and return them in a list of dict containing the keys atoms, symmetry and repeat for the ASE structure, the symmetry group number and which iteration it is, respectively.

Parameters:

  • group (list of int, or int) – the symmetry group to generate or a list of them

  • species (tuple of str) – which species to include, defines the stoichiometry together with num_ions

  • num_ions (tuple of int) – how many of each species to include, defines the stoichiometry together with species

  • dim (int) – dimensionality of the symmetry group, 0 is point groups, 1 is rod groups, 2 is layer groups and 3 is space groups

  • repeat (int) – how many random structures to generate

  • allow_exceptions (bool) – when generating multiple structures, silence errors when the requested stoichiometry and symmetry group are incompatible

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

  • **kwargs – passed to pyxtal.pyxtal function verbatim

Returns:

the generated structure, if repeat==1 and only one symmetry group is requested list of dict of all generated structures, if repeat>1 or multiple symmetry groups are requested

Return type:

ase.Atoms

Raises:

  • ValueError – if species and num_ions are not of the same length

  • ValueError – if stoichiometry and symmetry group are incompatible and allow_exceptions==False or only one structure is requested

assyst.crystals.sample_space_groups(formulas: Formulas | Iterable[dict[str, int]], spacegroups: list[int] | tuple[int, ...] | Iterable[int] | None = None, min_atoms: int = 1, max_atoms: int = 10, max_structures: int | None = None, dim: Literal[0, 1, 2, 3] = 3, tolerance: Literal['metallic', 'atomic', 'molecular', 'vdW'] | DistanceFilter | dict = 'metallic', rng: int | Generator | None = None) → Iterator[Atoms][source]

Create symmetric random structures.

Parameters:

  • formulas (Formulas or collections.abc.Iterable of dict from str to int) – list of chemical formulas

  • spacegroups (list of int) – which space groups to generate

  • min_atoms (int) – do not generate structures smaller than this

  • max_atoms (int) – do not generate structures larger than this

  • max_structures (int) – generate at most this many structures

  • dim (one of 0, 1, 2, or 3) – the dimensionality of the structures to generate; if lower than 3 the code generates samples no longer from space groups, but from the subperiodic layer, rod, or point groups.

  • tolerance (str, dict of elements to radii) – specifies minimum allowed distances between atoms in generated structures; if str then it should be one values understood by pyxtal.tolerance.Tol_matrix; if dict each value gives the minimum radius allowed for an atom, whether a given distance is allowed then depends on the sum of the radii of the respective elements

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

Yields:

ase.Atoms – random symmetric crystal structures