Back to main menu

## Mode: difference

#### Syntax

`atomsk --diff <file1> <file2> [options]`

#### Description

This mode computes the differences between two atomic configurations. The displacement vectors are defined by the subtraction of the positions of the <file1> from those of the <file2> (in other words, dx=x2-x1 ). The two files may be in different formats as long as these formats are supported by Atomsk. Both files shall correspond to the same system (i.e. same atom types, same lattice, etc.) for the computation to make sense.

If both files contain exactly the same number of atoms, then Atomsk assumes that atoms are sorted in the same order, i.e. atom i in <file1> corresponds to atom i in <file2>. If it is not the case, then you may use the mode "--match-id" to sort them in the same order. Computation of differences is then straightforward. If one or more atoms change their atomic number between the two files, a new auxiliary property named "diff_Z" is also created.

If the two files contain different numbers of atoms, then atoms from the <file1> are paired to those from <file2> in an injective way, i.e. so that each atom from <file1> is paired at maximum with only one atom from <file2>. If <file1> contains fewer atoms, then all its atoms should be paired, but some atoms from <file2> will not be paired and will be ignored in the calculation. If <file1> contains the most atoms, then some of its atoms cannot be paired. Atomsk then creates a new auxiliary property named "deleted_atoms", equal to zero for all atoms that were paired, and to 1 for atoms that could not be paired (i.e. atoms that were deleted when going from <file1> to <file2>). Differences are then computed only for atoms that were paired.

If auxiliary properties exist in both systems, then the difference between matching auxiliary properties is also computed, i.e. for auxiliary properties that have exactly the same name in both input files. Auxiliary properties that exist in one input file but not the other are ignored, and will not appear in the final files.

The results are written in six separate files which names are prefixed with the name of the <file2>:

- *_diff.xyz: contains atomic positions from the first file, and the displacement vectors between the two files (in cartesian coordinates); this file is compatible with the XYZ format.
- *_diff.xsf: same as above, but complying to XSF format; xCrySDen can read this file and display displacement vectors; beware that xCrySDen understands these vectors as FORCES (not as displacement vectors), so it may be tricky to set these vectors to the correct scale.
- *_both.xsf: contains the atomic positions of both files in the XSF format. Sometimes it can be useful to "superimpose" the two structures to see how they differ.
- *_stat.txt: text file containing statistics about the displacements: minimum/maximum displacements, average, standard deviation... Statistics are given for the whole system, as well as for each individual atom species.
- *_norm.dat: contains the norm of the displacement vector for each atom (in Å), with the format "`i dr species`" (`i`=index of atom, `dr`=norm of displacement).
- *_hist.dat: contains the number of atoms versus the displacement, i.e. the number of atoms that have a displacement between x and x+dx, for x ranging from zero to the maximum value of displacement. Meant to be displayed as a histogram.

Note that this mode assumes that coordinates are not wrapped. If they are wrapped (either because the simulation code has written wrapped coordinates in the file, or because you run Atomsk with the option `-wrap`) then some atoms may seem to teleport from one end of the supercell to another, and displacement vectors may be wrong. If coordinates are wrapped you may unwrap them first with the mode `--unwrap`.

If you use this mode with one or several options, then these options will be applied on the two files before the difference is computed.

#### Examples

- `atomsk --diff initial.grs final.xsf`

  This will compute the difference in atom positions between `initial.grs` and `final.xsf`.

Back to main menu