VoroTop

VoroTop identifies local structure by comparing the topology of each particle's Voronoi cell against a filter: a list of the cell topologies associated with each structure of interest. VoroTypes is a companion Python program that builds such filters exactly. Given a crystal structure, it enumerates every combinatorial type of Voronoi cell that can arise from an infinitesimal perturbation of the crystal, and writes the result as a filter file that VoroTop and the VoroTop modifier in OVITO can read directly.

For some structures, such as BCC, the Voronoi cell is unchanged by small perturbations, and a single topology suffices. In many others, including FCC, HCP and most intermetallics, the Voronoi tessellation has degenerate vertices at which more than four cells meet. Thermal motion resolves each degenerate vertex in one of several ways, so a single crystal gives rise to many distinct cell topologies: 2,815 for FCC and 9,556 for HCP. VoroTypes finds all of them by enumerating the triangulations of each degenerate vertex and combining them, rather than by sampling. Filters built this way are complete and reproducible, which matters most for complex crystals, where sampling can miss rare types.

VoroTypes requires Python 3.10 or later and pymatgen. It is available on GitHub; the current version is 1.2.

git clone https://github.com/VoroTop/VoroTypes.git
cd VoroTypes
pip install -r requirements.txt

VoroTypes reads CIF and POSCAR files, such as those available from the Materials Project. The following command enumerates the Voronoi cell types of aluminum (FCC) and writes the filter file AL_MP-134.filter, listing all Weinberg vectors for each symmetrically distinct atom site:

python enumerate_cells.py Al_mp-134.cif

The filter is then used with VoroTop in the usual way:

VoroTop system.dump -f AL_MP-134.filter -l

Three nested filter variants can be produced. The default filter contains every fully resolved cell type, and is recommended for finite-temperature simulations. The option --primary restricts the filter to primary resolutions, those that occur with positive probability in the limit of vanishing perturbation. The option --all-types adds partially resolved types, in which some degenerate vertices remain unresolved.

The full list of options and further examples are given in the README.

Version 1.2 adds support for two-dimensional crystals through the option -2, mirroring VoroTop's own -2 option. In two dimensions the topology of a Voronoi cell is recorded by its p-vector: the number of edges of the cell, followed by the numbers of edges of its neighbors in cyclic order (see Lazar et al., 2024). Square, triangular, kagome, Lieb and honeycomb lattices are built in:

python enumerate_cells.py -2 square
VoroTop system.dump -2 -f square.filter -l

Other lattices can be described in a short text file giving the two lattice vectors and the fractional coordinates of each atom, as in this example for the Lieb lattice. Ready-made filters for the square, triangular, Lieb and kagome lattices are available in the Filter Library, together with a note on why the honeycomb lattice is not included.

The Filter Library contains VoroTypes filters for 1,088 stable materials from the Materials Project, spanning all seven crystal systems and 91 space groups, as well as the two-dimensional lattices above. Filters for common structures such as BCC, FCC and HCP are also listed on the Download page.

Some crystals have degenerate vertices of high order, and the number of ways to resolve them all grows very quickly. Structures for which this number is much above 10⁶ may be impractical to enumerate; for these, VoroTop's -mf option builds a filter stochastically by sampling perturbed copies of the crystal. The enumeration also depends on the exact atomic coordinates, so the reference structure should match the one used in the simulation.

Users of VoroTypes are asked to cite:

• Lazar, E.A. and Rycroft, C.H., "VoroTypes: automated enumeration of Voronoi cell topologies for structural identification of complex crystals in atomistic simulations", arXiv, 2026.
• Lazar, E.A. and Rycroft, C.H., "Structural identification in general crystalline systems via Voronoi cell topology", arXiv, 2026.

Two-dimensional Voronoi topology, including p-vectors, is discussed in:

• Lazar, E.A., Lu, J., Rycroft, C.H., and Schwarcz, D., "Characterizing structural features of two-dimensional particle systems through Voronoi topology", arXiv, Model. Simul. Mater. Sci. Eng. 32:085022, 2024.