pyiron_atomistics.atomistics.structure.factories.ase.AseFactory

pyiron_atomistics.atomistics.structure.factories.ase.AseFactory#

class pyiron_atomistics.atomistics.structure.factories.ase.AseFactory[source]#

Bases: object

__init__()#

Methods

__init__()

bulk([crystalstructure, a, b, c, alpha, ...])

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

crystal([basis, occupancies, spacegroup, ...])

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

cut([a, b, c, clength, origo, nlayers, ...])

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

molecule([vacuum])

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

read([index, format, parallel, ...])

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

stack(atoms2[, axis, cell, fix, maxstrain, ...])

Returns an ASE's tools result as a pyiron_atomistics.atomistics.structure.atoms.Atoms.
bulk(crystalstructure: str | None = None, a: float | None = None, b: float | None = None, c: float | None = None, *, alpha: float | None = None, covera: float | None = None, u: float | None = None, orthorhombic: bool = False, cubic: bool = False, basis=None) → Atoms#

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.

crystal(basis=None, occupancies=None, spacegroup=1, setting=1, cell=None, cellpar=None, ab_normal=(0, 0, 1), a_direction=None, size=(1, 1, 1), onduplicates='warn', symprec=0.001, pbc=True, primitive_cell=False, **kwargs) → Atoms#

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

ase.spacegroup.xtal docstring:

Create an Atoms instance for a conventional unit cell of a

space group.

Parameters:

symbolsstr | sequence of str | sequence of Atom | Atoms

Element symbols of the unique sites. Can either be a string formula or a sequence of element symbols. E.g. (‘Na’, ‘Cl’) and ‘NaCl’ are equivalent. Can also be given as a sequence of Atom objects or an Atoms object.

basislist of scaled coordinates

Positions of the unique sites corresponding to symbols given either as scaled positions or through an atoms instance. Not needed if symbols is a sequence of Atom objects or an Atoms object.

occupancieslist of site occupancies

Occupancies of the unique sites. Defaults to 1.0 and thus no mixed occupancies are considered if not explicitly asked for. If occupancies are given, the most dominant species will yield the atomic number. The occupancies in the atoms.info[‘occupancy’] dictionary will have integers keys converted to strings. The conversion is done in order to avoid unexpected conversions when using the JSON serializer.

spacegroupint | string | Spacegroup instance

Space group given either as its number in International Tables or as its Hermann-Mauguin symbol.

setting1 | 2

Space group setting.

cell3x3 matrix

Unit cell vectors.

cellpar[a, b, c, alpha, beta, gamma]

Cell parameters with angles in degree. Is not used when cell is given.

ab_normalvector

Is used to define the orientation of the unit cell relative to the Cartesian system when cell is not given. It is the normal vector of the plane spanned by a and b.

a_directionvector

Defines the orientation of the unit cell a vector. a will be parallel to the projection of a_direction onto the a-b plane.

size3 positive integers

How many times the conventional unit cell should be repeated in each direction.

onduplicates‘keep’ | ‘replace’ | ‘warn’ | ‘error’
Action if basis contain symmetry-equivalent positions:

‘keep’ - ignore additional symmetry-equivalent positions ‘replace’ - replace ‘warn’ - like ‘keep’, but issue an UserWarning ‘error’ - raises a SpacegroupValueError

symprecfloat

Minimum “distance” betweed two sites in scaled coordinates before they are counted as the same site.

pbcone or three bools

Periodic boundary conditions flags. Examples: True, False, 0, 1, (1, 1, 0), (True, False, False). Default is True.

primitive_cellbool

Whether to return the primitive instead of the conventional unit cell.

Keyword arguments:

All additional keyword arguments are passed on to the Atoms constructor. Currently, probably the most useful additional keyword arguments are info, constraint and calculator.

Examples:

Two diamond unit cells (space group number 227)

>>> diamond = crystal('C', [(0,0,0)], spacegroup=227,
...     cellpar=[3.57, 3.57, 3.57, 90, 90, 90], size=(2,1,1))
>>> ase.view(diamond)

A CoSb3 skutterudite unit cell containing 32 atoms

>>> skutterudite = crystal(('Co', 'Sb'),
...     basis=[(0.25,0.25,0.25), (0.0, 0.335, 0.158)],
...     spacegroup=204, cellpar=[9.04, 9.04, 9.04, 90, 90, 90])
>>> len(skutterudite)
32
cut(a=(1, 0, 0), b=(0, 1, 0), c=None, clength=None, origo=(0, 0, 0), nlayers=None, extend=1.0, tolerance=0.01, maxatoms=None)#

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

