FreeSurface

class atomman.defect.FreeSurface(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, 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-07)

Bases: object

Class for generating free surface atomic configurations using clean planar slices.

property conventional_setting: str

The lattice setting/centering associated with the conventional cell (used if ucell is primitive)

Type:

str

property cutboxvector: str

The box vector for the cut direction.

Type:

str

property cutindex: int

The Cartesian index for the cut direction.

Type:

int

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 FreeSurface object based on record(s) retrieved from the reference database.

Parameters:

  • name (str or None, optional) – The name of the free_surface record to retrieve from the database. Alternatively, you can use any other query keyword arguments supported by the free_surface 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 free_surface (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 FreeSurface object based on parameters in a free_surface record and unit cell information.

Parameters:

  • record (atomman.library.record.FreeSurface, str, file-like object or DataModelDict) – A FreeSurface 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.

property hkl: ndarray

Crystal plane in Miller or Miller-Bravais indices

Type:

numpy.ndarray

property rcell: System

the rotated cell to use in building the defect system.

Type:

atomman.System

property rcellwidth: float

The width of rcell in the cutindex direction.

Type:

float

set_shift(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)

Directly set the shift value based on shiftindex, or shift and shiftscale. NOTE that the shift value can alternatively be set during class initialization or when surface() is called.

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 shiftindex = 0 is 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 shiftindex = 0 is 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.

property shift: ndarray

The particular shift value that will be or was used to construct the defect system

Type:

numpy.NDArray

property shifts: list

All shift values that place the fault halfway between atomic layers in rcell.

Type:

list

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) → System

Generates and returns a free surface atomic system.

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.

Returns:

The free surface atomic system.

Return type:

atomman.System

property surfacearea: float

The surface area of one of the hkl planes.

Type:

float

property system: System

The built free surface system.

Type:

atomman.System

property transform: ndarray

The Cartesian transformation tensor associated with rotating from ucell to rcell

Type:

numpy.ndarray

property ucell: System

The unit cell to use in building the defect system.

Type:

atomman.System

unique_shifts(symprec: float = 1e-05, trial_image_range: int = 1, atol: float = 1e-08, return_indices: bool = False) → ndarray | Tuple[ndarray, list]

Use crystal symmetry operations to filter the list of shift values to only those that are symmetrically unique. Note that the identified unique shifts can still result in the creation of energetically equivalent free surfaces if the free surface introduces a symmetry operation not present in the bulk crystal.

Parameters:

  • symprec (float) – The symmetry precision tolerance value used in spglib.

  • trial_image_range (int, more than or equal to 1.) – Maximum cell images searched in finding translationally equivalent planes. The default value is one, which corresponds to search the 27 neighbor images, [-1, 1]^3. The default value may not be sufficient for largely distorted lattice.

  • atol (float) – The absolute tolerance used in comparing two crystal planes.

  • return_indices (bool) – If True then the indices of shift that correspond to the identified unique shifts will be returned as well. Default value is False (only return the shift vectors).

Returns:

  • unique_shifts (np.ndarray, (# of unique shifts, 3)) – The symmetrically unique shift vectors.

  • unique_indices (list) – The indices of shifts that correspond to the identified unique shifts.

property uvws: ndarray

The conventional Miller or Miller-Bravais crystal vectors associated with the rcell box vectors.

Type:

numpy.ndarray