Local order

Radial distribution function

RadialDistributionFunction

RadialDistributionFunction(r_max, bins=200)

The radial distribution function g(r) and its partial functions.

Parameters:

Name	Type	Description	Default
r_max	float64	Largest distance in Å.	required
bins	int32	Number of bins of equal width. Default 200.	200

compute

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

The functions of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms; partial functions need an element column.	required
neighbors	NeighborList	A neighbor list of this system with a cutoff of at least r_max.	None

Returns:

Type	Description
RadialDistributionResult	The functions, normalized by the number density of the box.

RadialDistributionResult dataclass

RadialDistributionResult(r, edges, g, coordination, partial)

Bases: Result

A radial distribution function and its partial functions.

Attributes:

Name	Type	Description
r	ndarray	(bins,) float64 centers of the bins in Å.
edges	ndarray	(bins + 1,) float64 edges of the bins in Å.
g	ndarray	(bins,) float64, the radial distribution function.
coordination	ndarray	(bins,) float64 mean number of neighbors closer than the upper edge of each bin.
partial	dict	(bins,) partial function of each pair of elements (a, b), a not after b by atomic number; empty without an element column.

pair

pair(a, b)

The partial function of elements a and b, in either order.

Coordination

CoordinationNumber

CoordinationNumber(cutoff=None, *, cutoffs=None)

The number of neighbors of each atom within a cutoff.

Parameters:

Name	Type	Description	Default
cutoff	float64	Cutoff in Å for every pair.	None
cutoffs	dict	Cutoff in Å for each pair of elements (a, b), in either order; pairs not given are never neighbors. Give cutoff or cutoffs.	None

compute

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

The counts of a system.

Parameters:

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

Returns:

Type	Description
CoordinationResult	The counts of each atom.

CoordinationResult dataclass

CoordinationResult(coordination, partial)

Bases: Result

Number of neighbors of each atom.

Attributes:

Name	Type	Description
coordination	ndarray	(N,) int64 number of neighbors.
partial	dict	(N,) int64 number of neighbors of each element, by element; empty without an element column.

CoordinationPolyhedra

CoordinationPolyhedra(cutoff=None, *, num_neighbors=None, bonds=False)

The convex hull of the neighbors of atoms, as OVITO's coordination polyhedra. Give exactly one of cutoff, num_neighbors and bonds.

Parameters:

Name	Type	Description	Default
cutoff	float64	The neighbors closer than this, in Å.	None
num_neighbors	int32	The nearest neighbors, this many.	None
bonds	bool	The atoms bonded to each, by the bonds of the topology.	False

compute

compute(system, atoms=None)

The polyhedra about some atoms of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
atoms	array_like	A boolean mask or indices of the atoms at the middle of the polyhedra. Default all.	None

Returns:

Type	Description
CoordinationPolyhedraResult	The mesh of the polyhedra and their volumes.

CoordinationPolyhedraResult dataclass

CoordinationPolyhedraResult(mesh, atoms, owners, volumes)

Bases: Result

Coordination polyhedra.

Attributes:

Name	Type	Description
mesh	TriangleMesh	The faces of every polyhedron, its vertices at the neighbors next to the atom, whole, even where they stick out of the box.
atoms	ndarray	(M,) int64, the atom at the middle of each polyhedron.
owners	ndarray	(F,) int64, the polyhedron of each triangle of the mesh, an index of atoms.
volumes	ndarray	(M,) float64, the volume of each polyhedron in ų; 0 for fewer than four neighbors or neighbors in a plane.

Bond angles

BondAngleDistribution

BondAngleDistribution(cutoff=None, bins=180, *, cutoffs=None)

The distribution of the angles between the bonds of each atom, in total and for each triplet of elements.

Parameters:

Name	Type	Description	Default
cutoff	float64	Bond length in Å for every pair.	None
bins	int32	Number of bins from 0 to 180 degrees. Default 180.	180
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

compute

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

The distribution 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
BondAngleResult	Counts of the angles between every two bonds of an atom.

BondAngleResult dataclass

BondAngleResult(angle, edges, counts, density, partial)

Bases: Result

The distribution of angles between bonds of the same atom.

Attributes:

