Defects and deformation

Dislocation analysis

DislocationAnalysis

DislocationAnalysis(crystal, *, circuit_length=14, stretch=9, perfect_only=False, point_separation=2.5, smoothing=1, mesh_smoothing=8, interface_mesh=False)

Dislocations of a crystal by the dislocation extraction algorithm (DXA): Burgers circuits on the mesh between the tetrahedra of the atoms where the crystal maps onto the perfect lattice and the rest.

Parameters:

Name	Type	Description	Default
crystal	str	The crystal: fcc, hcp, bcc, cubic_diamond or hexagonal_diamond.	required
circuit_length	int32	Number of edges of the longest Burgers circuit that finds a line; at least 3. Default 14.	14
stretch	int32	Number of edges more a circuit may grow to follow a line. Default 9.	9
perfect_only	bool	Find perfect dislocations only: the stacking faults of fcc and hcp, or of the diamonds, count as defects, without partial dislocations at their edges. Default False.	False
point_separation	float64	Sparseness of the points along the lines: each point is the mean of a run of the points found, longer where the lines are wider; 0 keeps them all. Default 2.5.	2.5
smoothing	int32	Number of smoothing steps of the lines. Default 1.	1
mesh_smoothing	int32	Number of smoothing steps of the defect mesh. Default 8.	8
interface_mesh	bool	Also give the interface mesh, between the tetrahedra of the good crystal and the rest, on which the circuits run. Default False.	False

compute

compute(system, *, progress=None, cancel=None)

The dislocations of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, no two at the same position.	required

Returns:

Type	Description
DislocationResult	The dislocation lines, the structure and crystal cluster of each atom.

Raises:

Type	Description
InvalidParameter	For a box so short along a periodic direction that an atom meets its own periodic image or an edge of the mesh spans half of it: replicate the system first.

DislocationResult dataclass

DislocationResult(crystal, lines, junctions, structure, names, colors, crystal_cluster, clusters, defect_mesh, defect_atoms, interface_mesh=None, interface_atoms=None)

Bases: Result

The dislocations of a crystal.

Attributes:

Name	Type	Description
crystal	str	The crystal analyzed.
lines	tuple of DislocationLine	The dislocation lines.
junctions	ndarray	(J, 3) float64, the points in Å where three or more lines meet, in the box.
structure	ndarray	(N,) int8 structure of each atom, an index into names.
names	tuple of str	The structures: other, fcc, hcp, bcc, cubic_diamond and hexagonal_diamond.
colors	tuple of tuple of float64	Default RGB color of each structure, from 0 to 1.
crystal_cluster	ndarray	(N,) int64 crystal cluster of each atom, -1 for none.
clusters	CrystalClusters	The crystal clusters.
defect_mesh	TriangleMesh	The surface around the defects that are not dislocations, such as grain boundaries, free surfaces and voids, closed at the free ends of the lines, its normals pointing out of the crystal.
defect_atoms	ndarray	(V,) int64 the atom at each vertex of the defect mesh, -1 at the end of a line.
interface_mesh	TriangleMesh or None	The mesh between the tetrahedra of the good crystal and the rest, its normals pointing into the good crystal, when asked for.
interface_atoms	ndarray or None	(V,) int64 the atom at each vertex of the interface mesh, when asked for.

total_length property

total_length

Total length of the lines in Å.

counts

counts()

Number of atoms of each structure, by name.

lengths

lengths()

Total length in Å of the lines of each family of Burgers vectors of the crystal, "other" last.

DislocationLine dataclass

DislocationLine(points, burgers, spatial_burgers, cluster, family, length, loop, infinite, junctions)

A dislocation line between two junctions or free ends, or closed on itself.

Attributes:

Name	Type	Description
points	ndarray	(P, 3) float64 points along the line in Å, unwrapped: consecutive points are close also across a periodic boundary.
burgers	ndarray	(3,) float64, the Burgers vector in the lattice frame of its crystal cluster, in units of the lattice constant, such as (0.5, 0.5, 0) for a/2[110]: the hexagonal lattices with c along z and a1 along x, in units of the cubic lattice constant with the same nearest neighbors.
spatial_burgers	ndarray	(3,) float64, the Burgers vector in Å along the axes of the box, as the crystal cluster is turned and stretched.
cluster	int32	The crystal cluster of the frame of the Burgers vector.
family	str	The family of the Burgers vector, such as "1/2<110>", or "other".
length	float64	Length in Å.
loop	bool	Whether the line closes on itself: a loop, or a line through periodic boundaries.
infinite	bool	Whether the line closes through periodic boundaries.
junctions	tuple of int32	The junctions at the first and the last point, -1 for a free end and for the ends of a closed line.

