defect
Functions and attributes

atomman.defect.
differential_displacement
(system_0, system_1, burgers, plotxaxis='x', plotyaxis='y', xlim=None, ylim=None, zlim=None, neighbors=None, cutoff=None, component='standard', axes=None, plot_scale=1, atom_color=None, atom_cmap=None, display_final_pos=False, return_data=False) 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 (arraylike object) – The dislocation’s Burgers vector.
plotxaxis (str or arraylike object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting xaxis. 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 arraylike object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting yaxis. 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 xaxis 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 yaxis 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 nonscrew components.
axes (arraylike 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.
 Returns
fig (matplotlib.figure) – The generated figure.
data (dict) – Contains differential displacement vectors and arrow plotting information. Returned if return_data is True.

atomman.defect.
dislocation_array
(system, dislsol=None, m=None, n=None, burgers=None, bwidth=None, cutoff=None) 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 nonperiodic, resulting in free surfaces parallel to the dislocation’s slip plane.
 Parameters
system (atomman.System) – A perfect, bulk atomic system.
dislsol (atomman.defect.Stroh or atomman.defect.IsotropicVolterra, optional) – A dislocation solution to use to displace atoms by. If not given, all atoms will be given linear displacements associated with the longrange limits.
m (arraylike 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 (arraylike object, optional) – The dislocation solution n unit vector. This vector is normal to the slip plane. Only needed if dislsol is not given.
burgers (arraylike 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 halfplane 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.defect.
dislocation_system_transform
(ξ_uvw, slip_hkl, m=None, n=None, box=None, tol=1e08) Utility function for getting the transformation matrix to the dislocation system based on crystal orientation vectors.
 Parameters
ξ_uvw (arraylike object) – The Miller crystal vector associated with the dislocation’s line direction.
slip_hkl (arraylike object) – The Miller plane indices associated with the dislocation’s slip plane.
m (arraylike object, optional) – The m unit vector for the solution. m, n, and u (dislocation line) should be righthand orthogonal. Default value is [1, 0, 0] (xaxis).
n (arraylike object, optional) – The n unit vector for the solution. m, n, and u (dislocation line) should be righthand orthogonal. Default value is [0, 1, 0] (yaxis).
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 nearzero values. Default value is 1e8.

atomman.defect.
disregistry
(basesystem, dislsystem, m=[1.0, 0.0, 0.0], n=[0.0, 1.0, 0.0], planepos=[0.0, 0.0, 0.0]) 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 dislocationcontaining system.
m (arraylike 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 xaxis).
n (arraylike 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 yaxis).
planepos (arraylike 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 coordcoordinates (atomic columns) neighboring the slip plane.
disregistry (numpy.ndarray) – A (N, 3) array of the dislocation’s disregistry at each coord.

atomman.defect.
dumbbell
(system, pos=None, ptd_id=None, db_vect=None, scale=False, atol=None, **kwargs) 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 peratom 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 peratom 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 (arraylike 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 (arraylike object) – Vector shift to apply to the atoms in the dumbbell.
scale (bool, optional) – Indicates if pos and db_vect are Cartesian (False) or boxrelative (True). Default value is False.
atol (float, optional) – Absolute tolerance for positionbased searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to peratom 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.defect.
free_surface_basis
(hkl, box=None, cutboxvector='c', maxindex=None, return_hexagonal=None, return_planenormal=False, conventional_setting=None) 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 inplane vector determination algorithm by W. Sun and G. Cedar, Surface Science, 617, 5359 (2013) to identify two inplane vectors and the plane normal. The shortest inplane vector is identified, as well as an outofplane vector close to the plane normal. The second inplane vector is then selected to be a shortest inplane vector that is not parallel to the first.
 Parameters
hkl (arraylike object) – The free surface plane to generate expressed in either 3 indices Miller (hkl) format or 4 indices MillerBravais (hkil) format.
box (atomman.Box, optional) – The box object associated with the unit cell. Used to identify the best uvw set for the outofplane box vector. Default value uses a cubic box.
cutboxvector (str, optional) – Specifies which of the three box vectors corresponds to the outofplane vector. Default value is c.
maxindex (int, optional) – Max uvw index value to use in identifying the best uvw set for the outofplane vector. If not given, will use the largest absolute index between the given hkl and the initial inplane vector guesses.
return_hexagonal (bool, optional) – Flag for indicating if the returned vectors are expressed in Miller [uvw] format (False) or MillerBravais [uvtw] format (True). The MillerBravais 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 MillerBravais (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 facecentered, ‘i’ for bodycentered, and ‘a’, ‘b’, or ‘c’ for sidecentered. 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 MillerBravais [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.

atomman.defect.
interstitial
(system, pos, scale=False, atol=None, **kwargs) Generates a new system by adding an interstitial point defect. 1. Adds a new atom to the end of the Atoms list. 2. Adds peratom 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 peratom 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 (arraylike object) – Position of the atom being added.
scale (bool, optional) – Indicates if pos is Cartesian (False) or boxrelative (True). Default value is False.
atol (float, optional) – Absolute tolerance for positionbased searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to peratom 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.defect.
nye_tensor
(system, p_vectors, theta_max=27, axes=None, neighbors=None, cutoff=None) Computes strain properties and Nye tensor for a defect containing system.
 Parameters
system (atomman.System) – The atomic system to compute the peratom strain properties and Nye tensor for.
p_vectors (arraylike 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 (arraylike object, optional) – 3x3 array of righthanded 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 peratom properties ‘strain’, ‘strain_invariant_1’, ‘strain_invariant_2’, ‘angular_velocity’, and ‘Nye_tensor’.
 Return type

atomman.defect.
nye_tensor_p
(system, neighbors=None, cutoff=None) 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 defectfree 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

atomman.defect.
pn_arctan_disregistry
(xmax=None, xstep=None, xnum=None, burgers=None, center=0.0, halfwidth=1, normalize=True, shift=True) Computes the classic PeierlsNabarro arctan disregistry for an array of points x.
δ(x) = b / π * arctan(x / ξ) + b / 2
 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 (numpy.ndarray, optional) – The Burgers vector 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 xcoordinates for the disregistry values.
disregistry (numpy.ndarray) – The disregistry vector at each xcoordinate.

atomman.defect.
point
(system, ptd_type='v', pos=None, ptd_id=None, db_vect=None, scale=False, atol=None, **kwargs) 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 (arraylike 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 (arraylike object, optional) – Vector associated with the dumbbell interstitial (‘db’ style).
scale (bool, optional) – Indicates if pos and db_vect are Cartesian (False) or boxrelative (True). Default value is False.
atol (float, optional) – Absolute tolerance for positionbased searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to peratom 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.defect.
slip_vector
() 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

atomman.defect.
solve_volterra_dislocation
(C, burgers, ξ_uvw=None, slip_hkl=None, transform=None, axes=None, box=None, m=[1, 0, 0], n=[0, 1, 0], tol=1e08) 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 (arraylike object) – The dislocation’s Burgers vector.
ξ_uvw (arraylike 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 (arraylike object) – The Miller plane indices associated with the dislocation’s slip plane. Must be given with slip_hkl to identify the transformation matrix to use on C and burgers.
transform (arraylike 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 (arraylike 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 (arraylike object, optional) – The m unit vector for the solution. m, n, and u (dislocation line) should be righthand orthogonal. Default value is [1,0,0] (xaxis).
n (arraylike object, optional) – The n unit vector for the solution. m, n, and u (dislocation line) should be righthand orthogonal. Default value is [0,1,0] (yaxis). n is normal to the dislocation slip plane.
tol (float) – Tolerance parameter used to round off nearzero values. Default value is 1e8.
Returns –
atomman.defect.VolterraDislocation – The dislocation solution of the appropriate type.

atomman.defect.
substitutional
(system, pos=None, ptd_id=None, atype=1, scale=False, atol=None, **kwargs) 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 peratom 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 peratom 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 (arraylike 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 boxrelative (True). Default value is False.
atol (float, optional) – Absolute tolerance for positionbased searching. Default value is 0.01 angstroms.
**kwargs (any, optional) – Keyword arguments corresponding to peratom 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.defect.
vacancy
(system, pos=None, ptd_id=None, scale=False, atol=None) Generates a new system by adding a vacancy point defect. 1. Removes the indicated atom from the system 2. Adds peratom 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 (arraylike 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 boxrelative (True). Default value is False.
atol (float, optional) – Absolute tolerance for positionbased searching. Default value is 0.01 angstroms.
 Returns
A new system with the vacancy added.
 Return type