defect

Classes

Functions and attributes

Generates a differential displacement plot for characterizing dislocations.

Parameters:

system_0 (atomman.system) – The base/reference system to use.
system_1 (atomman.system) – The defect/current system to use.
burgers (array-like object) – The dislocation’s Burgers vector.
plotxaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting x-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘x’ = [1, 0, 0].
plotyaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting y-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘y’ = [0, 1, 0].
xlim (tuple, optional) – The minimum and maximum coordinates along the plotting x-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.
ylim (tuple, optional) – The minimum and maximum coordinates along the plotting y-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.
zlim (tuple, optional) – The minimum and maximum coordinates normal to the plotting axes (i.e. plotxaxis X plotyaxis) to include in the fit. Values are taken in the specified length_unit. The optimum zlim should encompass only a single periodic slice. If not given, then the limits are set based on min and max atomic coordinates along the axis.
neighbors (atomman.NeighborList, optional) – The neighbor list associated with system_0 to use. Either neighbors or cutoff must be given, or system_0 must have a neighbors attribute.
cutoff (float, optional) – Cutoff distance for computing a neighbor list for system_0. Either neighbors or cutoff must be given, or system_0 have a neighbors attribute.
component (str, optional) – Indicates the style of the calculation to use. ‘standard’ (default) plots the differential displacements between atoms in the Burgers direction. ‘xy’ plots the differential displacements within the xy plotting plane. This is useful for screw dislocations with localized non-screw components.
axes (array-like object, optional) – 3x3 transformation array to apply to the Burgers vector to make it correspond to the system’s orientation.
plot_scale (float, optional) – Scalar for multiplying the magnitude of the differential displacement arrows. Default value is 1 (no scaling).
atom_color (str or list, optional) – Matplotlib color name(s) to use to display the atoms. If str, that color will be assigned to all atypes. If list, must give a color value or None for each atype. Default value (None) will use cmap instead. Note: atom_color and atom_cmap can be used together as long as exactly one color or cmap is given for each unique atype.
atom_cmap (str or list, optional) – Matplotlib colormap name(s) to use to display the atoms. Atoms will be colored based on their initial positions and scaled using zlim. If str, that cmap will be assigned to all atypes. If list, must give a cmap value or None for each atype. Default value (None) will use ‘hsv’ cmap. Note: atom_color and atom_cmap can be used together as long as exactly one color or cmap is given for each unique atype.
display_final_pos (bool, optional) – Flag to display positions of atoms and arrows relative to final configuration (system_1) rather than initial configuration (system_0). Note that this does not affect the atom’s cmap color as the initial plotzaxis is always used.
return_data (bool, optional) – If True, will return a dict containing the differential displacement vectors and vector positions. Default is False. Note: returned values are oriented relative to the plotting axes.
matplotlib_axes (matplotlib.Axes.axes, optional) – An existing matplotlib axes object. If given, the differential displacement plot will be added to the specified axes of an existing figure. This allows for subplots to be constructed.

Returns:

fig (matplotlib.figure) – The generated figure. Not returned if matplotlib_axes is given.
data (dict) – Contains differential displacement vectors and arrow plotting information. Returned if return_data is True.

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:

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

Generates the uvw box vector orientations for a dislocation atomic configuration. The three returned uvw vectors will coincide with ξ_uvw - the line direction, an in-plane crystal vector close to m, and an out-of-plane crystal vector close to n (the slip plane normal).

Parameters:

ξ_uvw (array-like object) – The Miller crystal vector associated with the dislocation’s line direction.
slip_hkl (array-like object) – The Miller plane indices associated with the dislocation’s slip plane.
m (array-like object, optional) – The m unit vector for the solution. m, n, and u (dislocation line) should be right-hand orthogonal. Default value is [1, 0, 0] (x-axis).
n (array-like object, optional) – The n unit vector for the solution. m, n, and u (dislocation line) should be right-hand orthogonal. Default value is [0, 1, 0] (y-axis).
box (atomman.Box, optional) – The unit cell’s box that the crystal vectors are taken with respect to. If not given, will use a cubic box with a=1 (vects are taken as Cartesian).
tol (float, optional) – Tolerance parameter used to round off near-zero values. Default value is 1e-8.
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.
return_hexagonal (bool, optional) – Flag for indicating if the returned vectors are expressed in Miller [uvw] format (False) or Miller-Bravais [uvtw] format (True). The Miller-Bravais format is only allowed if box is in the standard hexagonal setting: a=b!=c, alpha=beta=90, gamma=120. Default value is False if hkl is given in the 3 indices Miller (hkl) format and True if it is given in the 4 indices Miller-Bravais (hkil) format.
return_transform (bool, optional) – If True, the associated Cartesian transformation matrix will also be returned. Default value is False.