CrystalClusters dataclass

CrystalClusters(structure, size, orientation)

Bases: Result

The crystal clusters: atoms of one structure joined through their neighbors into one lattice frame.

Attributes:

Name	Type	Description
structure	ndarray	(C,) int8 structure of each cluster, an index into the names of the result.
size	ndarray	(C,) int64 number of atoms of each.
orientation	ndarray	(C, 3, 3) float64, the matrix that takes vectors of the lattice frame of each, in units of the lattice constant, to vectors in Å along the axes of the box, from the neighbors of its atoms.

Wigner-Seitz analysis

WignerSeitz

WignerSeitz(reference, *, affine=False)

Wigner-Seitz analysis: each atom belongs to the cell of its nearest reference site; empty sites are vacancies and crowded ones hold interstitials.

Parameters:

Name	Type	Description	Default
reference	System	The reference sites, usually the perfect crystal.	required
affine	bool	Map the atoms into the reference box by their fractional coordinates before assigning them, which removes a homogeneous deformation of the box. Default False.	False

compute

compute(system, *, progress=None, cancel=None)

The site of each atom and the occupancy of each site.

Parameters:

Name	Type	Description	Default
system	System	The atoms, any number of them, in a box with the periodicity of the reference.	required

Returns:

Type	Description
WignerSeitzResult	The site of each atom and the number of atoms on each site.

WignerSeitzResult dataclass

WignerSeitzResult(site, occupancy)

Bases: Result

Occupancy of the reference sites.

Attributes:

Name	Type	Description
site	ndarray	(N,) int32 reference site of each atom, the nearest one (the first of equally near sites), as mdapy.index_dtype.
occupancy	ndarray	(M,) int64 number of atoms on each reference site.

vacancies property

vacancies

Reference sites without atoms.

interstitials property

interstitials

Reference sites with more than one atom.

vacancy_count property

vacancy_count

Number of empty sites.

interstitial_count property

interstitial_count

Number of atoms beyond one on each site.

Cluster analysis

ClusterAnalysis

ClusterAnalysis(cutoff=None, *, cutoffs=None, unwrap=False, center_of_mass=False, gyration=False)

Clusters of atoms joined by bonds shorter than a cutoff.

Parameters:

Name	Type	Description	Default
cutoff	float64	Bond length in Å for every pair.	None
cutoffs	dict	Bond length in Å for each pair of elements (a, b), in either order; pairs not given are never bonded. Give cutoff or cutoffs.	None
unwrap	bool	Give the positions with each cluster unbroken by the periodic boundaries. Default False.	False
center_of_mass	bool	Compute the mass and the center of mass of each cluster. Default False.	False
gyration	bool	Compute the gyration tensor and the radius of gyration of each cluster. Default False.	False

compute

compute(system, *, neighbors=None, progress=None, cancel=None)

The clusters of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms; per-element cutoffs need an element column.	required
neighbors	NeighborList	A neighbor list of this system with at least the largest cutoff.	None

Returns:

Type	Description
ClusterResult	The cluster of each atom; ties in size are ordered by their first atom.

ClusterResult dataclass

ClusterResult(cluster, sizes, spanning, unwrapped=None, masses=None, center_of_mass=None, radius_of_gyration=None, gyration_tensor=None)

Bases: Result

Clusters of bonded atoms.

Attributes:

Name	Type	Description
cluster	ndarray	(N,) int64 cluster of each atom, numbered from 0 by decreasing size.
sizes	ndarray	(clusters,) int64 number of atoms of each cluster.
spanning	ndarray	(clusters,) bool, whether the cluster joins another periodic image of itself, spanning the box; its unwrapped positions, center of mass and gyration then depend on the order of the bonds.
unwrapped	ndarray or None	(N, 3) float64 positions in Å with each cluster unbroken by the periodic boundaries, the first atom of each cluster at its own position, when computed.
masses	ndarray or None	(clusters,) float64 total mass of each cluster in amu, or its number of atoms when the system has neither masses nor elements, with the center of mass.
center_of_mass	ndarray or None	(clusters, 3) float64 center of mass of each cluster in Å, from the unwrapped positions, when computed.
radius_of_gyration	ndarray or None	(clusters,) float64 radius of gyration of each cluster in Å, when computed.
gyration_tensor	ndarray or None	(clusters, 3, 3) float64 gyration tensor of each cluster in Ų, with the radius of gyration.

Surface mesh

SurfaceMesh

SurfaceMesh(radius=4.0, smoothing=8, *, regions=False, surface=False)

The surface of the solid the atoms make, by the alpha-shape method: the space a probe sphere cannot enter is solid.

Parameters:

Name	Type	Description	Default
radius	float64	Radius of the probe sphere in Å: the tetrahedra of the Delaunay tessellation of the atoms whose circumscribed sphere is smaller are solid. Larger than the distance between neighbors, and smaller than the voids looked for. Default 4.	4.0
smoothing	int32	Number of smoothing steps of the mesh, which round its shape and keep the volumes. Default 8.	8
regions	bool	Also give the regions of solid and empty space, and the voids among them. Default False.	False
surface	bool	Also mark the atoms on the surface. Default False.	False

compute

compute(system, *, progress=None, cancel=None)

The surface of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, no two at the same position. Out of a box that is not periodic is empty space.	required

Returns:

Type	Description
SurfaceMeshResult	The surface, its area and the volume of the solid.

Raises:

Type	Description
InvalidParameter	For a periodic box so short that an atom meets its own periodic image: replicate the system first.

SurfaceMeshResult dataclass

SurfaceMeshResult(mesh, atoms, area, solid_volume, regions=None, surface=None)

Bases: Result

The surface of the solid.

Attributes:

Name	Type	Description
mesh	TriangleMesh	The surface, its normals pointing out of the solid.
atoms	ndarray	(V,) int64 the atom at each vertex of the mesh.
area	float64	Area of the surface in Ų.
solid_volume	float64	Volume of the solid in ų.
regions	SurfaceRegions or None	The solid and empty regions, when asked for.
surface	ndarray or None	(N,) bool whether each atom lies on the surface, when asked for.

SurfaceRegions dataclass

SurfaceRegions(solid, volume, area, exterior, periodic, faces)

Bases: Result

The regions of connected solid or empty space the surface separates.

Attributes:

Name	Type	Description
solid	ndarray	(R,) bool whether each region is solid.
volume	ndarray	(R,) float64 volume of each region in ų; infinite for the exterior one.
area	ndarray	(R,) float64 area of the surface around each region in Ų.
exterior	ndarray	(R,) bool whether the region is the empty space around the atoms, out of a box that is not periodic.
periodic	ndarray	(R,) bool whether the region runs across a periodic boundary into its own periodic image, without end.
faces	ndarray	(F, 2) int64 the solid and the empty region on the two sides of each triangle of the mesh.

voids property

voids

(K,) int64 the empty regions enclosed by the solid on every side.

TriangleMesh

TriangleMesh(vertices, faces, shifts=None, box=None)

A mesh of triangles, which may cross the periodic boundaries of a box.

Parameters:

Name	Type	Description	Default
vertices	array_like	(V, 3) float64 positions of the vertices in Å.	required
faces	array_like	(F, 3) int64 vertices of each triangle, counterclockwise seen from the side its normal points to.	required
shifts	array_like	(F, 3, 3) int32 periodic image of each corner: corner k of triangle f is at vertices[faces[f, k]] + shifts[f, k] @ box.matrix. Default all in the box.	None
box	Box	The box of the periodic images; needed with shifts.	None

Raises:

Type	Description
InvalidParameter	For arrays of the wrong shape, vertices that are not finite, faces of vertices that do not exist, or shifts without a box.

vertices property

vertices

(V, 3) positions of the vertices in Å.

faces property

faces

(F, 3) int64 vertices of each triangle.

shifts property

shifts

(F, 3, 3) int8 periodic image of each corner, or None.

box property

box

The box of the periodic images, or None.

