matscipy.dislocation

Tools for studying structure and movement of dislocations.

Functions

`check_duplicates`(atoms[, distance])	Returns a mask of atoms that have at least one other atom closer than distance
`compare_configurations`(dislo, bulk, ...[, ...])	Compares two dislocation configurations based on the gradient of
`cost_function`(pos, dislo, bulk, cylinder_r, ...)	Cost function for fitting analytical displacement field
`dipole_displacement_angle`(W_bulk, ...[, ...])	Generates a simple displacement field for two dislocations in a dipole configuration uding simple Voltera solution as u = b/2 * angle
`fit_core_position`(dislo_image, bulk, ...[, ...])	Use cost_function() to fit atomic positions to Stroh solution with
`fit_core_position_images`(images, bulk, ...)	Call fit_core_position() for a list of Atoms objects, e.g. NEB images.
`gamma_line`(unit_cell[, calc, shift_dir, ...])	This function performs a calculation of a cross-sections in 'shift_dir` of the generalized stacking fault (GSF) gamma surface with surface orientation.
`get_centering_mask`(atoms, radius[, ...])
`get_elastic_constants`([pot_path, ...])	return lattice parameter, and cubic elastic constants: C11, C12, 44 using matscipy function pot_path - path to the potential
`get_u_img`(W_bulk, dislo_coord_left, ...[, ...])	Function for getting displacemnt filed for images of quadrupole cells used by make_screw_quadrupole
`make_barrier_configurations`([elastic_param, ...])	Creates the initial and final configurations for the NEB calculation
`make_edge_cyl`(alat, C11, C12, C44[, ...])	makes edge dislocation using atomman library
`make_edge_cyl_001_100`(a0, C11, C12, C44, ...)	Function to produce consistent edge dislocation configuration.
`make_screw_cyl`(alat, C11, C12, C44[, ...])	Makes screw dislocation using atomman library
`make_screw_cyl_kink`(alat, C11, C12, C44[, ...])	Function to create kink configuration based on make_screw_cyl() function.
`make_screw_quadrupole`(alat[, left_shift, ...])	Generates a screw dislocation dipole configuration
`make_screw_quadrupole_kink`(alat[, kind, ...])	Generates kink configuration using make_screw_quadrupole() function
`ovito_dxa_straight_dislo_info`(disloc[, ...])	A function to extract information from ovito dxa analysis.
`plot_bulk`(atoms[, n_planes, ax, ms])	Plots x, y coordinates of atoms colored according to non-equivalent planes in z plane
`plot_vitek`(dislo, bulk[, alat, plot_axes, ...])	Plots vitek map from ase configurations.
`read_dislo_QMMM`([filename, image])	Reads extended xyz file with QMMM configuration Uses "region" for mapping of QM, MM and fixed atoms Sets ase.constraints.FixAtoms constraint on fixed atoms
`screw_cyl_octahedral`(alat, C11, C12, C44[, ...])	Generates a set of octahedral positions with scan_r radius.
`screw_cyl_tetrahedral`(alat, C11, C12, C44[, ...])	Generates a set of tetrahedral positions with scan_r radius.
`show_NEB_configurations`(images, bulk[, ...])	Plots Vitek differential displacement maps for the list of images for example along the NEB path.
`show_configuration`(disloc, bulk, u[, fixed_mask])	shows the displacement fixed atoms.
`slice_long_dislo`(kink, kink_bulk, b)	Function to slice a long dislocation configuration to perform

Classes

`AnisotropicDislocation`(axes, slip_plane, ...)	Displacement and displacement gradient field of straight dislocation in anisotropic elastic media.
`BCCEdge100110Dislocation`(a[, C11, C12, C44, ...])
`BCCEdge100Dislocation`(a[, C11, C12, C44, C, ...])
`BCCEdge111Dislocation`(a[, C11, C12, C44, C, ...])
`BCCEdge111barDislocation`(a[, C11, C12, C44, ...])
`BCCMixed111Dislocation`(a[, C11, C12, C44, ...])
`BCCScrew111Dislocation`(a[, C11, C12, C44, ...])
`BodyCenteredCubicOctahedralFactory`()	A factory for creating octahedral lattices in bcc structure
`BodyCenteredCubicTetrahedralFactory`()	A factory for creating tetrahedral lattices in bcc structure
`CubicCrystalDislocation`(a[, C11, C12, C44, ...])	Abstract base class for modelling a single dislocation
`CubicCrystalDislocationQuadrupole`(...)
`CubicCrystalDissociatedDislocation`(a[, C11, ...])	Abstract base class for modelling dissociated dislocation systems
`DiamondGlide30degreePartial`(a[, C11, C12, ...])
`DiamondGlide60Degree`(a[, C11, C12, C44, C, ...])
`DiamondGlide90degreePartial`(a[, C11, C12, ...])
`DiamondGlideScrew`(a[, C11, C12, C44, C, symbol])
`FCCEdge110Dislocation`(a[, C11, C12, C44, C, ...])
`FCCEdgeShockleyPartial`(a[, C11, C12, C44, ...])
`FCCScrew110Dislocation`(a[, C11, C12, C44, ...])
`FCCScrewShockleyPartial`(a[, C11, C12, C44, ...])
`FixedLineAtoms`(a, direction)	Constrain atoms to move along a given direction only.
`Quadrupole`	alias of `CubicCrystalDislocationQuadrupole`

matscipy.dislocation.make_screw_cyl(alat, C11, C12, C44, cylinder_r=10, cutoff=5.5, hard_core=False, center=[0.0, 0.0, 0.0], l_extend=[0.0, 0.0, 0.0], symbol='W')

Makes screw dislocation using atomman library

Parameters:

alat (float) – Lattice constant of the material.
C11 (float) – C11 elastic constant of the material.
C12 (float) – C12 elastic constant of the material.
C44 (float) – C44 elastic constant of the material.
cylinder_r (float) – radius of cylinder of unconstrained atoms around the dislocation in angstrom
cutoff (float) – Potential cutoff for Marinica potentials for FS cutoff = 4.4
hard_core (bool) – Description of parameter hard_core.
center (type) –

The position of the dislocation core and the center of the
cylinder with FixAtoms condition
l_extend (float) – extension of the box. used for creation of initial dislocation position with box equivalent to the final position
symbol (string) – Symbol of the element to pass to ase.lattice.cubic.SimpleCubicFactory default is “W” for tungsten

Returns:

disloc (ase.Atoms object) – screw dislocation cylinder.
bulk (ase.Atoms object) – bulk disk used to generate dislocation
u (np.array) – displacement per atom.

matscipy.dislocation.make_edge_cyl(alat, C11, C12, C44, cylinder_r=10, cutoff=5.5, symbol='W')

makes edge dislocation using atomman library

cylinder_r - radius of cylinder of unconstrained atoms around the: dislocation in angstrom

cutoff - potential cutoff for Marinica potentials for FS cutoff = 4.4

symbolstring: Symbol of the element to pass to ase.lattice.cubic.SimpleCubicFactory default is “W” for tungsten

matscipy.dislocation.plot_vitek(dislo, bulk, alat=3.16, plot_axes=None, xyscale=10)

Plots vitek map from ase configurations.

Parameters:

dislo (ase.Atoms) – Dislocation configuration.
bulk (ase.Atoms) – Corresponding bulk configuration for calculation of displacements.
alat (float) – Lattice parameter for calculation of neighbour list cutoff.
plot_axes (matplotlib.Axes.axes object) – Existing axes to plot on, allows to pass existing matplotlib axes have full control of the graph outside the function. Makes possible to plot multiple differential displacement maps using subplots. Default is None, then new graph is created by plt.subplots() Description of parameter plot_axes.
xyscale (float) – xyscale of the graph

Return type:

None

matscipy.dislocation.show_NEB_configurations(images, bulk, xyscale=7, show=True, core_positions=None)

Plots Vitek differential displacement maps for the list of images for example along the NEB path.

Parameters:

images (list of ase.Atoms) – List of configurations with dislocations.
bulk (ase.Atoms) – Corresponding bulk configuration for calculation of displacements.
xyscale (float) – xyscale of the graph
show (bool) – Show the figure after plotting. Default is True.
core_positions (list) – [x, y] position of dislocation core to plot

