pyiron_atomistics.atomistics.structure.has_structure.HasStructure

class pyiron_atomistics.atomistics.structure.has_structure.HasStructure

Bases: ABC

Mixin for classes that have one or more structures attached to them.

Necessary overrides are _get_structure() and _number_of_structures().

get_structure() checks that iteration_step is valid; implementations of _get_structure() therefore don’t have to check it.

number_of_structures may be zero, e.g. if there’s no structure stored in the object yet or a job will compute this structure, but hasn’t been run yet.

Sub classes that wish to document special behavior of their implementation of get_structure() may do so by adding documention to it in the “Methods:” sub section of their class docstring.

Sub classes may support custom data types as indices for frame in get_structure() by overriding _translate_frame().

The example below shows how to implement this mixin and how to check whether an object derives from it

>>> from pyiron_atomistics.atomistics.structure.atoms import Atoms
>>> class Foo(HasStructure):
...     '''
...     Methods:
...         .. method:: get_structure
...             returns structure with single Fe atom at (0, 0, 0)
...     '''
...     def _get_structure(self, frame=-1, wrap_atoms=True):
...         return Atoms(symbols=['Fe'], positions=[[0,0,0]])
...     def _number_of_structures(self):
...         return 1

>>> f = Foo()
>>> for s in f.iter_structures():
...     print(s)
Fe: [0. 0. 0.]
pbc: [False False False]
cell:
Cell([0.0, 0.0, 0.0])

>>> isinstance(f, HasStructure)
True

abstract _get_structure(frame=-1, wrap_atoms=True)

abstract _number_of_structures()

_translate_frame(frame)

Translate frame to an integer for _get_structure().

Parameters:

frame (object) – any object to translate into an integer id

Returns:

valid integer to be passed to _get_structure()

Return type:

int

Raises:

KeyError – if given frame does not exist in this object

__init__()

Methods

__init__()
animate_structures([spacefill, show_cell, ...])	Animate a series of atomic structures.
collect_structures([filter_function])	Collects a copy of all structures in a compact StructureStorage.
get_structure([frame, wrap_atoms, ...])	Retrieve structure from object.
iter_structures([wrap_atoms])	Iterate over all structures in this object.
transform_structures(modify)	Return a modified object by applying a function to each object lazily.

Attributes

number_of_structures

maximum iteration_step + 1 that can be passed to get_structure().

animate_structures(spacefill: bool = True, show_cell: bool = True, center_of_mass: bool = False, particle_size: float = 0.5, camera: str = 'orthographic')

Animate a series of atomic structures.

Parameters:

• spacefill (bool) – If True, then atoms are visualized in spacefill stype

• show_cell (bool) – True if the cell boundaries of the structure is to be shown

• particle_size (float) – Scaling factor for the spheres representing the atoms. (The radius is determined by the atomic number)

• center_of_mass (bool) – False (default) if the specified positions are w.r.t. the origin

• camera (str) – camera perspective, choose from “orthographic” or “perspective”

Returns:

nglview IPython widget

Return type:

animation

collect_structures(filter_function=None) → StructureStorage

Collects a copy of all structures in a compact StructureStorage.

This can be used to force lazily applied modifications with transform_structures() or simply to obtain a known object type from a generic HasStructure object.

Parameters:

filter_function (function) – include structure only if this function returns True for it

Returns:

a copy of all (filtered) structures

Return type:

StructureStorage

get_structure(frame=-1, wrap_atoms=True, iteration_step=None)

Retrieve structure from object. The number of available structures depends on the job and what kind of calculation has been run on it, see number_of_structures.

Parameters:

frame (int, object) – index of the structure requested, if negative count from the back; if

:param _translate_frame() is overridden: :param frame will pass through it: :param iteration_step: deprecated alias for frame :type iteration_step: int :param wrap_atoms: True if the atoms are to be wrapped back into the unit cell :type wrap_atoms: bool

Returns:

the requested structure

Return type:

pyiron_atomistics.atomistics.structure.atoms.Atoms

Raises:

IndexError – if not -number_of_structures <= iteration_step < number_of_structures

iter_structures(wrap_atoms=True)

Iterate over all structures in this object.

Parameters:

wrap_atoms (bool) – True if the atoms are to be wrapped back into the unit cell; passed to get_structure()

Yields:

pyiron_atomistics.atomistitcs.structure.atoms.Atoms – every structure attached to the object

property number_of_structures

maximum iteration_step + 1 that can be passed to get_structure().

Type:

int

transform_structures(modify) → TransformStructure

Return a modified object by applying a function to each object lazily.

Parameters:

modify (function) – applied to each structure, has to return the modified structure

Returns:

a container with the modified structures

Return type:

TransformStructure