pyiron_atomistics.atomistics.structure.factory.StructureFactory

pyiron_atomistics.atomistics.structure.factory.StructureFactory#

class pyiron_atomistics.atomistics.structure.factory.StructureFactory[source]#

Bases: PyironFactory

__init__()[source]#

Methods

__init__()

aimsgb_build(axis, sigma, plane, initial_struct)

Generate a grain boundary structure based on the aimsgb.GrainBoundary module.

aimsgb_info(axis, max_sigma)

Provides a list of possible GB structures for a given rotational axis and upto the given maximum sigma value.

ase_bulk(*args, **kwargs)

Returns an ASE's bulk result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase_read(*args, **kwargs)

Returns an ASE's formats result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

atoms([symbols, positions, numbers, tags, ...])

Creates a atomistics.structure.atoms.Atoms instance.

bulk(name[, crystalstructure, a, c, covera, ...])

Creating bulk systems (using ASE bulk module).

crystal(element, bravais_basis, lattice_constant)

Create a crystal structure using pyiron's native crystal structure generator

cut(*args, **kwargs)

Returns an ASE's tools result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

element(parent_element[, new_element_name, ...])

param parent_element:

The parent element eq. "N", "O", "Mg" etc.

from_ase(ase_obj)

Convert an ase.atoms.Atoms structure object to its equivalent pyiron structure

from_ovito(ovito_obj)

param ovito_obj:

from_pymatgen(structure)

Convert pymatgen Structure object to pyiron atoms object (pymatgen->ASE->pyiron)

high_index_surface(element, ...[, ...])

Gives a slab positioned at the bottom with the high index surface computed by high_index_surface_info().

high_index_surface_info(element, ...[, ...])

Gives the miller indices of high index surface required to create a stepped and kink surface, based on the general orientation and length of terrace, step and kinks respectively.

pyxtal(group, species, num_ions[, dim, ...])

Generate random crystal structures with PyXtal.

read(*args, **kwargs)

Returns an ASE's formats result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

read_using_ase(*args, **kwargs)

read_using_pymatgen(*args, **kwargs)

stack(*args, **kwargs)

Returns an ASE's tools result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

surface(element, surface_type[, size, ...])

Generate a surface based on the ase.build.surface module.

surface_hkl(lattice, hkl, layers[, vacuum, ...])

Use ase.build.surface to build a surface with surface normal (hkl).

Attributes

aimsgb

ase

compound

materialsproject

aimsgb_build(axis, sigma, plane, initial_struct, to_primitive=False, delete_layer='0b0t0b0t', add_if_dist=0.0)[source]#

Generate a grain boundary structure based on the aimsgb.GrainBoundary module.

Parameters:

  • axis – Rotational axis for the GB you want to construct (for example, axis=[1,0,0])

  • sigma (int) – The sigma value of the GB you want to construct (for example, sigma=5)

  • plane – The grain boundary plane of the GB you want to construct (for example, plane=[2,1,0])

  • initial_struct – Initial bulk structure from which you want to construct the GB (a pyiron structure object).

  • delete_layer – To delete layers of the GB. For example, delete_layer=’1b0t1b0t’. The first 4 characters is for first grain and the other 4 is for second grain. b means bottom layer and t means top layer. Integer represents the number of layers to be deleted. The first t and second b from the left hand side represents the layers at the GB interface. Default value is delete_layer=’0b0t0b0t’, which means no deletion of layers.

  • add_if_dist – If you want to add extra interface distance, you can specify add_if_dist. Default value is add_if_dist=0.0

  • to_primitive – To generate primitive or non-primitive GB structure. Default value is to_primitive=False

  • uc_a (int) – Number of unit cell of grain A. Default to 1.

  • uc_b (int) – Number of unit cell of grain B. Default to 1.

Returns:

final grain boundary structure

Return type:

Atoms

aimsgb_info(axis, max_sigma)[source]#

Provides a list of possible GB structures for a given rotational axis and upto the given maximum sigma value.

Parameters:

  • axis – Rotational axis for the GB you want to construct (for example, axis=[1,0,0])

  • max_sigma (int) – The maximum value of sigma upto which you want to consider for your

  • GB (for example, sigma=5)

Returns:

{sigma value: {‘theta’: [theta value],

’plane’: the GB planes”) ‘rot_matrix’: array([the rotational matrix]), ‘csl’: [array([the csl matrix])]}}

Return type:

A list of possible GB structures in the format

To construct the grain boundary select a GB plane and sigma value from the list and pass it to the GBBuilder.gb_build() function along with the rotational axis and initial bulk structure.