Returns:

uvws (numpy.ndarray) – 3x3 array of Miller [uvw] vectors or 3x4 array of Miller-Bravais [uvtw] vectors to rotate the unit cell for a dislocation configuration.
transform (numpy.ndarray) – The Cartesian transformation matrix. Only returned if return_transform is True.

Raises:

ValueError – If invalid hkl indices values are given.
AssertionError – If the search fails to find any of the three [uvw] rotation vectors.

Utility function for getting the transformation matrix to the dislocation system based on crystal orientation vectors.

Parameters:

ξ_uvw (array-like object) – The Miller crystal vector associated with the dislocation’s line direction.
slip_hkl (array-like object) – The Miller plane indices associated with the dislocation’s slip plane.
m (array-like object, optional) – The m unit vector for the solution. m, n, and u (dislocation line) should be right-hand orthogonal. Default value is [1, 0, 0] (x-axis).
n (array-like object, optional) – The n unit vector for the solution. m, n, and u (dislocation line) should be right-hand orthogonal. Default value is [0, 1, 0] (y-axis).
box (atomman.Box, optional) – The unit cell’s box that the crystal vectors are taken with respect to. If not given, will use a cubic box with a=1 (vects are taken as Cartesian).
tol (float, optional) – Tolerance parameter used to round off near-zero values. Default value is 1e-8.

Returns:

The (3,3) transformation matrix.

Return type:

numpy.ndarray

Computes the disregistry profile for a dislocation system.

Parameters:

basesystem (atomman.System) – A perfect reference system with atoms directly corresponding to atoms in dislsystem.
dislsystem (atomman.System) – A dislocation-containing system.
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. Default value is [1,0,0] (Cartesian x-axis).
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. Default value is [0,1,0] (Cartesian y-axis).
planepos (array-like object, optional) – A position on the slip plane so that the plane can be fully defined. The slip plane position should fall between two planes of atoms. Default value is [0,0,0].

Returns:

coord (numpy.ndarray) – The (N,) array of unique coord-coordinates (atomic columns) neighboring the slip plane.
disregistry (numpy.ndarray) – A (N, 3) array of the dislocation’s disregistry at each coord.

Generates a new system by adding a dumbbell interstitial point defect.

1. Copies the indicated atom and moves both the original and copy to the end of the Atoms list. 2. Displaces the dumbbell atoms position’s by +-db_vect. 3. Adds per-atom property old_id if it doesn’t exist corresponding to the atom ids in the original system. 4. Sets any of the new atom’s per-atom properties to values given as kwargs. Any undefined properties are left unchanged.

Parameters:

system (atomman.System) – The base System to add the defect to.
pos (array-like object, optional) – Position of the atom being modified. Either pos or ptd_id must be given.
ptd_id (int, optional) – Id of the atom to be modified. Either pos or ptd_id must be given.
db_vect (array-like object) – Vector shift to apply to the atoms in the dumbbell.
scale (bool, optional) – Indicates if pos and db_vect are Cartesian (False) or box-relative (True). Default value is False.
atol (float, optional) – Absolute tolerance for position-based searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to per-atom property values for the new atom in the dumbbell. By default, all properties are left unchanged (i.e. same as atom that was copied).

Returns:

A new system with the dumbbell added.

Return type:

atomman.System

Generates the uvw box vector orientations for a free surface atomic system. In determining the uvw sets, two sets will be in the specified hkl plane and one will be out of the plane. Uses free surface in-plane vector determination algorithm by W. Sun and G. Cedar, Surface Science, 617, 53-59 (2013) to identify two in-plane vectors and the plane normal. The shortest in-plane vector is identified, as well as an out-of-plane vector close to the plane normal. The second in-plane vector is then selected to be a shortest in-plane vector that is not parallel to the first.