areas property

areas

(F,) area of each triangle in Ų.

area property

area

Total area of the triangles in Ų.

normals property

normals

(F, 3) unit normal of each triangle; zero for a triangle without area.

corners

corners()

The corners of each triangle, each triangle whole.

Returns:

Type	Description
ndarray	(F, 3, 3) float64 positions in Å.

pieces

pieces()

The triangles inside the box: each moved by whole periods so that its center lies in the box, then cut where it crosses a periodic face and the part outside moved in through the opposite face. Without a box, the triangles as they are.

Returns:

Name	Type	Description
corners	ndarray	(T, 3, 3) float64, the corners of each piece in Å, counterclockwise as its triangle.
triangle	ndarray	(T,) int64 the triangle of each piece.

Chemical species

ChemicalSpecies

ChemicalSpecies(radii='covalent', *, scale=None, tolerance=None, cutoffs=None)

Molecules: atoms joined by bonds shorter than their radii allow, and their chemical formulas.

Two atoms of radii r_i and r_j are bonded when closer than scale * (r_i + r_j) + tolerance, or than the cutoff given for their pair of elements.

Parameters:

Name	Type	Description	Default
radii	(covalent, vdw)	The radius of each element: the covalent radii (Cordero et al. 2008), as Jmol bonds atoms; the van der Waals radii (Alvarez 2013), as VMD and OVITO bond atoms, two hydrogen atoms never bonded unless cutoffs say so; or radii in Å by element. Default "covalent".	"covalent"
scale	float64	Factor on the sum of the radii. Default 0.6 with van der Waals radii, 1 otherwise.	None
tolerance	float64	Length added to it, in Å. Default 0.45 with covalent radii, 0 otherwise.	None
cutoffs	dict	Bond length in Å for pairs of elements (a, b), in either order, instead of the radii; 0 for pairs never bonded.	None

bond_lengths

bond_lengths(elements)

The longest bond between each pair of the elements.

Parameters:

Name	Type	Description	Default
elements	iterable of str	Chemical symbols.	required

Returns:

Type	Description
dict	The bond length in Å of each pair (a, b), a before b in the order given; 0 for pairs never bonded.

Raises:

Type	Description
InvalidParameter	If an element has no radius and its pairs no cutoffs.

compute

compute(system, *, neighbors=None, progress=None, cancel=None)

The molecules of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column.	required
neighbors	NeighborList	A neighbor list of this system with at least the longest bond.	None

Returns:

Type	Description
SpeciesResult	The molecule of each atom and the formula of each molecule.

Raises:

Type	Description
MissingProperty	If the system has no element column.
InvalidParameter	If an element has no radius.

count

count(frames)

The number of molecules of each formula in each frame.

Parameters:

Name	Type	Description	Default
frames	iterable of System	The frames, such as a trajectory.	required

Returns:

Type	Description
DataFrame	A frame column, from 0, and a column of counts for each formula, the most common over all frames first.

SpeciesResult dataclass

SpeciesResult(molecule, formulas, sizes)

Bases: Result

Molecules of bonded atoms and their chemical formulas.

Attributes:

Name	Type	Description
molecule	ndarray	(N,) int64 molecule of each atom, numbered from 1 by decreasing size, ties by their first atom.
formulas	ndarray	(M,) str, chemical formula of each molecule, in Hill order.
sizes	ndarray	(M,) int64 number of atoms of each molecule.

counts

counts()

The number of molecules of each formula, the most common first.

Atomic displacement

AtomicDisplacement

AtomicDisplacement(reference, *, minimum_image=True, affine=False)

The displacement of each atom from its position in a reference configuration.

Parameters:

Name	Type	Description	Default
reference	System	The reference configuration: the atoms of the systems to compare, matched by the column id when both have it, otherwise in the same order.	required
minimum_image	bool	Take along each periodic direction the periodic image of the reference position nearest the atom. Default True.	True
affine	bool	Measure the displacements in the reference box: the current positions mapped into it first, which removes the homogeneous deformation of the box. Default False.	False

compute

compute(system)

The displacements of the atoms of a configuration.

Parameters:

Name	Type	Description	Default
system	System	The current configuration.	required

Returns:

Type	Description
AtomicDisplacementResult	The displacement of each atom, in its order.

