1VORO++(1) General Commands Manual VORO++(1)
2
6 voro++ - a 3D Voronoi cell library
7
9 voro++ [options] <x_min> <x_max> <y_min> <y_max> <z_min> <z_max> <file‐
10 name>
11
13 Voro++ is a software library for carrying out three-dimensional compu‐
14 tations of the Voronoi tessellation. A distinguishing feature of the
15 Voro++ library is that it carries out cell-based calculations, comput‐
16 ing the Voronoi cell for each particle individually, rather than com‐
17 puting the Voronoi tessellation as a global network of vertices and
18 edges. It is particularly well-suited for applications that rely on
19 cell-based statistics, where features of Voronoi cells ( eg. volume,
20 centroid, number of faces) can be used to analyze a system of parti‐
21 cles.
22 Voro++ is written in C++ and can be built as a static library that can
25 be linked to. This man page describes a command-line utility that is
26 provided with the library, which can be used to access most of the
27 library's functionality. The utility imports text files of particle
28 positions, computes the Voronoi cells for them, and then saves text
29 files containing various types of information about the Voronoi cells.
30
33 The input file should have entries on separate lines with the following
34 format:
35 <Numerical ID label> <x coordinate> <y coordinate> <z coordi‐
37 nate>
38 When the command imports the particles, any that lie outside the con‐
40 tainer geometry are ignored. The program then computes Voronoi cells
41 for all the particles, and generates an output file using the same
42 filename but with a ".vol" suffix, that has the following entries:
43 <Numerical ID label> <x coordinate> <y coordinate> <z coordi‐
45 nate> <Voronoi cell volume>
46 To compute different statistics about the Voronoi cells, the -c option
48 can be used to specify a custom output string. By default, the command
49 assumes non-periodic boundary conditions, although this can be modified
50 with the -p option described below. If periodicity is enabled, then
51 particles will be re-mapped into the primary domain when the file is
52 imported.
53 Under normal operation, the output file should have exactly the same
56 number of lines in as the input file. However, if particles lie outside
57 the container geometry, they will be omitted by the program, and will
58 not appear in the output file. In certain cases, a Voronoi cell for a
59 valid particle may be completely deleted ( eg. by a wall cut) and it
60 will also not appear in the output file. By default, the particles in
61 the output file may be ordered differently to those in the input file,
62 although the original ordering can be preserved with the -o option
63 described below.
64
67 To carry out the computation, the code divides the computational box
68 into a grid of equally-sized rectangular blocks. Particles are inter‐
69 nally sorted into this grid for computational efficiency, with maximum
70 performance usually being achieved when there is an average of 3 to 8
71 particles per block. Performance is also improved if the blocks are
72 close to cubes, with similar side lengths in three directions. In gen‐
73 eral the code is not very sensitive to the block size, and reasonable
74 performance is achieved over a large range of values.
75 By default, the code estimates the grid size to use by counting the
77 number of particles in the input file and choosing the number of blocks
78 to aim for a 3 to 8 particles per block. However, is also possible to
79 manually configure the grid size using the -l and -n options.
80
83 The utility accepts the following basic options:
84 -c <string>
87 This option allows the format of the output file to be custom‐
88 ized to hold a variety of statistics about the computed Voronoi
89 cells. The specified string can contain regular characters, plus
90 control sequences beginning with percentage signs that are
91 expanded to contain different Voronoi cell statistics. See below
92 for a full custom output reference.
93 -g If this option is specified, then an additional output file is
95 generated with the ".gnu" extension, which contains a descrip‐
96 tion of all the cells in a format that can be viewed using gnu‐
97 plot using the splot command. Caution: For large input files,
98 the gnuplot output file will be extremely large, so this option
99 is best used on smaller systems.
100 -h or --help
102 This option prints out a summary of the command syntax and the
103 available options.
104 -hc This option prints out all the available control sequences for
106 the customized output.
107 -l <len>
109 Manually specify a typical length scale between particles, with
110 which to configure the internal grid size. For example, if the
111 particles represent densely-packed hard spheres of diameter d,
112 then d would be an appropriate value to use. The length scale
113 can be used to estimate the optimal grid size. Using this option
114 will result in a small performance boost, since the internal
115 grid can be set up immediately, and it is not necessary to tem‐
116 porarily store the input file contents while estimating the grid
117 size.
118 -m <mem>
120 Manually specify the initial number of particles that can be
121 stored in each block. By default a value of 8 is used. For any
122 block where this limit is reached, the code will dynamically
123 allocate more memory as neccessary, so usually it is not neces‐
124 sary to alter this.
125 -n <nx> <ny> <nz>
127 Manually specify the internal computational grid to have nx, ny,
128 and nz blocks in the x, y, and z directions respectively, giving
129 nx*ny*nz blocks in total. Manually specifying the size will
130 result in a small performance boost, since the internal grid can
131 be set up immediately, and it is not necessary to temporarily
132 store the input file contents while estimating the size.
133 -o Ensure that particles in the output file are in the same order
135 as those in the input file. This may result in a very small
136 increase in memory usage and execution time, and is turned off
137 by default.
138 -p Make the container periodic in all three coordinate directions.
140 -px Make container periodic in the x direction.
142 -py Make container periodic in the y direction.
144 -pz Make container periodic in the z direction.
146 -r Carry out a Voronoi tessellation for a polydisperse particle
148 arrangement using the radical Voronoi tessellation. For this
149 case, an extra column is required in the input file, that con‐
150 tains the particle radii. The radii are also included in the
151 output file.
152 -v Verbose output. After the computation is completed, some statis‐
154 tics are printed about the container geometry, the internal com‐
155 putational grid, the number of particles imported, the number
156 Voronoi cells computed, and the volume of the computed Voronoi
157 cells.
158 --version
160 Print version information.
161 -y Save the particles in POV-Ray format to "filename_p.pov" and the
163 Voronoi cells in POV-Ray format to "filename_v.pov". Caution:
164 For large input files, the POV-Ray Voronoi cell file will be
165 extremely large, so this option is best used on smaller systems.
166 -yp Save the particles in POV-Ray format to "filename_p.pov".
168 -yv Save the Voronoi cells in POV-Ray format to "filename_v.pov".
170
173 In addition, a number of options can be used to specify wall objects.
174 Walls are implemented by applying extra plane cuts during the cell con‐
175 struction process. At present, four wall types are supported:
176 -wb <x1> <x2> <x3> <x4> <x5> <x6>
179 Add six plane wall objects to make a box containing the space
180 x1<x<x2, x3<y<x4, and x5<z<z6. This can be useful for embedding
181 a smaller box within a larger container, in cases when the
182 influence of particles outside the smaller box still need to be
183 considered. This option is shorthand to avoid using the -wp
184 option six times.
185 -wc <x1> <x2> <x3> <x4> <x5> <x6> <x7>
187 Add a cylindrical wall object, where (x1,x2,x3) is a point on
188 the cylinder axis, (x4,x5,x6) is a vector along the cylinder
189 axis, and x7 is the cylinder radius.
190 -wo <x1> <x2> <x3> <x4> <x5> <x6> <x7>
192 Add a conical wall object, with apex at (x1,x2,x3), axis along
193 (x4,x5,x6), and half angle x7 (specified in radians).
194 -ws <x1> <x2> <x3> <x4>
196 Add a spherical wall object, centered on (x1,x2,x3), with radius
197 x4.
198 -wp <x1> <x2> <x3> <x4>
200 Add a plane wall object, with normal (x1,x2,x3), and displace‐
201 ment x4.
202 Each wall is accounted for using a single approximating plane;
204 several of the examples on the library website discuss this in
205 more detail. If neighbor information is requested via the custom
206 output string, then the walls are numbered sequentially, start‐
207 ing at -7 and decreasing.
208
211 The output files created by Voro++ can be fully customized to contain a
212 variety of different statistics about the computed Voronoi cells. This
213 is done by specifying a format string that contains text plus addi‐
214 tional control sequences that begin with percentage signs. The output
215 file contains a line for each particle, where the control sequences are
216 expanded to different statistics. Several examples on the library web‐
217 site describe the customized output in more detail.
218 Particle-related entries:
221 %i The particle ID number.
224 %x The x coordinate of the particle.
226 %y The y coordinate of the particle.
228 %z The z coordinate of the particle.
230 %q The position vector of the particle, short for "%x %y %z".
232 %r The radius of the particle (only printed if the polydisperse
234 information is available).
235 Vertex-related entries:
238 %w The number of vertices in the Voronoi cell.
241 %p A list of the vertices of the Voronoi cell in the format
243 (x,y,z), relative to the particle center.
244 %P A list of the vertices of the Voronoi cell in the format
246 (x,y,z), relative to the global coordinate system.
247 %o A list of the orders of each vertex.
249 %m The maximum radius squared of a vertex position, relative to the
251 particle center.
252 Edge-related entries:
255 %g The number of edges of the Voronoi cell.
258 %E The total edge distance.
260 %e A list of perimeters of each face.
262 Face-related entries:
265 %s The number of faces of the Voronoi cell.
268 %F The total surface area of the Voronoi cell.
270 %A A frequency table of the orders of the faces.
272 %a A list of the orders of the faces, showing how many edges make
274 up each face.
275 %f A list of areas of each face.
277 %t A list of bracketed sequences of vertices that make up each
279 face.
280 %l A list of normal vectors for each face.
282 %n A list of the neighboring particle or wall IDs corresponding to
284 each face. The list can contain negative numbers. For the non-
285 periodic case these correspond to when the particles have faces
286 created by the edges of the computational region. The numbers -1
287 to -6 correspond to the minimum x, maximum x, minimum y, maximum
288 y, minimum z, and maximum z walls respectively. For periodic
289 boundary conditions, negative numbers correspond to the cases
290 when a face of the Voronoi cell is created by the periodic image
291 of the current particle.
292 In general, the neighbor information will be symmetric, so that
294 if particle A reports particle B as a neighbor, then particle B
295 will report particle A as a neighbor. However, due to the fact
296 that Voro++ computes each Voronoi cell individually, it does not
297 provide an explicit guarantee that the neighbor information will
298 always be symmetric. Suppose there is a very small Voronoi face
299 connecting A to B - it may be the case that due to roundoff
300 error, the Voronoi cell computed for particle A has a face con‐
301 necting it to B, but the cell computed for particle B does not
302 have a face connecting it to A. If the user requires perfectly
303 symmetric neighbor information, this can be achieved by scanning
304 the output for any one-sided connections, and either deleting
305 them or adding in the reverse connections. The face areas output
306 from "%f" can also be used to remove connections between parti‐
307 cles that only have a very small face between them.
308 Volume-related entries:
311 %v The volume of the Voronoi cell.
313 %c The centroid of the Voronoi cell, relative to the particle cen‐
315 ter.
316 %C The centroid of the Voronoi cell, in the global coordinate sys‐
318 tem.
319
323 Voro++ is written and maintained by Chris H. Rycroft, a visiting assis‐
324 tant professor in the Department of Mathematics, University of Califor‐
325 nia, Berkeley and Department of Mathematics, Lawrence Berkeley National
326 Laboratory. Feedback about the code is welcome; please email
327 chr@alum.mit.edu.
328
330 Contact Chris H. Rycroft (chr@alum.mit.edu) to report problems with the
331 code.
332
334 See the library website http://math.lbl.gov/voro++/ for complete docu‐
335 mentation and examples.
3364th Berkeley Distribution October 17 2013 VORO++(1)