<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="particles.modifiers.voronoi_analysis"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Voronoi analysis</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/voronoi_analysis_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
    This analysis modifier calculates the Voronoi tessellation of the simulation box, taking the particle positions as Voronoi cell centers. 
    By default two quantities are output by the analysis modifier for each particle:
    The volume of the particle's Voronoi cell and the number of faces the Voronoi cell has. Since the face count
    is equal to the number of nearest neighbors of the particle, this quantity is also called the coordination number.    
  </para>
  
  <para>
    In addition the modifier can compute the <emphasis>Voronoi index</emphasis> of each cell,
    which is a vector of integers constituting a histogram of the number of edges on the faces of the Voronoi cell.
    This index vector can be considered a characteristic signature of a particle's coordination structure.
    For instance, an icosahedral coordination structure corresponds to the Voronoi index vector (0,0,0,0,12,0,...).
    In other words, these indices describe a polyhdron with exactly 12 faces with 5 edges each. 
    To select all atoms having this kind of icosahedral coordination structure we can use the 
    <link linkend="particles.modifiers.expression_select">Expression select</link>
    modifier with the Boolean expression:
    <programlisting>VoronoiIndex.3==0 &amp;&amp; VoronoiIndex.4==0 &amp;&amp; VoronoiIndex.5==12 &amp;&amp; VoronoiIndex.6==0</programlisting>
    (<literal>VoronoiIndex.1</literal> and <literal>VoronoiIndex.2</literal> are always zero because faces with less than three edges do not exist.)
  </para> 
  
  <para>
    If you are interested in the Voronoi indices computed by the analysis modifier for a particular atom, you can use the
    <link linkend="usage.particle_inspection_utility">Particle Inspection</link> utility to select the atom
    in the viewports and display its properties (including the assigned Voronoi indices).
  </para> 

  <para>
    If you want to know what is the Voronoi index vector that occurs most frequently in your atomistic system, 
    you can perform a statistical analysis of the computed Voronoi indices using a custom Python script.
    You can find an example script in the <link xlink:href="python/introduction/examples.html#computing-voronoi-indices">OVITO scripting manual</link>.
  </para>
  
  <para>
    Note that the modifier calculates the Voronoi tessellation of the volume enclosed by the simulation cell only (and not 
    entire space). Thus, Voronoi cells will be truncated at the simulation box boundaries (unless periodic boundary conditions are used).
    No computation will be performed for particles located outside the (non-periodic) simulation box boundaries 
    (but they will still be taken into account when calculating the Voronoi cells of particles inside the box).
  </para>
  
  <simplesect> 
    <title>Parameters</title>

    <variablelist>

      <varlistentry>
        <term>Face area threshold</term>
        <listitem>
          <para>
             Specifies a minimum area for faces of a Voronoi cell. The modifier will ignore any Voronoi cell faces with an area smaller than this
             threshold when computing the coordination number and the Voronoi index of particles.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Compute Voronoi indices</term>
        <listitem>
          <para>
             Lets the modifier calculate the Voronoi indices of particles. The modifier stores the computed indices in a vector particle property
             named <code>Voronoi Index</code>. The <emphasis>i</emphasis>-th component of this property will contain the number of faces of the 
             Voronoi cell that have <emphasis>i</emphasis> edges. Thus, the first two components of the per-particle vector will always be zero, because the minimum
             number of edges a polygon can have is three.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Maximum edge count</term>
        <listitem>
          <para>
             Controls the order up to which Voronoi indices are computed. Note that Voronoi faces with a more edges than this maximum will be ignored when calculating the index vector.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Edge length threshold</term>
        <listitem>
          <para>
             Specifies the minimum length an edge must have to be considered in the Voronoi index calculation. Edges that are shorter
             than this threshold will be ignored when counting the number of edges of a Voronoi face.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Generate neighbor bonds</term>
        <listitem>
          <para>
             If this option is enabled, the modifier outputs the bonds between pairs of
             neighboring particles. A bond is generated for every Voronoi face whose
             area is larger than the specified face area threshold, and which has at least three edges
             longer than the specified edge length threshold.
          </para>
          <para>
             Note that bonds in periodic simulation cells are computed using the minimum image convention,
             which requires that the cell is at least twice as large in each periodic direction as the 
             longest neighbor bond. In cases where the cell is shorter, the computed bonds might be incorrect.
          </para>
        </listitem>
      </varlistentry>
            
      <varlistentry>
        <term>Use particle radii</term>
        <listitem>
          <para>
             Lets the modifier compute the poly-disperse Voronoi tessellation, which takes into account the radii of particles.
             Otherwise a mono-disperse Voronoi tessellation is computed, which is independent of the particle sizes.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Use only selected particles</term>
        <listitem>
          <para>
             Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be treated as if they did not exist.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </simplesect>
  
  <simplesect> 
    <title>Acknowledgment</title>
    <para>This modifier uses the <link xlink:href="http://math.lbl.gov/voro++/">Voro++ package</link> of Chris Rycroft to compute Voronoi polyhedra.</para>
  </simplesect>
  
</section>