Name	Type	Description
angle	ndarray	(bins,) float64 centers of the bins in degrees.
edges	ndarray	(bins + 1,) float64 edges of the bins in degrees.
counts	ndarray	(bins,) int64 number of angles in each bin.
density	ndarray	(bins,) float64, the counts normalized to unit area, per degree.
partial	dict	(bins,) int64 counts of the angles b-a-c for each triplet of elements (a, b, c): the atom a at the vertex, its neighbors b and c, b not after c by atomic number; empty without an element column.

triplet

triplet(vertex, b, c)

The counts of the angles b-vertex-c, b and c in either order.

Bond lengths

BondLengthDistribution

BondLengthDistribution(bins=100, cutoff=None)

The distribution of the lengths of the bonds of a topology, in total and for each pair of elements, as OVITO's bond length distribution.

Parameters:

Name	Type	Description	Default
bins	int32	Number of bins. Default 100.	100
cutoff	float64	The upper end of the bins in Å; longer bonds are not counted. By default the longest bond.	None

compute

compute(system)

The distribution of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms with bonds in their topology, such as those of a LAMMPS data file or of covalent_bonds; each bond is measured to the nearest periodic image of its second atom.	required

Returns:

Type	Description
BondLengthResult	The counts of the lengths, from 0 to the cutoff.

BondLengthResult dataclass

BondLengthResult(length, edges, counts, density, lengths, partial)

Bases: Result

The distribution of the lengths of the bonds of a topology.

Attributes:

Name	Type	Description
length	ndarray	(bins,) float64 centers of the bins in Å.
edges	ndarray	(bins + 1,) float64 edges of the bins in Å.
counts	ndarray	(bins,) int64 number of bonds in each bin.
density	ndarray	(bins,) float64, the counts normalized to unit area, per Å.
lengths	ndarray	(bonds,) float64, the length of each bond, in the order of the topology.
partial	dict	(bins,) int64 counts of the bonds between each pair of elements (a, b), a not after b by atomic number; empty without an element column.

pair

pair(a, b)

The counts of the bonds a-b, a and b in either order.

Structure factor

StructureFactor

StructureFactor(q_max, bins=200, *, method='direct', r_max=None)

The static structure factor S(q) of a periodic system and its partial factors.

Parameters:

Name	Type	Description	Default
q_max	float64	Largest |q| in 1/Å.	required
bins	int32	Number of bins of |q| of equal width. Default 200.	200
method	(direct, debye)	Sum over the wave vectors that fit the box (default), or transform of the radial distribution function up to r_max.	"direct"
r_max	float64	Largest distance of the Debye method in Å; default half the length of the longest lattice vector.	None

compute

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

The structure factor of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms in a box periodic in every direction; partial factors need an element column.	required
neighbors	NeighborList	With the Debye method, a neighbor list of this system reaching r_max.	None

Returns:

Type	Description
StructureFactorResult	The factor averaged over shells of |q|.

StructureFactorResult dataclass

StructureFactorResult(q, edges, s, vectors, partial, faber_ziman, method)

Bases: Result

A static structure factor and its partial factors.

Attributes:

Name	Type	Description
q	ndarray	(bins,) float64 centers of the bins of |q| in 1/Å.
edges	ndarray	(bins + 1,) float64 edges of the bins in 1/Å.
s	ndarray	(bins,) float64, the structure factor; with the direct method, averaged over the vectors of each bin and NaN in bins without vectors.
vectors	ndarray or None	(bins,) int64 number of vectors in each bin, one of each pair q, -q, with the direct method; None with the Debye method.
partial	dict	(bins,) partial factor S_ab of each pair of elements (a, b), a not after b by atomic number, normalized so that s is the sum of S_aa and twice S_ab; empty without an element column.
faber_ziman	dict	(bins,) Faber-Ziman partial factor A_ab of each pair, keyed as partial.
method	str	"direct" or "debye".

pair

pair(a, b)

The partial factor S_ab of elements a and b, in either order.

Spatial correlation

SpatialCorrelation

SpatialCorrelation(first, second=None, *, grid_spacing=3.0, window=True, direct=False, cutoff=5.0, bins=50)

The spatial correlation function of two properties of the atoms, the mean of the first at one place times the second at a distance r from it, by fast Fourier transforms on a grid, as OVITO's spatial correlation function.

Parameters:

