Voro++

Voro++ command-line utility reference

The Voro++ distribution contains a command-line utility that carry out many standard Voronoi calculations. It can read text files of particle systems, and output versions with Voronoi cell volume appended. The program has the following syntax:

Command-line arguments

<length_scale>

This number should be set to a typical particle length scale in the system, and it is use to configure the code for maximum efficiency. Using a typical particle diameter in the system usually works well. Tuning the value may result in slightly different performance.

<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:

When the command imports the particles, any which 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:

By default, the command assumes non-periodic boundary conditions. The particles in the output file may be ordered differently to those in the input file.

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.

-n

This option turns on the neighbor tracking procedure. In each line of the output file, a list of the numerical ID labels is appended that corresponds to the neighboring particles that created each face of the current particle's Voronoi cell. The list can contain negative numbers. For the non-periodic case these correspond to when the particles have faces created by walls. 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.

-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.

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:

-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 using the -n option, then the walls are numbered sequentially, starting at -7 and decreasing.