<a href="voro_09_09_8hh.html">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> <span class="comment">// Voro++, a 3D cell-based Voronoi library</span></div>
<div class="line"><a name="l00008"></a><span class="lineno"> 8</span> <span class="comment"> * \brief A file that loads all of the Voro++ header files. */</span></div>
<div class="line"><a name="l00012"></a><span class="lineno"> 12</span> <span class="comment"> * Voro++ is a software library for carrying out three-dimensional computations</span></div>
<div class="line"><a name="l00013"></a><span class="lineno"> 13</span> <span class="comment"> * of the Voronoi tessellation. A distinguishing feature of the Voro++ library</span></div>
<div class="line"><a name="l00014"></a><span class="lineno"> 14</span> <span class="comment"> * is that it carries out cell-based calculations, computing the Voronoi cell</span></div>
<div class="line"><a name="l00015"></a><span class="lineno"> 15</span> <span class="comment"> * for each particle individually, rather than computing the Voronoi</span></div>
<div class="line"><a name="l00016"></a><span class="lineno"> 16</span> <span class="comment"> * tessellation as a global network of vertices and edges. It is particularly</span></div>
<div class="line"><a name="l00017"></a><span class="lineno"> 17</span> <span class="comment"> * well-suited for applications that rely on cell-based statistics, where</span></div>
<div class="line"><a name="l00018"></a><span class="lineno"> 18</span> <span class="comment"> * features of Voronoi cells (eg. volume, centroid, number of faces) can be</span></div>
<div class="line"><a name="l00019"></a><span class="lineno"> 19</span> <span class="comment"> * used to analyze a system of particles.</span></div>
<div class="line"><a name="l00021"></a><span class="lineno"> 21</span> <span class="comment"> * Voro++ is written in C++ and can be built as a static library that can be</span></div>
<div class="line"><a name="l00022"></a><span class="lineno"> 22</span> <span class="comment"> * linked to. This manual provides a reference for every function in the class</span></div>
<div class="line"><a name="l00023"></a><span class="lineno"> 23</span> <span class="comment"> * structure. For a general overview of the program, see the Voro++ website at</span></div>
<div class="line"><a name="l00024"></a><span class="lineno"> 24</span> <span class="comment"> * http://math.lbl.gov/voro++/ and in particular the example programs at</span></div>
<div class="line"><a name="l00025"></a><span class="lineno"> 25</span> <span class="comment"> * http://math.lbl.gov/voro++/examples/ that demonstrate many of the library's</span></div>
<div class="line"><a name="l00028"></a><span class="lineno"> 28</span> <span class="comment"> * \section class C++ class structure</span></div>
<div class="line"><a name="l00029"></a><span class="lineno"> 29</span> <span class="comment"> * The code is structured around several C++ classes. The voronoicell_base</span></div>
<div class="line"><a name="l00030"></a><span class="lineno"> 30</span> <span class="comment"> * class contains all of the routines for constructing a single Voronoi cell.</span></div>
<div class="line"><a name="l00031"></a><span class="lineno"> 31</span> <span class="comment"> * It represents the cell as a collection of vertices that are connected by</span></div>
<div class="line"><a name="l00032"></a><span class="lineno"> 32</span> <span class="comment"> * edges, and there are routines for initializing, making, and outputting the</span></div>
<div class="line"><a name="l00033"></a><span class="lineno"> 33</span> <span class="comment"> * cell. The voronoicell_base class form the base of the voronoicell and</span></div>
<div class="line"><a name="l00035"></a><span class="lineno"> 35</span> <span class="comment"> * whether neighboring particle ID information for each face must be tracked or</span></div>
<div class="line"><a name="l00036"></a><span class="lineno"> 36</span> <span class="comment"> * not. Collectively, these classes are referred to as "voronoicell classes"</span></div>
<div class="line"><a name="l00037"></a><span class="lineno"> 37</span> <span class="comment"> * within the documentation.</span></div>
<div class="line"><a name="l00039"></a><span class="lineno"> 39</span> <span class="comment"> * There is a hierarchy of classes that represent three-dimensional particle</span></div>
<div class="line"><a name="l00040"></a><span class="lineno"> 40</span> <span class="comment"> * systems. All of these are derived from the voro_base class, which contains</span></div>
<div class="line"><a name="l00041"></a><span class="lineno"> 41</span> <span class="comment"> * constants that divide a three-dimensional system into a rectangular grid of</span></div>
<div class="line"><a name="l00042"></a><span class="lineno"> 42</span> <span class="comment"> * equally-sized rectangular blocks; this grid is used for computational</span></div>
<div class="line"><a name="l00043"></a><span class="lineno"> 43</span> <span class="comment"> * efficiency during the Voronoi calculations.</span></div>
<div class="line"><a name="l00045"></a><span class="lineno"> 45</span> <span class="comment"> * The container_base, container, and container_poly are then derived from the</span></div>
<div class="line"><a name="l00046"></a><span class="lineno"> 46</span> <span class="comment"> * voro_base class to represent a particle system in a specific</span></div>
<div class="line"><a name="l00047"></a><span class="lineno"> 47</span> <span class="comment"> * three-dimensional rectangular box using both periodic and non-periodic</span></div>
<div class="line"><a name="l00048"></a><span class="lineno"> 48</span> <span class="comment"> * boundary conditions. In addition, the container_periodic_base,</span></div>
<div class="line"><a name="l00050"></a><span class="lineno"> 50</span> <span class="comment"> * a particle system in a three-dimensional non-orthogonal periodic domain,</span></div>
<div class="line"><a name="l00051"></a><span class="lineno"> 51</span> <span class="comment"> * defined by three periodicity vectors that represent a parallelepiped.</span></div>
<div class="line"><a name="l00052"></a><span class="lineno"> 52</span> <span class="comment"> * Collectively, these classes are referred to as "container classes" within</span></div>
<div class="line"><a name="l00053"></a><span class="lineno"> 53</span> <span class="comment"> * the documentation.</span></div>
<div class="line"><a name="l00055"></a><span class="lineno"> 55</span> <span class="comment"> * The voro_compute template encapsulates all of the routines for computing</span></div>
<div class="line"><a name="l00056"></a><span class="lineno"> 56</span> <span class="comment"> * Voronoi cells. Each container class has a voro_compute template within</span></div>
<div class="line"><a name="l00057"></a><span class="lineno"> 57</span> <span class="comment"> * it, that accesses the container's particle system, and computes the Voronoi</span></div>
<div class="line"><a name="l00060"></a><span class="lineno"> 60</span> <span class="comment"> * There are several wall classes that can be used to apply certain boundary</span></div>
<div class="line"><a name="l00061"></a><span class="lineno"> 61</span> <span class="comment"> * conditions using additional plane cuts during the Voronoi cell compution.</span></div>
<div class="line"><a name="l00062"></a><span class="lineno"> 62</span> <span class="comment"> * The code also contains a number of small loop classes, c_loop_all,</span></div>
<div class="line"><a name="l00063"></a><span class="lineno"> 63</span> <span class="comment"> * c_loop_subset, c_loop_all_periodic, and c_loop_order that can be used to</span></div>
<div class="line"><a name="l00064"></a><span class="lineno"> 64</span> <span class="comment"> * iterate over a certain subset of particles in a container. The latter class</span></div>
<div class="line"><a name="l00065"></a><span class="lineno"> 65</span> <span class="comment"> * makes use of a special particle_order class that stores a specific order of</span></div>
<div class="line"><a name="l00066"></a><span class="lineno"> 66</span> <span class="comment"> * particles within the container. The library also contains the classes</span></div>
<div class="line"><a name="l00067"></a><span class="lineno"> 67</span> <span class="comment"> * pre_container_base, pre_container, and pre_container_poly, that can be used</span></div>
<div class="line"><a name="l00068"></a><span class="lineno"> 68</span> <span class="comment"> * as temporary storage when importing data of unknown size.</span></div>
<div class="line"><a name="l00071"></a><span class="lineno"> 71</span> <span class="comment"> * The voronoicell class represents a single Voronoi cell as a convex</span></div>
<div class="line"><a name="l00072"></a><span class="lineno"> 72</span> <span class="comment"> * polyhedron, with a set of vertices that are connected by edges. The class</span></div>
<div class="line"><a name="l00073"></a><span class="lineno"> 73</span> <span class="comment"> * contains a variety of functions that can be used to compute and output the</span></div>
<div class="line"><a name="l00074"></a><span class="lineno"> 74</span> <span class="comment"> * Voronoi cell corresponding to a particular particle. The command init()</span></div>
<div class="line"><a name="l00075"></a><span class="lineno"> 75</span> <span class="comment"> * can be used to initialize a cell as a large rectangular box. The Voronoi cell</span></div>
<div class="line"><a name="l00076"></a><span class="lineno"> 76</span> <span class="comment"> * can then be computed by repeatedly cutting it with planes that correspond to</span></div>
<div class="line"><a name="l00077"></a><span class="lineno"> 77</span> <span class="comment"> * the perpendicular bisectors between that particle and its neighbors.</span></div>
<div class="line"><a name="l00079"></a><span class="lineno"> 79</span> <span class="comment"> * This is achieved by using the plane() routine, which will recompute the</span></div>
<div class="line"><a name="l00080"></a><span class="lineno"> 80</span> <span class="comment"> * cell's vertices and edges after cutting it with a single plane. This is the</span></div>
<div class="line"><a name="l00081"></a><span class="lineno"> 81</span> <span class="comment"> * key routine in voronoicell class. It begins by exploiting the convexity</span></div>
<div class="line"><a name="l00082"></a><span class="lineno"> 82</span> <span class="comment"> * of the underlying cell, tracing between edges to work out if the cell</span></div>
<div class="line"><a name="l00083"></a><span class="lineno"> 83</span> <span class="comment"> * intersects the cutting plane. If it does not intersect, then the routine</span></div>
<div class="line"><a name="l00084"></a><span class="lineno"> 84</span> <span class="comment"> * immediately exits. Otherwise, it finds an edge or vertex that intersects</span></div>
<div class="line"><a name="l00085"></a><span class="lineno"> 85</span> <span class="comment"> * the plane, and from there, traces out a new face on the cell, recomputing</span></div>
<div class="line"><a name="l00086"></a><span class="lineno"> 86</span> <span class="comment"> * the edge and vertex structure accordingly.</span></div>
<div class="line"><a name="l00088"></a><span class="lineno"> 88</span> <span class="comment"> * Once the cell is computed, there are many routines for computing features of</span></div>
<div class="line"><a name="l00089"></a><span class="lineno"> 89</span> <span class="comment"> * the the Voronoi cell, such as its volume, surface area, or centroid. There</span></div>
<div class="line"><a name="l00090"></a><span class="lineno"> 90</span> <span class="comment"> * are also many routines for outputting features of the Voronoi cell, or</span></div>
<div class="line"><a name="l00091"></a><span class="lineno"> 91</span> <span class="comment"> * writing its shape in formats that can be read by Gnuplot or POV-Ray.</span></div>
<div class="line"><a name="l00094"></a><span class="lineno"> 94</span> <span class="comment"> * The voronoicell class has a public member p representing the</span></div>
<div class="line"><a name="l00095"></a><span class="lineno"> 95</span> <span class="comment"> * number of vertices. The polyhedral structure of the cell is stored</span></div>
<div class="line"><a name="l00096"></a><span class="lineno"> 96</span> <span class="comment"> * in the following arrays:</span></div>
<div class="line"><a name="l00098"></a><span class="lineno"> 98</span> <span class="comment"> * - pts: a one-dimensional array of floating point numbers, that represent the</span></div>
<div class="line"><a name="l00099"></a><span class="lineno"> 99</span> <span class="comment"> * position vectors x_0, x_1, ..., x_{p-1} of the polyhedron vertices.</span></div>
<div class="line"><a name="l00100"></a><span class="lineno"> 100</span> <span class="comment"> * - nu: the order of each vertex n_0, n_1, ..., n_{p-1}, corresponding to</span></div>
<div class="line"><a name="l00101"></a><span class="lineno"> 101</span> <span class="comment"> * the number of other vertices to which each is connected.</span></div>
<div class="line"><a name="l00102"></a><span class="lineno"> 102</span> <span class="comment"> * - ed: a two-dimensional table of edges and relations. For the ith vertex,</span></div>
<div class="line"><a name="l00103"></a><span class="lineno"> 103</span> <span class="comment"> * ed[i] has 2n_i+1 elements. The first n_i elements are the edges e(j,i),</span></div>
<div class="line"><a name="l00104"></a><span class="lineno"> 104</span> <span class="comment"> * where e(j,i) is the jth neighbor of vertex i. The edges are ordered</span></div>
<div class="line"><a name="l00105"></a><span class="lineno"> 105</span> <span class="comment"> * according to a right-hand rule with respect to an outward-pointing normal.</span></div>
<div class="line"><a name="l00106"></a><span class="lineno"> 106</span> <span class="comment"> * The next n_i elements are the relations l(j,i) which satisfy the property</span></div>
<div class="line"><a name="l00107"></a><span class="lineno"> 107</span> <span class="comment"> * e(l(j,i),e(j,i)) = i. The final element of the ed[i] list is a back</span></div>
<div class="line"><a name="l00108"></a><span class="lineno"> 108</span> <span class="comment"> * pointer used in memory allocation.</span></div>
<div class="line"><a name="l00110"></a><span class="lineno"> 110</span> <span class="comment"> * In a very large number of cases, the values of n_i will be 3. This is because</span></div>
<div class="line"><a name="l00111"></a><span class="lineno"> 111</span> <span class="comment"> * the only way that a higher-order vertex can be created in the plane()</span></div>
<div class="line"><a name="l00112"></a><span class="lineno"> 112</span> <span class="comment"> * routine is if the cutting plane perfectly intersects an existing vertex. For</span></div>
<div class="line"><a name="l00113"></a><span class="lineno"> 113</span> <span class="comment"> * random particle arrangements with position vectors specified to double</span></div>
<div class="line"><a name="l00114"></a><span class="lineno"> 114</span> <span class="comment"> * precision this should happen very rarely. A preliminary version of this code</span></div>
<div class="line"><a name="l00115"></a><span class="lineno"> 115</span> <span class="comment"> * was quite successful with only making use of vertices of order 3. However,</span></div>
<div class="line"><a name="l00116"></a><span class="lineno"> 116</span> <span class="comment"> * when calculating millions of cells, it was found that this approach is not</span></div>
<div class="line"><a name="l00117"></a><span class="lineno"> 117</span> <span class="comment"> * robust, since a single floating point error can invalidate the computation.</span></div>
<div class="line"><a name="l00118"></a><span class="lineno"> 118</span> <span class="comment"> * This can also be a problem for cases featuring crystalline arrangements of</span></div>
<div class="line"><a name="l00119"></a><span class="lineno"> 119</span> <span class="comment"> * particles where the corresponding Voronoi cells may have high-order vertices</span></div>
<div class="line"><a name="l00120"></a><span class="lineno"> 120</span> <span class="comment"> * by construction.</span></div>
<div class="line"><a name="l00122"></a><span class="lineno"> 122</span> <span class="comment"> * Because of this, Voro++ takes the approach that it if an existing vertex is</span></div>
<div class="line"><a name="l00123"></a><span class="lineno"> 123</span> <span class="comment"> * within a small numerical tolerance of the cutting plane, it is treated as</span></div>
<div class="line"><a name="l00124"></a><span class="lineno"> 124</span> <span class="comment"> * being exactly on the plane, and the polyhedral topology is recomputed</span></div>
<div class="line"><a name="l00125"></a><span class="lineno"> 125</span> <span class="comment"> * accordingly. However, while this improves robustness, it also adds the</span></div>
<div class="line"><a name="l00126"></a><span class="lineno"> 126</span> <span class="comment"> * complexity that n_i may no longer always be 3. This causes memory management</span></div>
<div class="line"><a name="l00127"></a><span class="lineno"> 127</span> <span class="comment"> * to be significantly more complicated, as different vertices require a</span></div>
<div class="line"><a name="l00128"></a><span class="lineno"> 128</span> <span class="comment"> * different number of elements in the ed[][] array. To accommodate this, the</span></div>
<div class="line"><a name="l00129"></a><span class="lineno"> 129</span> <span class="comment"> * voronoicell class allocated edge memory in a different array called mep[][],</span></div>
<div class="line"><a name="l00130"></a><span class="lineno"> 130</span> <span class="comment"> * in such a way that all vertices of order k are held in mep[k]. If vertex</span></div>
<div class="line"><a name="l00131"></a><span class="lineno"> 131</span> <span class="comment"> * i has order k, then ed[i] points to memory within mep[k]. The array ed[][]</span></div>
<div class="line"><a name="l00132"></a><span class="lineno"> 132</span> <span class="comment"> * is never directly initialized as a two-dimensional array itself, but points</span></div>
<div class="line"><a name="l00133"></a><span class="lineno"> 133</span> <span class="comment"> * at allocations within mep[][]. To the user, it appears as though each row of</span></div>
<div class="line"><a name="l00134"></a><span class="lineno"> 134</span> <span class="comment"> * ed[][] has a different number of elements. When vertices are added or</span></div>
<div class="line"><a name="l00135"></a><span class="lineno"> 135</span> <span class="comment"> * deleted, care must be taken to reorder and reassign elements in these</span></div>
<div class="line"><a name="l00138"></a><span class="lineno"> 138</span> <span class="comment"> * During the plane() routine, the code traces around the vertices of the cell,</span></div>
<div class="line"><a name="l00139"></a><span class="lineno"> 139</span> <span class="comment"> * and adds new vertices along edges which intersect the cutting plane to</span></div>
<div class="line"><a name="l00140"></a><span class="lineno"> 140</span> <span class="comment"> * create a new face. The values of l(j,i) are used in this computation, as</span></div>
<div class="line"><a name="l00141"></a><span class="lineno"> 141</span> <span class="comment"> * when the code is traversing from one vertex on the cell to another, this</span></div>
<div class="line"><a name="l00142"></a><span class="lineno"> 142</span> <span class="comment"> * information allows the code to immediately work out which edge of a vertex</span></div>
<div class="line"><a name="l00143"></a><span class="lineno"> 143</span> <span class="comment"> * points back to the one it came from. As new vertices are created, the l(j,i)</span></div>
<div class="line"><a name="l00144"></a><span class="lineno"> 144</span> <span class="comment"> * are also updated to ensure consistency. To ensure robustness, the plane</span></div>
<div class="line"><a name="l00145"></a><span class="lineno"> 145</span> <span class="comment"> * cutting algorithm should work with any possible combination of vertices</span></div>
<div class="line"><a name="l00146"></a><span class="lineno"> 146</span> <span class="comment"> * which are inside, outside, or exactly on the cutting plane.</span></div>
<div class="line"><a name="l00148"></a><span class="lineno"> 148</span> <span class="comment"> * Vertices exactly on the cutting plane create some additional computational</span></div>
<div class="line"><a name="l00149"></a><span class="lineno"> 149</span> <span class="comment"> * difficulties. If there are two marginal vertices connected by an existing</span></div>
<div class="line"><a name="l00150"></a><span class="lineno"> 150</span> <span class="comment"> * edge, then it would be possible for duplicate edges to be created between</span></div>
<div class="line"><a name="l00151"></a><span class="lineno"> 151</span> <span class="comment"> * those two vertices, if the plane routine traces along both sides of this</span></div>
<div class="line"><a name="l00152"></a><span class="lineno"> 152</span> <span class="comment"> * edge while constructing the new face. The code recognizes these cases and</span></div>
<div class="line"><a name="l00153"></a><span class="lineno"> 153</span> <span class="comment"> * prevents the double edge from being formed. Another possibility is the</span></div>
<div class="line"><a name="l00154"></a><span class="lineno"> 154</span> <span class="comment"> * formation of vertices of order two or one. At the end of the plane cutting</span></div>
<div class="line"><a name="l00155"></a><span class="lineno"> 155</span> <span class="comment"> * routine, the code checks to see if any of these are present, removing the</span></div>
<div class="line"><a name="l00156"></a><span class="lineno"> 156</span> <span class="comment"> * order one vertices by just deleting them, and removing the order two</span></div>
<div class="line"><a name="l00157"></a><span class="lineno"> 157</span> <span class="comment"> * vertices by connecting the two neighbors of each vertex together. It is</span></div>
<div class="line"><a name="l00158"></a><span class="lineno"> 158</span> <span class="comment"> * possible that the removal of a single low-order vertex could result in the</span></div>
<div class="line"><a name="l00159"></a><span class="lineno"> 159</span> <span class="comment"> * creation of additional low-order vertices, so the process is applied</span></div>
<div class="line"><a name="l00160"></a><span class="lineno"> 160</span> <span class="comment"> * recursively until no more are left.</span></div>
<div class="line"><a name="l00163"></a><span class="lineno"> 163</span> <span class="comment"> * There are four container classes available for general usage: container,</span></div>
<div class="line"><a name="l00164"></a><span class="lineno"> 164</span> <span class="comment"> * container_poly, container_periodic, and container_periodic_poly. Each of</span></div>
<div class="line"><a name="l00165"></a><span class="lineno"> 165</span> <span class="comment"> * these represent a system of particles in a specific three-dimensional</span></div>
<div class="line"><a name="l00166"></a><span class="lineno"> 166</span> <span class="comment"> * geometry. They contain routines for importing particles from a text file,</span></div>
<div class="line"><a name="l00167"></a><span class="lineno"> 167</span> <span class="comment"> * and adding particles individually. They also contain a large number of</span></div>
<div class="line"><a name="l00168"></a><span class="lineno"> 168</span> <span class="comment"> * analyzing and outputting the particle system. Internally, the routines that</span></div>
<div class="line"><a name="l00169"></a><span class="lineno"> 169</span> <span class="comment"> * compute Voronoi cells do so by making use of the voro_compute template.</span></div>
<div class="line"><a name="l00170"></a><span class="lineno"> 170</span> <span class="comment"> * Each container class contains routines that tell the voro_compute template</span></div>
<div class="line"><a name="l00171"></a><span class="lineno"> 171</span> <span class="comment"> * about the specific geometry of this container.</span></div>
<div class="line"><a name="l00174"></a><span class="lineno"> 174</span> <span class="comment"> * The voro_compute template encapsulates the routines for carrying out the</span></div>
<div class="line"><a name="l00175"></a><span class="lineno"> 175</span> <span class="comment"> * Voronoi cell computations. It contains data structures suchs as a mask and a</span></div>
<div class="line"><a name="l00176"></a><span class="lineno"> 176</span> <span class="comment"> * queue that are used in the computations. The voro_compute template is</span></div>
<div class="line"><a name="l00177"></a><span class="lineno"> 177</span> <span class="comment"> * associated with a specific container class, and during the computation, it</span></div>
<div class="line"><a name="l00178"></a><span class="lineno"> 178</span> <span class="comment"> * calls routines in the container class to access the particle positions that</span></div>
<div class="line"><a name="l00179"></a><span class="lineno"> 179</span> <span class="comment"> * are stored there.</span></div>
<div class="line"><a name="l00181"></a><span class="lineno"> 181</span> <span class="comment"> * The key routine in this class is compute_cell(), which makes use of a</span></div>
<div class="line"><a name="l00182"></a><span class="lineno"> 182</span> <span class="comment"> * voronoicell class to construct a Voronoi cell for a specific particle in the</span></div>
<div class="line"><a name="l00183"></a><span class="lineno"> 183</span> <span class="comment"> * container. The basic approach that this function takes is to repeatedly cut</span></div>
<div class="line"><a name="l00184"></a><span class="lineno"> 184</span> <span class="comment"> * the Voronoi cell by planes corresponding neighboring particles, and stop</span></div>
<div class="line"><a name="l00185"></a><span class="lineno"> 185</span> <span class="comment"> * when it recognizes that all the remaining particles in the container are too</span></div>
<div class="line"><a name="l00186"></a><span class="lineno"> 186</span> <span class="comment"> * far away to possibly influence cell's shape. The code makes use of two</span></div>
<div class="line"><a name="l00187"></a><span class="lineno"> 187</span> <span class="comment"> * possible methods for working out when a cell computation is complete:</span></div>
<div class="line"><a name="l00189"></a><span class="lineno"> 189</span> <span class="comment"> * - Radius test: if the maximum distance of a Voronoi cell</span></div>
<div class="line"><a name="l00190"></a><span class="lineno"> 190</span> <span class="comment"> * vertex from the cell center is R, then no particles more than a distance</span></div>
<div class="line"><a name="l00191"></a><span class="lineno"> 191</span> <span class="comment"> * 2R away can possibly influence the cell. This a very fast computation to</span></div>
<div class="line"><a name="l00192"></a><span class="lineno"> 192</span> <span class="comment"> * do, but it has no directionality: if the cell extends a long way in one</span></div>
<div class="line"><a name="l00193"></a><span class="lineno"> 193</span> <span class="comment"> * direction then particles a long distance in other directions will still</span></div>
<div class="line"><a name="l00194"></a><span class="lineno"> 194</span> <span class="comment"> * need to be tested.</span></div>
<div class="line"><a name="l00195"></a><span class="lineno"> 195</span> <span class="comment"> * - Region test: it is possible to test whether a specific region can</span></div>
<div class="line"><a name="l00196"></a><span class="lineno"> 196</span> <span class="comment"> * possibly influence the cell by applying a series of plane tests at the</span></div>
<div class="line"><a name="l00197"></a><span class="lineno"> 197</span> <span class="comment"> * point on the region which is closest to the Voronoi cell center. This is a</span></div>
<div class="line"><a name="l00198"></a><span class="lineno"> 198</span> <span class="comment"> * slower computation to do, but it has directionality.</span></div>
<div class="line"><a name="l00200"></a><span class="lineno"> 200</span> <span class="comment"> * Another useful observation is that the regions that need to be tested are</span></div>
<div class="line"><a name="l00201"></a><span class="lineno"> 201</span> <span class="comment"> * simply connected, meaning that if a particular region does not need to be</span></div>
<div class="line"><a name="l00202"></a><span class="lineno"> 202</span> <span class="comment"> * tested, then neighboring regions which are further away do not need to be</span></div>
<div class="line"><a name="l00205"></a><span class="lineno"> 205</span> <span class="comment"> * For maximum efficiency, it was found that a hybrid approach making use of</span></div>
<div class="line"><a name="l00206"></a><span class="lineno"> 206</span> <span class="comment"> * both of the above tests worked well in practice. Radius tests work well for</span></div>
<div class="line"><a name="l00207"></a><span class="lineno"> 207</span> <span class="comment"> * the first few blocks, but switching to region tests after then prevent the</span></div>
<div class="line"><a name="l00208"></a><span class="lineno"> 208</span> <span class="comment"> * code from becoming extremely slow, due to testing over very large spherical</span></div>
<div class="line"><a name="l00209"></a><span class="lineno"> 209</span> <span class="comment"> * shells of particles. The compute_cell() routine therefore takes the</span></div>
<div class="line"><a name="l00210"></a><span class="lineno"> 210</span> <span class="comment"> * following approach:</span></div>
<div class="line"><a name="l00212"></a><span class="lineno"> 212</span> <span class="comment"> * - Initialize the voronoicell class to fill the entire computational domain.</span></div>
<div class="line"><a name="l00213"></a><span class="lineno"> 213</span> <span class="comment"> * - Cut the cell by any wall objects that have been added to the container.</span></div>
<div class="line"><a name="l00214"></a><span class="lineno"> 214</span> <span class="comment"> * - Apply plane cuts to the cell corresponding to the other particles which</span></div>
<div class="line"><a name="l00215"></a><span class="lineno"> 215</span> <span class="comment"> * are within the current particle's region.</span></div>
<div class="line"><a name="l00216"></a><span class="lineno"> 216</span> <span class="comment"> * - Test over a pre-computed worklist of neighboring regions, that have been</span></div>
<div class="line"><a name="l00217"></a><span class="lineno"> 217</span> <span class="comment"> * ordered according to the minimum distance away from the particle's</span></div>
<div class="line"><a name="l00218"></a><span class="lineno"> 218</span> <span class="comment"> * position. Apply radius tests after every few regions to see if the</span></div>
<div class="line"><a name="l00219"></a><span class="lineno"> 219</span> <span class="comment"> * calculation can terminate.</span></div>
<div class="line"><a name="l00220"></a><span class="lineno"> 220</span> <span class="comment"> * - If the code reaches the end of the worklist, add all the neighboring</span></div>
<div class="line"><a name="l00221"></a><span class="lineno"> 221</span> <span class="comment"> * regions to a new list.</span></div>
<div class="line"><a name="l00222"></a><span class="lineno"> 222</span> <span class="comment"> * - Carry out a region test on the first item of the list. If the region needs</span></div>
<div class="line"><a name="l00223"></a><span class="lineno"> 223</span> <span class="comment"> * to be tested, apply the plane() routine for all of its particles, and then</span></div>
<div class="line"><a name="l00224"></a><span class="lineno"> 224</span> <span class="comment"> * add any neighboring regions to the end of the list that need to be tested.</span></div>
<div class="line"><a name="l00225"></a><span class="lineno"> 225</span> <span class="comment"> * Continue until the list has no elements left.</span></div>
<div class="line"><a name="l00227"></a><span class="lineno"> 227</span> <span class="comment"> * The compute_cell() routine forms the basis of many other routines, such as</span></div>
<div class="line"><a name="l00228"></a><span class="lineno"> 228</span> <span class="comment"> * store_cell_volumes() and draw_cells_gnuplot() that can be used to calculate</span></div>
<div class="line"><a name="l00229"></a><span class="lineno"> 229</span> <span class="comment"> * and draw the cells in a container.</span></div>
<div class="line"><a name="l00232"></a><span class="lineno"> 232</span> <span class="comment"> * Wall computations are handled by making use of a pure virtual wall class.</span></div>
<div class="line"><a name="l00233"></a><span class="lineno"> 233</span> <span class="comment"> * Specific wall types are derived from this class, and require the</span></div>
<div class="line"><a name="l00234"></a><span class="lineno"> 234</span> <span class="comment"> * specification of two routines: point_inside() that tests to see if a point</span></div>
<div class="line"><a name="l00235"></a><span class="lineno"> 235</span> <span class="comment"> * is inside a wall or not, and cut_cell() that cuts a cell according to the</span></div>
<div class="line"><a name="l00236"></a><span class="lineno"> 236</span> <span class="comment"> * wall's position. The walls can be added to the container using the</span></div>
<div class="line"><a name="l00237"></a><span class="lineno"> 237</span> <span class="comment"> * add_wall() command, and these are called each time a compute_cell() command</span></div>
<div class="line"><a name="l00238"></a><span class="lineno"> 238</span> <span class="comment"> * is carried out. At present, wall types for planes, spheres, cylinders, and</span></div>
<div class="line"><a name="l00239"></a><span class="lineno"> 239</span> <span class="comment"> * cones are provided, although custom walls can be added by creating new</span></div>
<div class="line"><a name="l00240"></a><span class="lineno"> 240</span> <span class="comment"> * classes derived from the pure virtual class. Currently all wall types</span></div>
<div class="line"><a name="l00241"></a><span class="lineno"> 241</span> <span class="comment"> * approximate the wall surface with a single plane, which produces some small</span></div>
<div class="line"><a name="l00242"></a><span class="lineno"> 242</span> <span class="comment"> * errors, but generally gives good results for dense particle packings in</span></div>
<div class="line"><a name="l00243"></a><span class="lineno"> 243</span> <span class="comment"> * direct contact with a wall surface. It would be possible to create more</span></div>
<div class="line"><a name="l00244"></a><span class="lineno"> 244</span> <span class="comment"> * accurate walls by making cut_cell() routines that approximate the curved</span></div>
<div class="line"><a name="l00247"></a><span class="lineno"> 247</span> <span class="comment"> * The wall objects can used for periodic calculations, although to obtain</span></div>
<div class="line"><a name="l00248"></a><span class="lineno"> 248</span> <span class="comment"> * valid results, the walls should also be periodic as well. For example, in a</span></div>
<div class="line"><a name="l00249"></a><span class="lineno"> 249</span> <span class="comment"> * domain that is periodic in the x direction, a cylinder aligned along the x</span></div>
<div class="line"><a name="l00250"></a><span class="lineno"> 250</span> <span class="comment"> * axis could be added. At present, the interior of all wall objects are convex</span></div>
<div class="line"><a name="l00251"></a><span class="lineno"> 251</span> <span class="comment"> * domains, and consequently any superposition of them will be a convex domain</span></div>
<div class="line"><a name="l00252"></a><span class="lineno"> 252</span> <span class="comment"> * also. Carrying out computations in non-convex domains poses some problems,</span></div>
<div class="line"><a name="l00253"></a><span class="lineno"> 253</span> <span class="comment"> * since this could theoretically lead to non-convex Voronoi cells, which the</span></div>
<div class="line"><a name="l00254"></a><span class="lineno"> 254</span> <span class="comment"> * internal data representation of the voronoicell class does not support. For</span></div>
<div class="line"><a name="l00255"></a><span class="lineno"> 255</span> <span class="comment"> * non-convex cases where the wall surfaces feature just a small amount of</span></div>
<div class="line"><a name="l00256"></a><span class="lineno"> 256</span> <span class="comment"> * negative curvature (eg. a torus) approximating the curved surface with a</span></div>
<div class="line"><a name="l00257"></a><span class="lineno"> 257</span> <span class="comment"> * single plane cut may give an acceptable level of accuracy. For non-convex</span></div>
<div class="line"><a name="l00258"></a><span class="lineno"> 258</span> <span class="comment"> * cases that feature internal angles, the best strategy may be to decompose</span></div>
<div class="line"><a name="l00259"></a><span class="lineno"> 259</span> <span class="comment"> * the domain into several convex subdomains, carry out a calculation in each,</span></div>
<div class="line"><a name="l00260"></a><span class="lineno"> 260</span> <span class="comment"> * and then add the results together. The voronoicell class cannot be easily</span></div>
<div class="line"><a name="l00261"></a><span class="lineno"> 261</span> <span class="comment"> * modified to handle non-convex cells as this would fundamentally alter the</span></div>
<div class="line"><a name="l00262"></a><span class="lineno"> 262</span> <span class="comment"> * algorithms that it uses, and cases could arise where a single plane cut</span></div>
<div class="line"><a name="l00263"></a><span class="lineno"> 263</span> <span class="comment"> * could create several new faces as opposed to just one.</span></div>
<div class="line"><a name="l00266"></a><span class="lineno"> 266</span> <span class="comment"> * The container classes have a number of simple routines for calculating</span></div>
<div class="line"><a name="l00267"></a><span class="lineno"> 267</span> <span class="comment"> * Voronoi cells for all particles within them. However, in some situations it</span></div>
<div class="line"><a name="l00268"></a><span class="lineno"> 268</span> <span class="comment"> * is desirable to iterate over a specific subset of particles. This can be</span></div>
<div class="line"><a name="l00269"></a><span class="lineno"> 269</span> <span class="comment"> * achieved with the c_loop classes that are all derived from the c_loop_base</span></div>
<div class="line"><a name="l00270"></a><span class="lineno"> 270</span> <span class="comment"> * class. Each class can iterate over a specific subset of particles in a</span></div>
<div class="line"><a name="l00271"></a><span class="lineno"> 271</span> <span class="comment"> * container. There are three loop classes for use with the container and</span></div>
<div class="line"><a name="l00274"></a><span class="lineno"> 274</span> <span class="comment"> * - c_loop_all will loop over all of the particles in a container.</span></div>
<div class="line"><a name="l00275"></a><span class="lineno"> 275</span> <span class="comment"> * - c_loop_subset will loop over a subset of particles in a container that lie</span></div>
<div class="line"><a name="l00276"></a><span class="lineno"> 276</span> <span class="comment"> * within some geometrical region. It can loop over particles in a</span></div>
<div class="line"><a name="l00277"></a><span class="lineno"> 277</span> <span class="comment"> * rectangular box, particles in a sphere, or particles that lie within</span></div>
<div class="line"><a name="l00279"></a><span class="lineno"> 279</span> <span class="comment"> * - c_loop_order will loop over a specific list of particles that were</span></div>
<div class="line"><a name="l00280"></a><span class="lineno"> 280</span> <span class="comment"> * previously stored in a particle_order class.</span></div>
<div class="line"><a name="l00282"></a><span class="lineno"> 282</span> <span class="comment"> * Several of the key routines within the container classes (such as</span></div>
<div class="line"><a name="l00283"></a><span class="lineno"> 283</span> <span class="comment"> * draw_cells_gnuplot and print_custom) have versions where they can be passed</span></div>
<div class="line"><a name="l00284"></a><span class="lineno"> 284</span> <span class="comment"> * a loop class to use. Loop classes can also be used directly and there are</span></div>
<div class="line"><a name="l00285"></a><span class="lineno"> 285</span> <span class="comment"> * some examples on the library website that demonstrate this. It is also</span></div>
<div class="line"><a name="l00286"></a><span class="lineno"> 286</span> <span class="comment"> * possible to write custom loop classes.</span></div>
<div class="line"><a name="l00288"></a><span class="lineno"> 288</span> <span class="comment"> * In addition to the loop classes mentioned above, there is also a</span></div>
<div class="line"><a name="l00289"></a><span class="lineno"> 289</span> <span class="comment"> * c_loop_all_periodic class, that is specifically for use with the</span></div>
<div class="line"><a name="l00290"></a><span class="lineno"> 290</span> <span class="comment"> * container_periodic and container_periodic_poly classes. Since the data</span></div>
<div class="line"><a name="l00291"></a><span class="lineno"> 291</span> <span class="comment"> * structures of these containers differ considerably, it requires a different</span></div>
<div class="line"><a name="l00292"></a><span class="lineno"> 292</span> <span class="comment"> * loop class that is not interoperable with the others.</span></div>
<div class="line"><a name="l00295"></a><span class="lineno"> 295</span> <span class="comment"> * Voro++ makes use of internal computational grid of blocks that are used to</span></div>
<div class="line"><a name="l00296"></a><span class="lineno"> 296</span> <span class="comment"> * configure the code for maximum efficiency. As discussed on the library</span></div>
<div class="line"><a name="l00297"></a><span class="lineno"> 297</span> <span class="comment"> * website, the best performance is achieved for around 5 particles per block,</span></div>
<div class="line"><a name="l00298"></a><span class="lineno"> 298</span> <span class="comment"> * with anything in the range from 3 to 12 giving good performance. Usually</span></div>
<div class="line"><a name="l00299"></a><span class="lineno"> 299</span> <span class="comment"> * the size of the grid can be chosen by ensuring that the number of blocks is</span></div>
<div class="line"><a name="l00300"></a><span class="lineno"> 300</span> <span class="comment"> * equal to the number of particles divided by 5.</span></div>
<div class="line"><a name="l00302"></a><span class="lineno"> 302</span> <span class="comment"> * However, this can be difficult to choose in cases when the number of</span></div>
<div class="line"><a name="l00303"></a><span class="lineno"> 303</span> <span class="comment"> * particles is not known a priori, and in thes cases the pre_container classes</span></div>
<div class="line"><a name="l00304"></a><span class="lineno"> 304</span> <span class="comment"> * can be used. They can import an arbitrary number of particle positions from</span></div>
<div class="line"><a name="l00305"></a><span class="lineno"> 305</span> <span class="comment"> * a file, dynamically allocating memory in chunks as necessary. Once particles</span></div>
<div class="line"><a name="l00306"></a><span class="lineno"> 306</span> <span class="comment"> * are imported, they can guess an optimal block arrangement to use for the</span></div>
<div class="line"><a name="l00307"></a><span class="lineno"> 307</span> <span class="comment"> * container class, and then transfer the particles to the container. By</span></div>
<div class="line"><a name="l00308"></a><span class="lineno"> 308</span> <span class="comment"> * default, this procedure is used by the command-line utility to enable it to</span></div>
<div class="line"><a name="l00309"></a><span class="lineno"> 309</span> <span class="comment"> * work well with arbitrary sizes of input data.</span></div>
<div class="line"><a name="l00311"></a><span class="lineno"> 311</span> <span class="comment"> * The pre_container class can be used when no particle radius information is</span></div>
<div class="line"><a name="l00312"></a><span class="lineno"> 312</span> <span class="comment"> * available, and the pre_container_poly class can be used when radius</span></div>
<div class="line"><a name="l00313"></a><span class="lineno"> 313</span> <span class="comment"> * information is available. At present, the pre_container classes can only be</span></div>
<div class="line"><a name="l00314"></a><span class="lineno"> 314</span> <span class="comment"> * used with the container and container_poly classes. They do not support</span></div>
<div class="line"><a name="l00315"></a><span class="lineno"> 315</span> <span class="comment"> * the container_periodic and container_periodic_poly classes. */</span></div>
<div class="line"><a name="l00320"></a><span class="lineno"> 320</span> <span class="preprocessor">#include "<a class="code" href="config_8hh.html" title="Master configuration file for setting various compile-time options.">config.hh</a>"</span></div>
<div class="line"><a name="l00321"></a><span class="lineno"> 321</span> <span class="preprocessor">#include "<a class="code" href="common_8hh.html" title="Header file for the small helper functions.">common.hh</a>"</span></div>
<div class="line"><a name="l00322"></a><span class="lineno"> 322</span> <span class="preprocessor">#include "<a class="code" href="cell_8hh.html" title="Header file for the voronoicell and related classes.">cell.hh</a>"</span></div>
<div class="line"><a name="l00323"></a><span class="lineno"> 323</span> <span class="preprocessor">#include "<a class="code" href="v__base_8hh.html" title="Header file for the base Voronoi container class.">v_base.hh</a>"</span></div>
<div class="line"><a name="l00324"></a><span class="lineno"> 324</span> <span class="preprocessor">#include "<a class="code" href="rad__option_8hh.html" title="Header file for the classes encapsulating functionality for the regular and radical Voronoi tessellat...">rad_option.hh</a>"</span></div>
<div class="line"><a name="l00325"></a><span class="lineno"> 325</span> <span class="preprocessor">#include "<a class="code" href="container_8hh.html" title="Header file for the container_base and related classes.">container.hh</a>"</span></div>
<div class="line"><a name="l00326"></a><span class="lineno"> 326</span> <span class="preprocessor">#include "<a class="code" href="unitcell_8hh.html" title="Header file for the unitcell class.">unitcell.hh</a>"</span></div>
<div class="line"><a name="l00327"></a><span class="lineno"> 327</span> <span class="preprocessor">#include "<a class="code" href="container__prd_8hh.html" title="Header file for the container_periodic_base and related classes.">container_prd.hh</a>"</span></div>
<div class="line"><a name="l00328"></a><span class="lineno"> 328</span> <span class="preprocessor">#include "<a class="code" href="pre__container_8hh.html" title="Header file for the pre_container and related classes.">pre_container.hh</a>"</span></div>
<div class="line"><a name="l00329"></a><span class="lineno"> 329</span> <span class="preprocessor">#include "<a class="code" href="v__compute_8hh.html" title="Header file for the voro_compute template and related classes.">v_compute.hh</a>"</span></div>
<div class="line"><a name="l00330"></a><span class="lineno"> 330</span> <span class="preprocessor">#include "<a class="code" href="c__loops_8hh.html" title="Header file for the loop classes.">c_loops.hh</a>"</span></div>
<div class="line"><a name="l00331"></a><span class="lineno"> 331</span> <span class="preprocessor">#include "<a class="code" href="wall_8hh.html" title="Header file for the derived wall classes.">wall.hh</a>"</span></div>