StackingFault

class atomman.defect.StackingFault(hkl: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], ucell: System, cutboxvector: str = 'c', maxindex: int | None = None, a1vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, a2vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, conventional_setting: str = 'p', shift: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, shiftindex: int | None = None, shiftscale: bool = False, tol: float = 1e-08)

Bases: FreeSurface

Class for generating stacking fault atomic configurations.

property a1vect_cart: ndarray

One of the two shift vectors in Cartesian relative to system.

Type:

numpy.ndarray

property a1vect_uvw: ndarray

One of the two conventional lattice shift vectors in Miller or Miller-Bravais indices.

Type:

numpy.ndarray

property a2vect_cart: ndarray

One of the two shift vectors in Cartesian relative to system.

Type:

numpy.ndarray

property a2vect_uvw: ndarray

One of the two conventional lattice shift vectors in Miller or Miller-Bravais indices.

Type:

numpy.ndarray

property abovefault: list

Indices of all atoms in system above the slip plane.

Type:

list

fault(a1: float | None = None, a2: float | None = None, outofplane: float | None = None, faultshift: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, minimum_r: float | None = None, a1vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, a2vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, faultpos_cart: float | None = None, faultpos_rel: float | None = None) → System

Generates a fault configuration by displacing all atoms above the slip plane.

Parameters:

  • a1 (float, optional) – The fractional coordinate of a1vect to shift by. Default value is 0.0.

  • a2 (float, optional) – The fractional coordinate of a2vect to shift by. Default value is 0.0.

  • outofplane (float, optional) – An out-of-plane shift, given in absolute units. Default value is 0.0.

  • faultshift (array-like object, optional) – The full shifting vector to displace the atoms above the slip plane by. Cannot be given with a1, a2, or outofplane.

  • minimum_r (float, optional) – Specifies the minimum allowed interatomic spacing across the slip plane. If any sets of atoms are closer than this value then the outofplane shift is increased. Default value is None, which performs no adjustment.

  • a1vect_uvw (array-like object, optional) – The crystal vector to use for one of the two shifting vectors. Included here for those wishing to override the values set during class initialization.

  • a2vect_uvw (array-like object, optional) – The crystal vector to use for one of the two shifting vectors. Included here for those wishing to override the values set during class initialization.

  • faultpos_rel (float, optional) – The position to place the slip plane within the system given as a relative coordinate along the out-of-plane direction. Included here for those wishing to override the value set when surface() was called. faultpos_rel and faultpos_cart cannot both be given.

  • faultpos_cart (float, optional) – The position to place the slip plane within the system given as a Cartesian coordinate along the out-of-plane direction. Included here for those wishing to override the value set when surface() was called. faultpos_rel and faultpos_cart cannot both be given.

Returns:

The atomic configuration with stacking fault shift

Return type:

atomman.System

property faultpos_cart: float

The Cartesian position of the slip plane.

Type:

float

property faultpos_rel: float

The fractional position of the slip plane.

Type:

float

classmethod fromdatabase(name: str | None = None, ucell: System | None = None, database: Database | None = None, prompt: bool = True, maxindex: int | None = None, tol: float = 1e-07, **kwargs)

Construct a StackingFault object based on record(s) retrieved from the reference database.

Parameters:

  • name (str or None, optional) – The name of the stacking_fault record to retrieve from the database. Alternatively, you can use any other query keyword arguments supported by the stacking_fault record style (see **kwargs below for more info).

  • ucell (atomman.System or None, optional) – The unit cell to use in generating the system. If None (default), then the crystal_prototype record that matches the defect’s family setting will be loaded from the database. Note that if None then the crystal-specific info (lattice constants and symbols) should be given here as kwargs (see below).

  • database (atomman.library.Database or None, optional) – A Database object to use to fetch the records. If None (default), then a new Database instance will be created.

  • prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching stacking_fault (or crystal_prototype) records are found. If prompt=False, then an error will be thrown if multiple matches are found.

  • maxindex (int, optional) – Max uvw index value to use in identifying the best uvw set for the out-of-plane vector. If not given, will use the largest absolute index between the given hkl and the initial in-plane vector guesses.

  • tol (float, optional) – Tolerance parameter used to round off near-zero values. Default value is 1e-8.

  • **kwargs (any) – The recognized kwargs include the query keywords for free_surface records (key, id, family, hkl, shiftindex, cutboxvector), and the crystal-specific parameters recognized by the prototype load style (a, b, c, alpha, beta, gamma, symbols). The non-trivial crystal-specific parameters should be for the crystal if ucell is not given above as the crystal prototype lacks this information.

classmethod fromrecord(record: str | IOBase | DataModelDict | Record, ucell: System | str | IOBase, maxindex: int | None = None, tol: float = 1e-07)

Construct a StackingFault object based on parameters in a stacking_fault record and unit cell information.

