<?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.dislocation_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>Dislocation analysis (DXA)</title>

  <para>
  
    <informalfigure>
      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row valign="bottom">
              <entry>Input:</entry>
              <entry>Output:</entry>
            </row>
            <row valign="top">
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/dislocation_analysis_example_input.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/dislocation_analysis_example_output.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
      
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/dislocation_analysis_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    
    This analysis modifier identifies all dislocations in a crystal, determines their Burgers vectors, 
    and outputs a line representation of the dislocation defects. The modifier implements the so-called
    <emphasis>Dislocation Extraction Algorithm</emphasis> (DXA), a computational method developed by the author of OVITO.
    The original DXA method has been described in the paper
    <blockquote><para>
<literallayout><link xlink:href="http://iopscience.iop.org/0965-0393/18/8/085001/">A. Stukowski and K. Albe.
Modelling Simul. Mater. Sci. Eng. 18, 085001 (2010)</link></literallayout>
    </para></blockquote>
    The current implementation in OVITO follows a newer, more general approach, which has been developed in 
    a follow-up paper:
    <blockquote><para>
<literallayout><link xlink:href="http://dx.doi.org/10.1088/0965-0393/20/8/085007">A. Stukowski, V.V. Bulatov and A. Arsenlis.
Modelling Simul. Mater. Sci. Eng. 20, 085007 (2012)</link></literallayout>
    </para></blockquote>
    Please cite the latter reference when using the <emphasis>Dislocation analysis</emphasis> modifier. A
    short overview on how the DXA works can be found at the end of this page.
  </para>

  <para>
    The DXA transforms the original atomistic representation of a dislocated crystal into a line-based representation 
    of the dislocation network. It determines the Burgers vector of each dislocation segment 
    and identifies dislocation junctions. The algorithm can recognize partial dislocations and also
    certain secondary grain boundary dislocations (e.g. twinning dislocations in FCC).
  </para>
  
  <para>
    Note that, even though the implementation of the DXA in OVITO is highly optimized, the algorithm is computationally
    expensive and requires sufficient working memory. <emphasis role="strong">The minimum memory requirement is 1 kilobyte per input atom!</emphasis>
    Thus, to analyze a dataset with 1 million atoms at least 1 GB of free memory is required.
  </para>

  <para>
    OVITO allows you to save the dislocation lines extracted by the modifier to a so-called <emphasis>Crystal Analysis file</emphasis> (CA file)
    using the program's <link linkend="usage.export">file export function</link>. This allows you to further process the 
    dislocation lines outside of OVITO or to reload the dislocation data at a later time without the need to reperform the 
    computationally expensive analysis. The CA file format is documented <link linkend="particles.modifiers.dislocation_analysis.fileformat">below</link>.
  </para>

   <simplesect>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>Input crystal type</term>
        <listitem>
          <para>This parameter specifies the lattice type of the input crystal. Currently, simple crystal stuctures such as
          FCC, HCP, BCC, and diamond are supported. The DXA ignores the chemical atom types. Thus,
          a zinc blende structure, for example, can simply be treated as a cubic diamond crystal.
          </para>
          <para>
          The selected input crystal type tells OVITO how to identify the local coordination structure of
          each atom and how to compute the local crystal orientation. The selected crystal type also determines 
          how the computed Burgers vectors are represented (three-component notation for crystals with cubic symmetry,
          four-component notation for hexagonal crystals).
          </para>
          <para>
          Furthermore, for each available crystal type, OVITO defines a set of dislocation classes into which the
          extracted dislocation lines are grouped. Dislocations with a Burgers vector that does not belong to any of the 
          predefined families are assigned to the category "Other". Currently, the list of dislocation classes is hardcoded
          and cannot be changed by the user. Please contact the developer if you think that a new dislocation class should be 
          added for a certain crystal type.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Trial circuit length</term>
        <listitem>
          <para>This sets the maximum length of trial Burgers circuits, which are constructed
          by the DXA to discover dislocations in the crystal. The maximum circuit length is specified
          in terms of the number of atom-to-atom steps. Dislocations whose core is too wide to be enclosed
          by a circuit of the given maximum length will not be found by the algorithm. 
          </para>
          <para>
          The default value for this parameter is 14, which is sufficient to discover all typical lattice dislocations
          in the types of crystals supported by the modifier. 
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Circuit stretchability</term>
        <listitem>
          <para>Once the DXA has discovered a dislocation segment and constructed a Burgers circuit around its dislocation core, the algorithm
          advances the circuit along the dislocation to generate a line presentation of the segment.
          The thickness of the core may vary along the dislocation (e.g. it becomes wider close to a dislocation junction).
          This is why the circuit has a certain amount of elasticity, which is set by the stretchability parameter.
          A value of 9 (the default), for example, allows the circuit to expand to a length that is 
          nine steps longer than the limit set by the <emphasis>trial circuit length</emphasis> parameter above.
          </para>
        </listitem>
      </varlistentry>
      <!-- 
      <varlistentry>
        <term>Reconstruct edge vectors</term>
        <listitem>
          <para>This option enables an additional algorithm step which enhances the identification of dislocations in some situations.
          The DXA then tries to reconstruct the mapping of the physical crystal to an ideal crystal from available information on the surrounding atoms.
          The goal of this step is to further extend the <emphasis>good</emphasis> crystal region and reduce
          the <emphasis>bad</emphasis> region around defect cores as far as possible. As a result, dislocations can now be found that have very wide cores or which are
          located in highly distorted crystal regions. For example, it may become possible in certain cases to extract the complete (primary) dislocation 
          content of a grain boundary with this option, even if the dislocation cores overlap.
          </para>
          <para>
          However, the reconstruction step may have side effects: The automated algorithm may report spurious dislocations in highly distorted regions of a 
          crystal (i.e. containing a very dense accumulation of defects), which a human would not consider proper dislocations. For example very short segments, 
          sometimes even shorter than their core diameter. Furthermore, as another side effect, the location and shape of regular dislocations reported by the algorithm may be
          less accurate if this option is enabled. The reason is that the Burgers circuit constructed by the algorithm will no longer enclose the 
          original, extended core of a dislocation, but an artificially shrinked version. However, the computed Burgers vector will not be affected by this.
          </para>
          <para>
          Please use this option only if you have experience in manually identifying 
          dislocations in atomistic simulations so you can verify the output of the algorithm if necessary.
          </para>
        </listitem>
      </varlistentry>
       -->
      <varlistentry>
        <term>Use only selected particles</term>
        <listitem>
          <para>This option restricts the analysis to the subset of currently selected atoms. 
          When activate, unselected atoms 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 dislocations in a crystal with a structure
          not supported by the modifier, but which has a sublattice that is supported
          (and you do not want to delete atoms belonging to the other sublattice(s) for some reason).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Output interface mesh</term>
        <listitem>
          <para>Tells the analysis modifier to display the so-called interface mesh, a closed manifold which separates 
          the good crystal region from the bad crystal region. The interface mesh is normally not of interest and 
          this option exists only for debugging purposes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Generate perfect dislocations</term>
        <listitem>
          <para>Restricts the identification to perfect dislocations. Normally, the DXA tries to identify
          partial dislocations (in FCC, HCP and diamond lattices). This option turns the identification
          of stacking faults, partial dislocations and also twinning dislocations off. As a result, the network produced by DXA will consist of perfect
          dislocations only, and leading and trailing partials of dissociated dislocations will be output as one line instead of two. 
          This option is useful in certain situations, e.g. when the extracted line network
          is going to be used as starting configuration for a discrete dislocation dynamics simulation that does not support partial dislocations.
          Make sure you set the <emphasis>Trial circuit length</emphasis> and <emphasis>Circuit stretchability</emphasis> parameters 
          to higher values when using this option, because longer Burgers circuits are required to trace perfect
          dislocations which are dissociated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Line smoothing level</term>
        <listitem>
          <para>The raw dislocation lines generated by the DXA are typically noisy (due to the atomistic nature of the dislocation cores)
          and need to be post-processed to produce smooth dislocation curves. This parameter controls the number of
          iterations of the smoothing algorithm to perform.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Line point separation</term>
        <listitem>
          <para>The raw dislocation lines generated by the DXA consist of a very dense sequence of points.
          To produce smooth lines, the number of points is reduced in a post-processing step. This parameter controls
          the desired distance between successive points along a dislocation line. The distance is only an approximate number
          and is measured in multiples of the interatomic spacing in the underlying crystal.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Surface smoothing level</term>
        <listitem>
          <para>The raw defect mesh generated by the DXA contains atomically sharp steps and needs to be 
          post-processed to produce a smooth surface. This parameter controls the number of
          iterations of the smoothing algorithm to perform.
          </para>
        </listitem>
      </varlistentry>
	</variablelist>
    </simplesect>

    <simplesect>
    <title>Outputs</title>
    <para>
       After analyzing the atomistic input crystal, the modifier produces serveral pieces of output: 
       <variablelist>
          <varlistentry>
          <term>Dislocation lines</term>
          <listitem>
          <para>The dislocation segments identified by the DXA are output as continuous lines. Each dislocation segment 
                has a starting point and an endpoint. The two define the orientation of the dislocation line (the <emphasis>line sense</emphasis>).
                Each end may be part of a <emphasis>junction</emphasis>, where it is connected to 
                other dislocation segments, or it may be a <emphasis>dangling</emphasis> end. Dislocations that merge into a crystal's surface
                or into other extended defects have dangling ends. If a dislocation is a loop, its starting point forms a 2-junction with its endpoint. 
                Dislocation loops need not be loop-shaped; they can also be infinite lines, going through a periodic boundary of the simulation cell.
          </para>
          <para>
                In addition to this geometric information, each dislocation segment has two additional properties: The ID of the crystallite cluster
                it is embedded in (see below) and its Burgers vector. The Burgers vector computed for a segment is its <emphasis>true</emphasis> Burgers vector, i.e.
                a vector in the ideal reference crystal frame.
          </para>
          </listitem>
          </varlistentry>
          
          <varlistentry>
          <term>Defect mesh</term>
          <listitem>
          <para>As part of the dislocation identification process, the DXA divides the input crystal into 
                a so-called <emphasis>good</emphasis> and a <emphasis>bad</emphasis> region. Within the good crystal region the algorithm was able to 
                map atoms to a perfect reference state. This part of space includes atoms that are in a perfect crystalline
                environment (which may be subject to slight elastic distortions), stacking faults, and coherent grain boundaries. The bad crystal region,
                in contrast, comprises those parts where the atomic arrangement does not resemble a perfect crystal (or any of the planar defects mentioned above).
                The cores of dislocations belong to the bad crystal region as well as other, unidentified defects, the outer surfaces, and 
                voids within the crystal.
          </para>
          <para>
                The DXA constructs the dividing surface which separates the good from the bad crystal region. This <emphasis>interface mesh</emphasis> is a two-dimensional manifold 
                that encloses the dislocation cores and all other defects in the crystal (except stacking faults and certain grain boundaries, which have been classified as 
                being part of the good region). This intermediate geometric data structure allows the DXA to effectively find dislocation lines by applying the Burgers circuit
                construction. Those parts of the interface mesh which are associated with dislocations will subsequently be removed. The remaining parts, which enclose non-dislocation
                defects, form the so-called <emphasis>defect mesh</emphasis>. It is a triangulated mesh, which is output by the DXA analysis modifier, and which represents 
                the bad crystal regions that have not been classified as dislocations.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term>Atomic structure types</term>
          <listitem>
          <para>As part of the DXA a structure identification is performed, in which the local environment of each atom is analyzed to identify
                atoms that form a perfect crystal lattice. This information is output by the modifier as a new particle property
                named <literal>Structure type</literal>. The atomic structure identification is based on the common neighbor analysis method,
                and the results are very similar to what you would get by applying the <link linkend="particles.modifiers.common_neighbor_analysis">Common Neighbor Analysis</link> 
                or the <link linkend="particles.modifiers.identify_diamond_structure">Identify Diamond Structure</link> modifier.
          </para>
          <para>
                Note that the list of structure types the algorithm looks for depends on the selected input crystal type. For example, if the selected input crystal type
                is "FCC", then the DXA will only look for atoms in FCC and HCP arrangements. The latter form stacking faults and coherent twin boundaries and
                are therefore important for the identification of partial dislocations in the FCC lattice.                
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term>Atomic clusters</term>
          <listitem>
          <para>After the atomic structure identification step is completed, the DXA combines atoms into clusters. A cluster is a contiguous crystallite consisting of atoms 
                of the same structural type (e.g. "FCC"). Atoms that are part of an FCC stacking fault, for instance, are grouped into an HCP cluster. 
                Another example: An FCC bicrystal with a coherent twin boundary gets divided into three clusters: Two FCC clusters for the grains and one HCP cluster that comprises the 
                atoms of the boundary core. 
          </para>
          <para>
                Each cluster created by the algorithm has a unique ID (a positive integer), and the modifier outputs the assignments of atoms to clusters as 
                a new particle property named <literal>Cluster</literal>, containing the ID of the cluster the atom belongs to.
                Atoms with an undentified coordination structure are not part of any cluster, which is indicated by the special value 0.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term>Cluster graph</term>
          <listitem>
          <para>The atomic clusters form an abstract adjacency graph, which is built up by the algorithm. 
                For example, a bicrystal with two grains separated by a grain boundary can be described 
                in terms of a graph with three nodes (the three atomic clusters) and two edges connecting both grains with the grain boundary cluster.
                Each cluster establishes a local lattice coordinate system, and the true Burgers vector computed by the DXA for a dislocation
                embedded in a crystal cluster is expressed in this coordinate frame.
                A graph edge connecting two adjacent cluster carries information about their crystallographic orientation relationship. 
                This orientation relationship, which is described in terms of a transformation matrix, can be used to rotate 
                vectors from the lattice coordinate frame of one grain to other grain. Ultimately, this abstract description of a polycrystalline
                microstructure enables the identification of dislocations (which can involve Burgers circuits that cross grain boundaries and stacking faults).
          </para>
          <para>
                Even though the cluster graph is generated by the DXA modifier as an intermediate data structure, OVITO currently provides no means for the user to access
                or visualize this output data. Future versions of the program may come with a user interface that allows to inspect the generated cluster graph.
          </para>
          </listitem>
          </varlistentry>
          
       </variablelist>
    </para>
    <para>
        Note that you can position the mouse cursor over an extracted dislocation line in the viewports to let OVITO display its properties in the status bar 
        of the main window. Alternatively, you can use the "Inspect Dislocations" utility on the utilities tab of OVITO's command panel to 
        list more properties of individual dislocation lines.
    </para>
    <para>
        The dislocation lines extracted by the modifier can be exported using OVITO's <link linkend="usage.export">file export function</link>.
        Currently, a simple text-based output format is supported, which is also used by another code (<emphasis>Crystal Analysis Tool</emphasis>) that implements the DXA.
        Please contact the author of OVITO if you need the specification of this CA dislocation file format. OVITO can also import CA files,
        which allows saving the results of a (possibly) expensive dislocation analysis to disk and then reloding them again later.
    </para>
  </simplesect> 
       
  <simplesect>
    <title>Technical background</title>
    <para>
       What follows is a brief summary of the Dislocation Extraction Algorithm (DXA). If you are interested
       in more details, please have a look at <link xlink:href="http://dx.doi.org/10.1088/0965-0393/20/8/085007">this paper</link>.
    </para>
    <para>
      <informalfigure>
      <informaltable frame="none">
       <tgroup cols="1">
          <tbody>
            <row>
              <entry><screenshot><mediaobject><imageobject>
              <imagedata fileref="images/modifiers/dxa/burgers_circuit.png" format="PNG" />
              </imageobject></mediaobject></screenshot></entry>
            </row>
            <row>
              <entry><para>
               Burgers circuit method to detect and identify a dislocation. A closed circuit around the dislocation is 
               translated from (a) the dislocated crystal to (b) the perfect reference crystal. The closure failure is called 
               the Burgers vector of the dislocation.
              </para></entry>
            </row>
          </tbody>
          </tgroup>
        </informaltable>
      </informalfigure> 
      The fundamental concept underlying the DXA is the Burgers circuit construction <link xlink:href="http://dx.doi.org/10.1080/14786445108561310">[Frank1951]</link>, which 
      is the canonical method already proposed in the 1950s to discriminate dislocations from other 
      crystal defects and to determine their Burgers vectors. In the formulation employed here, a Burgers circuit <emphasis>C</emphasis>
      is a path in the dislocated crystal consisting of a sequence of atom-to-atom steps (line elements &#x0394;<emphasis role="strong">x</emphasis>), 
      as shown in the figure. 
    </para>
    
    <para>
      We assume that there exists a mapping &#x0394;<emphasis role="strong">x</emphasis>&#x2192; &#x0394;<emphasis role="strong">x'</emphasis>
      that translates each line element of the path to a corresponding image, &#x0394;<emphasis role="strong">x'</emphasis>, in a perfect crystal 
      lattice. Summing these transformed line elements algebraically along the associated path, <emphasis>C'</emphasis>, 
      gives the true Burgers vector of the dislocation enclosed by <emphasis>C</emphasis>:
      <screenshot><mediaobject><imageobject>
        <imagedata fileref="images/modifiers/dxa/burgers_sum.png" format="PNG" />
      </imageobject></mediaobject></screenshot>
      The Burgers vector <emphasis role="strong">b</emphasis> is the closure failure of the path after transferring it to the perfect reference crystal. 
      Notably, the resulting vector <emphasis role="strong">b</emphasis> stays the same if we change the original circuit <emphasis>C</emphasis>, as long as it still 
      encloses the same dislocation. On the other hand, if <emphasis role="strong">b</emphasis>=<emphasis role="strong">0</emphasis>, we know that the Burgers circuit 
      did not enclose any defect with dislocation character (deliberately ignoring the possibility that the circuit encloses multiple dislocations whose Burgers vectors cancel). 
    </para>
    
    <para>
      Typically the Burger circuit construction is performed by hand to analyze two-dimensional crystal images obtained from 
      high-resolution microscopy or atomistic computer simulations. Human intuition and cognitive capabilities are required 
      to spot irregularities in the crystal lattice which are potential dislocation defects and to map path steps in elastically 
      distorted crystal regions to the ideal lattice. Automating these tasks poses a particular challenge when developing a 
      dislocation identification algorithm. First of all, an efficient strategy is needed that guides the construction of 
      Burgers circuits, given that there is no a priori knowledge of the dislocation positions, because it clearly is not 
      feasible to enumerate all possible circuits in a crystal to find the contained dislocations.     
    </para>
    
    <para>
      <informalfigure>
      <informaltable frame="none">
       <tgroup cols="1">
          <tbody>
            <row>
              <entry><screenshot><mediaobject><imageobject>
              <imagedata fileref="images/modifiers/dxa/edge_dislocation_tessellation.png" format="PNG" />
              </imageobject></mediaobject></screenshot></entry>
            </row>
            <row>
              <entry><para>
               (a) Delaunay tessellation of a dislocated crystal. Defect core atoms as identified by a structural characterization 
               technique are shown in a darker color. (b) Colored arrows indicate the computed mapping of tessellation edges to 
               corresponding ideal lattice vectors. Bad tessellation elements, for which the mapping to the perfect reference lattice
               cannot be determined, have been marked with a gray color. (c) Color legend for the eight different ideal lattice 
               vectors appearing in (b).
              </para></entry>
            </row>
          </tbody>
          </tgroup>
        </informaltable>
      </informalfigure> 
      Within the DXA framework, this problem is addressed by using the Delaunay tessellation of the dislocated input crystal 
      (figure a). The edges of this tessellation define the set of elementary atom-to-atom steps from which Burgers circuits 
      will be constructed. Before generating any circuits, the algorithm first tries to map each edge of the Delaunay tessellation 
      to a corresponding vector in the perfect reference crystal (figure b). This is done with the help of the Common Neighbor 
      Analysis (CNA) method, which finds atoms that form a perfect (but elastically strained) crystal lattice. Delaunay edges connecting 
      a crystalline atom with one of its neighbors are mapped to the corresponding ideal lattice vectors by the algorithm.
    </para>
    <para>
      Within the cores of dislocations, the atomic arrangement deviates considerably from a perfect crystal. Hence, the CNA will classify 
      these core atoms as non-crystalline atoms. All tessellation edges adjacent to such atoms will be marked as "bad" by the algorithm, 
      effectively excluding them from any Burgers circuits to be constructed. This corresponds to the original principle formulated by 
      F. C. Frank, which states that a valid Burgers circuit must not pass through so-called bad crystal. Good crystal regions, in contrast, 
      are defined as those parts where the mapping to the perfect reference crystal is nonambiguous. In fact, the DXA also divides space into 
      <emphasis>good</emphasis> and <emphasis>bad</emphasis> regions in this spirit as shown in figure (b). Those Delaunay elements (triangles in 2D, 
      tetrahedra in 3D systems) that are adjacent to one or more bad edges, which could not be mapped to an ideal lattice vector, are themselves 
      marked as bad elements, while all others are considered good volume elements.
    </para>
    <para>
      Now it is time to think about how to efficiently construct trial Burgers circuits to find and classify the dislocations in the crystal. 
      As mentioned above, the total number of possible circuits in a three-dimensional crystal is prohibitively large, and we need to find a 
      way to considerably reduce the search space. The solution is provided by the aforementioned partitioning into good and bad regions, 
      which defines a boundary surface separating the two regions. In three-dimensional systems this boundary is called the <emphasis>interface mesh</emphasis> and 
      is constituted by those triangular Delaunay facets having a good tetrahedral element on one side and a bad element on the other.
    </para>    
    <para>
      <informalfigure>
      <informaltable frame="none">
       <tgroup cols="1">
          <tbody>
            <row>
              <entry><screenshot><mediaobject><imageobject>
              <imagedata fileref="images/modifiers/dxa/dxa_interface_mesh.png" format="PNG" />
              </imageobject></mediaobject></screenshot></entry>
            </row>
            <row>
              <entry><para>
               Illustration of the line sweeping phase of the DXA. After constructing the interface mesh 
               enclosing the defect core atoms, the algorithm uses a Burgers circuit on the interface mesh 
               to sweep the dislocation line. While the Burgers circuit is being advanced in a step-wise fashion, 
               triangle by triangle, a continuous line representation of the dislocation defect is produced.
              </para></entry>
            </row>
          </tbody>
          </tgroup>
        </informaltable>
      </informalfigure> 
      The interface mesh, which is depicted in this figure, is a two-dimensional manifold that encloses all defects in the crystal (including 
      non-dislocation defects and even free surfaces of the crystal). Constructing trial Burgers circuits on this triangulated surface is 
      sufficient to discover all dislocations. Moreover, this approach helps to ensure that the generated Burgers circuits enclose only single 
      dislocation lines. Trial circuits generated by the DXA on the interface mesh are closed sequences of tessellation edges, and their Burgers 
      vectors are computed from the equation above by summing the respective ideal lattice vectors, which were determined in the 
      first algorithm step. All possible trial circuits up to some prescribed maximum length (modifier parameter <emphasis>Trial circuit length</emphasis>) can be 
      efficiently enumerated using a recursive search algorithm.
    </para>
    <para>
      The algorithm enumerates all possible circuits on the interface mesh in order of increasing length until one with a non-zero Burgers vector 
      is encountered. This seed circuit is subsequently used to discover the rest of the dislocation line. This happens by advancing the circuit 
      on the interface mesh and sweeping along the dislocation line as indicated in the figure. During this sweeping phase, a one-dimensional line 
      representation of the dislocation is generated by computing the new center of mass of the circuit each time it advances along the boundary of 
      the dislocation core. Here, a circuit can be pictured as a rubber band tightly wrapped around the dislocation's core. As the circuit moves 
      along the dislocation segment, it may need to locally expand to sweep over wider sections of the core, e.g. kinks or jogs. To prevent the 
      circuit from sweeping past dislocation junctions or interfaces, a hard limit is imposed on the maximum circuit length (modifier parameter <emphasis>Circuit stretchability</emphasis>).
    </para>
  </simplesect>
  
  <simplesect xml:id="particles.modifiers.dislocation_analysis.fileformat">
  <title>CA file format</title>
  <para>
      The dislocation lines extracted by the analysis modifier can be exported to this simple text-based file format,
      which is described next.
  </para>
  <para>
      A CA file always begins with the string <code>CA_FILE_VERSION</code> followed by the file format version number.
      The current version written by OVITO is 6.
  </para>
  <para>
      The body of the file is divided into a sequence of sections, each section starting with an all-uppercase
      keyword, e.g. <code>STRUCTURE_TYPES</code> or <code>DISLOCATIONS</code>. The order in which sections appear in the file is fixed,
      but certain sections are optional and may be missing depending on the kinds of data that were exported.
      When parsing a CA file, sections that are of no interest can be skipped by seeking to the next known keyword, 
      which always appears at the beginning of a new line.
  </para>
  <para>
      The following sections can appear in a CA file:
      <variablelist>
        <varlistentry><term><code>CA_LIB_VERSION</code></term><listitem>
        <para>Specifies the code version of the Crystal Analysis program that produced the file. Always <code>0.0.0</code> for files written by OVITO.</para></listitem></varlistentry>

        <varlistentry><term><code>METADATA</code></term><listitem>
        <para>An optional line of additional information, e.g. the simulation timestep at which the dislocations have been extracted.</para></listitem></varlistentry>

        <varlistentry><term><code>STRUCTURE_TYPES</code></term><listitem>
        <para>The number of lattice structures which will be defined next. OVITO writes a hard-coded list of lattice structures.</para>
        <variablelist>
          <varlistentry><term><code>STRUCTURE_TYPE</code></term><listitem>
          <para>The unique ID of the lattice structure type.</para></listitem></varlistentry>

          <varlistentry><term><code>NAME</code></term><listitem>
          <para>The human-readable short name of the structure.</para></listitem></varlistentry>

          <varlistentry><term><code>FULL_NAME</code></term><listitem>
          <para>The human-readable long name of the structure.</para></listitem></varlistentry>

          <varlistentry><term><code>COLOR</code></term><listitem>
          <para>The RGB color that represents the lattice structure in OVITO.</para></listitem></varlistentry>

          <varlistentry><term><code>TYPE</code></term><listitem>
          <para>The kind of structure this is. OVITO only knows structures of type <code>LATTICE</code>.</para></listitem></varlistentry>

          <varlistentry><term><code>BURGERS_VECTOR_FAMILIES</code></term><listitem>
          <para>The number of special dislocation types predefined for this lattice structure, which will be specified next.</para>
          <variablelist>
            <varlistentry><term><code>BURGERS_VECTOR_FAMILY</code></term><listitem>
            <para>The ID of this predefined Burgers vectors family, followed by the human-readable name
            of the dislocation type, followed by the Burgers vector (in Cartesian lattice coordinates), followed by the RGB color assigned
            to dislocation lines of this predefined type.</para></listitem></varlistentry>
          </variablelist>
          </listitem></varlistentry>
          
          <varlistentry><term><code>END_STRUCTURE_TYPE</code></term><listitem>
          <para>Marks the end of the definition of the current lattice structure type in the file.</para></listitem></varlistentry>
          
        </variablelist>
        </listitem></varlistentry>

        <varlistentry><term><code>SIMULATION_CELL_ORIGIN</code></term><listitem>
        <para>The Cartesian coordinates of the simulation cell corner.</para></listitem></varlistentry>

        <varlistentry><term><code>SIMULATION_CELL_MATRIX</code></term><listitem>
        <para>Simulation cell matrix. Columns of this 3x3 matrix are the edge vectors of the simulation box.</para></listitem></varlistentry>

        <varlistentry><term><code>PBC_FLAGS</code></term><listitem>
        <para>Periodic boundary condition flags for the three spatial directions.</para></listitem></varlistentry>

        <varlistentry><term><code>CLUSTERS</code></term><listitem>
        <para>The number of crystallite clusters the atomistic solid was divided into by the DXA. What follows is the list of of crystallite clusters.</para>
        
        <variablelist>
          <varlistentry><term><code>CLUSTER</code></term><listitem>
          <para>The unique ID of the crystallite atom cluster.</para></listitem></varlistentry>

          <varlistentry><term><code>CLUSTER_STRUCTURE</code></term><listitem>
          <para>The lattice structure type of the crystallite. This is a reference to one of the structures type IDs defined under the <code>STRUCTURE_TYPES</code> section.</para></listitem></varlistentry>

          <varlistentry><term><code>CLUSTER_ORIENTATION</code></term><listitem>
          <para>A 3x3 transformation matrix that defines the orientation of the crystallite in the simulation coordinate system. 
          It transforms lattice vectors to the spatial frame and includes the rotation of the crystallite, the lattice constant,
          and possible elastic strains of the crystal (averaged over all atoms that belong to the crystallite). Given a column vector
          in the lattice coordinate system, the corresponding spatial vector is obtained by left-multiplying the transformation
          matrix to the vector.
          </para></listitem></varlistentry>

          <varlistentry><term><code>CLUSTER_COLOR</code></term><listitem>
          <para>A color assigned to the crystallite by OVITO.</para></listitem></varlistentry>
          
          <varlistentry><term><code>CLUSTER_SIZE</code></term><listitem>
          <para>The number of atoms that are part of the crystallite.</para></listitem></varlistentry>

          <varlistentry><term><code>END_CLUSTER</code></term><listitem>
          <para>Marks the end of this cluster definition in the file.</para></listitem></varlistentry>
          
        </variablelist>
        </listitem></varlistentry>
       
        <varlistentry><term><code>DISLOCATIONS</code></term><listitem>
        <para>The number of dislocation lines extracted by the DXA, followed by the definition of each line.
        Each dislocation line definition consists of the following information:
        <orderedlist>
        <listitem><para>The zero-based index of the dislocation.</para></listitem>
        <listitem><para>The Burgers vector of the dislocation in the local Cartesian lattice coordinate system of the crystallite cluster.</para></listitem>
        <listitem><para>The ID of the crystallite cluster the dislocation is embedded in. This defines how the local Burgers vector is transformed to the global simulation coordinate system.</para></listitem>
        <listitem><para>The number of vertices along the line.</para></listitem>
        <listitem><para>The list of vertex coordinates. For closes loops, the first and the lattice vertex coincide. If the line crosses a periodic boundary of the simulation cell, vertex coordinates are unwrapped.</para></listitem>
        </orderedlist>
        </para>
        </listitem></varlistentry>
        
        <varlistentry><term><code>DISLOCATION_JUNCTIONS</code></term><listitem>
        <para>Defines the connectivity between dislocation lines (i.e. dislocation junctions or nodes). This sections contains two 
        text lines per dislocation defined in the <code>DISLOCATIONS</code> section. Each of the two lines
        contains two numbers. The first line defines what the <emphasis>end</emphasis> point (i.e. last vertex) of the dislocation is connected to,
        the second line specifies the connectivity of the <emphasis>starting</emphasis> point (i.e. first vertex) of the dislocation.
        The second number in each of the two text lines refers to the zero-based index of another dislocation
        the current dislocation is connected to. The first number, which can be either 0 or 1, specifies
        whether it is connected to the end (1) or the beginning (0) of that other dislocation line.</para>
        <para>
        This connectivity encoding is used to define dislocation nodes/junctions in terms of circular lists. For example,
        a node with three dislocation arms A, B, C is defined such that one end point of dislocation A points to
        an end point of B, which in turn points to an end point of C, which in turn points again back to A.
        </para>
        <para>
        In the output of the DXA algorithm 1-nodes, 2-nodes, and <emphasis>n</emphasis>-nodes (<emphasis>n</emphasis>&gt;2)
        are possible. A 1-node is a dangling end of a dislocation, which terminates at the surface of a crystal or
        merges into another kind of defect (e.g. a grain boundary). In this case the circular connectivity list consists only of 
        one line end, which points to itself. 2-nodes occur for closed dislocation loops or infinite lines that cross a periodic boundary.
        3-nodes and higher are regular dislocation junctions.
        </para></listitem></varlistentry>
        
      </variablelist>
  </para>
  </simplesect>
  
</section>