Name	Type	Description	Default
first	str	A column of one value per atom, a component such as "velocities.x", or an expression over the columns.	required
second	str	The other property; default the first, its autocorrelation.	None
grid_spacing	float64	The approximate size in Å of the cells of the grid. Default 3.	3.0
window	bool	Weight the atoms by a Hann window along the directions of the box that are not periodic. Default True.	True
direct	bool	Also sum the correlation over the pairs of neighbors closer than cutoff. Default False.	False
cutoff	float64	The distance in Å of the direct summation. Default 5.	5.0
bins	int32	The number of bins of the direct summation. Default 50.	50

compute

compute(system)

The correlation function of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, in a box of some volume.	required

Returns:

Type	Description
SpatialCorrelationResult	The correlation in real and reciprocal space and the moments of the two properties.

Raises:

Type	Description
InvalidParameter	For a property that is not one number per atom, no atoms, or a grid spacing larger than a quarter of the box.

SpatialCorrelationResult dataclass

SpatialCorrelationResult(r, correlation, rdf, q, reciprocal, means, mean_squares, mean_product, neighbor_r=None, neighbor_correlation=None, neighbor_rdf=None)

Bases: Result

The spatial correlation function of two properties.

Attributes:

Name	Type	Description
r	ndarray	(bins,) float64 centers of the distance bins in Å, up to half the shortest distance between opposite faces of the box.
correlation	ndarray	(bins,) float64, the correlation function in each bin, from the grid.
rdf	ndarray	(bins,) float64, the radial distribution function of the same grid.
q	ndarray	(wavevectors,) float64 centers of the wavevector bins in 1/Å.
reciprocal	ndarray	(wavevectors,) float64, the correlation function in reciprocal space.
means	ndarray	(2,) float64, the mean of each property over the atoms.
mean_squares	ndarray	(2,) float64, the mean of the square of each property.
mean_product	float64	The mean over the atoms of the product of the two properties.
neighbor_r	ndarray or None	(neighbor bins,) float64 centers of the bins of the direct summation in Å, when computed.
neighbor_correlation	ndarray or None	(neighbor bins,) float64, the correlation function summed over the pairs of neighbors, when computed.
neighbor_rdf	ndarray or None	(neighbor bins,) float64, the radial distribution function of the pairs of neighbors, when computed.

Steinhardt parameters

SteinhardtParameters

SteinhardtParameters(degrees=(4, 6), *, num_neighbors=None, cutoff=None, voronoi=False, weighted=False, average=False, solid=False, solid_degree=6, bond_threshold=0.7, min_solid_bonds=7)

Steinhardt bond-orientational order parameters q_l.

Parameters:

Name	Type	Description	Default
degrees	sequence of int32	The degrees l, from 0 to 20. Default (4, 6).	(4, 6)
num_neighbors	int32	The neighbors of an atom are its num_neighbors nearest; default 12 unless cutoff or voronoi is given.	None
cutoff	float64	The neighbors of an atom are those closer than cutoff, in Å.	None
voronoi	bool	The neighbors of an atom are those that share a face of its Voronoi cell. Default False.	False
weighted	bool	With voronoi, weight each neighbor by the area of its face. Default False.	False
average	bool	Average the harmonics of each atom with those of its neighbors first (Lechner and Dellago). Default False.	False
solid	bool	Also tell solid-like atoms from liquid-like ones by their bonds (ten Wolde, Ruiz-Montero and Frenkel). Default False.	False
solid_degree	int32	With solid, the degree l of the harmonics of the bonds. Default 6.	6
bond_threshold	float64	With solid, a bond is solid-like when the normalized product of the harmonics of its two atoms exceeds it. Default 0.7.	0.7
min_solid_bonds	int32	With solid, an atom is solid-like with at least so many solid-like bonds. Default 7.	7

compute

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

The parameters of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
neighbors	NeighborList	Neighbors of this system: within at least cutoff, at least num_neighbors per atom, or, with voronoi, Voronoi neighbors.	None

Returns:

Type	Description
SteinhardtResult	q_l of each atom; atoms without neighbors have 0. With solid, also the solid-like bonds and atoms.

SteinhardtResult dataclass

SteinhardtResult(degrees, q, average, solid_bonds=None, solid=None, voronoi=False, weighted=False)

Bases: Result

Order parameters of each atom.

Attributes:

Name	Type	Description
degrees	tuple of int32	The degrees l.
q	ndarray	(N, len(degrees)) float64, the parameter q_l of each atom and degree.
average	bool	Whether the parameters are averaged over the neighbors.
solid_bonds	ndarray or None	(N,) int32 the number of solid-like bonds of each atom, with solid; else None.
solid	ndarray or None	(N,) bool whether each atom is solid-like, with solid; else None.
voronoi	bool	Whether the neighbors are those of the Voronoi tessellation.
weighted	bool	Whether they are weighted by the areas of the faces.

Warren-Cowley parameters

WarrenCowley

WarrenCowley(cutoff=None, *, num_neighbors=None)

Warren-Cowley parameters of chemical short-range order.

Parameters:

Name	Type	Description	Default
cutoff	float64 or sequence of float64	Neighbors closer than cutoff, in Å; increasing cutoffs make shells of neighbors, each from the cutoff before it to its own.	None
num_neighbors	int32 or sequence of int32	The num_neighbors nearest neighbors; a sequence makes shells of the nearest neighbors, the first so many nearest, then the next so many. Give cutoff or num_neighbors.	None

compute

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

The parameters 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 cutoff, or at least num_neighbors per atom.	None

Returns:

Type	Description
WarrenCowleyResult	The parameter of each pair of elements; NaN for an element whose atoms have no neighbors.

WarrenCowleyResult dataclass

WarrenCowleyResult(elements, alpha)

Bases: Result

Warren-Cowley short-range order parameters.

Attributes:

Name	Type	Description
elements	tuple of str	The elements, by atomic number.
alpha	ndarray	(elements, elements) float64 parameter of each pair: row a, column b is 1 - p(b | a) / c_b; (shells, elements, elements) for shells of neighbors.

Voronoi analysis

VoronoiAnalysis

VoronoiAnalysis(*, face_threshold=0.0, relative_face_threshold=0.0, edge_threshold=0.0, faces=False, polyhedra=False)

Voronoi cells: the region of space closer to each atom than to any other, periodic images included.

Parameters:

Name	Type	Description	Default
face_threshold	float64	Faces of this area or less, in Ų, do not count. Default 0.	0.0
relative_face_threshold	float64	Faces of this fraction of the surface of their cell or less do not count, from 0 to below 1. Default 0.	0.0
edge_threshold	float64	Edges shorter than this, in Å, do not count; faces with fewer than three edges that count do not count. Default 0.	0.0
faces	bool	Also give the faces of each cell that count: the atom across each, its area and its edges. Default False.	False
polyhedra	bool	Also give the shapes of the cells. Default False.	False

compute

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

The cells of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, no two at the same position. Directions that are not periodic are closed by the faces of the box, moved out as far as needed to include every atom.	required

Returns:

Type	Description
VoronoiResult	The cell of each atom.

VoronoiResult dataclass

VoronoiResult(volume, coordination, radius, offsets=None, j=None, shifts=None, areas=None, edges=None, polyhedra=None)

Bases: Result

Voronoi cells of the atoms.

Attributes:

Name	Type	Description
volume	ndarray	(N,) float64 volume of each cell in ų.
coordination	ndarray	(N,) int64 number of faces that count shared with other atoms.
radius	ndarray	(N,) float64 distance from each atom to the farthest vertex of its cell, in Å.
offsets	ndarray or None	(N + 1,) int64: the faces that count of atom i are offsets[i]:offsets[i + 1]; with the faces.
j	ndarray or None	(F,) int32, the atom across each face, or -1 for a wall of the box, of mdapy.index_dtype; with the faces.
shifts	ndarray or None	(F, 3) int8 periodic image of that atom; with the faces.
areas	ndarray or None	(F,) float64 area of each face in Ų; with the faces.
edges	ndarray or None	(F,) int32 number of edges of each face that count; with the faces.
polyhedra	VoronoiPolyhedra or None	The shapes of the cells, when asked for.

index

index(largest=8)

The Voronoi index of each cell.

Parameters:

Name	Type	Description	Default
largest	int32	The largest number of edges counted. Default 8.	8

Returns:

Type	Description
ndarray	(N, largest - 2) int64 number of faces with 3, 4, ..., largest edges shared with other atoms.

Raises:

Type	Description
InvalidParameter	For largest below 3, or a result without the faces.

