VORO++(1)VORO++(1)NAME
voro++ - a 3D Voronoi cell library
SYNOPSIS
voro++ [options] <x_min> <x_max> <y_min> <y_max> <z_min> <z_max> <file‐
name>
DESCRIPTION
Voro++ is a software library for carrying out three-dimensional compu‐
tations of the Voronoi tessellation. A distinguishing feature of the
Voro++ library is that it carries out cell-based calculations, comput‐
ing the Voronoi cell for each particle individually, rather than com‐
puting 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 parti‐
cles.
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 coordi‐
nate>
When the command imports the particles, any that lie outside the con‐
tainer 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 coordi‐
nate> <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 inter‐
nally 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 gen‐
eral 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.
OPTIONS
The utility accepts the following basic options:
-c This option allows the format of the output file to be custom‐
ized to hold a variety of statistics about the computed Voronoi
cells. The specified string can contain regular characters, plus
control sequences beginning with percentage signs that are
expanded to contain different Voronoi cell statistics. See below
for a full custom output reference.
-g If this option is specified, then an additional output file is
generated with the ".gnu" extension, which contains a descrip‐
tion of all the cells in a format that can be viewed using gnu‐
plot using the splot command. Caution: For large input files,
the gnuplot output file will be extremely large, so this option
is best used on smaller systems.
-h This option prints out a summary of the command syntax and the
available options.
-hc This option prints out all the available control sequences for
the customized output.
-l Manually specify a typical length scale between particles, with
which to configure the internal grid size. For example, if the
particles represent densely-packed hard spheres of diameter d,
then d would be an appropriate value to use. The length scale
can be used to estimate the optimal grid size. Using this option
will result in a small performance boost, since the internal
grid can be set up immediately, and it is not necessary to tem‐
porarily store the input file contents while estimating the grid
size.
-m Manually specify the initial number of particles that can be
stored in each block. By default a value of 8 is used. For any
block where this limit is reached, the code will dynamically
allocate more memory as neccessary, so usually it is not neces‐
sary to alter this.
-n Manually specify the internal computational grid to have nx, ny,
and nz blocks in the x, y, and z directions respectively, giving
nx*ny*nz blocks in total. Manually specifying the size will
result in a small performance boost, since the internal grid can
be set up immediately, and it is not necessary to temporarily
store the input file contents while estimating the size.
-o Ensure that particles in the output file are in the same order
as those in the input file. This may result in a very small
increase in memory usage and execution time, and is turned off
by default.
-p Make the container periodic in all three coordinate directions.
-px Make container periodic in the x direction.
-py Make container periodic in the y direction.
-pz Make container periodic in the z direction.
-r Carry out a Voronoi tessellation for a polydisperse particle
arrangement using the radical Voronoi tessellation. For this
case, an extra column is required in the input file, that con‐
tains the particle radii. The radii are also included in the
output file.
-v Verbose output. After the computation is completed, some statis‐
tics are printed about the container geometry, the internal com‐
putational grid, the number of particles imported, the number
Voronoi cells computed, and the volume of the computed Voronoi
cells.
--version
Print version information.
-y Save the particles in POV-Ray format to "filename_p.pov" and the
Voronoi cells in POV-Ray format to "filename_v.pov". Caution:
For large input files, the POV-Ray Voronoi cell file will be
extremely large, so this option is best used on smaller systems.
-yp Save the particles in POV-Ray format to "filename_p.pov".
-yv Save the Voronoi cells in POV-Ray format to "filename_v.pov".
OPTIONS FOR WALLS
In addition, a number of options can be used to specify wall objects.
Walls are implemented by applying extra plane cuts during the cell con‐
struction process. At present, four wall types are supported:
-wb Add six plane wall objects to make a box containing the space
x1<x<x2, x3<y<x4, and x5<z<z6. This can be useful for embedding
a smaller box within a larger container, in cases when the
influence of particles outside the smaller box still need to be
considered. This option is shorthand to avoid using the -wp
option six times.
-wc Add a cylindrical wall object, where (x1,x2,x3) is a point on
the cylinder axis, (x4,x5,x6) is a vector along the cylinder
axis, and x7 is the cylinder radius.
-wo Add a conical wall object, with apex at (x1,x2,x3), axis along
(x4,x5,x6), and half angle x7 (specified in radians).
-ws Add a spherical wall object, centered on (x1,x2,x3), with radius
x4.
-wp Add a plane wall object, with normal (x1,x2,x3), and displace‐
ment x4.
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, start‐
ing 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 addi‐
tional 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 web‐
site describe the customized output in more detail.
Particle-related entries:
%i The particle ID number.
%x The x coordinate of the particle.
%y The y coordinate of the particle.
%z The z coordinate of the particle.
%q The position vector of the particle, short for "%x %y %z".
%r The radius of the particle (only printed if the polydisperse
information is available).
Vertex-related entries:
%w The number of vertices in the Voronoi cell.
%p A list of the vertices of the Voronoi cell in the format
(x,y,z), relative to the particle center.
%P A list of the vertices of the Voronoi cell in the format
(x,y,z), relative to the global coordinate system.
%o A list of the orders of each vertex.
%m The maximum radius squared of a vertex position, relative to the
particle center.
Edge-related entries:
%g The number of edges of the Voronoi cell.
%E The total edge distance.
%e A list of perimeters of each face.
Face-related entries:
%s The number of faces of the Voronoi cell.
%F The total surface area of the Voronoi cell.
%A A frequency table of the orders of the faces.
%a A list of the orders of the faces, showing how many edges make
up each face.
%f A list of areas of each face.
%t A list of bracketed sequences of vertices that make up each
face.
%l A list of normal vectors for each face.
%n A list of the neighboring particle or wall IDs corresponding to
each face. The list can contain negative numbers. For the non-
periodic case these correspond to when the particles have faces
created by the edges of the computational region. The numbers -1
to -6 correspond to the minimum x, maximum x, minimum y, maximum
y, minimum z, and maximum z walls respectively. For periodic
boundary conditions, negative numbers correspond to the cases
when a face of the Voronoi cell is created by the periodic image
of the current particle.
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 con‐
necting 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 parti‐
cles that only have a very small face between them.
Volume-related entries:
%v The volume of the Voronoi cell.
%c The centroid of the Voronoi cell, relative to the particle cen‐
ter.
%C The centroid of the Voronoi cell, in the global coordinate sys‐
tem.
AUTHOR
Voro++ is written and maintained by Chris H. Rycroft, a visiting assis‐
tant professor in the Department of Mathematics, University of Califor‐
nia, Berkeley and Department of Mathematics, Lawrence Berkeley National
Laboratory. Feedback about the code is welcome; please email
chr@alum.mit.edu.
BUGS
Contact Chris H. Rycroft (chr@alum.mit.edu) to report problems with the
code.
SEE ALSO
See the library website http://math.lbl.gov/voro++/ for complete docu‐
mentation and examples.
4th Berkeley Distribution October 17 2013 VORO++(1)