Parameters:

hkl (array-like object) – The free surface plane to generate expressed in either 3 indices Miller (hkl) format or 4 indices Miller-Bravais (hkil) format.
box (atomman.Box, optional) – The box object associated with the unit cell. Used to identify the best uvw set for the out-of-plane box vector. Default value uses a cubic box.
cutboxvector (str, optional) – Specifies which of the three box vectors corresponds to the out-of-plane vector. Default value is c.
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.
return_hexagonal (bool, optional) – Flag for indicating if the returned vectors are expressed in Miller [uvw] format (False) or Miller-Bravais [uvtw] format (True). The Miller-Bravais format is only allowed if box is in the standard hexagonal setting: a=b!=c, alpha=beta=90, gamma=120. Default value is False if hkl is given in the 3 indices Miller (hkl) format and True if it is given in the 4 indices Miller-Bravais (hkil) format.
return_planenormal (bool, optional) – If True, the computed Cartesian plane normal will also be returned. Default value is False.
conventional_setting (str, optional) – Allows for rotations of a primitive unit cell box to be determined from (hkl) indices specified relative to a conventional unit cell. Allowed settings: ‘p’ for primitive (no conversion), ‘f’ for face-centered, ‘i’ for body-centered, and ‘a’, ‘b’, or ‘c’ for side-centered. Default behavior is to perform no conversion, i.e. take (hkl) relative to the given box.

Returns:

uvws (numpy.ndarray) – 3x3 array of Miller [uvw] vectors or 3x4 array of Miller-Bravais [uvtw] vectors to rotate the unit cell for a free surface configuration.
planenormal (numpy.ndarray) – The Cartesian plane normal vector. Only returned if return_planenormal is True.

Raises:

ValueError – If invalid hkl indices values are given.
AssertionError – If the search fails to find any of the three [uvw] rotation vectors.

Generates a new system by adding an interstitial point defect. 1. Adds a new atom to the end of the Atoms list. 2. Adds per-atom property old_id if it doesn’t exist corresponding to the atom ids in the original system. 3. Sets any of the new atom’s per-atom properties to values given as kwargs. Any undefined properties are given zero values except atype, which is set to 1.

Parameters:

system (atomman.System) – The base System to add the defect to.
pos (array-like object) – Position of the atom being added.
scale (bool, optional) – Indicates if pos is Cartesian (False) or box-relative (True). Default value is False.
atol (float, optional) – Absolute tolerance for position-based searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to per-atom property values for the new atom. By default, atype==1 and all other properties are set to be all zeros for the property’s shape.

Returns:

A new system with the interstitial added.

Return type:

atomman.System

Computes strain properties and Nye tensor for a defect containing system.

Parameters:

system (atomman.System) – The atomic system to compute the per-atom strain properties and Nye tensor for.
p_vectors (array-like object) – List(s) of radial distance vectors between each atom and its nearest neighbors in a perfect crystal setting. If one list of p_vectors is given, then it is applied to all atoms.
theta_max (float, optional) – The maximum theta angle in degrees to use when searching for matches between p vectors and q vectors. Optimum values are dependent on the crystal structure. Default value is 27, which is the original value used for fcc crystals.
axes (array-like object, optional) – 3x3 array of right-handed orthogonal axes. If given, will be used to transform the p_vectors before computing the Nye tensor.
neighbors (atomman.NeighborList, optional) – The neighbor list associated with system to use. Either neighbors or cutoff must be given, or system must have a neighbors attribute.
cutoff (float) – Cutoff distance for computing a neighbor list for system. Either neighbors or cutoff must be given, or system have a neighbors attribute.

Returns:

Contains the per-atom properties ‘strain’, ‘strain_invariant_1’, ‘strain_invariant_2’, ‘angular_velocity’, and ‘Nye_tensor’.

Return type:

dict

atomman.defect.nye_tensor_p(system: System, neighbors: NeighborList | None = None, cutoff: float | None = None) → ndarray

