voro++ (1) - Linux Man Pages
voro++: a 3D Voronoi cell library
voro++ - a 3D Voronoi cell library
SYNOPSISvoro++ [options] <x_min> <x_max> <y_min> <y_max> <z_min> <z_max> <filename>
Voro++ is a software library for carrying out three-dimensional computations of the Voronoi tessellation. A distinguishing feature of the Voro++ library is that it carries out cell-based calculations, computing the Voronoi cell for each particle individually, rather than computing the Voronoi tessellation as a global network of vertices and edges. It is particularly well-suited for applications that rely on cell-based statistics, where features of Voronoi cells ( eg. volume, centroid, number of faces) can be used to analyze a system of particles.
Voro++ is written in C++ and can be built as a static library that can be linked to. This man page describes a command-line utility that is provided with the library, which can be used to access most of the library's functionality. The utility imports text files of particle positions, computes the Voronoi cells for them, and then saves text files containing various types of information about the Voronoi cells.
FILE INPUT AND OUTPUT
The input file should have entries on separate lines with the following format:
- <Numerical ID label> <x coordinate> <y coordinate> <z coordinate>
When the command imports the particles, any that lie outside the container geometry are ignored. The program then computes Voronoi cells for all the particles, and generates an output file using the same filename but with a ".vol" suffix, that has the following entries:
- <Numerical ID label> <x coordinate> <y coordinate> <z coordinate> <Voronoi cell volume>
To compute different statistics about the Voronoi cells, the -c option can be used to specify a custom output string. By default, the command assumes non-periodic boundary conditions, although this can be modified with the -p option described below. If periodicity is enabled, then particles will be re-mapped into the primary domain when the file is imported.
Under normal operation, the output file should have exactly the same number of lines in as the input file. However, if particles lie outside the container geometry, they will be omitted by the program, and will not appear in the output file. In certain cases, a Voronoi cell for a valid particle may be completely deleted ( eg. by a wall cut) and it will also not appear in the output file. By default, the particles in the output file may be ordered differently to those in the input file, although the original ordering can be preserved with the -o option described below.
INTERNAL COMPUTATIONAL GRID
To carry out the computation, the code divides the computational box into a grid of equally-sized rectangular blocks. Particles are internally sorted into this grid for computational efficiency, with maximum performance usually being achieved when there is an average of 3 to 8 particles per block. Performance is also improved if the blocks are close to cubes, with similar side lengths in three directions. In general the code is not very sensitive to the block size, and reasonable performance is achieved over a large range of values.
By default, the code estimates the grid size to use by counting the number of particles in the input file and choosing the number of blocks to aim for a 3 to 8 particles per block. However, is also possible to manually configure the grid size using the -l and -n options.
OPTIONSThe utility accepts the following basic options:
OPTIONS FOR WALLSIn addition, a number of options can be used to specify wall objects. Walls are implemented by applying extra plane cuts during the cell construction process. At present, four wall types are supported:
Each wall is accounted for using a single approximating plane; several of the examples on the library website discuss this in more detail. If neighbor information is requested via the custom output string, then the walls are numbered sequentially, starting at -7 and decreasing.
CUSTOM OUTPUT COMMANDS
The output files created by Voro++ can be fully customized to contain a variety of different statistics about the computed Voronoi cells. This is done by specifying a format string that contains text plus additional control sequences that begin with percentage signs. The output file contains a line for each particle, where the control sequences are expanded to different statistics. Several examples on the library website describe the customized output in more detail.
In general, the neighbor information will be symmetric, so that if particle A reports particle B as a neighbor, then particle B will report particle A as a neighbor. However, due to the fact that Voro++ computes each Voronoi cell individually, it does not provide an explicit guarantee that the neighbor information will always be symmetric. Suppose there is a very small Voronoi face connecting A to B - it may be the case that due to roundoff error, the Voronoi cell computed for particle A has a face connecting it to B, but the cell computed for particle B does not have a face connecting it to A. If the user requires perfectly symmetric neighbor information, this can be achieved by scanning the output for any one-sided connections, and either deleting them or adding in the reverse connections. The face areas output from "%f" can also be used to remove connections between particles that only have a very small face between them.
AUTHORVoro++ is written and maintained by Chris H. Rycroft, a visiting assistant professor in the Department of Mathematics, University of California, Berkeley and Department of Mathematics, Lawrence Berkeley National Laboratory. Feedback about the code is welcome; please email chr [at] alum.mit.edu.
BUGSContact Chris H. Rycroft (chr [at] alum.mit.edu) to report problems with the code.
SEE ALSOSee the library website http://math.lbl.gov/voro++/ for complete documentation and examples.