# Dislocation

class atomman.defect.Dislocation(ucell: System, C: ElasticConstants, burgers: Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray], ξ_uvw: Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray], slip_hkl: Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray], m: Optional[Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray]] = [0, 1, 0], n: Optional[Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray]] = [0, 0, 1], shift: Optional[Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray]] = None, shiftindex: = None, shiftscale: = None, tol: float = 1e-08)

Bases: object

array_boundary(box: Box, width: float)

Constructs a shape associated with the boundary regions used by the periodicarray() generation method. The returned shape will encompass all atoms except those within width distance of the non-periodic surface.

Parameters:
• box (atomman.Box) – The box associated with the full (base) system.

• width (float) – The width of the boundary region

Returns:

The Shape object excluding the boundary region

Return type:

atomman.region.PlaneSet

property base_system: System

The “perfect crystal” reference system associated with the dislocation system

Type:

atomman.System

box_boundary(box: Box, width: float)

Constructs a shape associated with the box-style boundary region. Used by the monopole() generation method. The returned shape will encompass all atoms except those within width distance of the two non-periodic surfaces.

Parameters:
• box (atomman.Box) – The box associated with the full (base) system.

• width (float) – The width of the boundary region

Returns:

The Shape object excluding the boundary region

Return type:

atomman.region.PlaneSet

property cutindex: int

0=a, 1=b, 2=c

Type:

int

Type:

The index of the box vector that is not within the slip plane

cylinder_boundary(box: Box, width: float)

Constructs a shape associated with the cylinder-style boundary region. Used by the monopole() generation method. The returned shape will encompass a cylinder of atoms centered around the dislocation line leaving a boundary region that will be at least width wide everywhere.

Parameters:
• box (atomman.Box) – The box associated with the full (base) system.

• width (float) – The minimum width of the boundary region.

Returns:

The Shape object excluding the boundary region

Return type:

atomman.region.Cylinder

property disl_system: System

The generated dislocation system

Type:

atomman.System

The elastic dislocation solution

Type:

classmethod fromref(ucell: System, C: ElasticConstants, model: Union[str, IOBase, DataModelDict], tol: float = 1e-08)

Initializes a Dislocation object based on pre-defined dislocation parameters from a reference record.

Parameters:
• ucell (atomman.System) – The unit cell to use as the seed for generating the dislocation monopole system.

• C (atomman.ElasticConstants) – The elastic constants associated with the bulk crystal structure for ucell.

• model (str, file-like object or DataModelDict) – The reference record containing dislocation parameters to use.

• tol (float) – A cutoff tolerance used with obtaining the dislocation solution. Only needs to be changed if there are issues with obtaining a solution.

property lineindex: int

0=a, 1=b, 2=c

Type:

int

Type:

The index of the box vector that coincides with the dislocation line

monopole(sizemults: = None, amin: float = 0.0, bmin: float = 0.0, cmin: float = 0.0, shift: Optional[Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray]] = None, shiftindex: = None, shiftscale: bool = False, boundaryshape: str = 'cylinder', boundarywidth: float = 0.0, boundaryscale: bool = False, return_base_system: bool = False)

Constructs a dislocation monopole atomic configuration containing a single perfectly straight dislocation. The resulting system will be periodic along the box vector direction that corresponds to the dislocation’s line direction, and non-periodic in the other two box vector directions. Boundary atoms near the two free surfaces will be identified by changing their atype values making it easy to identify them later for assigning different boundary conditions.

Parameters:
• sizemults (tuple, optional) – The size multipliers to use when generating the system. Values are limited to being positive integers. The multipliers for the two non-periodic directions must be even. If not given, the default multipliers will be 2 for the non-periodic directions and 1 for the periodic direction.

• amin (float, optional) – A minimum thickness to use for the a box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both amin and sizemults is given, then the larger multiplier for the two will be used.

• bmin (float, optional) – A minimum thickness to use for the b box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both bmin and sizemults is given, then the larger multiplier for the two will be used.

• cmin (float, optional) – A minimum thickness to use for the c box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both cmin and sizemults is given, then the larger multiplier for the two will be used.

• shift (array-like object, optional) – A rigid body shift to apply to the rotated cell prior to inserting the dislocation. Should be selected such that the ideal slip plane does not correspond to any atomic planes. 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 will use the shift set during class initialization.

• shiftindex (float, optional) – The index of the identified optimum shifts based on the rotated cell to use. Different values allow for the selection of different atomic planes neighboring the slip plane. Note that shiftindex values only apply shifts normal to the slip plane; best shifts for non-planar dislocations (like bcc screw) may also need a shift in the slip plane. Cannot be given with shiftindex. If neither shift nor shiftindex is given then shiftindex = 0 is used then will use the shift set during class initialization.

• 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.

• boundaryshape (str, optional) – Indicates the shape of the boundary region to use. Options are ‘cylinder’ (default) and ‘box’. For ‘cylinder’, the non-boundary region is defined by a cylinder with axis along the dislocation line and a radius that ensures the boundary is at least boundarywidth thick. For ‘box’, the boundary region will be exactly boundarywidth thick all around.

