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 three-dimensional space. VoroTop reads input from several standard formats which include 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. (preprint).


Command-line Options
***
The documentation below is for version 0.4;
documentation for version 0.3 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:

-f Specifies a filter file to use for analysis. If this option is used, then a new output file (either in LAMMPS dump or AtomEye cfg format) will be created that includes the original data plus the structure types as determined by the given filter.
-w 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 [19] 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 using Weinberg vectors 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 cubed root of the Voronoi cell volume; 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.
-od
-o		 By default, VoroTop saves output to the directory in which the input data is located, and using the input filename as a base name. For example, if the input filename is ~/research/SFT.00100, then Weinberg vectors will be saved to ~/research/SFT.00100.wvectors and a distribution of Weinberg vectors will be saved to ~/research/SFT.00100.distribution. The -od option allows specification of an alternate output directory; the -o options allows specification of an alternate output base name.

File Formats

VoroTop can currently read AtomEye cfg and LAMMPS dump files.


Performance

VoroTop is built on the extremely efficient Voro++ libraries. 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, and so can process data for nearly two 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