Returns:

If the show is False else returns None

Return type:

figure

matscipy.dislocation.show_configuration(disloc, bulk, u, fixed_mask=None): shows the displacement fixed atoms.

matscipy.dislocation.get_elastic_constants(pot_path=None, calculator=None, delta=0.01, symbol='W', verbose=True, fmax=0.0001, smax=0.001)

return lattice parameter, and cubic elastic constants: C11, C12, 44 using matscipy function pot_path - path to the potential

symbolstring: Symbol of the element to pass to ase.lattice.cubic.SimpleCubicFactory default is “W” for tungsten

matscipy.dislocation.make_barrier_configurations(elastic_param=None, pot_path=None, calculator=None, cylinder_r=10, hard_core=False, **kwargs)

Creates the initial and final configurations for the NEB calculation: The positions in FixedAtoms constrained region are average between final and initial configurations

Parameters:

pot_path (string) – Path to the potential file.
calculator (type) – Description of parameter calculator.
cylinder_r (float) –

Radius of cylinder of unconstrained atoms around the
dislocation in angstrom.
hard_core (bool) – Type of the core hard or soft. If hard is chosen the displacement field is reversed.
**kwargs – Keyword arguments to pass to make_screw_cyl() function.

Returns:

disloc_ini (ase.Atoms) – Initial dislocation configuration.
disloc_fin (ase.Atoms) – Final dislocation configuration.
bulk (ase.Atoms) – Perfect bulk configuration for Vitek displacement maps

matscipy.dislocation.make_screw_cyl_kink(alat, C11, C12, C44, cylinder_r=40, kink_length=26, kind='double', **kwargs)

Function to create kink configuration based on make_screw_cyl() function. Double kink configuration is in agreement with quadrupoles in terms of formation energy. Single kink configurations provide correct and stable structure, but formation energy is not accessible?

Parameters:

alat (float) – Lattice constant of the material.
C11 (float) – C11 elastic constant of the material.
C12 (float) – C12 elastic constant of the material.
C44 (float) – C44 elastic constant of the material.
cylinder_r (float) – radius of cylinder of unconstrained atoms around the dislocation in angstrom
kink_length (int) – Length of the cell per kink along b in unit of b, must be even.
kind (string) – kind of the kink: right, left or double
**kwargs – Keyword arguments to pass to make_screw_cyl() function.

Returns:

kink (ase.atoms) – kink configuration
reference_straight_disloc (ase.atoms) – reference straight dislocation configuration
large_bulk (ase.atoms) – large bulk cell corresponding to the kink configuration

matscipy.dislocation.slice_long_dislo(kink, kink_bulk, b)

Function to slice a long dislocation configuration to perform: dislocation structure and core position analysis

Parameters:

kink (ase.Atoms) – kink configuration to slice
kink_bulk (ase.Atoms) – corresponding bulk configuration to perform mapping for slicing
b (float) – burgers vector b should be along z direction

Returns:

sliced_kink (list of [sliced_bulk, sliced_kink]) – sliced configurations 1 b length each
disloc_z_positions (float) – positions of each sliced configuration (center along z)

matscipy.dislocation.compare_configurations(dislo, bulk, dislo_ref, bulk_ref, alat, cylinder_r=None, print_info=True, remap=True, bulk_neighbours=None, origin=(0.0, 0.0))

Compares two dislocation configurations based on the gradient of: the displacements along the bonds.

Parameters:

dislo (ase.Atoms) – Dislocation configuration.
bulk (ase.Atoms) – Corresponding bulk configuration for calculation of displacements.
dislo_ref (ase.Atoms) – Reference dislocation configuration.
bulk_ref (ase.Atoms) – Corresponding reference bulk configuration for calculation of displacements.
alat (float) – Lattice parameter for calculation of neghbour list cutoff.
cylinder_r (float or None) – Radius of region of comparison around the dislocation coreself. If None makes global comparison based on the radius of dislo configuration, else compares the regions with cylinder_r around the dislocation core position.
print_info (bool) – Flag to switch print statement about the type of the comparison
remap (bool) – Flag to swtich off remapping of atoms between deformed and reference configurations. Only set this to true if atom order is the same!
bulk_neighbours – Optionally pass in bulk neighbours as a tuple (bulk_i, bulk_j)
origin (tuple) – Optionally pass in coordinate origin (x0, y0)

Returns:

The Du norm of the differences per atom.

Return type:

float

matscipy.dislocation.cost_function(pos, dislo, bulk, cylinder_r, elastic_param, hard_core=False, print_info=True, remap=True, bulk_neighbours=None, origin=(0, 0))

Cost function for fitting analytical displacement field: and detecting dislocation core position. Uses compare_configurations function for the minimisation of the core position.

Parameters:

pos (list of float) – Positions of the core to build the analytical solution [x, y].
dislo (ase.Atoms) – Dislocation configuration.
bulk (ase.Atoms) – Corresponding bulk configuration for calculation of displacements.
cylinder_r (float or None) – Radius of region of comparison around the dislocation coreself. If None makes global comparison based on the radius of dislo configuration, else compares the regions with cylinder_r around the dislocation core position.
elastic_param (list of float) – List containing alat, C11, C12, C44
hard_core (bool) – type of the core True for hard
print_info (bool) – Flag to switch print statement about the type of the comparison
bulk_neighbours (tuple or None) – Optionally pass in neighbour list for bulk reference config to save computing it each time.
origin (tuple) – Optionally pass in coordinate origin (x0, y0)

Returns:

Error for optimisation (result from compare_configurations function)

Return type:

float

matscipy.dislocation.fit_core_position(dislo_image, bulk, elastic_param, hard_core=False, core_radius=10, current_pos=None, bulk_neighbours=None, origin=(0, 0), return_error=False)

Use cost_function() to fit atomic positions to Stroh solution with

scipy.optimize.minimize is used to perform the fit using Powell’s method.

Parameters:

dislo_image (ase.atoms.Atoms)
bulk (ase.atoms.Atoms)
elastic_param (array-like) – [alat, C11, C12, C44]
hard_core (bool)
core_radius (float)
current_pos (array-like) – array [core_x, core_y] containing initial guess for core position
bulk_neighbours (tuple) – cache of bulk neigbbours to speed up calcualtion. Should be a tuple (bulk_I, bulk_J) as returned by matscipy.neigbbours.neighbour_list(‘ij’, bulk, alat).
origin (tuple) – Optionally pass in coordinate origin (x0, y0)
return_error (bool) – Optionally return the scipy.optimize.minimize error of the fit. Requires an additional cost_function() call.

Return type:

core_pos - array [core_x, core_y]

matscipy.dislocation.fit_core_position_images(images, bulk, elastic_param, bulk_neighbours=None, origin=(0, 0), return_errors=False)

Call fit_core_position() for a list of Atoms objects, e.g. NEB images

Parameters:

images (list) – list of Atoms object for dislocation configurations
bulk (ase.atoms.Atoms) – bulk reference configuration
elastic_param (list) – as for fit_core_position().
bulk_neighbours – as for fit_core_position().
origin (tuple) – Optionally pass in coordinate origin (x0, y0)
return_errors (bool) – Optionally return the scipy.optimize.minimize list of errors of the fit.

Returns:

core_positions

Return type:

array of shape (len(images), 2)

matscipy.dislocation.screw_cyl_tetrahedral(alat, C11, C12, C44, scan_r=15, symbol='W', imp_symbol='H', hard_core=False, center=(0.0, 0.0, 0.0))

Generates a set of tetrahedral positions with scan_r radius.: Applies the screw dislocation displacement for creating an initial guess for the H positions at dislocation core.

Parameters:

alat (float) – Lattice constant of the material.
C11 (float) – C11 elastic constant of the material.
C12 (float) – C12 elastic constant of the material.
C44 (float) – C44 elastic constant of the material.
scan_r (float) – Radius of the region to create tetrahedral positions.
symbol (string) – Symbol of the element to pass to ase.lattuce.cubic.SimpleCubicFactory default is “W” for tungsten
imp_symbol (string) – Symbol of the elemnt to pass creat Atoms object default is “H” for hydrogen
hard_core (float) – Type of the dislocatino core if True then -u (sign of displacement is flipped) is applied. Default is False i.e. soft core is created.