• boundarywidth (float, optional) – The width of the boundary region to apply. Default value is 0.0, i.e. no boundary region. All atoms in the boundary region will have their atype values changed.

• boundaryscale (bool, optional) – If False (Default), the boundarywidth will be taken as absolute. If True, the boundarywidth will be taken relative to the magnitude of the unit cell’s a box vector.

• return_base_system (bool, optional) – If True then the dislocation-free base system corresponding to the dislocation system will also be returned. The base system is used as a reference state for most of the dislocation analysis tools.

Returns:

• base_system (atomman.System) – The base “perfect crystal” reference system associated with the dislocation system. Only returned if return_base_system is True.

• disl_system (atomman.System) – The generated dislocation monopole system.

periodicarray(sizemults: = None, amin: float = 0.0, bmin: float = 0.0, cmin: float = 0.0, shift: Optional[Union[int, float, complex, str, bytes, generic, Sequence[Union[int, float, complex, str, bytes, generic]], Sequence[Sequence[Any]], _SupportsArray]] = None, shiftindex: = None, shiftscale: bool = False, boundarywidth: float = 0.0, boundaryscale: bool = False, linear: bool = False, cutoff: = None, return_base_system: bool = False)

Constructs a dislocation monopole atomic configuration containing a single perfectly straight dislocation. The resulting system will be periodic along the box vector direction that corresponds to the dislocation’s line direction, and non-periodic in the other two box vector directions. Boundary atoms near the two free surfaces will be identified by changing their atype values making it easy to identify them later for assigning different boundary conditions.

Parameters:
• sizemults (tuple, optional) – The size multipliers to use when generating the system. Values are limited to being positive integers. The multipliers for the two non-periodic directions must be even. If not given, the default multipliers will be 2 for the non-periodic directions and 1 for the periodic direction.

• amin (float, optional) – A minimum thickness to use for the a box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both amin and sizemults is given, then the larger multiplier for the two will be used.

• bmin (float, optional) – A minimum thickness to use for the b box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both bmin and sizemults is given, then the larger multiplier for the two will be used.

• cmin (float, optional) – A minimum thickness to use for the c box vector direction of the final system. Default value is 0.0. For the non-periodic directions, the resulting vector multiplier will be even. If both cmin and sizemults is given, then the larger multiplier for the two will be used.

• shift (float, optional) – A rigid body shift to apply to the rotated cell prior to inserting the dislocation. Should be selected such that the ideal slip plane does not correspond to any atomic planes. 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 optimum shifts based on the rotated cell to use. Different values allow for the selection of different atomic planes neighboring the slip plane. Note that shiftindex values only apply shifts normal to the slip plane; best shifts for non-planar dislocations (like bcc screw) may also need a shift in the slip plane. Cannot be given with shiftindex. 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.

• boundarywidth (float, optional) – The width of the boundary region to apply. Default value is 0.0, i.e. no boundary region. All atoms in the boundary region will have their atype values changed and will be displaced by linear displacements.

• boundaryscale (bool, optional) – If False (Default), the boundarywidth will be taken as absolute. If True, the boundarywidth will be taken relative to the magnitude of the unit cell’s a box vector.

• linear (bool, optional) – If True, then only linear displacements will be used and not the dislocation solution. Using only linear displacements is useful for screw dislocations and dislocations with large stacking fault distances. If False (default) then the dislocation solution will be used for the middle displacements and linear displacements only in the boundary region.

• cutoff (float, optional) – Cutoff distance to use for identifying duplicate atoms to remove. For dislocations with an edge component, applying the displacements creates an extra half-plane of atoms that will have (nearly) identical positions with other atoms after altering the boundary conditions. Default value is 0.5 Angstrom.

• return_base_system (bool, optional) – If True then the dislocation-free base system corresponding to the dislocation system will also be returned. The base system is used as a reference state for most of the dislocation analysis tools.

Returns:

• base_system (atomman.System) – The base “perfect crystal” reference system associated with the dislocation system. If the Burgers vector has an edge component then the atoms deleted when generating disl_system will also be deleted from base_system. Only returned if return_base_system is True.

• disl_system (atomman.System) – The generated periodic array of dislocations system.

property rcell: System

The cell associated with rotating ucell to coincide with the dislocation solution

Type:

atomman.System

property shift: ndarray

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

Type:

numpy.NDArray

property shifts: list

All identified shifts that will place the slip plane halfway between atomic planes

Type:

list

property transform: ndarray

The 3x3 Cartesian transformation matrix associated with rotating from ucell to rcell

Type:

numpy.NDArray

property ucell: System

The crystal unit cell used as the basis for constructing the dislocation system

Type:

atomman.System

property uvws: ndarray

The 3x3 array of uvw Miller vectors used to rotate ucell to rcell

Type:

numpy.NDArray