Parameters:

  • record (atomman.library.record.StackingFault, str, file-like object or DataModelDict) – A StackingFault record object or the model contents for one.

  • ucell (atomman.System) – The unit cell to use in generating the system.

  • maxindex (int, optional) – Max uvw index value to use in identifying the best uvw set for the out-of-plane vector. If not given, will use the largest absolute index between the given hkl and the initial in-plane vector guesses.

  • tol (float, optional) – Tolerance parameter used to round off near-zero values. Default value is 1e-8.

iterfaultmap(num_a1: int | None = None, num_a2: int | None = None, outofplane: float | None = None, minimum_r: float | None = None, a1vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, a2vect_uvw: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, faultpos_cart: float | None = None, faultpos_rel: float | None = None) → Generator[Tuple[float, float, System], None, None]

Iterates over generalized stacking fault configurations associated with a 2D map of equally spaced a1, a2 coordinates.

Parameters:

  • num_a1 (int) – The number of a1 values to generate systems for. Default value is 1 (only generate for a1=0.0).

  • num_a2 (int) – The number of a2 values to generate systems for. Default value is 1 (only generate for a2=0.0).

  • outofplane (float, optional) – An out-of-plane shift, given in absolute units. Default value is 0.0.

  • minimum_r (float, optional) – Specifies the minimum allowed interatomic spacing across the slip plane. If any sets of atoms are closer than this value then the outofplane shift is increased. Default value is None, which performs no adjustment.

  • a1vect_uvw (array-like object, optional) – The crystal vector to use for one of the two shifting vectors. Included here for those wishing to override the values set during class initialization.

  • a2vect_uvw (array-like object, optional) – The crystal vector to use for one of the two shifting vectors. Included here for those wishing to override the values set during class initialization.

  • faultpos_rel (float, optional) – The position to place the slip plane within the system given as a relative coordinate along the out-of-plane direction. Included here for those wishing to override the value set when surface() was called. faultpos_rel and faultpos_cart cannot both be given.

  • faultpos_cart (float, optional) – The position to place the slip plane within the system given as a Cartesian coordinate along the out-of-plane direction. Included here for those wishing to override the value set when surface() was called. faultpos_rel and faultpos_cart cannot both be given.

Yields:

  • a1 (float) – The a1 fractional coordinate of a1vect.

  • a2 (float) – The a2 fractional coordinate of a2vect.

  • atomman.System – The fault configuration associated with the a1, a2 shift.

surface(shift: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, shiftindex: int | None = None, shiftscale: bool = None, vacuumwidth: float | None = None, minwidth: float | None = None, sizemults: list | None = None, even: bool = False, faultpos_rel: float | None = None, faultpos_cart: float | None = None) → System

Generates the free surface atomic system, which is used as the basis for generating the stacking fault configuration(s).

Parameters:

  • shift (array-like object, optional) – Applies a shift to all atoms. Different values allow for free surfaces with different termination planes to be selected. shift is taken as absolute if shiftscale is False, or relative to the rotated cell’s box vectors if shiftscale is True. Cannot be given with shiftindex. If neither shift nor shiftindex is given then the current value set to the shift attribute will be used.

  • shiftindex (float, optional) – The index of the identified shifts based on the rotated cell to use. Different values allow for the selection of different atomic planes neighboring the slip plane. Cannot be given with shift. If neither shift nor shiftindex is given then the current value set to the shift attribute will be used.

  • shiftscale (bool, optional) – If False (default), a given shift value will be taken as absolute Cartesian. If True, a given shift will be taken relative to the rotated cell’s box vectors.

  • vacuumwidth (float, optional) – If given, the free surface is created by modifying the system’s box to insert a region of vacuum with this width. This is typically used for DFT calculations where it is computationally preferable to insert a vacuum region and keep all dimensions periodic.

  • sizemults (list or tuple, optional) – The three System.supersize multipliers [a_mult, b_mult, c_mult] to use on the rotated cell to build the final system. Note that the cutboxvector sizemult must be an integer and not a tuple. Default value is [1, 1, 1].

  • minwidth (float, optional) – If given, the sizemult along the cutboxvector will be selected such that the width of the resulting final system in that direction will be at least this value. If both sizemults and minwidth are given, then the larger of the two in the cutboxvector direction will be used.

  • even (bool, optional) – A True value means that the sizemult for cutboxvector will be made an even number by adding 1 if it is odd. Default value is False.

  • faultpos_rel (float, optional) – The position to place the slip plane within the system given as a relative coordinate along the out-of-plane direction. faultpos_rel and faultpos_cart cannot both be given. Default value is 0.5 if faultpos_cart is also not given.

  • faultpos_cart (float, optional) – The position to place the slip plane within the system given as a Cartesian coordinate along the out-of-plane direction. faultpos_rel and faultpos_cart cannot both be given.

Returns:

The free surface atomic system.

Return type:

atomman.System