centertuple of floats: Coordinates of dislocation core (center) (x, y, z). Default is (0., 0., 0.)

Returns:: Atoms object with predicted tetrahedral positions around dislocation core.
Return type:: ase.Atoms object

matscipy.dislocation.screw_cyl_octahedral(alat, C11, C12, C44, scan_r=15, symbol='W', imp_symbol='H', hard_core=False, center=(0.0, 0.0, 0.0))

Generates a set of octahedral positions with scan_r radius.: Applies the screw dislocation displacement for creating an initial guess for the H positions at dislocation core.

Parameters:

alat (float) – Lattice constant of the material.
C11 (float) – C11 elastic constant of the material.
C12 (float) – C12 elastic constant of the material.
C44 (float) – C44 elastic constant of the material.
symbol (string) – Symbol of the element to pass to ase.lattuce.cubic.SimpleCubicFactory default is “W” for tungsten
imp_symbol (string) – Symbol of the elemnt to pass creat Atoms object default is “H” for hydrogen
symbol – Symbol of the elemnt to pass creat Atoms object
hard_core (float) – Type of the dislocatino core if True then -u (sign of displacement is flipped) is applied. Default is False i.e. soft core is created.
center (tuple of floats) – Coordinates of dislocation core (center) (x, y, z). Default is (0., 0., 0.)

Returns:

Atoms object with predicted tetrahedral positions around dislocation core.

Return type:

ase.Atoms object

class matscipy.dislocation.BodyCenteredCubicTetrahedralFactory

Bases: SimpleCubicFactory

A factory for creating tetrahedral lattices in bcc structure

Attributes:

element_basis

Methods

`__call__`(symbol[, directions, miller, size, ...])	Create a lattice.
`align`()	Align the first axis along x-axis and the second in the x-y plane.
`check_basis_volume`()	Check the volume of the unit cell.
`convert_to_natural_basis`()	Convert directions and miller indices to the natural basis.
`find_directions`(directions, miller)	Find missing directions and miller indices from the specified ones.
`find_ortho`(idx)	Replace keyword 'ortho' or 'orthogonal' with a direction.
`get_lattice_constant`()	Get the lattice constant of an element with cubic crystal structure.
`inside`(point)	Is a point inside the unit cell?
`make_crystal_basis`()	Make the basis matrix for the crystal unit cell and the system unit cell.
`make_list_of_atoms`()	Repeat the unit cell.
`make_unit_cell`()	Make the unit cell.
`print_directions_and_miller`([txt])	Print direction vectors and Miller indices.
`process_element`(element)	Extract atomic number from element
`put_atom`(point)	Place an atom given its integer coordinates.

calc_num_atoms

xtal_name = 'bcc_tetrahedral'

bravais_basis: Sequence[Sequence[float]] | None = [[0.0, 0.5, 0.25], [0.0, 0.5, 0.75], [0.0, 0.25, 0.5], [0.0, 0.75, 0.5], [0.5, 0.0, 0.75], [0.25, 0.0, 0.5], [0.75, 0.0, 0.5], [0.5, 0.0, 0.25], [0.5, 0.25, 0.0], [0.5, 0.75, 0.0], [0.25, 0.5, 0.0], [0.75, 0.5, 0.0]]

align(): Align the first axis along x-axis and the second in the x-y plane.

atoms_in_unit_cell = 1

basis_factor = 1.0

calc_num_atoms()

check_basis_volume(): Check the volume of the unit cell.

chop_tolerance = 1e-10

convert_to_natural_basis(): Convert directions and miller indices to the natural basis.

element_basis: Sequence[int] | None = None

find_directions(directions, miller): Find missing directions and miller indices from the specified ones.

find_ortho(idx): Replace keyword ‘ortho’ or ‘orthogonal’ with a direction.

get_lattice_constant(): Get the lattice constant of an element with cubic crystal structure.

inside(point): Is a point inside the unit cell?

int_basis = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

inverse_basis = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

inverse_basis_factor = 1.0

make_crystal_basis(): Make the basis matrix for the crystal unit cell and the system unit cell.

make_list_of_atoms(): Repeat the unit cell.

make_unit_cell(): Make the unit cell.

other = {0: (1, 2), 1: (2, 0), 2: (0, 1)}

print_directions_and_miller(txt=''): Print direction vectors and Miller indices.

process_element(element): Extract atomic number from element

put_atom(point): Place an atom given its integer coordinates.

class matscipy.dislocation.BodyCenteredCubicOctahedralFactory

Bases: SimpleCubicFactory

A factory for creating octahedral lattices in bcc structure

Attributes:

element_basis

Methods

`__call__`(symbol[, directions, miller, size, ...])	Create a lattice.
`align`()	Align the first axis along x-axis and the second in the x-y plane.
`check_basis_volume`()	Check the volume of the unit cell.
`convert_to_natural_basis`()	Convert directions and miller indices to the natural basis.
`find_directions`(directions, miller)	Find missing directions and miller indices from the specified ones.
`find_ortho`(idx)	Replace keyword 'ortho' or 'orthogonal' with a direction.
`get_lattice_constant`()	Get the lattice constant of an element with cubic crystal structure.
`inside`(point)	Is a point inside the unit cell?
`make_crystal_basis`()	Make the basis matrix for the crystal unit cell and the system unit cell.
`make_list_of_atoms`()	Repeat the unit cell.
`make_unit_cell`()	Make the unit cell.
`print_directions_and_miller`([txt])	Print direction vectors and Miller indices.
`process_element`(element)	Extract atomic number from element
`put_atom`(point)	Place an atom given its integer coordinates.

calc_num_atoms

xtal_name = 'bcc_octahedral'

bravais_basis: Sequence[Sequence[float]] | None = [[0.5, 0.5, 0.0], [0.0, 0.0, 0.5], [0.5, 0.0, 0.0], [0.5, 0.0, 0.5], [0.0, 0.5, 0.0], [0.0, 0.5, 0.5]]

align(): Align the first axis along x-axis and the second in the x-y plane.

atoms_in_unit_cell = 1

basis_factor = 1.0

calc_num_atoms()

check_basis_volume(): Check the volume of the unit cell.

chop_tolerance = 1e-10

convert_to_natural_basis(): Convert directions and miller indices to the natural basis.

element_basis: Sequence[int] | None = None

find_directions(directions, miller): Find missing directions and miller indices from the specified ones.

find_ortho(idx): Replace keyword ‘ortho’ or ‘orthogonal’ with a direction.

get_lattice_constant(): Get the lattice constant of an element with cubic crystal structure.

inside(point): Is a point inside the unit cell?

int_basis = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

inverse_basis = array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

inverse_basis_factor = 1.0

make_crystal_basis(): Make the basis matrix for the crystal unit cell and the system unit cell.

make_list_of_atoms(): Repeat the unit cell.

make_unit_cell(): Make the unit cell.

other = {0: (1, 2), 1: (2, 0), 2: (0, 1)}

print_directions_and_miller(txt=''): Print direction vectors and Miller indices.

process_element(element): Extract atomic number from element

put_atom(point): Place an atom given its integer coordinates.

matscipy.dislocation.dipole_displacement_angle(W_bulk, dislo_coord_left, dislo_coord_right, shift=0.0, mode=1.0): Generates a simple displacement field for two dislocations in a dipole configuration uding simple Voltera solution as u = b/2 * angle

matscipy.dislocation.get_u_img(W_bulk, dislo_coord_left, dislo_coord_right, n_img=10, n1_shift=0, n2_shift=0): Function for getting displacemnt filed for images of quadrupole cells used by make_screw_quadrupole

matscipy.dislocation.make_screw_quadrupole(alat, left_shift=0, right_shift=0, n1u=5, symbol='W')

Generates a screw dislocation dipole configuration: for effective quadrupole arrangement. Works for BCC systems.

Parameters:

alat (float) – Lattice parameter of the system in Angstrom.
left_shift (float, optional) – Shift of the left dislocation core in number of dsitances to next equivalent disocation core positions needed for creation for final configuration for NEB. Default is 0.
right_shift (float, optional) – shift of the right dislocation core in number of dsitances to next equivalent disocation core positions needed for creation for final configuration for NEB. Default is 0.
n1u (int, odd number) – odd number! length of the cell a doubled distance between core along x. Main parameter to calculate cell vectors
symbol (string) – Symbol of the element to pass to ase.lattuce.cubic.SimpleCubicFactory default is “W” for tungsten

Returns:

disloc_quadrupole (ase.Atoms) – Resulting quadrupole configuration.
W_bulk (ase.Atoms) – Perfect system.
dislo_coord_left (list of float) – Coodrinates of left dislocation core [x, y]
dislo_coord_right (list of float) – Coodrinates of right dislocation core [x, y]

Notes

Calculation of cell vectors

From [1] we take:

Unit vectors for the cell are:

\[u = \frac{1}{3}[1 \bar{2} 1];\]

\[v = \frac{1}{3}[2 \bar{1} \bar{1}];\]

\[z = b = \frac{1}{2}[1 1 1];\]

Cell vectors are:

\[C_1 = n^u_1 u + n^v_1 v + C^z_1 z;\]

\[C_2 = n^u_2 u + n^v_2 v + C^z_2 z;\]

\[C_3 = z\]

For quadrupole arrangement n1u needs to be odd number, for 135 atoms cell we take n1u=5
To have quadrupole as as close as possible to a square one has to take:

\[2 n^u_2 + n^v_2 = n^u_1\]

\[n^v_2 \approx \frac{n^u_1}{\sqrt{3}}\]

for n1u = 5:

\[n^v_2 \approx \frac{n^u_1}{\sqrt{3}} = 2.89 \approx 3.0\]

\[n^u_2 = \frac{1}{2} (n^u_1 - n^v_2) \approx \frac{1}{2} (5-3)=1\]

Following [2] cell geometry is optimized by ading tilt compomemts

Cz1 and Cz2 for our case of n1u = 3n - 1:

Easy core

\[C^z_1 = + \frac{1}{3}\]

\[C^z_2 = + \frac{1}{6}\]

Hard core

\[C^z_1 = + \frac{1}{3}\]

\[C^z_2 = + \frac{1}{6}\]

may be typo in the paper check the original!

References:

[1]

Ventelon, L. & Willaime, F. J ‘Core structure and Peierls potential of screw dislocations in alpha-Fe from first principles: cluster versus dipole approaches’ Computer-Aided Mater Des (2007) 14(Suppl 1): 85. https://doi.org/10.1007/s10820-007-9064-y

[2]

Cai W. (2005) Modeling Dislocations Using a Periodic Cell. In: Yip S. (eds) Handbook of Materials Modeling. Springer, Dordrecht https://link.springer.com/chapter/10.1007/978-1-4020-3286-8_42

matscipy.dislocation.make_screw_quadrupole_kink(alat, kind='double', n1u=5, kink_length=20, symbol='W')

Generates kink configuration using make_screw_quadrupole() function: works for BCC structure. The method is based on paper https://doi.org/10.1016/j.jnucmat.2008.12.053

Parameters:

alat (float) – Lattice parameter of the system in Angstrom.
kind (string) – kind of the kink: right, left or double
n1u (int) – Number of lattice vectors for the quadrupole cell (make_screw_quadrupole() function)
kink_length (int) – Length of the cell per kink along b in unit of b, must be even.
symbol (string) – Symbol of the element to pass to ase.lattuce.cubic.SimpleCubicFactory default is “W” for tungsten

Returns:

kink (ase.atoms) – kink configuration
reference_straight_disloc (ase.atoms) – reference straight dislocation configuration
large_bulk (ase.atoms) – large bulk cell corresponding to the kink configuration

matscipy.dislocation.make_edge_cyl_001_100(a0, C11, C12, C44, cylinder_r, cutoff=5.5, tol=1e-06, symbol='W')

Function to produce consistent edge dislocation configuration.

Parameters:

alat (float) – Lattice constant of the material.
C11 (float) – C11 elastic constant of the material.
C12 (float) – C12 elastic constant of the material.
C44 (float) – C44 elastic constant of the material.
cylinder_r (float) – Radius of cylinder of unconstrained atoms around the dislocation in angstrom.
cutoff (float) – Potential cutoff for determenition of size of fixed atoms region (2*cutoff)
tol (float) – Tolerance for generation of self consistent solution.
symbol (string) – Symbol of the element to pass to ase.lattuce.cubic.SimpleCubicFactory default is “W” for tungsten

Returns:

bulk (ase.Atoms object) – Bulk configuration.
disloc (ase.Atoms object) – Dislocation configuration.
disp (np.array) – Corresponding displacement.

matscipy.dislocation.read_dislo_QMMM(filename=None, image=None)

Reads extended xyz file with QMMM configuration Uses “region” for mapping of QM, MM and fixed atoms Sets ase.constraints.FixAtoms constraint on fixed atoms

Parameters:

filename (path to xyz file)
image (image with "region" array to set up constraint and extract qm_mask)

Returns:

dislo_QMMM (Output ase.Atoms object) – Includes “region” array and FixAtoms constraint
qm_mask (array mask for QM atoms mapping)

matscipy.dislocation.plot_bulk(atoms, n_planes=3, ax=None, ms=200): Plots x, y coordinates of atoms colored according to non-equivalent planes in z plane

matscipy.dislocation.ovito_dxa_straight_dislo_info(disloc, structure='BCC', replicate_z=3)

A function to extract information from ovito dxa analysis. Current version works for 1b thick configurations containing straight dislocations.

Parameters:

disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
replicate_z (int) – Specifies number of times to replicate the configuration along the dislocation line. Ovito dxa analysis needs at least 3b thick cell to work.

Returns:

Results

Return type:

np.array(position, b, line, angle)

matscipy.dislocation.get_centering_mask(atoms, radius, core_position=[0.0, 0.0, 0.0], extension=[0.0, 0.0, 0.0])

matscipy.dislocation.check_duplicates(atoms, distance=0.1): Returns a mask of atoms that have at least one other atom closer than distance

class matscipy.dislocation.AnisotropicDislocation(axes, slip_plane, disloc_line, burgers, C11=None, C12=None, C44=None, C=None)

Bases: object

Displacement and displacement gradient field of straight dislocation in anisotropic elastic media. Ref: pp. 467 in J.P. Hirth and J. Lothe, Theory of Dislocations, 2nd ed. Similar to class CubicCrystalDislocation.

Methods

`deformation_gradient`(bulk_positions[, ...])	3D displacement gradient tensor of the dislocation.
`displacement`(bulk_positions[, center])	Displacement field of a straight dislocation.

__init__(axes, slip_plane, disloc_line, burgers, C11=None, C12=None, C44=None, C=None): Setup a dislocation in a cubic crystal. C11, C12 and C44 are the elastic constants in the Cartesian geometry. The arg ‘axes’ is a 3x3 array containing axes of frame of reference (eg.crack system). The dislocation parameters required are the slip plane normal (‘slip_plane’), the dislocation line direction (‘disloc_line’) and the Burgers vector (‘burgers’).

displacement(bulk_positions, center=array([0., 0., 0.]))

Displacement field of a straight dislocation. Currently only for 2D, can be extended. :param bulk_positions: Positions of atoms in the bulk cell (with axes == self.axes) :type bulk_positions: array :param center: Position of the dislocation core within the cell :type center: 3x1 array

Returns:: disp – Stroh displacements along the crack running direction (axes[0]) and crack plane normal (axes[1]).
Return type:: array

deformation_gradient(bulk_positions, center=array([0., 0., 0.]), return_2D=False)

3D displacement gradient tensor of the dislocation.

Parameters:

bulk_positions (array) – Positions of atoms in the bulk cell (with axes == self.axes)
center (3x1 array) – Position of the dislocation core within the cell

Returns:

du_dx, du_dy, du/dz, dv_dx, dv_dy, dv/dz, dw/dx, dw/dy, dw/dz – Displacement gradients: dx, dy, dz: changes in dislocation core position along the three axes of self.axes du, dv, dw: changes in displacements of atoms along the three axes of self.axes, in response to changes in dislocation core position

