VoroTop
Voronoi Cell Topology
Visualization & Analysis Toolkit

General Overview

VoroTop is a command-line tool written in C++11 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 aides us in visualizing them.

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
***
The documentation below is for version 1.0;
documentation for version 0.4 is available here.
***

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.
-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. This option requires specifying the number of samples and the desired magnitude of the perturbation. 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.
-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 struc- ture 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.
-t Many modern processers are able to run concurrent threads, after 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.

File Formats

VoroTop can currently read LAMMPS dump files.


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 AtomEye cfg files scales roughly as O(n), where n is the number of particles. Running on a 2.53GHz processor, VoroTop can currently compute roughly 30,000 Weinberg vectors per second in three dimensions, and so can process data for nearly two million particles per minute. In two dimensions, VoroTop can compute roughly 160,000 Voronoi cells and p-vectors per second, or roughly ten million particles per minute.


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