ase_bulk(*args, **kwargs)[source]#

Returns an ASE’s bulk result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase.build.bulk docstring:

Creating bulk systems.

Crystal structure and lattice constant(s) will be guessed if not provided.

name: str

Chemical symbol or symbols as in ‘MgO’ or ‘NaCl’.

crystalstructure: str

Must be one of sc, fcc, bcc, tetragonal, bct, hcp, rhombohedral, orthorhombic, mcl, diamond, zincblende, rocksalt, cesiumchloride, fluorite or wurtzite.

a: float

Lattice constant.

b: float

Lattice constant. If only a and b is given, b will be interpreted as c instead.

c: float

Lattice constant.

alpha: float

Angle in degrees for rhombohedral lattice.

covera: float

c/a ratio used for hcp. Default is ideal ratio: sqrt(8/3).

u: float

Internal coordinate for Wurtzite structure.

orthorhombic: bool

Construct orthorhombic unit cell instead of primitive cell which is the default.

cubic: bool

Construct cubic unit cell if possible.

ase_read(*args, **kwargs)[source]#

Returns an ASE’s formats result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase.io.formats docstring:

Read Atoms object(s) from file.

filename: str or file

Name of the file to read from or a file descriptor.

index: int, slice or str

The last configuration will be returned by default. Examples:

  • index=0: first configuration

  • index=-2: second to last

  • index=':' or index=slice(None): all

  • index='-3:' or index=slice(-3, None): three last

  • index='::2' or index=slice(0, None, 2): even

  • index='1::2' or index=slice(1, None, 2): odd

format: str

Used to specify the file-format. If not given, the file-format will be guessed by the filetype function.

parallel: bool

Default is to read on master and broadcast to slaves. Use parallel=False to read on all slaves.

do_not_split_by_at_sign: bool

If False (default) filename is splitted by at sign @

Many formats allow on open file-like object to be passed instead of filename. In this case the format cannot be auto-detected, so the format argument should be explicitly given.

static atoms(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, indices=None, elements=None, dimension=None, species=None, **qwargs)[source]#

Creates a atomistics.structure.atoms.Atoms instance.

Parameters:

  • elements (list/numpy.ndarray) – List of strings containing the elements or a list of atomistics.structure.periodic_table.ChemicalElement instances

  • numbers (list/numpy.ndarray) – List of atomic numbers of elements

  • symbols (list/numpy.ndarray) – List of chemical symbols

  • positions (list/numpy.ndarray) – List of positions

  • scaled_positions (list/numpy.ndarray) – List of scaled positions (relative coordinates)

  • pbc (boolean) – Tells if periodic boundary conditions should be applied

  • cell (list/numpy.ndarray) – A 3x3 array representing the lattice vectors of the structure

  • momenta (list/numpy.ndarray) – List of momentum values

  • tags (list/numpy.ndarray) – A list of tags

  • masses (list/numpy.ndarray) – A list of masses

  • magmoms (list/numpy.ndarray) – A list of magnetic moments

  • charges (list/numpy.ndarray) – A list of point charges

  • celldisp

  • constraint (list/numpy.ndarray) – A list of constraints

  • calculator – ASE calculator

  • info (list/str) – ASE compatibility

  • indices (list/numpy.ndarray) – The list of species indices

  • dimension (int) – Dimension of the structure

  • species (list) – List of species

Returns:

The required structure instance

Return type:

pyiron.atomistics.structure.atoms.Atoms

bulk(name, crystalstructure=None, a=None, c=None, covera=None, u=None, orthorhombic=False, cubic=False)[source]#

Creating bulk systems (using ASE bulk module). Crystal structure and lattice constant(s) will be guessed if not provided.

name (str): Chemical symbol or symbols as in ‘MgO’ or ‘NaCl’. crystalstructure (str): Must be one of sc, fcc, bcc, hcp, diamond, zincblende,

rocksalt, cesiumchloride, fluorite or wurtzite.

a (float): Lattice constant. c (float): Lattice constant. c_over_a (float): c/a ratio used for hcp. Default is ideal ratio: sqrt(8/3). u (float): Internal coordinate for Wurtzite structure. orthorhombic (bool): Construct orthorhombic unit cell instead of primitive cell which is the default. cubic (bool): Construct cubic unit cell if possible.

Returns:

Required bulk structure

Return type:

pyiron.atomistics.structure.atoms.Atoms

static crystal(element, bravais_basis, lattice_constant)[source]#

Create a crystal structure using pyiron’s native crystal structure generator