Return type:

1D arrays

class matscipy.dislocation.CubicCrystalDislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: object

Abstract base class for modelling a single dislocation

Attributes:

ADstroh
C
N_cores
alat
axes
burgers
burgers_dimensionless
crystalstructure
glide_distance
glide_distance_dimensionless
name
stroh
unit_cell
unit_cell_core_position
unit_cell_core_position_dimensionless

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

n_planes = 3

self_consistent = True

pbc = [True, True, True]

stroh = None

ADstroh = None

avail_methods = ['atomman', 'adsl']

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

N_cores

burgers_dimensionless

axes

unit_cell_core_position_dimensionless

parity = array([0., 0.])

alat

unit_cell

C

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

property burgers

set_burgers(burgers)

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

property unit_cell_core_position

property glide_distance

plot_unit_cell(ms=250, ax=None)

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

glide_distance_dimensionless

crystalstructure

name

class matscipy.dislocation.CubicCrystalDissociatedDislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Abstract base class for modelling dissociated dislocation systems

Attributes:

ADstroh
C
N_cores
alat
burgers
burgers_dimensionless
glide_distance
left_dislocation
name
new_left_burgers
new_right_burgers
right_dislocation
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, partial_distance, ...])	Overloaded function to make dissociated dislocations.
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

new_left_burgers = None

new_right_burgers = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dissociated dislocation in a cubic crystal with burgers vector b = b_left + b_right.

Parameters:

CubicCrystalDislocation (identical to)

Raises:

ValueError – If resulting burgers vector burgers is not a sum of burgers vectors of left and right dislocations.
ValueError – If one of the properties of left and righ dislocations are not the same.

left_dislocation

right_dislocation

N_cores

crystalstructure()

axes()

unit_cell_core_position_dimensionless()

parity()

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parameters given here refer to a low-level method (ndarray(…)) for instantiating an array.

For more information, refer to the numpy module and examine the methods and attributes of an array.

Parameters:

below) ((for the __new__ method; see Notes)
shape (tuple of ints) – Shape of created array.
dtype (data-type, optional) – Any object that can be interpreted as a numpy data type.
buffer (object exposing buffer interface, optional) – Used to fill the array with data.
offset (int, optional) – Offset of array data in buffer.
strides (tuple of ints, optional) – Strides of data in memory.
order ({'C', 'F'}, optional) – Row-major (C-style) or column-major (Fortran-style) order.

T

Transpose of the array.

Type:: ndarray

data

The array’s elements, in memory.

Type:: buffer

dtype

Describes the format of the elements in the array.

Type:: dtype object

flags

Dictionary containing information related to memory use, e.g., ‘C_CONTIGUOUS’, ‘OWNDATA’, ‘WRITEABLE’, etc.

Type:: dict

flat

Flattened version of the array as an iterator. The iterator allows assignments, e.g., x.flat = 3 (See ndarray.flat for assignment examples; TODO).

Type:: numpy.flatiter object

imag

Imaginary part of the array.

Type:: ndarray

real

Real part of the array.

Type:: ndarray

size

Number of elements in the array.

Type:: int

itemsize

The memory use of each array element in bytes.

Type:: int

nbytes

The total number of bytes required to store the array data, i.e., itemsize * size.

Type:: int

ndim

The array’s number of dimensions.

Type:: int

shape

Shape of the array.

Type:: tuple of ints

strides

The step-size required to move from one element to the next in memory. For example, a contiguous (3, 4) array of type int16 in C-order has strides (8, 2). This implies that to move from element to element in memory requires jumps of 2 bytes. To move from row-to-row, one needs to jump 8 bytes at a time (2 * 4).

Type:: tuple of ints

ctypes

Class containing properties of the array needed for interaction with ctypes.

Type:: ctypes object

base

If the array is a view into another array, that array is its base (unless that array is also a view). The base array is where the array data is actually stored.

Type:: ndarray

See also

array: Construct an array.
zeros: Create an array, each element of which is zero.
empty: Create an array, but leave its allocated memory unchanged (i.e., it contains “garbage”).
dtype: Create a data-type.
numpy.typing.NDArray: An ndarray alias generic w.r.t. its dtype.type <numpy.dtype.type>.

Notes

There are two modes of creating an array using __new__:

If buffer is None, then only shape, dtype, and order are used.
If buffer is an object exposing the buffer interface, then all keywords are interpreted.

No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier ways of constructing an ndarray.

First mode, buffer is None:

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
       [     nan, 2.5e-323]])

Second mode:

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

property n_planes

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

property self_consistent

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property glide_distance_dimensionless

periodic_displacements(positions, v1, v2, core_positions, disp_tol=0.001, max_neighs=15, verbose='periodic', **kwargs)

Calculate the stroh displacements for the periodic structure defined by 2D lattice vectors v1 & v2 given the core positions.

positions: np.array: Atomic positions to calculate displacements at
v1, v2: np.array: Lattice vectors defining periodicity in XY plane (dislocation line is in Z)
core_positions: np.array: positions of the all dislocation cores (including all partial cores)
disp_tol: float: Displacement tolerance controlling the termination of displacement convergence
max_neighs: int: Maximum number of nth-nearest neighbour cells to consider max_neighs=0 is just the current cell, max_neighs=1 also includes nearest-neighbour cells, …
verbose: bool, str or None: Controls verbosity of the displacement solving False, None, or “off” : No printing “periodic” (default) : Prints status of the periodic displacement convergence True : Also prints status of self-consistent solutions for each dislocation

(i.e. verbose=True for CubicCrystalDislocation.displacements())
**kwargs: Other keyword arguments fed to self.displacements() (e.g. method=”adsl”)

Returns:: disps – displacements
Return type:: np.array

build_quadrupole(glide_separation=4, partial_distance=0, extension=0, verbose='periodic', left_offset=None, right_offset=None, **kwargs)

Build periodic quadrupole cell

Parameters:

glide_separation (int) – Number of glide distances separating the two dislocation cores
partial_distance (int or list of int) – Distance between dissociated partial dislocations If a list, specify a partial distance for each dislocation If an int, specify a partial distance for both dislocations
extension (int) – Argument to modify the minimum length of the cell in the glide (x) direction. Cell will always be at least (2 * glide_separation) + partial_distance + extension glide vectors long Useful for setting up images for glide barrier calculations, as start and end structures must be the same size for the NEB method
verbose (bool, str, or None) – Verbosity value to be fed to CubicCrystalDislocationQuadrupole.periodic_displacements
left_offset (np.array) – Translational offset (in Angstrom) for the left and right dislocation cores (i.e. for the +b and -b cores)
right_offset (np.array) – Translational offset (in Angstrom) for the left and right dislocation cores (i.e. for the +b and -b cores)

build_glide_quadrupoles(nims, invert_direction=False, glide_left=True, glide_right=True, left_offset=None, right_offset=None, *args, **kwargs)

Construct a sequence of quadrupole structures providing an initial guess of the dislocation glide trajectory

Parameters:

nims (int) – Number of images to generate
invert_direction (bool) – Invert the direction of the glide invert_direction=False (default) glides in the +x direction invert_direction=True glides in the -x direction
glide_left (bool) – Flags for toggling whether the left/right cores are allowed to glide
glide_right (bool) – Flags for toggling whether the left/right cores are allowed to glide
*args – Fed to self.build_quadrupole()
**kwargs – Fed to self.build_quadrupole()

build_kink_quadrupole_glide_structs(kink_map=None, *args, **kwargs)

Build a reference quadrupole bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_quadrupole

build_kink_quadrupole_from_glide_structs(ref_bulk, glide_structs, kink_map, struct_map, smooth_width=None, layer_decimal_precision=3)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_quadrupole_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_quadrupole_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Use the same kink_map as the call to build_kink_quadrupole_glide_structs
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_quadrupole_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
layer_decimal_precision: float: Tolerance for trying to determine the top atomic layer of the cell (required in order to ensure complete periodicity) Top layer is defined as any atom with z component >= max(atom_z) - 10**(-layer_tol) in fractional coordinates

