Structure identification

Common neighbor analysis

CommonNeighborAnalysis

CommonNeighborAnalysis(cutoff=None)

Common neighbor analysis: fcc, hcp, bcc and icosahedral atoms.

Parameters:

Name	Type	Description	Default
cutoff	float64	Cutoff of the neighbors and of the bonds between them, in Å. Without it, each atom has its own cutoff from its nearest neighbors (adaptive common neighbor analysis).	None

compute

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

The structure type of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	Neighbors of this system: with a cutoff, within at least the cutoff; without, at least the 14 nearest of each atom.	None

Returns:

Type	Description
StructureResult	Types other, fcc, hcp, bcc and ico.

StructureResult dataclass

StructureResult(structure, names, colors, *, method)

Bases: Result

Structure type of each atom.

Attributes:

Name	Type	Description
structure	ndarray	(N,) int8 type of each atom, an index into names.
names	tuple of str	Name of each type.
colors	tuple of tuple of float64	Default RGB color of each type, from 0 to 1.
method	str	The method, which names the column, as cna_structure.

counts

counts()

Number of atoms of each type, by name.

Polyhedral template matching

PolyhedralTemplateMatching

PolyhedralTemplateMatching(structures=('fcc', 'hcp', 'bcc'), *, rmsd_cutoff=0.1, deformation_gradient=False, ordering=False, template_neighbors=False)

Polyhedral template matching: the structure, orientation and deformation of the neighborhood of each atom, and its chemical ordering.

Parameters:

Name	Type	Description	Default
structures	iterable of str	The structures to look for, of NAMES but other. Default fcc, hcp and bcc.	('fcc', 'hcp', 'bcc')
rmsd_cutoff	float64	Atoms whose root-mean-square deviation from the best template is larger are other; 0 for no cutoff. Default 0.1.	0.1
deformation_gradient	bool	Compute the elastic deformation gradient of each atom. Default False.	False
ordering	bool	Identify the chemical ordering of each atom from the elements. Default False.	False
template_neighbors	bool	Give the neighbors of each atom in the order of its template. Default False.	False

compute

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

The structure of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column for the ordering.	required
neighbors	NeighborList	Neighbors of this system with at least the 18 nearest of each atom.	None

Returns:

Type	Description
PTMResult	The structure types, orientations and the other results.

Raises:

Type	Description
InvalidParameter	If an atom has fewer than 18 neighbors in the given list.
MissingProperty	If the ordering is asked for without an element column.

PTMResult dataclass

PTMResult(structure, names, colors, rmsd, interatomic_distance, orientation, correspondences, template_index, deformation_gradient=None, ordering=None, ordering_names=(), neighbors=None, *, method)

Bases: StructureResult

Polyhedral template matching of each atom.

Attributes:

Name	Type	Description
structure	ndarray	(N,) int8 type of each atom, an index into names.
names	tuple of str	Name of each type.
colors	tuple of tuple of float64	Default RGB color of each type, from 0 to 1.
rmsd	ndarray	(N,) float64 root-mean-square deviation from the best template, 0 for an atom that matches none.
interatomic_distance	ndarray	(N,) float64 distance in Å between nearest neighbors of the matched lattice, 0 for none.
orientation	ndarray	(N, 4) float64, the rotation of the matched lattice from its standard orientation as a quaternion (x, y, z, w), zeros for none.
correspondences	ndarray	(N,) uint64 the order of the neighbors matching the template, as OVITO encodes it.
template_index	ndarray	(N,) int8 which of the equivalent templates of a structure matched.
deformation_gradient	ndarray or None	(N, 3, 3) float64, the elastic deformation gradient from the template to the neighbors, when computed.
ordering	ndarray or None	(N,) int8 chemical ordering, an index into ordering_names, when identified.
ordering_names	tuple of str	Name of each ordering type.
neighbors	ndarray or None	(N, 16) int32, the neighbors of each atom in the order of the points of its template, -1 after its count, when asked for.

Ackland-Jones analysis

AcklandJonesAnalysis

Ackland-Jones bond-angle analysis: fcc, hcp, bcc and icosahedral atoms.

compute

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

The structure type of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	Neighbors of this system with at least the 14 nearest of each atom.	None

Returns:

Type	Description
StructureResult	Types other, fcc, hcp, bcc and ico.

Raises:

Type	Description
InvalidParameter	If an atom has fewer than 14 neighbors in the given list.

Centro-symmetry parameter

CentroSymmetryParameter

CentroSymmetryParameter(num_neighbors=12)

The centro-symmetry parameter: zero for an atom whose neighbors come in opposite pairs.

Parameters:

Name	Type	Description	Default
num_neighbors	int32	Number of nearest neighbors, even: 12 for fcc, 8 for bcc. Default 12.	12

compute

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

The parameter of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	Neighbors of this system with at least num_neighbors per atom.	None