Generates a list of p vectors for each atom to be used by the nye_tensor() function. The p vectors correspond to the radial distance vectors between an atom and each of its neighbors within a cutoff distance in a “perfect crystal” reference state.

Parameters:

system (atomman.system) – The base/reference system to use. This should be a defect-free perfect crystal system with atom ids directly corresponding to atoms in any system that you want to analyze with the Nye tensor.
neighbors (atomman.NeighborList, optional) – The neighbor list associated with system to use. Either neighbors or cutoff must be given, or system must have a neighbors attribute.
cutoff (float) – Cutoff distance for computing a neighbor list for system. Either neighbors or cutoff must be given, or system have a neighbors attribute.

Returns:

The list of p distance vectors for each atom in system.

Return type:

numpy.ndarray

Computes the classic Peierls-Nabarro arctan disregistry for an array of points x.

δ(x) = b / π * arctan(x / ξ) + b / 2

Parameters:

x (array-like or None, optional) – The exact values of x to use. Can be specified instead of the xmax, xstep, and xnum parameters.
xmax (float or None, optional) – Maximum value of x to use. Minimum value is taken as -xmax. At least 2 of xmax, xstep, and xnum must be not None. Default value is None.
xstep (float or None, optional) – Step size to use between each x value. At least 2 of xmax, xstep, and xnum must be not None. Default value is None.
xnum (int or None, optional) – Number of x values to use. At least 2 of xmax, xstep, and xnum must be not None. Default value is None.
burgers (float, numpy.ndarray, optional) – The Burgers vector or Burgers vector magnitude for the dislocation. Default value is [1, 0, 0].
center (float) – The x coordinate to center the dislocation at. Default value is 0.0.
halfwidth (float, optional) – The dislocation halfwidth to use. Default value is 1.
normalize (bool, optional) – If True (default), the disregistry values will be scaled such that the two endpoints differ by exactly one Burgers vector.
shift (bool, optional) – If True (default), the disregistry will range [0, 0, 0] to burgers. If False, the disregistry will range from -burgers to burgers.

Returns:

x (numpy.ndarray) – The x-coordinates for the disregistry values.
disregistry (numpy.ndarray) – The disregistry vector at each x-coordinate.

Generates a new System where a point defect has been inserted.

Parameters:

system (atomman.System) – The base System to add the defect to.
ptd_type (str, optional) – Key indicating which type of defect to add. Default value is ‘v’: - ‘v’ : vacancy. - ‘i’ : positional interstitial. - ‘s’ : substitutional. - ‘db’ : dumbbell interstitial.
pos (array-like object, optional) – Position for adding the defect atom (all styles).
ptd_id (int, optional) – Atom id where defect is added. Alternative to using pos (‘v’, ‘s’, ‘db’ styles).
db_vect (array-like object, optional) – Vector associated with the dumbbell interstitial (‘db’ style).
scale (bool, optional) – Indicates if pos and db_vect are Cartesian (False) or box-relative (True). Default value is False.
atol (float, optional) – Absolute tolerance for position-based searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to per-atom property values for the new atom (‘i’, ‘s’, ‘db’ styles).

Raises:

AssertionError – If parameters are given for styles that don’t allow them.
ValueError – If an invalid ptd_type is given.

Returns:

A new system containing the defect.

Return type:

atomman.System

atomman.defect.slip_vector(system_0, system_1, neighbors=None, cutoff=None)

Compute the slip vectors for all atoms. Note that this differs from the original formulation in that it is not normalized by number of slipped neighbors.

s_i = -Σ_j d_ij(t) - d_ij(0)

where j is neighbor atoms of atom i, and d_ij() is vector distance between atoms i and j at time t.

Parameters:

system_0 (atomman.system) – The base/reference system to use.
system_1 (atomman.system) – The defect/current system to use.
neighbors (atomman.NeighborList, optional) – The neighbor list associated with system_0 to use. Either neighbors or cutoff must be given, or system_0 must have a neighbors attribute.
cutoff (float, optional) – Cutoff distance for computing a neighbor list for system_0. Either neighbors or cutoff must be given, or system_0 have a neighbors attribute.