VoronoiPolyhedra dataclass

VoronoiPolyhedra(vertices, vertex_offsets, face_offsets, corner_offsets, corners, j, areas)

Bases: Result

The shapes of the Voronoi cells: their vertices and all their faces.

Attributes:

Name	Type	Description
vertices	ndarray	(V, 3) float64 positions of the vertices in Å, each cell with its own.
vertex_offsets	ndarray	(N + 1,) int64: the vertices of the cell of atom i are vertex_offsets[i]:vertex_offsets[i + 1].
face_offsets	ndarray	(N + 1,) int64: the faces of the cell of atom i are face_offsets[i]:face_offsets[i + 1].
corner_offsets	ndarray	(F + 1,) int64: the corners of face f are corners[corner_offsets[f]:corner_offsets[f + 1]].
corners	ndarray	(C,) int64 vertex of each corner, counterclockwise seen from outside the cell.
j	ndarray	(F,) int32, the atom across each face, or -1 for a wall of the box, of mdapy.index_dtype.
areas	ndarray	(F,) float64 area of each face in Ų.

Ring statistics

RingStatistics

RingStatistics(max_size=8, *, min_size=3, cutoff=None, cutoffs=None)

The rings of a network of bonds: closed paths through distinct atoms in which no two atoms are closer through the network than along the ring (shortest-path rings).

Parameters:

Name	Type	Description	Default
max_size	int32	The largest ring, at most 36. Default 8.	8
min_size	int32	The smallest ring, at least 3. Default 3.	3
cutoff	float64	Atoms closer than it, in Å, are bonded.	None
cutoffs	dict	The bond length in Å of each pair of elements (a, b), in either order; pairs not given are never bonded. Without cutoff or cutoffs, the bonds of the topology of the system.	None

compute

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

The rings of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column for cutoffs per pair of elements, or bonds in their topology without a cutoff.	required

Returns:

Type	Description
RingResult	The rings, their sizes and how many each atom is in.

Raises:

Type	Description
MissingProperty	Without a cutoff, for a system without bonds in its topology; with cutoffs per pair of elements, without an element column.

RingResult dataclass

RingResult(atoms, shifts, sizes, counts, per_atom)

Bases: Result

The rings of a network of bonds.

Attributes:

Name	Type	Description
atoms	ndarray	(M, max_size) int64 the atoms of each ring in order around it, from its atom of the smallest index on toward the smaller of its two neighbors; -1 after the last.
shifts	ndarray	(M, max_size, 3) int32 the periodic image of each atom of a ring relative to its first atom.
sizes	ndarray	(M,) int64 the number of atoms of each ring.
counts	ndarray	(max_size + 1,) int64 the number of rings of each size.
per_atom	ndarray	(N,) int64 the number of rings each atom is in.

polygons

polygons(system)

The rings as polygons, for pictures.

Parameters:

Name	Type	Description	Default
system	System	The system of the rings.	required

Returns:

Name	Type	Description
mesh	TriangleMesh	A fan of triangles about the center of each ring, across the periodic boundaries of the box.
ring	ndarray	(F,) int64, the ring of each triangle, for colors such as by its size.

Entropy fingerprint

EntropyFingerprint

EntropyFingerprint(cutoff, sigma=0.2, *, local_density=False, average_cutoff=None)

The pair entropy fingerprint of Piaggi and Parrinello.

Parameters:

Name	Type	Description	Default
cutoff	float64	Largest distance of the local radial distribution, in Å.	required
sigma	float64	Width of the Gaussian that smears each neighbor, in Å, and of the bins. Default 0.2.	0.2
local_density	bool	Use the density of the neighbors within cutoff of each atom instead of that of the system. Default False.	False
average_cutoff	float64	Average each atom's value with those of its neighbors closer than this, in Å.	None

compute

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

The fingerprint of each atom.

Parameters:

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

Returns:

Type	Description
EntropyResult	The fingerprint of each atom.

EntropyResult dataclass

EntropyResult(entropy, average, local_density=False)

Bases: Result

The pair entropy fingerprint of each atom.

Attributes:

Name	Type	Description
entropy	ndarray	(N,) float64 entropy in units of the Boltzmann constant; more negative is more ordered.
average	bool	Whether it is averaged over neighbors.
local_density	bool	Whether it uses the density around each atom.