Voronoi tessellation

VoroTop

Voronoi Cell Topology Visualization & Analysis Toolkit

General Overview

VoroTop is a command-line tool written in C++14 which can be used to analyze systems of particles in two- and three-dimensional space. VoroTop reads input that includes information regarding the number of particles, their coordinates, and boundary conditions of the system. After using Voro++ to compute the Voronoi cell of each atom, VoroTop then determines its topology. This data can be saved as is or further processed. Voronoi topology allows us to study the structure of these systems, and greatly aids us in visualizing them.

Please see the VoroTop Tutorial Through Examples for hands-on lessons for learning how to use VoroTop. Through carefully designed examples, you will learn to perform various types of Voronoi topology analysis, starting from basic calculations to more advanced techniques.

A more complete description of VoroTop can be found in the paper, "VoroTop: Voronoi Cell Topology Visualization and Analysis Toolkit", in Model. Simul. Mater. Sci. Eng. (arXiv).

Command-line Options
Documentation for older versions is available for version 0.4 and version 0.3.

VoroTop is run from the command line as follows:

VoroTop <filename> [options]

The [options] allow the user to specify desired output as follows:

-2 By default, systems are treated as three-dimensional. If this option is specified, then the system is interpreted as two-dimensional. If x, y, and z coordinates are all specified, then only the x and y coordinates are considered.
-f Specifies a filter file to use for analysis. If this option is used, then a new LAMMPS dump output file will be created that includes the original data plus the structure types as determined by the given filter.
-mf Generates a filter file from a crystal structure. The input structure is replicated to at least a 5×5×5 supercell, and the Voronoi topology of each particle is computed. Good-Turing coverage and Chao1 estimates are included in the filter file header. This option supports both exact and perturbation modes.
-l Outputs a LAMMPS dump file with classification data. This is the default output format when -f is used alone.
-vt The Voronoi topology of each particle in the system is computed and saved to disk. In two-dimensional systems, the following information is recorded for the Voronoi cell of each particle: its number of edges, its number of neighbors with 3, 4, 5, etc. edges, its canonical p-vector, the order of its symmetry group, and its chirality. Left-handed chirality is indicated by -1, right-handed chirality is indicated by 1, and a non-chiral Voronoi topology is indicated by 0.

In three-dimensional systems, Weinberg's graph-tracing algorithm is used to compute the topology of each Voronoi cell and store it as a vector of integers, which is recorded to an output file <filename.wvectors>. The following is also recorded for each atom: the number of faces, the face-index (i.e., the number of faces with each number of edges), and the order of the automorphism group of the Voronoi cell. The chirality of the Voronoi cell (+1 or -1 for chiral cells, 0 for achiral ones) is also recorded.
-d This option calculates the distribution of Voronoi topologies, and records it as a histogram of p-vectors (in two dimensions) or Weinberg vectors (in three dimensions) to a file <filename.distribution>.
-g This feature computes a distribution of topologies from perturbed versions of the input system. The input structure is replicated to build a sufficiently large sample, and perturbations are applied. The first parameter specifies the target sample count and the second specifies the perturbation magnitude. Perturbations are sampled from a normal Gaussian centered at the origin and with a standard deviation equal to the specified magnitude times the square root of the Voronoi cell area, in two dimensions, or the cubed root of the Voronoi cell volume, in three dimensions; a magnitude of 0.05 is suggested. Good-Turing coverage and Chao1 estimates are included in the output distribution file.
-r To each indeterminate structure type is associated two resolving structure types, with one preferred. If more perturbed copies resolve to the non-preferred structure type than to the preferred type, then that is considered the resolved type; otherwise the preferred type is considered the resolved type. This feature requires a filter that includes information about which structure types are indeterminate and how they should be resolved. By default, 5 perturbations are considered, though a different number can be specified at the command line. Output includes both the indeterminate and resolved structure types.
-c Clusters of defect atoms are identified and recorded. Each defect and crystal cluster is assigned a unique index, ordered by size. Positive indices indicate crystal clusters; negative indices indicate defect clusters. Also recorded for each atom is the size of the cluster to which it belongs. By default, all atoms with structure types listed in the specified filter are treated as crystalline, and defect clusters are built only from atoms whose structure types are not listed. If an index is specified, then only atoms with that structure type are considered crystalline for the purpose of cluster analysis, and clusters are built from atoms with other structure types. If the -r option is specified, then cluster analysis uses resolved types for analysis.
-v Computes the Voronoi pair correlation function, as described here or here. This is the average number of Voronoi neighbors at each Voronoi distance from a central particle, averaged over all particles and normalized by data from the ideal gas. If an integer is specified, then the program will compute the Voronoi pair correlation function up to that maximum k; if left unspecified, this will be computed up to k=50.

The -u option outputs the unnormalized version of the Voronoi pair correlation function. This is the average number of Voronoi neighbors at each Voronoi distance from a central particle, averaged over all particles.
-e Outputs an EPS (Encapsulated PostScript) image for two-dimensional systems. A coloring scheme can be specified by index (0–8), using a 12-color palette.
-n Suppresses Voronoi cell drawing in EPS output.
-t Many modern processors are able to run concurrent threads, often two per core. By default VoroTop uses two fewer threads than the maximum number of hyperthreads available. If this option is specified and followed by a number, VoroTop will use that number of threads.
-h Displays the help message with a summary of all command-line options.
File Formats

VoroTop supports the following input file formats, which are automatically detected:

Both orthogonal and triclinic periodic cells are supported.

Building

VoroTop requires the dev branch of the Voro++ library. VoroTop uses OpenMP for multithreading; on macOS, Apple Clang does not support OpenMP, so GCC must be used instead (e.g., installed via MacPorts or Homebrew). See the GitHub repository for full build instructions.

Performance

VoroTop is built on the extremely efficient Voro++ libraries. The present version is built on a new multithreaded version of Voro++. After computing the Voronoi cells using Voro++, the calculations of Weinberg vectors, distributions, and the creation of output files scales roughly as O(n), where n is the number of particles. VoroTop uses multithreading to take advantage of modern multi-core processors.

License

VoroTop is released under an OpenSource BSD (3-Clause) license. This license permits redistribution and use of source and binaries, with or without modification, to both academic and for-profit groups.

Related Publications