<?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.atomic_strain"
         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>Atomic strain</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/atomic_strain_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
  This modifier calculates the atomic-level strain tensors based on two
  configurations of the system. See
  <link xlink:href="http://dx.doi.org/10.1103/PhysRevE.57.7192">[Falk, Langer, Phys. Rev. E 57 (1998), 7192]</link>
  and <link
  xlink:href="http://li.mit.edu/Archive/Activities/Archive/Papers/07/Shimizu07a.pdf">[Shimizu, Ogata, Li, Mater.
  Trans. 48 (2007), 2923]</link> for a description of how the per-particle deformation
  tensors are calculated by OVITO.</para>

  <para>The data set to which the modifier is applied is considered the
  <emphasis>current</emphasis> (=deformed) configuration of the system. The
  <emphasis>reference</emphasis> (=initial) configuration of the system is
  loaded from a separate input file by the modifier.</para>

  <para>OVITO calculates the local deformation gradient tensor <inlineequation><mathphrase>F</mathphrase></inlineequation> for each particle
  from the relative displacements of the particle's neighbors within the given
  cutoff radius. Note that this set of neighbors is determined in
  the <emphasis>initial</emphasis> configuration for each particle. At least three
  non-coplanar neighbors are required to calculate <inlineequation><mathphrase>F</mathphrase></inlineequation> for a central particle.
  Thus, the calculation will fail for isolated or undercoordinated particles. The
  modifier can select those invalid particles in the output for diagnostic purposes.</para>

  <para>After calculating the atomic deformation gradient tensor <inlineequation><mathphrase>F</mathphrase></inlineequation>, the
  Green-Lagrangian strain tensor <inlineequation><mathphrase>E=1/2(F<superscript>T</superscript>F-I)</mathphrase></inlineequation> 
  is derived from it. The modifier also calculates the <emphasis>von Mises</emphasis> local shear invariant and the
  volumetric (hydrostatic) part of the strain tensor and outputs these scalar quantities as particle properties.</para>

  <para>The modifier can output the residual of the deformation gradient calculation.
  This is a measure for the non-affine part of the local deformation and was termed
  <inlineequation><mathphrase>D<superscript>2</superscript><subscript>min</subscript></mathphrase></inlineequation>
  by Falk &amp; Langer. This measure was used by these authors as a diagnostic for
  identifying local irreversible shear transformations in amorphous solids.</para>

  <para>The atomic deformation gradient <inlineequation><mathphrase>F</mathphrase></inlineequation> can be decomposed into the matrix product 
  <inlineequation><mathphrase>F=RU</mathphrase></inlineequation> 
  with <inlineequation><mathphrase>R</mathphrase></inlineequation> being a rotation matrix and <inlineequation><mathphrase>U</mathphrase></inlineequation> the right stretch tensor.
  <inlineequation><mathphrase>U</mathphrase></inlineequation> is symmetric positive definite. The local rotation <inlineequation><mathphrase>R</mathphrase></inlineequation> is output by the modifier
  as a particle property named <literal>Rotation</literal>, which is encoded as a quaternion with four components <literal>X</literal>, <literal>Y</literal>, <literal>Z</literal>,
  and <literal>W</literal>. From this, the angle of rotation in radians can be obtained with the formula <inlineequation><mathphrase>2*acos(Rotation.W)</mathphrase></inlineequation>,
  e.g., using the <link linkend="particles.modifiers.compute_property">Compute Property modifier</link>.
  </para>

  <para>Use the <emphasis>"Reference: External file"</emphasis> panel to pick the
  file containing the initial particle positions. Note
  that this reference file must contain the same set of particles as the
  current configuration received by the modifier from the upstream part of the modification pipeline. 
  That means you should not delete particles before applying the <emphasis>Atomic
  strain</emphasis> modifier and the analysis modifier should be usually placed at the
  beginning of the processing pipeline.</para>

  <para>
  To calculate the displacement of a given particle in the current configuration, the modifier needs to
  find the corresponding particle in the reference configuration of the system.
  If particles possess unique IDs (i.e. the <literal>Particle Identifier</literal> property is present), the modifier will
  use this information to map particles from the reference configuration to
  the current configuration and vice versa. If no particle IDs are defined, the modifier assumes
  that particles have the same ordering in both configurations.</para>
  
  <para>
  Note that OVITO assumes particle positions to be column vectors. Some programs such as <emphasis>AtomEye</emphasis> use a different convention
  and assume them to be row vectors.
  </para>
  
  <simplesect>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>Cutoff radius</term>
        <listitem>
          <para>Controls the range of neighbors that are taken
          into account to compute the deformation gradient tensor of a particle.
          This radius must be large enough to include at least three non-coplanar neighbors for
          every particle in the reference configuration. The larger the cutoff, the larger 
          the volume over which the local deformation gradient tensor is averaged.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Eliminate homogeneous cell deformation</term>
        <listitem>
          <para>This option lets the modifier first rescale the current
          simulation cell including all particle coordinates to match the 
          cell shape in the reference configuration before calculating the deformation tensors. This effectively eliminates any
          macroscopic, homogeneous deformation of the simulation cell, and the
          calculated deformation tensors will reflect only the internal, microscopic displacements of particles.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Assume unwrapped coordinates</term>
        <listitem>
          <para>This only affects the treatment of simulation cells with
          periodic boundary conditions. If activated, the particle coordinates
          in the reference and the current configuration are taken as is. If
          this option is not active, the minimum image convention is used to
          deal with particles that have crossed a periodic boundary.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Output deformation gradient tensors</term>
        <listitem>
          <para>If activated, the modifier stores the nine components of the calculated per-particle
          deformation gradient tensors in an output property. Turn this off to save memory if you
          do not need the complete deformation gradient tensors.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Output strain tensors</term>

        <listitem>
          <para>If activated, the modifier stores the six components of the calculated per-particle
          strain tensors in an output property. Turn this off to save memory if you
          do not need the complete strain tensor tensors.</para>
        </listitem>
      </varlistentry>      

      <varlistentry>
        <term>Output non-affine squared displacements</term>

        <listitem>
          <para>If activated, the modifier computes the non-affine displacements in an output
          property. This is the residual of the least squares fit of the deformation gradient
          tensor (i.e. the <inlineequation><mathphrase>D<superscript>2</superscript><subscript>min</subscript></mathphrase></inlineequation>
	  property of Falk &amp; Langer). Turn this off to save memory if you do not need non-affine
	  displacements.</para>
        </listitem>
      </varlistentry>      
      
      <varlistentry>
        <term>Output rotations</term>

        <listitem>
          <para>If activated, the modifier outputs a particle property named <literal>Rotation</literal>
          with the local (micro)rotations obtained from the polar decomposition <inlineequation><mathphrase>F=RU</mathphrase></inlineequation>
          of the atomic deformation gradient. The rotation matrix <inlineequation><mathphrase>R</mathphrase></inlineequation>  
          is converted to a quaternion representation for output.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Output stretch tensors</term>

        <listitem>
          <para>If activated, the modifier outputs a particle property named <literal>Stretch Tensor</literal>
          with the <inlineequation><mathphrase>U</mathphrase></inlineequation> tensors obtained from the polar decomposition <inlineequation><mathphrase>F=RU</mathphrase></inlineequation>
          of the atomic deformation gradient. The symmetric matrix <inlineequation><mathphrase>U</mathphrase></inlineequation>  
          is converted to a six-component representation for output.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Select invalid particles</term>

        <listitem>
          <para>If activated, the modifier selects those particles for which it
          could not calculate the local deformation gradient and strain tensors
          (due to too few neighbors within the cutoff radius).</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 calculate the displacement vectors. 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 to calculate the displacement vectors. 
          This allows computing incremental displacement vectors (similar to discrete velocity vectors).
          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 displacement vectors will not be computed for simulation frames for which the resulting reference frame is negative or out of range.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </simplesect>
</section>
