<?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.common_neighbor_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>Common neighbor analysis</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/common_neighbor_analysis_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
  This analysis modifier performs the <emphasis>Common Neighbor Analysis</emphasis> (CNA) [<link
  xlink:href="http://dx.doi.org/10.1021/j100303a014">Honeycutt and Andersen, J. Phys. Chem. 91, 4950</link>] 
  for a particle system. The CNA is an algorithm to compute a fingerprint for
  pairs of atoms, which is designed to characterize the local structural environment. 
  Typically, the CNA is used as an effective filtering method to classify atoms in crystalline systems 
  [<link xlink:href="http://dx.doi.org/10.1016/0927-0256(94)90109-0">Faken and Jonsson, Comput. Mater. Sci. 2, 279</link>], 
  with the goal to get a precise understanding of which atoms are associated with which phases, 
  and which are associated with defects.
  </para>
  
  <para>
  The modifier supports three different modes of operation:
  <variablelist>

  <varlistentry><term>Conventional CNA (with fixed cutoff)</term>
  <listitem>
  <para>Here, a threshold distance criterion is used to determine whether a pair of atoms
  is bonded or not. The cutoff distance must be chosen
  according to the crystal structure at hand. For face-centered cubic (FCC)
  and hexagonal close-packed (HCP) structures the cutoff radius must lie midway between 
  the first and the second shell of neighbors. 
  For body-centered cubic (BCC) structures the cutoff radius should be positioned
  between the second and the third neighbor shell. OVITO provides a list of
  optimal cutoff distances for FCC and BCC crystal structures formed by common pure
  elements. These optimal radii can be found in the <guilabel>Presets</guilabel>
  drop-down list.</para>
  </listitem></varlistentry>

  <varlistentry><term>Adaptive CNA (with variable cutoff)</term>
  <listitem>
  <para>Sometimes it may be difficult to choose the right cutoff radius for the conventional CNA, in particular in the
  case of multiphase systems. This is why an adaptive version of the CNA has been
  developed that works without a fixed cutoff. The
  <emphasis>Adaptive Common Neighbor Analysis</emphasis> (a-CNA) method [<link
  xlink:href="http://dx.doi.org/10.1088/0965-0393/20/4/045021">Stukowski,
  Modell. Simul. Mater. Sci. Eng. 20, 045021</link>] determines the optimal cutoff radius automatically 
  for each individual particle.</para>
  </listitem></varlistentry>
  
  <varlistentry><term>Bond-based CNA (without cutoff)</term>
  <listitem>
  <para>The modifier also supports a <emphasis>bond-based</emphasis> mode of operation. Then the CNA indices 
  are computed based on the existing network of bonds between particles (without using a cutoff radius
  and irrespective of the distance between particles). This mode requires that bonds between
  particles have previously been defined, for example using a <link linkend="particles.modifiers.create_bonds">Create Bonds</link> modifier
  or by loading them from a data file. Furthermore, in the bond-based mode, the modifier
  outputs the computed per-bond CNA indices as a new bond property named <literal>CNA indices</literal>,
  which can be used for further statistical analyses.
  The computed CNA bond indices may be accessed from a Python script, <link xlink:href="python/introduction/examples.html#example-compute-cna-bond-indices">see this example</link>.
  </para>
  </listitem></varlistentry>
    
  </variablelist>
  </para>

  <para>
  The modifier classifies each particle according to its structural environment and stores 
  the results in a new particle property named <literal>Structure Type</literal>.
  This allows you to subsequently select and filter out particles of a certain structural type, e.g. by using the 
  <link linkend="particles.modifiers.select_particle_type">Select Particle Type</link> modifier.
  The structural types are encoded as integer values:
    <itemizedlist>
    
      <listitem>
        <para>0 = Other, unknown coordination structure</para>
      </listitem>
    
      <listitem>
        <para>1 = FCC, face-centered cubic</para>
      </listitem>

      <listitem>
        <para>2 = HCP, hexagonal close-packed</para>
      </listitem>

      <listitem>
        <para>3 = BCC, body-centered cubic</para>
      </listitem>

      <listitem>
        <para>4 = ICO, icosahedral coordination</para>
      </listitem>

    </itemizedlist>
  </para>
  
  <para>
    To identify diamond lattice structures, please use the 
    <link linkend="particles.modifiers.identify_diamond_structure">Identify Diamond Structure</link> modifier instead.
  </para>

  <para>
    The CNA modifier requires access to the complete set of input particles to perform the analysis. It should therefore be placed at the 
    beginning of the processing pipeline, preceding any modifiers that delete particles.
  </para>
  
  <para>
    The <emphasis>Use only selected particles</emphasis> option restricts the analysis to the
    currently selected particles. If this option is activated, unselected particles will be ignored 
    (as if they did not exist) and will be assigned the structure type "Other".
    This option can be useful if you want to identify defects in a crystal structure
    not supported by the CNA method, but which has a sublattice that can be identified by the CNA
    (and you do not want to delete particles belonging to the other sublattice(s) for some reason).
    This option has no effect in <emphasis>bond-based</emphasis> mode.
  </para>
  
</section>
