# Displacement vectors

This modifier calculates the displacement vectors of particles based on two configurations of the simulated system.

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

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 `Displacement` particle property and may be visualized as arrows. Alternatively, you can use the Color coding modifier to visualize the displacement magnitude of each particle.

Use the "Reference: External file" 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.

The vectors computed by the modifier are stored in the `Displacement` particle property. In addition, the magnitude of each displacement vector is stored in the `Displacement Magnitude` particle property.

The visual appearance of the computed vectors is controlled by the attached vector display object. 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.

## Parameters

Affine mapping

  This option applies an affine transformation to the simulation cell and all particle positions prior to calculating the displacement vectors. This can be used to effectively eliminate contributions to the displacements from the macroscopic deformation of the simulation cell and retain only the internal (non-affine) motion of the particles.

  The following table shows the effect of the mapping option on the calculated displacement vector of a particle. When mapping is turned off (first row), the vector is simply calculated from the new and old absolute particle positions irrespective of the changing cell shape. The second option, "To reference", applies an affine transformation to the particle positions of the deformed configuration such that they are first mapped to the reference cell before calculating the displacement vectors. Note that this transformation is applied only virtually during the displacement vector calculation. The last option, "To current", does the opposite of the second option: it maps the reference particle positions to the deformed cell before calculating the displacements.

  Note: The "To reference" setting corresponds to the eliminate homogeneous cell deformation option found in older program versions.

Assume unwrapped coordinates

  This option only affects simulations cells with periodic boundary conditions. If activated, the particle coordinates in the reference and the current configuration are always taken as is and the displacement vectors are directly calculated from the coordinate differences, even for particles that crossed a periodic boundary. If this option is not checked, which is the default, the minimum image convention is used to deal with particles that have crossed a periodic boundary as indicated in the figure below.

  Note: For directions without periodic boundary conditions, assume unwrapped coordinates is the standard behavior.
Constant reference configuration

  If this option is active, the specified animation frame from the reference simulation sequence is used as a fixed reference to calculate the displacement vectors. This is the default mode.

Relative to current frame

  If this option is active, then a varying reference configuration is used to calculate the displacement vectors. This allows computing incremental displacement vectors (similar to discrete velocity vectors). The frame offset paremeter controls the temporal 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.