VoroTop: Voronoi Cell Topology Visualization and Analysis Toolkit

General Overview

VoroTop is a command-line tool written in C++ which can be used to analyze systems of particles in three-dimensional space. 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.

VoroTop reads input from several standard formats which include information regarding the number of particles, their coordinates, and boundary conditions of the system.

A more complete description of VoroTop can be found in the paper, "VoroTop: Voronoi Cell Topology Visualization and Analysis Toolkit".

Command-line Options

VoroTop is run from the command line as follows:

VoroTop <filename> [options]

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


	`-ff`	Specifies a filter file to use for analysis. If this option is used, then a new output file is created in AtomEye cfg format; the new output includes the original data plus the structure types as determined by the given filter.
	`-w`	Compute Weinberg vector for each particle, save to file <filename.wvectors>.
	`-d`	Compute distribution of Weinberg vectors, save to file <filename.distribution>.
	`-g`	Compute distribution of Weinberg vectors for perturbations of a system. This option should be followed by two numbers, one specifying the number of samples, the other specifying the size of the random perturbations.
	`-df`	Generates a cfg file <filename.cfg> using the distribution of types in the sample; distribution is saved to <filename.distribution_filter>. Each topological type is given a unique structure ID, with the most common type labeled 0, and less frequent types labeled with increasing values. This can be useful for studying new structures.
	`-c`	Cluster analysis. Particles with topological types not included in the specified filter are considered to be defects. Defect particles with adjacent Voronoi cells are considered to belong to the same defect; we call each Voronoi-contiguous set of defect particles a cluster and assign the constituent particles a unique index. Similar cluster analysis is also performed for types in the filter. This option requires loading a filter file for analysis.
	`-o`	Specify output file primary name <filename>. If requested, Weinberg vectors will be saved to <filename.wvectors>; distribution will be saved to <filename.distribution>; AtomEye data will be saved to <filename.cfg>.
	`-od`	Specify output directory. If requested, output will be saved to specified directory.

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

Lazar, E.A. "VoroTop: Voronoi Cell Topology Visualization and Analysis Toolkit", download.
Lazar, E.A., Han, J., and Srolovitz, D.J. "A Topological Framework for Local Structure Analysis in Condensed Matter", arxiv, Proc. Natl. Acad. Sci. 112:E5769 (2015).
Landweber, P.S., Lazar, E.A., Patel, N. "On fiber diameters of continuous maps", arXiv, Amer. Math. Monthly 123:4, 2016 (see also "A Surprise For Big-Data Analytics").
Lazar, E.A., Mason, J.K., MacPherson, R.D. and Srolovitz, D.J. "Complete topology of cells, grains, and bubbles in three-dimensional microstructures", arXiv, Phys. Rev. Lett. 109:095505, 2012.