Raises:

Type	Description
InvalidParameter	For atoms not in the reference, or a reference of another number of atoms without ids.

AtomicDisplacementResult dataclass

AtomicDisplacementResult(displacement, magnitude)

Bases: Result

The displacements of the atoms.

Attributes:

Name	Type	Description
displacement	ndarray	(N, 3) float64, the displacement of each atom from its reference position in Å; its column displacement.
magnitude	ndarray	(N,) float64, its length in Å; its column displacement_magnitude.

Atomic strain

AtomicStrain

AtomicStrain(reference, cutoff, *, affine=False, strain_tensor=False, d2min=False, neighbors=None)

Atomic strain: the deformation gradient that best maps each atom's neighbor vectors in a reference configuration onto the current ones.

Parameters:

Name	Type	Description	Default
reference	System	The reference configuration, with the same atoms as the systems to compare: matched by the id column where both have one, else in the same order.	required
cutoff	float64	Neighbors in the reference closer than cutoff, in Å, define the neighbor vectors.	required
affine	bool	Measure the current vectors in the reference box, which removes the homogeneous deformation of the box. Default False.	False
strain_tensor	bool	Give the Green-Lagrange strain tensor of each atom. Default False.	False
d2min	bool	Compute the non-affine squared displacement of each atom. Default False.	False
neighbors	NeighborList	Neighbors of the reference within at least cutoff, used for every configuration; without, they are found again for each.	None

compute

compute(system, *, progress=None, cancel=None)

The strain of each atom of a configuration.

Parameters:

Name	Type	Description	Default
system	System	The current configuration: the atoms of the reference, each moved by less than half the box.	required

Returns:

Type	Description
StrainResult	The strain of each atom.

StrainResult dataclass

StrainResult(shear, volumetric, strain_tensor=None, d2min=None)

Bases: Result

The strain of each atom against the reference.

Attributes:

Name	Type	Description
shear	ndarray	(N,) float64 von Mises shear strain; NaN where the reference neighbors do not span three dimensions.
volumetric	ndarray	(N,) float64 volumetric strain, a third of the trace of the strain tensor.
strain_tensor	ndarray or None	(N, 3, 3) float64 Green-Lagrange strain, when computed.
d2min	ndarray or None	(N,) float64 non-affine squared displacement in Ų, the part of the neighbor vectors that the deformation gradient does not explain, when computed.

Elastic strain

ElasticStrain

ElasticStrain(crystal, a, c=None)

The elastic strain of each atom of a crystal: the deformation that maps the neighbors of the ideal crystal onto its own, as OVITO's elastic strain calculation.

Parameters:

Name	Type	Description	Default
crystal	str	The crystal: "fcc", "hcp", "bcc", "cubic_diamond" or "hexagonal_diamond". Its atoms are found as by the dislocation analysis, with the stacking faults of fcc and hcp, and of the diamonds, in the other structure.	required
a	float64	Lattice constant of the unstrained crystal in Å: of the cubic cell, or a of the hexagonal cell.	required
c	float64	Lattice constant c of the unstrained hexagonal cell in Å; default that of the ideal ratio, a √(8/3). Only for hcp and hexagonal diamond.	None

compute

compute(system, *, progress=None, cancel=None)

The elastic strain of the atoms of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, no two at the same position.	required

Returns:

Type	Description
ElasticStrainResult	The structure and the elastic strain of each atom.

Raises:

Type	Description
InvalidParameter	For a box so short along a periodic direction that an atom meets its own periodic image: replicate the system first.

ElasticStrainResult dataclass

ElasticStrainResult(structure, names, colors, strain_tensor, volumetric)

Bases: Result

The elastic strain of each atom.

Attributes:

Name	Type	Description
structure	ndarray	(N,) int8 structure of each atom, an index into names.
names	tuple of str	Names of the structures: other, fcc, hcp, bcc, cubic_diamond, hexagonal_diamond.
colors	tuple of tuple of float64	RGB color of each structure.
strain_tensor	ndarray	(N, 3, 3) float64 elastic strain of each atom of the crystal in the spatial frame; zero for the other atoms.
volumetric	ndarray	(N,) float64, a third of the trace of the strain; zero for the atoms not of the crystal.