build_minimal_kink_quadrupole(n_kink=1, layer_decimal_precision=3, smooth_width=None, *args, **kwargs)

Construct a quadrupole structure providing an initial guess of the dislocation kink mechanism. Produces a periodic array of kinks, where each kink is <= self.unit_cell[2, 2] Ang long

Parameters:

n_kink (int) – Number of glide distances to kink out. n_kink=1 for single kink in +x, n_kink=-2 for kink by two glide distances in -x.
layer_decimal_precision (float) – Tolerance for trying to determine the top atomic layer of the cell (required in order to ensure complete periodicity) Top layer is defined as any atom with z component >= max(atom_z) - 10**(-layer_tol) in fractional coordinates
smooth_width (float) – Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args – Fed to self.build_quadrupole()
**kwargs – Fed to self.build_quadrupole()

build_kink_quadrupole(kink_map=None, layer_decimal_precision=3, smooth_width=None, *args, **kwargs)

Construct a quadrupole structure providing an initial guess of the dislocation kink mechanism. Produces a periodic array of kinks, where each kink is z_reps * self.unit_cell[2, 2] Ang long

Parameters:

kink_map (iterable of ints or None) – Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
layer_decimal_precision (float) – Tolerance for trying to determine the top atomic layer of the cell (required in order to ensure complete periodicity) Top layer is defined as any atom with z component >= max(atom_z) - 10**(-layer_tol) in fractional coordinates
smooth_width (float) – Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args – Fed to self.build_quadrupole()
**kwargs – Fed to self.build_quadrupole()

view_quad(system, *args, **kwargs)

Specialised wrapper of view_cyl for showing quadrupoles, as the quadrupole cell causes the plot to be rotated erroneously

Takes the same args and kwargs as view_cyl

ADstroh = None

C

N_cores

property alat

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, partial_distance=0, core_position=array([0., 0., 0.]), extension=array([0., 0., 0.]), fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Overloaded function to make dissociated dislocations. Partial distance is provided as an integer to define number of glide distances between two partials.

Parameters:

radius (float) – radius of the cell
partial_distance (int) – distance between partials (SF length) in number of glide distances. Default is 0 -> non dissociated dislocation with b = b_left + b_right is produced
extension (np.array) – Shape (2, 3) array giving additional extension vectors from each dislocation core. Used to add extra bulk, e.g. to set up glide configurations.
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

new_left_burgers = None

new_right_burgers = None

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

matscipy.dislocation.Quadrupole: alias of CubicCrystalDislocationQuadrupole

class matscipy.dislocation.BCCScrew111Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 3

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.BCCEdge111Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

n_planes = 6

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.BCCEdge111barDislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

n_planes = 1

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.BCCMixed111Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

glide_distance_dimensionless

unit_cell_core_position_dimensionless

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 3

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.BCCEdge100Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

n_planes = 2

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.BCCEdge100110Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

n_planes = 2

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.DiamondGlide30degreePartial(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

glide_distance_dimensionless

unit_cell_core_position_dimensionless

n_planes = 2

self_consistent = False

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.DiamondGlide90degreePartial(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

unit_cell_core_position_dimensionless

burgers_dimensionless

glide_distance_dimensionless

n_planes = 2

self_consistent = False

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.DiamondGlideScrew(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDissociatedDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
new_right_burgers
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, partial_distance, ...])	Overloaded function to make dissociated dislocations.
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
left_dislocation
plot_unit_cell
right_dislocation
set_burgers

burgers_dimensionless = array([ 0.5, -0.5, 0. ])

new_left_burgers = array([ 0.33333333, -0.16666667, -0.16666667])

left_dislocation

right_dislocation

name = '1/2<110> screw'

ADstroh = None

C

N_cores

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dissociated dislocation in a cubic crystal with burgers vector b = b_left + b_right.

Parameters:

CubicCrystalDislocation (identical to)

Raises:

ValueError – If resulting burgers vector burgers is not a sum of burgers vectors of left and right dislocations.
ValueError – If one of the properties of left and righ dislocations are not the same.

property alat

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

axes = array([[ 1, 1, -2], [ 1, 1, 1], [ 1, -1, 0]])

build_cylinder(radius, partial_distance=0, core_position=array([0., 0., 0.]), extension=array([0., 0., 0.]), fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Overloaded function to make dissociated dislocations. Partial distance is provided as an integer to define number of glide distances between two partials.

Parameters:

radius (float) – radius of the cell
partial_distance (int) – distance between partials (SF length) in number of glide distances. Default is 0 -> non dissociated dislocation with b = b_left + b_right is produced
extension (np.array) – Shape (2, 3) array giving additional extension vectors from each dislocation core. Used to add extra bulk, e.g. to set up glide configurations.
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

crystalstructure = 'diamond'

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

glide_distance_dimensionless = 0.6123724356957945

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 2

new_right_burgers = None

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = False

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell

property unit_cell_core_position

unit_cell_core_position_dimensionless = array([0.20412415, 0.50518149, 0. ])

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.DiamondGlide60Degree(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDissociatedDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
new_right_burgers
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, partial_distance, ...])	Overloaded function to make dissociated dislocations.
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
left_dislocation
plot_unit_cell
right_dislocation
set_burgers

burgers_dimensionless = array([ 0.5, 0. , -0.5])

new_left_burgers = array([ 0.33333333, -0.16666667, -0.16666667])

left_dislocation

right_dislocation

name = '1/2<110> 60 degree screw'

ADstroh = None

C

N_cores

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dissociated dislocation in a cubic crystal with burgers vector b = b_left + b_right.

Parameters:

CubicCrystalDislocation (identical to)

Raises:

ValueError – If resulting burgers vector burgers is not a sum of burgers vectors of left and right dislocations.
ValueError – If one of the properties of left and righ dislocations are not the same.

property alat

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

axes = array([[ 1, 1, -2], [ 1, 1, 1], [ 1, -1, 0]])

build_cylinder(radius, partial_distance=0, core_position=array([0., 0., 0.]), extension=array([0., 0., 0.]), fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Overloaded function to make dissociated dislocations. Partial distance is provided as an integer to define number of glide distances between two partials.

Parameters:

radius (float) – radius of the cell
partial_distance (int) – distance between partials (SF length) in number of glide distances. Default is 0 -> non dissociated dislocation with b = b_left + b_right is produced
extension (np.array) – Shape (2, 3) array giving additional extension vectors from each dislocation core. Used to add extra bulk, e.g. to set up glide configurations.
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

crystalstructure = 'diamond'

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

glide_distance_dimensionless = 0.6123724356957945

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 2

new_right_burgers = None

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = False

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell

property unit_cell_core_position

unit_cell_core_position_dimensionless = array([0.20412415, 0.50518149, 0. ])

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.FCCScrewShockleyPartial(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

glide_distance_dimensionless

n_planes = 2

unit_cell_core_position_dimensionless

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.FCCEdgeShockleyPartial(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, core_position, ...])	Build dislocation cylinder for single dislocation system
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
plot_unit_cell
set_burgers

crystalstructure

axes

burgers_dimensionless

unit_cell_core_position_dimensionless

glide_distance_dimensionless

n_planes = 6

name

C

alat

unit_cell

N_cores

ADstroh = None

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dislocation in a cubic crystal

The dislocation is defined by the crystal unit cell, elastic constants, crystal axes, burgers vector and optional shift and parity vectors.

The crystal used as the base for constructing dislocations can be defined by a lattice constant and a chemical symbol. For multi-species systems, an ase Atoms object defining the cubic unit cell can instead be used.

Elastic constants can be defined either through defining C11, C12 and C44, or by passing the full 6x6 elasticity matrix

Parameters:

a (lattice constant OR cubic ase.atoms.Atoms object) – Lattice constant passed to ase.lattice.cubic constructor or Atoms object used by ase.build.cut to get unit cell in correct orientation
C11 (float) – Elastic Constants (in GPa) for cubic symmetry
C12 (float) – Elastic Constants (in GPa) for cubic symmetry
C44 (float) – Elastic Constants (in GPa) for cubic symmetry
C (np.array) – Full 6x6 elasticity matrix (in GPa)
symbol (str) – Chemical symbol used to construct unit cell (if “a” is a lattice constant)

alat

lattice parameter (in A)

Type:: float

unit_cell

bulk cell used to generate dislocations

Type:: ase.atoms.Atoms object

axes

unit cell axes (b is normally along z direction)

Type:: np.array of float

burgers_dimensionless

burgers vector of the dislocation class, in a dimensionless alat=1 system

Type:: np.array of float

burgers

burgers vector of the atomistic dislocation

Type:: np.array of float

unit_cell_core_position

dislocation core position in the unit cell used to shift atomic positions to make the dislocation core the center of the cell

Type:: np.array of float

parity

Type:: np.array

glide_distance

distance (in A) to the next equivalent core position in the glide direction

Type:: float

n_planes

number of non equivalent planes in z direction

Type:: int

self_consistent

default value for the displacement calculation

Type:: float

crystalstructure

Name of basic structure defining atomic geometry (“fcc”, “bcc”, “diamond”)

Type:: str

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

build_cylinder(radius, core_position=array([0., 0., 0.]), extension=None, fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Build dislocation cylinder for single dislocation system

Parameters:

radius (float) – Radius of bulk surrounding the dislocation core
core_position (np.array) – Vector offset of the core position from default site
extension (np.array) – Add extra bulk to the system, to also surround a fictitious core that is at position core_position + extension
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
fix_width (float) – Defines a region to apply the FixAtoms ase constraint to Fixed region is given by (radius - fix_width) <= r <= radius, where the position r is measured from the dislocation core (or from the glide path, if extra_glide_widths is given)
self_consistent (bool) – Controls whether the displacement field used to construct the dislocation is converged self-consistently. If None (default), the value of self.self_consistent is used
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Get list of dislocation displacement solvers

As CubicCrystalDislocation models a single core, there is only one solver, therefore solvers is a len(1) list

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell_core_position

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.FCCScrew110Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDissociatedDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
new_right_burgers
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, partial_distance, ...])	Overloaded function to make dissociated dislocations.
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
left_dislocation
plot_unit_cell
right_dislocation
set_burgers

burgers_dimensionless = array([ 0.5, -0.5, 0. ])

new_left_burgers = array([ 0.33333333, -0.16666667, -0.16666667])

left_dislocation

right_dislocation

name = '1/2<110>{111} screw'

ADstroh = None

C

N_cores

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dissociated dislocation in a cubic crystal with burgers vector b = b_left + b_right.

Parameters:

CubicCrystalDislocation (identical to)

Raises:

ValueError – If resulting burgers vector burgers is not a sum of burgers vectors of left and right dislocations.
ValueError – If one of the properties of left and righ dislocations are not the same.

property alat

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

axes = array([[ 1, 1, -2], [ 1, 1, 1], [ 1, -1, 0]])

build_cylinder(radius, partial_distance=0, core_position=array([0., 0., 0.]), extension=array([0., 0., 0.]), fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Overloaded function to make dissociated dislocations. Partial distance is provided as an integer to define number of glide distances between two partials.

Parameters:

radius (float) – radius of the cell
partial_distance (int) – distance between partials (SF length) in number of glide distances. Default is 0 -> non dissociated dislocation with b = b_left + b_right is produced
extension (np.array) – Shape (2, 3) array giving additional extension vectors from each dislocation core. Used to add extra bulk, e.g. to set up glide configurations.
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

crystalstructure = 'fcc'

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

glide_distance_dimensionless = 0.6123724356957945

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 2

new_right_burgers = None

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell

property unit_cell_core_position

unit_cell_core_position_dimensionless = array([0.83333333, 0.11111111, 0. ])

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.FCCEdge110Dislocation(a, C11=None, C12=None, C44=None, C=None, symbol='W')

Bases: CubicCrystalDissociatedDislocation

Attributes:

ADstroh
C
N_cores
alat
burgers
glide_distance
new_right_burgers
stroh
unit_cell
unit_cell_core_position

Methods

`build_cylinder`(radius[, partial_distance, ...])	Overloaded function to make dissociated dislocations.
`build_kink_cylinder`([kink_map, smooth_width])	Build a cylindrical cell with a dislocation kink network, defined by kink_map
`build_kink_from_glide_cyls`(ref_bulk, ...[, ...])	Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs
`build_kink_glide_structs`([kink_map])	Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]).
`displacements`(bulk_positions, core_positions)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`get_solvers`([method])	Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers
`init_adsl`()	Init adsl (Anisotropic DiSLocation) solver
`init_atomman`()	Init atomman stroh solution solver (requires atomman)
`init_solver`([method])	Run the correct solver initialiser
`invert_burgers`()	Modify dislocation to produce same dislocation with opposite burgers vector
`ovito_dxa`(disloc)	General interface for ovito dxa analysis.
`self_consistent_displacements`(solvers, ...)	Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0]).
`view_cyl`(system[, scale, CNA_color, ...])	NGLview-based visualisation tool for structures generated from the dislocation class