Parameters:

  • element (str) – Element name

  • bravais_basis (str) – Basis type

  • lattice_constant (float/list) – Lattice constants

Returns:

The required crystal structure

Return type:

pyiron.atomistics.structure.atoms.Atoms

cut(*args, **kwargs)[source]#

Returns an ASE’s tools result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase.build.tools docstring:

Cuts out a cell defined by a, b, c and origo from a

sufficiently repeated copy of atoms.

Typically, this function is used to create slabs of different sizes and orientations. The vectors a, b and c are in scaled coordinates and defines the returned cell and should normally be integer-valued in order to end up with a periodic structure. However, for systems with sub-translations, like fcc, integer multiples of 1/2 or 1/3 might also make sense for some directions (and will be treated correctly).

Parameters:

atoms: Atoms instance

This should correspond to a repeatable unit cell.

a: int | 3 floats

The a-vector in scaled coordinates of the cell to cut out. If integer, the a-vector will be the scaled vector from origo to the atom with index a.

b: int | 3 floats

The b-vector in scaled coordinates of the cell to cut out. If integer, the b-vector will be the scaled vector from origo to the atom with index b.

c: None | int | 3 floats

The c-vector in scaled coordinates of the cell to cut out. if integer, the c-vector will be the scaled vector from origo to the atom with index c. If None it will be along cross(a, b) converted to real space and normalised with the cube root of the volume. Note that this in general is not perpendicular to a and b for non-cubic systems. For cubic systems however, this is redused to c = cross(a, b).

clength: None | float

If not None, the length of the c-vector will be fixed to clength Angstroms. Should not be used together with nlayers.

origo: int | 3 floats

Position of origo of the new cell in scaled coordinates. If integer, the position of the atom with index origo is used.

nlayers: None | int

If nlayers is not None, the returned cell will have nlayers atomic layers in the c-direction.

extend: 1 or 3 floats

The extend argument scales the effective cell in which atoms will be included. It must either be three floats or a single float scaling all 3 directions. By setting to a value just above one, e.g. 1.05, it is possible to all the corner and edge atoms in the returned cell. This will of cause make the returned cell non-repeatable, but is very useful for visualisation.

tolerance: float

Determines what is defined as a plane. All atoms within tolerance Angstroms from a given plane will be considered to belong to that plane.

maxatoms: None | int

This option is used to auto-tune tolerance when nlayers is given for high zone axis systems. For high zone axis one needs to reduce tolerance in order to distinguise the atomic planes, resulting in the more atoms will be added and eventually MemoryError. A too small tolerance, on the other hand, might result in inproper splitting of atomic planes and that too few layers are returned. If maxatoms is not None, tolerance will automatically be gradually reduced until nlayers atomic layers is obtained, when the number of atoms exceeds maxatoms.

Example: Create an aluminium (111) slab with three layers.

>>> import ase
>>> from ase.spacegroup import crystal
>>> from ase.build.tools import cut

# First, a unit cell of Al >>> a = 4.05 >>> aluminium = crystal(‘Al’, [(0,0,0)], spacegroup=225, … cellpar=[a, a, a, 90, 90, 90])

# Then cut out the slab >>> al111 = cut(aluminium, (1,-1,0), (0,1,-1), nlayers=3)

Example: Visualisation of the skutterudite unit cell

>>> from ase.spacegroup import crystal
>>> from ase.build.tools import cut

# Again, create a skutterudite unit cell >>> a = 9.04 >>> skutterudite = crystal( … (‘Co’, ‘Sb’), … basis=[(0.25,0.25,0.25), (0.0, 0.335, 0.158)], … spacegroup=204, … cellpar=[a, a, a, 90, 90, 90])

# Then use origo to put ‘Co’ at the corners and extend to # include all corner and edge atoms. >>> s = cut(skutterudite, origo=(0.25, 0.25, 0.25), extend=1.01) >>> ase.view(s) # doctest:+SKIP

static element(parent_element, new_element_name=None, spin=None, potential_file=None)[source]#
Parameters:

  • parent_element (str, int) – The parent element eq. “N”, “O”, “Mg” etc.

  • new_element_name (str) – The name of the new parent element (can be arbitrary)

  • spin (float) – Value of the magnetic moment (with sign)

  • potential_file (str) – Location of the new potential file if necessary

Returns:

atomistics.structure.periodic_table.ChemicalElement instance

static from_ase(ase_obj)#

Convert an ase.atoms.Atoms structure object to its equivalent pyiron structure

Parameters:

ase_obj (ase.atoms.Atoms) – The ase atoms instance to convert

Returns:

The equivalent pyiron structure

Return type:

pyiron.atomistics.structure.atoms.Atoms

static from_ovito(ovito_obj)#
Parameters:

ovito_obj

Returns:

static from_pymatgen(structure)#

Convert pymatgen Structure object to pyiron atoms object (pymatgen->ASE->pyiron)

Parameters:

pymatgen_obj – pymatgen Structure object

Returns:

pyiron atoms object

high_index_surface(element, crystal_structure, lattice_constant, terrace_orientation=None, step_orientation=None, kink_orientation=None, step_down_vector=None, length_step=3, length_terrace=3, length_kink=1, layers=60, vacuum=10)[source]#

Gives a slab positioned at the bottom with the high index surface computed by high_index_surface_info(). :param element: The parent element eq. “N”, “O”, “Mg” etc. :type element: str :param crystal_structure: The crystal structure of the lattice :type crystal_structure: str :param lattice_constant: The lattice constant :type lattice_constant: float :param terrace_orientation: The miller index of the terrace. default: [1,1,1] :type terrace_orientation: list :param step_orientation: The miller index of the step. default: [1,1,0] :type step_orientation: list :param kink_orientation: The miller index of the kink. default: [1,1,1] :type kink_orientation: list :param step_down_vector: The direction for stepping down from the step to next terrace. default: [1,1,0] :type step_down_vector: list :param length_terrace: The length of the terrace along the kink direction in atoms. default: 3 :type length_terrace: int :param length_step: The length of the step along the step direction in atoms. default: 3 :type length_step: int :param length_kink: The length of the kink along the kink direction in atoms. default: 1 :type length_kink: int :param layers: Number of layers of the high_index_surface. default: 60 :type layers: int :param vacuum: Thickness of vacuum on the top of the slab. default:10 :type vacuum: float

Returns:

pyiron_atomistics.atomistics.structure.atoms.Atoms instance Required surface

Return type:

slab

high_index_surface_info(element, crystal_structure, lattice_constant, terrace_orientation=None, step_orientation=None, kink_orientation=None, step_down_vector=None, length_step=3, length_terrace=3, length_kink=1)[source]#

Gives the miller indices of high index surface required to create a stepped and kink surface, based on the general orientation and length of terrace, step and kinks respectively. The microfacet notation used is based on the work of Van Hove et al.,[1].

[1] Van Hove, M. A., and G. A. Somorjai. “A new microfacet notation for high-Miller-index surfaces of cubic materials with terrace, step and kink structures.” Surface Science 92.2-3 (1980): 489-518.

Parameters:

  • element (str) – The parent element eq. “N”, “O”, “Mg” etc.

  • crystal_structure (str) – The crystal structure of the lattice

  • lattice_constant (float) – The lattice constant

  • terrace_orientation (list) – The miller index of the terrace eg., [1,1,1]

  • step_orientation (list) – The miller index of the step eg., [1,1,0]

  • kink_orientation (list) – The miller index of the kink eg., [1,1,1]

  • step_down_vector (list) – The direction for stepping down from the step to next terrace eg., [1,1,0]

  • length_terrace (int) – The length of the terrace along the kink direction in atoms eg., 3

  • length_step (int) – The length of the step along the step direction in atoms eg., 3

  • length_kink (int) – The length of the kink along the kink direction in atoms eg., 1

Returns:

The high miller index surface which can be used to create slabs fin_kink_orientation: The kink orientation lying in the terrace fin_step_orientation: The step orientation lying in the terrace

Return type:

high_index_surface

static pyxtal(group: int | List[int], species: Tuple[str], num_ions: Tuple[int], dim=3, repeat=1, storage=None, allow_exceptions=True, **kwargs) → Atoms | StructureStorage#

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 integers or repeat>1, generate multiple structures and return them in a StructureStorage.

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

  • storage (StructureStorage, optional) – when generating multiple structures, add them to this instead of creating a new storage

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

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

Returns:

the generated structure, if repeat==1 and only one symmetry group is requested StructureStorage: a storage of all generated structure, if repeat>1 or multiple symmetry groups are requested

Return type:

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

read(*args, **kwargs)[source]#

Returns an ASE’s formats result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase.io.formats docstring:

Read Atoms object(s) from file.

filename: str or file

Name of the file to read from or a file descriptor.

index: int, slice or str

The last configuration will be returned by default. Examples:

  • index=0: first configuration

  • index=-2: second to last

  • index=':' or index=slice(None): all

  • index='-3:' or index=slice(-3, None): three last

  • index='::2' or index=slice(0, None, 2): even

  • index='1::2' or index=slice(1, None, 2): odd

