Dislocation

Bases: object

array_boundary(box: Box, width: float) → PlaneSet

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

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

build_disl_array(base_system: System, linear: bool = False, bwidth: float | None = None, cutoff: float | None = None) → System

Method that converts a bulk crystal system into a periodic array of dislocations. A single dislocation is inserted using a dislocation solution. The system’s box and pbc are altered such that the system is periodic and compatible across the two box vectors contained in the slip plane. The third box vector is non-periodic, resulting in free surfaces parallel to the dislocation’s slip plane.

Parameters:

base_system (atomman.System) – A perfect, bulk atomic system.
dislsol (atomman.defect.VolterraDislocation, optional) – A dislocation solution to use to displace atoms by. If not given, all atoms will be given linear displacements associated with the long-range limits.
m (array-like object, optional) – The dislocation solution m unit vector. This vector is in the slip plane and perpendicular to the dislocation line direction. Only needed if dislsol is not given.
n (array-like object, optional) – The dislocation solution n unit vector. This vector is normal to the slip plane. Only needed if dislsol is not given.
burgers (array-like object, optional) – The Cartesian Burger’s vector for the dislocation relative to the given system’s Cartesian coordinates. Only needed if dislsol is not given.
bwidth (float, optional) – The width of the boundary region at the free surfaces. Atoms within the boundaries will be displaced by linear displacements instead of by the dislocation solution. Only given if dislsol is not None. Default value if dislsol is given is 10 Angstroms.
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 cutoff value is 0.5 Angstrom.

Returns:

The resulting periodic array of dislocations system. An additional atoms property ‘old_id’ will be added to map the atoms in the defect system back to the associated atoms in the original system.

Return type:

atomman.System

property cutindex: int

The index of the box vector that is not within the slip plane: 0=a, 1=b, 2=c.

Type:: int

cylinder_boundary(box: Box, width: float) → Cylinder

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

Constructs a dislocation dipole configuration as described by Li, Wang, Chang, Cai, Bulatov, Ho, Yip, Phys Rev B 70(10) (2004) 104113 https://doi.org/10.1103/Physrevb.70.104113. Two parallel dislocations with opposite Burgers vectors will be inserted into the system using a Volterra solution. The resulting configuration is periodic in all three directions and constitutes a regularly-spaced 2D grid of parallel dislocations. A shear strain is also applied to the system of 1/2 the Burgers vector to counteract the elastic strain of the dislocations and ensure stability.

Parameters:

sizemults (tuple) – The three size multipliers to use when generating the system. Values should be positive integers if boxtilt is False. When boxtilt is True, the multipliers are limited to values that result in full lattice vectors once the tilt is added. Depending on the system, fractional values may be possible, or some integer values not allowed.
boxtilt (bool, optional) – If True (default) then a tilt will be applied to the system such that the resulting periodic configuration will be consistent with a “quadripole” representation in which each dislocation will be surrounded by dislocations of the opposite sign in both the m- and n- directions. This is achieved by adding half of the box vector most aligned with the m-axis to the box vector most aligned with the n-axis. A value of False will not tilt the system, so only the sizemults will be applied to the rotated cell. The non-tilted system will have dislocations of the same sign aligned along the n-axis.
numreplicas (int, optional) – Indicates how many image cells are used for computing the displacement field of the dipole. A rectangular grid of images is used meaning that there will be NxN total cells evaluated, of which NxN-1 will be image cells. Default value is 5.
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.
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.

Uses the method of Cai, Bulatov, Chang, Li & Yip, Phil Mag 2003, 83(5), 539-567 https://doi.org/10.1080/0141861021000051109 to compute the displacement associated with a dislocation dipole in a periodic lattice.

Parameters:

dislsol (atomman.defect.VolterraDislocation) – A Volterra dislocation solution object. This provides the dislocation orientation (m, n vectors) and the displacement solutions for the two individual dislocations of opposite Burgers vectors.
pos (array-like object) – The coordinates to evaluate the displacement at.
x1 (float or array-like object) – The coordinate(s) of the first dislocation. If a float is given, it will be multiplied by the dislocation solution’s m vector.
x2 (float or array-like object) – The coordinate(s) of the second dislocation. If a float is given, it will be multiplied by the dislocation solution’s m vector.
mvect (array-like object) – One of the two 2D cell vectors. This should be parallel to the dislocation solution’s m vector and a whole periodic lattice vector.
nvect (array-like object) – One of the two 2D cell vectors. This should be a whole lattice vector with major component along the dislocation solution’s n vector. It does not need to be parallel to n and can have components in either of the two coordinate directions.
N (int, optional) – Indicates how many image cells are used. A rectangular grid of images is used meaning that there will be NxN total cells evaluated, of which NxN-1 will be image cells. Default value is 5.

Returns:

displacement – The associated displacement field evaluated at pos for the dipole configuration.

Return type:

numpy.NDArray

property disl_system: System

The generated dislocation system.

Type:: atomman.System

property dislsol: VolterraDislocation

The elastic dislocation solution

Type:: atomman.defect.VolterraDislocation

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

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

Parameters:

name (str or None, optional) – The name of the dislocation record to retrieve from the database. Alternatively, you can use any other query keyword arguments supported by the dislocation 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).
C (atomman.ElasticConstants, optional) – The elastic constants associated with the bulk crystal structure for ucell. Required, but future versions may fetch from the database.
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 dislocation (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, character, family), 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, C: ElasticConstants, tol: float = 1e-08)

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

Parameters:

record (atomman.library.record.Dislocation, str, file-like object or DataModelDict) – A Dislocation record object or the model contents for one.
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

The index of the box vector that coincides with the dislocation line: 0=a, 1=b, 2=c.

Type:: int

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.

property motionindex: int

The index of the box vector that is not the line or cut directions: 0=a, 1=b, 2=c.

Type:: int

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 rotated cell that coincides with the dislocation solution orientation.

Type:: atomman.System

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.

set_systems(base_system: System, disl_system: System)

Used by the configuration generators to set base and dislocation systems as class attributes.

Parameters:

base_system (atomman.System) – The base reference system.
disl_system (atomman.System) – The dislocation 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 reference conventional unit cell for the dislocation system.

Type:: atomman.System

property ucell_prim: System

The primitive unit cell of ucell used as the basis for constructing rcell.

Type:: atomman.System

property uvws: ndarray

The 3x3 array of uvw Miller vectors that correspond to the rcell orientation.

Type:: numpy.NDArray

property uvws_prim: ndarray

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

Type:: numpy.NDArray

Dislocation

Table of Contents

Previous topic

Next topic