molecule(vacuum=None, **kwargs)#

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

ase.build.molecule docstring:

Create an atomic structure from a database.

This is a helper function to easily create molecules from the g2 and extra databases.

Parameters:

  • name (str) – Name of the molecule to build.

  • vacuum (float, optional) – Amount of vacuum to pad the molecule with on all sides.

  • supplied (Additional keyword arguments (kwargs) can be)

  • passed (which are)

  • ase.Atoms. (to)

Returns:

An ASE Atoms object corresponding to the specified molecule.

Return type:

ase.atoms.Atoms

Notes

To see a list of allowed names, try:

>>> from ase.collections import g2
>>> print(g2.names)  
    ['PH3', 'P2', 'CH3CHO', 'H2COH', 'CS', 'OCHCHO', 'C3H9C', 'CH3COF',
    'CH3CH2OCH3', 'HCOOH', 'HCCl3', 'HOCl', 'H2', 'SH2', 'C2H2',
    'C4H4NH', 'CH3SCH3', 'SiH2_s3B1d', 'CH3SH', 'CH3CO', 'CO', 'ClF3',
    'SiH4', 'C2H6CHOH', 'CH2NHCH2', 'isobutene', 'HCO', 'bicyclobutane',
    'LiF', 'Si', 'C2H6', 'CN', 'ClNO', 'S', 'SiF4', 'H3CNH2',
    'methylenecyclopropane', 'CH3CH2OH', 'F', 'NaCl', 'CH3Cl',
    'CH3SiH3', 'AlF3', 'C2H3', 'ClF', 'PF3', 'PH2', 'CH3CN',
    'cyclobutene', 'CH3ONO', 'SiH3', 'C3H6_D3h', 'CO2', 'NO',
    'trans-butane', 'H2CCHCl', 'LiH', 'NH2', 'CH', 'CH2OCH2',
    'C6H6', 'CH3CONH2', 'cyclobutane', 'H2CCHCN', 'butadiene', 'C',
    'H2CO', 'CH3COOH', 'HCF3', 'CH3S', 'CS2', 'SiH2_s1A1d', 'C4H4S',
    'N2H4', 'OH', 'CH3OCH3', 'C5H5N', 'H2O', 'HCl', 'CH2_s1A1d',
    'CH3CH2SH', 'CH3NO2', 'Cl', 'Be', 'BCl3', 'C4H4O', 'Al', 'CH3O',
    'CH3OH', 'C3H7Cl', 'isobutane', 'Na', 'CCl4', 'CH3CH2O', 'H2CCHF',
    'C3H7', 'CH3', 'O3', 'P', 'C2H4', 'NCCN', 'S2', 'AlCl3', 'SiCl4',
    'SiO', 'C3H4_D2d', 'H', 'COF2', '2-butyne', 'C2H5', 'BF3', 'N2O',
    'F2O', 'SO2', 'H2CCl2', 'CF3CN', 'HCN', 'C2H6NH', 'OCS', 'B', 'ClO',
    'C3H8', 'HF', 'O2', 'SO', 'NH', 'C2F4', 'NF3', 'CH2_s3B1d',
    'CH3CH2Cl', 'CH3COCl', 'NH3', 'C3H9N', 'CF4', 'C3H6_Cs', 'Si2H6',
    'HCOOCH3', 'O', 'CCH', 'N', 'Si2', 'C2H6SO', 'C5H8', 'H2CF2', 'Li2',
    'CH2SCH2', 'C2Cl4', 'C3H4_C3v', 'CH3COCH3', 'F2', 'CH4', 'SH',
    'H2CCO', 'CH3CH2NH2', 'Li', 'N2', 'Cl2', 'H2O2', 'Na2', 'BeH',
    'C3H4_C2v', 'NO2']
>>> from ase.build.molecule import extra
>>> print(extra.keys())  
    dict_keys(['Be2', 'C7NH5', 'BDA', 'biphenyl', 'C60'])

Examples

>>> from ase.build import molecule
>>> atoms = molecule('H2O')
read(index: Any | None = None, format: str | None = None, parallel: bool = True, do_not_split_by_at_sign: bool = False, **kwargs) → Atoms | list[Atoms]#

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(atoms2, axis=2, cell=None, fix=0.5, maxstrain=0.5, distance=None, reorder=False, output_strained=False)#

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)