build_glide_configurations
build_impurity_cylinder
left_dislocation
plot_unit_cell
right_dislocation
set_burgers

crystalstructure = 'fcc'

burgers_dimensionless = array([ 0.5, -0.5, 0. ])

new_left_burgers = array([ 0.33333333, -0.16666667, -0.16666667])

left_dislocation

right_dislocation

name = '1/2<110> edge'

ADstroh = None

C

N_cores

__init__(a, C11=None, C12=None, C44=None, C=None, symbol='W')

This class represents a dissociated dislocation in a cubic crystal with burgers vector b = b_left + b_right.

Parameters:

CubicCrystalDislocation (identical to)

Raises:

ValueError – If resulting burgers vector burgers is not a sum of burgers vectors of left and right dislocations.
ValueError – If one of the properties of left and righ dislocations are not the same.

property alat

atm = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

atomman = <module 'atomman' from '/usr/local/lib/python3.10/dist-packages/atomman/__init__.py'>

avail_methods = ['atomman', 'adsl']

axes = array([[ 1, -1, 0], [ 1, 1, 1], [-1, -1, 2]])

build_cylinder(radius, partial_distance=0, core_position=array([0., 0., 0.]), extension=array([0., 0., 0.]), fixed_points=None, fix_width=10.0, self_consistent=None, method='atomman', verbose=True, return_cyl_mask=False, return_fix_mask=False, cyl_mask=None, **kwargs)

Overloaded function to make dissociated dislocations. Partial distance is provided as an integer to define number of glide distances between two partials.

Parameters:

radius (float) – radius of the cell
partial_distance (int) – distance between partials (SF length) in number of glide distances. Default is 0 -> non dissociated dislocation with b = b_left + b_right is produced
extension (np.array) – Shape (2, 3) array giving additional extension vectors from each dislocation core. Used to add extra bulk, e.g. to set up glide configurations.
fixed_points (np.array) – Shape (N, 3) array of points defining extra bulk. Similar to extension arg, but is not relative to core positions
method (str) – Displacement solver method name. See self.avail_methods for allowed values method = atomman requires atomman package
return_cyl_mask (bool) – Whether to additionally return the atoms mask
return_fix_mask (bool) – Whether to additionally return the FixAtoms mask
cyl_mask (np.array) – Enforce a specific cyl mask top convert supercell to cyl
Returns
--------
bulk (ase Atoms object) – Cylinder of bulk, for a formation energy reference
disloc (ase Atoms object:) – Cylinder containing dislocation
cyl_mask – If return_cyl_mask=True, return the mask used to convert suqare supercells to cylinders of correct shape
fix_mask (np.array) – If return_fix_mask=True, return the mask used for the FixAtoms constraint

build_glide_configurations(radius, average_positions=False, **kwargs)

build_impurity_cylinder(disloc, impurity, radius, imp_symbol='H', core_position=array([0., 0., 0.]), extension=None, self_consistent=False, extra_bulk_at_core=False, core_radius=0.5, shift=array([0., 0., 0.]))

build_kink_cylinder(kink_map=None, smooth_width=None, *args, **kwargs)

Build a cylindrical cell with a dislocation kink network, defined by kink_map

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]
*args, **kwargs: Extra arguments sent to self.build_cylinder

