<?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.wigner_seitz_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>Wigner-Seitz defect analysis</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/wigner_seitz_analysis_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
    This analysis modifier identifies point defects and counts vacancies and interstitials in a crystal
    using the so-called Wigner-Seitz cell method.
  </para>  

  <para>
    The Wigner-Seitz cell method works as follows: We assume that there exist two configurations of
    the atomistic system. One is the <emphasis>reference state</emphasis>, which is defect-free (typically a perfect crystal lattice).
    The other is the <emphasis>displaced configuration</emphasis>, which represents the defective state of the crystal to be analyzed.
    Here, some atoms have been displaced from their original sites.
  </para>
  <para>
    Each atomic site in the reference configuration defines the center of a Wigner-Seitz cell (also called Voronoi cell),
    which is the spatial region that belongs to that site. Any atom (from the displaced configuration) that is located within the Wigner-Seitz cell
    of a reference site is said to occupy that site. The analysis modifier basically counts the number of
    atoms from the displaced configuration that occupy each site from the reference configuration. Typically, 
    sites are occupied by exactly one atom each. However, some sites may by occupied by zero atoms (then we call it a vacancy)
    or by more than one atom (then we call the excess atoms interstitials).
  </para>
  <para>
    The modifier outputs the number of atoms sitting on each site as a new particle property named <literal>Occupancy</literal>.
    This property allows to subsequently filter out normal sites and show only defective sites (e.g. by using the <link linkend="particles.modifiers.expression_select">Expression Select</link> modifier).
    Furthermore, the modifier reports two global quantities:
    <variablelist>
      <varlistentry>
        <term>Number of vacancies</term>
        <listitem>
          <para>This is the total number of sites in the reference configuration which are not occupied by any atom 
          in the displaced configuration (sites with occupancy=0).</para>
        </listitem>
      </varlistentry> 
      <varlistentry>
        <term>Number of interstitials</term>
        <listitem>
          <para>This is the total number of excess atoms, summed over all sites of the reference configuration. 
          A site with occupancy=2 has one excess atom. A site with occupancy=3 has two excess atoms, and so forth.</para>
        </listitem>
      </varlistentry> 
    </variablelist>
  </para>
  <para>
    The number of atoms in the reference configuration and in the displaced configuration do not have to be the same. 
    However, if the two configurations do contain the same number of atoms, then the number of vacancies and the number of interstitials
    reported by the modifier will be equal. That is because, in this case, the sum over all occupancy numbers is equal to the
    number of sites in the reference configuration.
  </para>
  
  <para>
    The modifier loads the reference configuration from a separate input file.
    Use the <emphasis>"Reference: External file"</emphasis> panel to pick the
    file containing the reference particle positions, which define the defect-free state of the crystal.
    The displaced configuration is given by the particle dataset to which the Wigner-Seitz modifier is being applied.
  </para>
  
  <para>
    <emphasis>IMPORTANT NOTE</emphasis>: 
    After performing the analysis this modifier throws away the displaced configuration and completely replaces it with the 
    reference configuration loaded from the external file. Thus, as an effect of applying the Wigner-Seitz modifier you will 
    now see the reference configuration (defect-free crystal) instead of the displaced configuration (defective crystal) which you applied it to. 
    This makes sense because the computed occupancy numbers apply to the atomic sites of the reference configuration, 
    not to the atoms of the defective crystal. Keep in mind that the modifier only computes the number of atoms that occupy each
    site. It does not tell you which atom from the defective configuration occupies which site.
  </para>
  
  <para>
    However, if somewhat more detailed information is needed, the modifier provides the 
    <emphasis>Output per-type occupancies</emphasis> option. If actived, the modifer breaks down the
    occupancy number of each site into per-type counts. Thus, if your displaced configuration contains
    atoms of different types, then this allows you to determine how many atoms of each type occupy each
    site in the ideal reference crystal. The per-type occupancy numbers are output as
    vector components of the <literal>Occupancy</literal> particle property. For example, the
    property component <literal>Occupancy.1</literal> contains the number of atoms of type 1 that occupy a site.
  </para>

  <simplesect>
    <title>Parameters</title>

    <variablelist>

      <varlistentry>
        <term>Eliminate homogeneous cell deformation</term>
        <listitem>
          <para>This option lets the modifier first rescale the 
          simulation cell of the displaced configuration including all particle positions to match the 
          cell shape of the reference configuration before performing the Wigner-Seitz analysis. This effectively eliminates any
          macroscopic, homogeneous deformation of the simulation cell, and the atomic displacements will reflect only the internal motion of particles.</para>
        </listitem>
      </varlistentry>    

      <varlistentry>
        <term>Output per-type occupancies</term>
        <listitem>
          <para>If this option is active, the modifier outputs per-type occupancy numbers as explained above.</para>
        </listitem>
      </varlistentry>    

      <varlistentry>
        <term>Fixed reference configuration</term>
        <listitem>
          <para>If this option is active, the selected animation frame from the reference simulation sequence is used
          as a fixed reference to perform the analysis. This is the default mode.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Relative to current frame</term>
        <listitem>
          <para>If this option is active, then a changing reference configuration is used for the analysis.
          The frame offset controls the distance between reference and current frame and can be negative or positive. If it is negative, then the reference frame 
          precedes the current frame in the simulation sequence. 
          Note that the analysis will not be performed for frames for which the reference frame is negative or out of range.
          </para>
        </listitem>
      </varlistentry>
 
    </variablelist>
  </simplesect>
  
  <simplesect>
    <title>Implementation detail</title>
    <para>
       The Wigner-Seitz cell of a site is by definition the locus of points in space that are closer to that 
       site than to any of the other sites. Note, however, that the modifier never has to compute the shape of the 
       Wigner-Seitz cells explicitly to perform the analysis. It rather determines 
       the closest site from the reference configuration for each atom of the displaced configuration. 
       The occupancy counter of that site is then incremented by one.
    </para>
  </simplesect>
  
</section>