Returns:

Type	Description
CentroSymmetryResult	The parameter of each atom.

Raises:

Type	Description
InvalidParameter	If an atom has fewer neighbors.

CentroSymmetryResult dataclass

CentroSymmetryResult(csp)

Bases: Result

The centro-symmetry parameter of each atom.

Attributes:

Name	Type	Description
csp	ndarray	(N,) float64 parameter in Ų.

Common neighbor parameter

CommonNeighborParameter

CommonNeighborParameter(cutoff)

The common neighbor parameter: zero for an atom whose neighbors and their common neighbors are arranged symmetrically, as in fcc and bcc.

Parameters:

Name	Type	Description	Default
cutoff	float64	Neighbors and common neighbors are closer than cutoff, in Å.	required

compute

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

The parameter of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	A neighbor list of this system with at least the cutoff.	None

Returns:

Type	Description
CommonNeighborParameterResult	The parameter of each atom.

CommonNeighborParameterResult dataclass

CommonNeighborParameterResult(cnp)

Bases: Result

The common neighbor parameter of each atom.

Attributes:

Name	Type	Description
cnp	ndarray	(N,) float64 parameter in Ų; NaN for an atom without neighbors.

Diamond structure

DiamondStructure

Cubic and hexagonal diamond structures, from the arrangement of the second neighbors of each atom, and the first and second neighbors of diamond atoms.

compute

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

The structure type of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	Neighbors of this system with at least the 4 nearest of each atom.	None

Returns:

Type	Description
StructureResult	Types other, cubic_diamond, cubic_diamond_first_neighbor, cubic_diamond_second_neighbor, hexagonal_diamond, hexagonal_diamond_first_neighbor and hexagonal_diamond_second_neighbor.

Raises:

Type	Description
InvalidParameter	If an atom has fewer than 4 neighbors.

CHILL+

ChillPlus

ChillPlus(cutoff=3.5)

CHILL+: ice, clathrate hydrate and liquid water, from the correlation of the bond order of neighboring molecules.

Parameters:

Name	Type	Description	Default
cutoff	float64	Neighbors are the molecules closer than cutoff, in Å. Default 3.5, for the oxygen atoms of water.	3.5

compute

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

The type of each molecule.

Parameters:

Name	Type	Description	Default
system	System	One atom per molecule, for water its oxygen atoms.	required
neighbors	NeighborList	A neighbor list of this system reaching at least cutoff.	None

Returns:

Type	Description
StructureResult	Types other, hexagonal_ice, cubic_ice, interfacial_ice, hydrate and interfacial_hydrate.

Planar faults

PlanarFaults

PlanarFaults(structures=('fcc', 'hcp', 'bcc'), *, rmsd_cutoff=0.1, extrinsic=False)

Planar faults of fcc crystals: the hcp-like atoms of stacking faults and twin boundaries, found by polyhedral template matching.

Parameters:

Name	Type	Description	Default
structures	iterable of str	The structures polyhedral template matching looks for; fcc and hcp among them. Default fcc, hcp and bcc.	('fcc', 'hcp', 'bcc')
rmsd_cutoff	float64	Atoms whose root-mean-square deviation from the best template is larger are other; 0 for no cutoff. Default 0.1.	0.1
extrinsic	bool	Also find extrinsic stacking faults, two planes of hcp-like atoms with one plane of fcc atoms between them, which are otherwise two coherent twin boundaries. Default False.	False

compute

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

The planar fault type of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
ptm	PTMResult	Polyhedral template matching of system already done, with the neighbors in the order of the templates; done here when not given.	None
neighbors	NeighborList	Neighbors of system with at least the 18 nearest of each atom, for the template matching.	None

Returns:

Type	Description
PlanarFaultResult	The fault types.

Raises:

Type	Description
InvalidParameter	If ptm is not of system or has no neighbors in the order of the templates.

PlanarFaultResult dataclass

PlanarFaultResult(fault, names, colors, interatomic_distance)

Bases: Result

The planar fault type of each atom.

Attributes:

Name	Type	Description
fault	ndarray	(N,) int8 type of each atom, an index into names.
names	tuple of str	Name of each type.
colors	tuple of tuple of float64	Default RGB color of each type, from 0 to 1.
interatomic_distance	ndarray	(N,) float64 distance in Å between nearest neighbors of the lattice each atom matched, from polyhedral template matching.

counts

counts()

Number of atoms of each type, by name.

areas

areas()

Area in Ų of the intrinsic stacking faults, each two layers of atoms, of the coherent twin boundaries, each one, and of the extrinsic stacking faults, each two.

Grain segmentation

GrainSegmentation

GrainSegmentation(threshold=None, *, method='graph', min_grain_size=100, stacking_faults=True, adopt_orphans=True, structures=('fcc', 'hcp', 'bcc'), rmsd_cutoff=0.1)