Returns:

The computed slip vectors.

Return type:

numpy.ndarray

Wrapper function for generating VolterraDislocation children classes that provide linear elastic solutions for straight dislocations.

Parameters:

C (atomman.ElasticConstants) – The medium’s elastic constants.
burgers (array-like object) – The dislocation’s Burgers vector.
ξ_uvw (array-like object) – The Miller crystal vector associated with the dislocation’s line direction. Must be given with slip_hkl to identify the transformation matrix to use on C and burgers.
slip_hkl (array-like object) – The Miller plane indices associated with the dislocation’s slip plane. Must be given with ξ_uvw to identify the transformation matrix to use on C and burgers.
transform (array-like object, optional) – A 3x3 set of orthogonal Cartesian vectors that define the transformation matrix to use on C and burgers to convert from the standard (unit cell) and dislocation orientations. The 3 vectors will automatically be converted into unit vectors. Using this is an alternative to using ξ_uvw and slip_hkl.
axes (array-like object, optional) – Same as transform. Retained for backwards compatibility.
box (atomman.Box, optional) – The unit cell’s box that crystal vectors are taken with respect to. If not given, will use a cubic box with a=1 meaning that burgers, ξ_uvw and slip_hkl will be interpreted as Cartesian vectors.
m (str or array-like object, optional) – The 3D Cartesian unit vector to align with the dislocation solution’s m-axis, i.e. the in-plane direction perpendicular to the dislocation line. Also accepts str values of ‘x’, ‘y’, or ‘z’, in which case the dislocation axis will be aligned with the corresponding Cartesian axis. Default value is ‘x’.
n (str or array-like object, optional) – The 3D Cartesian unit vector to align with the dislocation solution’s n-axis, i.e. the slip plane normal. Also accepts str values of ‘x’, ‘y’, or ‘z’, in which case the dislocation axis will be aligned with the corresponding Cartesian axis. Default value is ‘y’.
cart_axes (bool, optional) – Setting this to True will also perform an assertion check that the m- and n-axes are both aligned with Cartesian axes. This is a requirement for some of the atomic configuration generators. Default value is False as the elastic solution by itself does not require the limitation.
tol (float) – Tolerance parameter used to round off near-zero values. Default value is 1e-8.

Returns:

The dislocation solution of the appropriate type.

Return type:

atomman.defect.VolterraDislocation

Generates a new system by adding a substitutional point defect. 1. Moves the indicated atom to the end of the list and changes its atype to the value given. 2. Adds per-atom property old_id if it doesn’t exist corresponding to the atom ids in the original system. 3. Sets any of the moved atom’s per-atom properties to values given as kwargs. Any undefined properties are left unchanged.

Parameters:

system (atomman.System) – The base System to add the defect to.
pos (array-like object, optional) – Position of the atom being modified. Either pos or ptd_id must be given.
ptd_id (int, optional) – Id of the atom to be modified. Either pos or ptd_id must be given.
atype (int, optional) – Integer atomic type to change the identified atom to. Must be different than the atom’s current id. Default value is 1.
scale (bool, optional) – Indicates if pos is Cartesian (False) or box-relative (True). Default value is False.
atol (float, optional) – Absolute tolerance for position-based searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to per-atom property values for the modified atom. By default, all properties (except atype) are left unchanged.

Returns:

A new system with the substitutional added.

Return type:

atomman.System

Generates a new system by adding a vacancy point defect. 1. Removes the indicated atom from the system 2. Adds per-atom property old_id if it doesn’t exist corresponding to the atom ids in the original system.

Parameters:

system (atomman.System) – The base System to add the defect to.
pos (array-like object, optional) – Position of the atom to be removed. Either pos or ptd_id must be given.
ptd_id (int, optional) – Id of the atom to be removed. Either pos or ptd_id must be given.
scale (bool, optional) – Indicates if pos is Cartesian (False) or box-relative (True). Default value is False.
atol (float, optional) – Absolute tolerance for position-based searching. Default value is 0.01 angstroms.

Returns:

A new system with the vacancy added.

Return type:

atomman.System

defect

Classes

Functions and attributes

Table of Contents

Previous topic

Next topic