Voro++ command-line utility reference

The Voro++ distribution contains a command-line utility that can carry out many standard Voronoi calculations. It can read text files of particle systems, compute the Voronoi cells for each particle, and output information about the Voronoi cells. The program has the following syntax:

voro++ [opts] <x_min> <x_max> <y_min> <y_max> <z_min> <z_max> <filename>

Command-line arguments

<x_min> and <x_max>
The minimum and maximum x coordinates of the box.
<y_min> and <y_max>
The minimum and maximum y coordinates of the box.
<z_min> and <z_max>
The minimum and maximum z coordinates of the box.
<filename>
The input file containing a list of particles and numerical ID labels.

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>

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–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–8 particles per block. However, is also possible to manually configure the grid size using the -l and -n options.

Basic command-line options

The utility accepts the following options:

-c <string>
This option allows the format of the output file to be customized 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 the full custom output reference.
-g
If this option is specified, then an additional output file is generated with the “.gnu” extension, which contains a description of all the cells in a format that can be viewed using gnuplot 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 or --help
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 <len>
Manually specify a typical length scale between particles, with which to configure the internal grid size. For example, if the particles represent densely 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 temporarily store the input file contents while estimating the grid size.
-m <mem>
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 necessary to alter this.
-n <nx> <ny> <nz>
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 contains the particle radii. The radii are also included in the output file.
-v
Verbose output. After the computation is completed, some statistics are printed about the container geometry, the internal computational 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”.

Command-line 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 construction process. At present, four wall types are supported:

-wb <x1> <x2> <x3> <x4> <x5> <x6>
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 <x1> <x2> <x3> <x4> <x5> <x6> <x7>
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 <x1> <x2> <x3> <x4> <x5> <x6> <x7>
Add a conical wall object, with apex at (x1,x2,x3), axis along (x4,x5,x6), and half angle x7 (specified in radians).
-ws <x1> <x2> <x3> <x4>
Add a spherical wall object, centered on (x1,x2,x3), with radius x4.
-wp <x1> <x2> <x3> <x4>
Add a plane wall object, with normal (x1,x2,x3), and displacement x4.

Each wall is accounted for using a single approximating plane – see the cylinder and frustum examples for a fuller discussion of this. If neighbor information is requested via the custom output string, then the walls are numbered sequentially, starting at -7 and decreasing.