build_kink_from_glide_cyls(ref_bulk, glide_structs, struct_map, smooth_width=None)

Build a kink cylinder cell from the given kink map, using the structures contained in glide_structs

ref_bulk: ase Atoms object: Reference bulk structure, as returned by self.build_kink_glide_structs
glide_structs: list of ase Atoms: Glide structures e.g. those produced by self.build_kink_glide_structs. The kink structure is constructed using glide_structs[kink_map[i]] for the ith cell.
struct_map: iterable of ints: Map of glide_structs back onto kink profile Obtained by a call to build_kink_glide_structs
smooth_width: float: Size (in Ang) of the region for displacement smoothing at each kink site. Larger smoothing width assumes a broader kink structure. Default is 0.5 * self.unit_cell.cell[2, 2]

build_kink_glide_structs(kink_map=None, *args, **kwargs)

Build a reference bulk and a minimal set of glide structures required to build a kink structure of the given kink map (default [0, 1]). Does not actually build the kink structure, this is handled by self.kink_from_glide_cyls.

kink_map: iterable of ints or None: Map of the location of the dislocation core in units of the glide vector Default (kink_map=None) is a kink map of [0, 1] See examples for more details.
*args, **kwargs: Extra arguments sent to self.build_cylinder

property burgers

displacements(bulk_positions, core_positions, method='atomman', self_consistent=True, tol=1e-06, max_iter=100, verbose=True, mixing=0.5, r_sc=None)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
self_consistent (bool) – Whether to detemine the dislocation displacements in a self-consistent manner (self_consistent=False is equivalent to max_iter=0)
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)
r_sc (float | None) – Optional cutoff for the self-consistent region. If r_sc=None, treat all displacements self-consistently. Atoms within r_sc radius of any dislocation core will be selected for the self-consistent treatment. Useful if displacement calculations are slow (i.e. for very large systems), or if the self-consistency creates issues in the dislocation structure (see https://github.com/libAtoms/matscipy/issues/265).

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

get_solvers(method='atomman')

Overload of CubicCrystalDislocation.get_solvers Get list of dislocation displacement solvers

Parameters:: method (str) – Method to use when calculating the Continuum Linear Elastic (CLE) dislocation displacements. See self.avail_methods for a list of accepted methods
Returns:: solvers – List of functions f(positions) = displacements
Return type:: list

property glide_distance

glide_distance_dimensionless = 0.3535533905932738

init_adsl(): Init adsl (Anisotropic DiSLocation) solver

init_atomman(): Init atomman stroh solution solver (requires atomman)

init_solver(method='atomman')

Run the correct solver initialiser

Solver init should take only the self arg, and set self.solver[method] to point to the function to calculate displacements

e.g. self.solvers[“atomman”] = self.stroh.displacement

invert_burgers(): Modify dislocation to produce same dislocation with opposite burgers vector

n_planes = 6

new_right_burgers = None

ovito_dxa(disloc)

General interface for ovito dxa analysis. dxa requires 3b thick cells at minimum, so uses ovito replicate if given structure is insufficient

Parameters:: disloc (ase.Atoms) – Atoms object containing the atomic configuration to analyse
Returns:: data – See https://www.ovito.org/docs/current/python/modules/ovito_data.html#ovito.data.DataCollection data.dislocations.segments is a list of all discovered dislocation segments
Return type:: ovito DataCollection object.

parity = array([0., 0.])

pbc = [True, True, True]

plot_unit_cell(ms=250, ax=None)

self_consistent = True

self_consistent_displacements(solvers, bulk_positions, core_positions, tol=1e-06, max_iter=100, verbose=True, mixing=0.8)

Compute dislocation displacements self-consistently, with max_iter capping the number of iterations Each dislocation core uses a separate solver, which computes the displacements associated with positions relative to that core (i.e. that the core is treated as lying at [0, 0, 0])

Parameters:

solvers (list) – List of functions, solvers[i] computes the displacement field for the dislocation defined by core_positions[i, :]
bulk_positions (np.array) – (N, 3) array of positions of atoms in the bulk configuration
core_positions (np.array) – Positions of each dislocation core (shape = (ncores, 3))
tol (float) – Displacement tolerance for the convergence of the self-consistent loop
max_iter (int) – Maximum number of iterations of the self-consistent cycle to run before throwing an exception If max_iter == 0, return the displacements from the first (0th) iteration with no error.
verbose (bool) – Enable/Disable printing progress of the self-consistent cycle each iteration
mixing (float) – Mixing parameter between self-consistent displacement iterations (if self_consistent=True)

Returns:

displacements (np.array)
shape (N, 3) array of displacements to apply to bulk_positions to form
the dislocation structure
Raises a RuntimeError if max_iter is reached without convergence

set_burgers(burgers)

stroh = None

property unit_cell

property unit_cell_core_position

unit_cell_core_position_dimensionless = array([0. , 0.16666667, 0. ])

view_cyl(system, scale=0.5, CNA_color=True, add_bonds=False, line_color=None, disloc_names=None, hide_arrows=False, mode='dxa', hide_bulk=False, hide_fixmask=True)

NGLview-based visualisation tool for structures generated from the dislocation class

Parameters:

system (ase.Atoms) – Dislocation system to view
scale (float) – Adjust radiusScale of add_ball_and_stick (add_bonds=True) or add_spacefill (add_bonds=False)
CNA_color (bool) – Turn on atomic/bond colours based on Common Neighbour Analysis structure identification
add_bonds (bool) – Add atomic bonds
line_color (list or list of lists) – [R, G, B] values for the colour of dislocation lines if a list of lists, line_color[i] defines the colour of the ith dislocation (see structure.info[“dislocation_types”])
disloc_names (list of str) – Manual override for the automatic naming of the dislocation lines (see structure.info[“dislocation_types”] for defaults)
hide_arrows (bool) – Hide arrows for placed on the dislocation lines
mode (str) – Mode for plotting dislocation line mode=”dxa” uses ovito dxa to plot an exact dislocation line mode=”cle” uses the cle solution used to generate the structure (if the dislocation line is straight)
hide_bulk (bool) – Use structure analysis to mask out the bulk atoms from the system
hide_fixmask (bool) – If hide_bulk is True, also hide any atoms included in the fix_mask (system.arrays[“fix_mask”]), if it is present

class matscipy.dislocation.FixedLineAtoms(a, direction)

Bases: object

Constrain atoms to move along a given direction only.

Methods

adjust_forces
adjust_positions

__init__(a, direction)

adjust_positions(atoms, newpositions)

adjust_forces(atoms, forces)

matscipy.dislocation.gamma_line(unit_cell, calc=None, shift_dir=0, surface=2, size=[2, 2, 2], factor=15, n_dots=11, relax=True, fmax=0.01, return_images=False)

This function performs a calculation of a cross-sections in ‘shift_dir` of the generalized stacking fault (GSF) gamma surface with surface orientation. A gamma surface is defined as the energy variation when the crystal is cut along a particular plane and then one of the resulting parts is displaced along a particular direction. This quantity is related to the energy landscape of dislocations and provides data out of equilibrium, preserving the crystal state. For examples for the case of W and more details see section 4.2 and figure 2 in [J. Phys.: Condens. Matter 25 (2013) 395502 (15pp)] (http://iopscience.iop.org/0953-8984/25/39/395502)

Parameters:

unit_cell (ase.Atoms) – Unit cell to construct gamma surface from. Should have a ase.calculator attached as calc in order to perform relaxation.
calc (ase.calculator) – if unit_cell.calc is None set unit_cell.calc to calc
shift_dir (int) – index of unit_cell axes to shift atoms
surface (int) – index of unit_cell axes to be the surface normal direction
size (list of ints) – start size of the cell
factor (int) – factor to increase the size of the cell along the surface normal direction
n_dots (int) – number of images along the gamma line
relax (bool) – flag to perform relaxation
fmax (float) – maximum force value for relaxation
return_images (bool) – flag to control if the atomic configurations are returned together with the results

Returns:

deltas (np.array) – shift distance of every image in Angstroms
totens (np.array) – gamma surface energy in eV / Angstroms^2
images (list of ase.Atoms) – images along the gamma surface. Returned if return_images is True