format: str

Used to specify the file-format. If not given, the file-format will be guessed by the filetype function.

parallel: bool

Default is to read on master and broadcast to slaves. Use parallel=False to read on all slaves.

do_not_split_by_at_sign: bool

If False (default) filename is splitted by at sign @

Many formats allow on open file-like object to be passed instead of filename. In this case the format cannot be auto-detected, so the format argument should be explicitly given.

stack(*args, **kwargs)[source]#

Returns an ASE’s tools result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.

ase.build.tools docstring:

Return a new Atoms instance with atoms2 stacked on top of

atoms1 along the given axis. Periodicity in all directions is ensured.

The size of the final cell is determined by cell, except that the length alongh axis will be the sum of atoms1.cell[axis] and atoms2.cell[axis]. If cell is None, it will be interpolated between atoms1 and atoms2, where fix determines their relative weight. Hence, if fix equals zero, the final cell will be determined purely from atoms1 and if fix equals one, it will be determined purely from atoms2.

An ase.geometry.IncompatibleCellError exception is raised if the cells of atoms1 and atoms2 are incompatible, e.g. if the far corner of the unit cell of either atoms1 or atoms2 is displaced more than maxstrain. Setting maxstrain to None disables this check.

If distance is not None, the size of the final cell, along the direction perpendicular to the interface, will be adjusted such that the distance between the closest atoms in atoms1 and atoms2 will be equal to distance. This option uses scipy.optimize.fmin() and hence require scipy to be installed.

If reorder is True, then the atoms will be reordered such that all atoms with the same symbol will follow sequencially after each other, eg: ‘Al2MnAl10Fe’ -> ‘Al12FeMn’.

If output_strained is True, then the strained versions of atoms1 and atoms2 are returned in addition to the stacked structure.

Example: Create an Ag(110)-Si(110) interface with three atomic layers on each side.

>>> import ase
>>> from ase.spacegroup import crystal
>>> from ase.build.tools import cut, stack
>>>
>>> a_ag = 4.09
>>> ag = crystal(['Ag'], basis=[(0,0,0)], spacegroup=225,
...              cellpar=[a_ag, a_ag, a_ag, 90., 90., 90.])
>>> ag110 = cut(ag, (0, 0, 3), (-1.5, 1.5, 0), nlayers=3)
>>>
>>> a_si = 5.43
>>> si = crystal(['Si'], basis=[(0,0,0)], spacegroup=227,
...              cellpar=[a_si, a_si, a_si, 90., 90., 90.])
>>> si110 = cut(si, (0, 0, 2), (-1, 1, 0), nlayers=3)
>>>
>>> interface = stack(ag110, si110, maxstrain=1)
>>> ase.view(interface)  
>>>
# Once more, this time adjusted such that the distance between
# the closest Ag and Si atoms will be 2.3 Angstrom (requires scipy).
>>> interface2 = stack(ag110, si110,
...                    maxstrain=1, distance=2.3)   
Optimization terminated successfully.
    ...
>>> ase.view(interface2)
static surface(element, surface_type, size=(1, 1, 1), vacuum=1.0, center=False, pbc=True, **kwargs)[source]#

Generate a surface based on the ase.build.surface module.

Parameters:

  • element (str) – Element name

  • surface_type (str) – The string specifying the surface type generators available through ase (fcc111,

  • etc.) (hcp0001)

  • size (tuple) – Size of the surface

  • vacuum (float) – Length of vacuum layer added to the surface along the z direction

  • center (bool) – Tells if the surface layers have to be at the center or at one end along the z-direction

  • pbc (list/numpy.ndarray) – List of booleans specifying the periodic boundary conditions along all three directions.

  • **kwargs – Additional, arguments you would normally pass to the structure generator like ‘a’, ‘b’,

  • etc. ('orthogonal')

Returns:

Required surface

Return type:

pyiron_atomistics.atomistics.structure.atoms.Atoms instance

static surface_hkl(lattice, hkl, layers, vacuum=1.0, center=False, pbc=True)[source]#

Use ase.build.surface to build a surface with surface normal (hkl).

Parameters:

  • lattice (pyiron_atomistics.atomistics.structure.atoms.Atoms/str) – bulk Atoms instance or str, e.g. “Fe”, from which to build the surface

  • hkl (list) – miller indices of surface to be created

  • layers (int) – # of atomic layers in the surface

  • vacuum (float) – vacuum spacing

  • center (bool) – shift all positions to center the surface in the cell

Returns:

Required surface

Return type:

pyiron_atomistics.atomistics.structure.atoms.Atoms instance