<?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.displacement_vectors"
         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>Displacement vectors</title>

  <para>
  
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/displacement_vectors_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
  This modifier calculates the displacement vectors of particles based on two 
  configurations of the simulated system.</para>

  <para>The current particle set (the one you apply the modifier to) is used as the
  <emphasis>current</emphasis> (or deformed) configuration of the system. The
  <emphasis>reference</emphasis> (or initial) particle coordinates are
  loaded from a separate input file by the modifier.</para>

  <para>
  The modifier calculates the displacement vector of each particle by subtracting its
  position in the reference configuration from the particle's position in the
  current configuration. The calculated vectors are stored in the <literal>Displacement</literal>
  particle property and may be visualized as arrows.
  Alternatively, you can use the <link linkend="particles.modifiers.color_coding">Color coding modifier</link> to
  visualize the displacement magnitude of each particle.</para>

  <para>Use the <guilabel>"Reference: External file"</guilabel> panel to select the
  file containing the initial particle positions. If particles do not possess identifiers, then
  the reference file must contain the same number of particles as the current configuration
  and they must be stored in the exact same order. If particles have IDs, then
  the modifier uses these unique IDs to map particles from the current configuration
  to the reference configuration. The storage orders in the simulation files do not have to be the same in this case.
  </para>

  <para>The vectors computed by the modifier are stored in the <literal>Displacement</literal>
  particle property. In addition, the magnitude of each displacement vector is stored in the 
  <literal>Displacement Magnitude</literal> particle property.
  </para>
  
  <para>    
    The visual appearance of the computed vectors is controlled by the attached 
    <link linkend="display_objects.vectors">vector display object</link>. Note that this display object
    is disabled by default and you have to explicitly enable it in the pipeline editor to see the displacement arrows
    in the viewports.
  </para>

  <simplesect>
    <title>Parameters</title>

    <variablelist>
      <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 displacement vectors. 
          This effectively eliminates any macroscopic, homogeneous deformation of the simulation cell, and the
          calculated vectors 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 checked, the minimum image convention is used to
          deal with particles that have crossed a periodic boundary.</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>