Grains of a polycrystal: groups of crystalline atoms of nearly the same lattice orientation, from polyhedral template matching, as OVITO's Grain segmentation modifier finds them.

Parameters:

Name	Type	Description	Default
threshold	float64	With method="graph", the largest log merge distance of the merges kept; by default chosen from the merges. With method="spanning_tree", the largest misorientation in degrees, needed.	None
method	str	"graph": clusters merged by node pair sampling of the graph of bonds weighted by their misorientation; "spanning_tree": merged along the bonds of least misorientation. Default "graph".	'graph'
min_grain_size	int64	Clusters of fewer atoms are no grains. Default 100.	100
stacking_faults	bool	The atoms of stacking faults and twin boundaries, hcp in fcc and hexagonal in cubic diamond or the other way round, join the grains around them. Default True.	True
adopt_orphans	bool	Atoms in no grain join the grain nearest along their bonds. Default True.	True
structures	iterable of str	The structures polyhedral template matching looks for. Default fcc, hcp and bcc.	('fcc', 'hcp', 'bcc')
rmsd_cutoff	float64	Atoms whose root-mean-square deviation from the best template is larger are of no structure; 0 for no cutoff. Default 0.1.	0.1

compute

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

The grains of system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, in a box at least twice as wide as their bonds along its periodic directions.	required
ptm	PTMResult	Polyhedral template matching of system already done, with orientations and the neighbors in the order of the templates; done here when not given.	None
neighbors	NeighborList	Neighbors of system with at least the 18 nearest of each atom, for the template matching.	None

Returns:

Type	Description
GrainResult	The grain of each atom and the grains.

Raises:

Type	Description
InvalidParameter	If ptm is not of system or has no neighbors in the order of the templates, or if the box is too short for the bonds.

GrainResult dataclass

GrainResult(grain, size, structure, names, orientation, center, radius, radius_of_gyration, colors, threshold, merge_distance, merge_size)

Bases: Result

The grains of a polycrystal.

Attributes:

Name	Type	Description
grain	ndarray	(N,) int64 grain of each atom, an index into the arrays of the grains, -1 for none.
size	ndarray	(G,) int64 number of atoms of each grain, largest first.
structure	ndarray	(G,) int8 structure of each grain, an index into names.
names	tuple of str	Names of the structures, those of polyhedral template matching.
orientation	ndarray	(G, 4) float64 mean lattice orientation of each grain as a quaternion (x, y, z, w).
center	ndarray	(G, 3) float64 center of mass of each grain in Å, inside the box.
radius	ndarray	(G,) float64 radius in Å of the smallest sphere about the center that holds the grain.
radius_of_gyration	ndarray	(G,) float64 radius of gyration in Å.
colors	ndarray	(G, 3) float64, a color for each grain, RGB from 0 to 1.
threshold	float64	The threshold applied: the log merge distance of graph clustering, or the misorientation in degrees of the spanning tree.
merge_distance	ndarray	(M,) float64 merge distance (graph clustering) or misorientation in degrees (spanning tree) of each merge of two clusters of at least 20 atoms, in the order of the merges.
merge_size	ndarray	(M,) float64 number of atoms of the smaller cluster of each of these merges.

count property

count

Number of grains.

atom_colors

atom_colors(none=(0.8, 0.8, 0.8))

(N, 3) the color of the grain of each atom, none for atoms in no grain.

Space group

SpaceGroup

SpaceGroup(*, tolerance=1e-05)

The space group of a crystal, its symmetry operations and the atoms they make equivalent, found by spglib.

Parameters:

Name	Type	Description	Default
tolerance	float64	Distance in Å within which atoms count as images of each other. Default 1e-5.	1e-05

compute

compute(system)

The space group of a crystal.

Parameters:

Name	Type	Description	Default
system	System	The cell of the crystal, periodic in every direction, of at most 2000 atoms; atoms of different elements, or else of different types, are different.	required

Returns:

Type	Description
SpaceGroupResult	The space group, its operations and the equivalent atoms.

Raises:

Type	Description
InvalidParameter	If the box is not periodic, there are no atoms or more than 2000, or spglib is not installed.

SpaceGroupResult dataclass

SpaceGroupResult(number, symbol, rotations, translations, equivalent)

Bases: Result

The space group of a crystal.

Attributes:

Name	Type	Description
number	int32	The number of the space group in the International Tables, 1 to 230.
symbol	str	Its Hermann–Mauguin symbol, such as "Fm-3m".
rotations	ndarray	(K, 3, 3) float64, the rotations of the K symmetry operations, acting on Cartesian column vectors.
translations	ndarray	(K, 3) float64, their translations in Å: operation k moves the point r to rotations[k] @ r + translations[k].
equivalent	ndarray	(N,) int64 the first atom that symmetry makes each atom equivalent to.