compute displace/atom command


compute ID group-ID displace/atom
  • ID, group-ID are documented in compute command

  • displace/atom = style name of this compute command

  • zero or more keyword/arg pairs may be appended

  • keyword = refresh

    refresh arg = name of per-atom variable


compute 1 all displace/atom
compute 1 all displace/atom refresh myVar


Define a computation that calculates the current displacement of each atom in the group from its original (reference) coordinates, including all effects due to atoms passing through periodic boundaries.

A vector of four quantities per atom is calculated by this compute. The first three elements of the vector are the \((dx,dy,dz)\) displacements. The fourth component is the total displacement (i.e., \(\sqrt{dx^2 + dy^2 + dz^2}\)).

The displacement of an atom is from its original position at the time the compute command was issued. The value of the displacement will be 0.0 for atoms not in the specified compute group.


Initial coordinates are stored in “unwrapped” form, by using the image flags associated with each atom. See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the read_data command for a discussion of image flags and how they are set for each atom. You can reset the image flags (e.g., to 0) before invoking this compute by using the set image command.


If you want the quantities calculated by this compute to be continuous when running from a restart file, then you should use the same ID for this compute, as in the original run. This is so that the fix this compute creates to store per-atom quantities will also have the same ID, and thus be initialized correctly with time = 0 atom coordinates from the restart file.

The refresh option can be used in conjunction with the “dump_modify refresh” command to generate incremental dump files.

The definition and motivation of an incremental dump file is as follows. Instead of outputting all atoms at each snapshot (with some associated values), you may only wish to output the subset of atoms with a value that has changed in some way compared to the value the last time that atom was output. In some scenarios this can result in a dramatically smaller dump file. If desired, by post-processing the sequence of snapshots, the values for all atoms at all timesteps can be inferred.

A concrete example using this compute, is a simulation of atom diffusion in a solid, represented as atoms on a lattice. Diffusive hops are rare. Imagine that when a hop occurs an atom moves more than a distance Dhop. For any snapshot we only want to output atoms that have hopped since the last snapshot. This can be accomplished with something like the following commands:

write_dump      all custom tmp.dump id type x y z    # see comment below

variable        Dhop equal 0.6
variable        check atom "c_dsp[4] > v_Dhop"
compute         dsp all displace/atom refresh check
dump            1 all custom 100 tmp.dump id type x y z
dump_modify     1 append yes thresh c_dsp[4] > ${Dhop} &
                refresh c_dsp delay 100

The dump_modify thresh command will only output atoms that have displaced more than \(0.6~\AA\) on each snapshot (assuming metal units). The dump_modify refresh option triggers a call to this compute at the end of every dump.

The refresh argument for this compute is the ID of an atom-style variable which calculates a Boolean value (0 or 1) based on the same criterion used by dump_modify thresh. This compute evaluates the atom-style variable. For each atom that returns 1 (true), the original (reference) coordinates of the atom (stored by this compute) are updated.

The effect of these commands is that a particular atom will only be output in the dump file on the snapshot after it makes a diffusive hop. It will not be output again until it makes another hop.

Note that in the first snapshot of a subsequent run, no atoms will be typically be output. That is because the initial displacement for all atoms is 0.0. If an initial dump snapshot is desired, containing the initial reference positions of all atoms, one way to do this is illustrated above. An initial write_dump command can be used before the first run. It will contain the positions of all the atoms, Options in the dump_modify command above will append new output to that same file and delay the output until a later timestep. The delay setting avoids a second time = 0 snapshot which would be empty.

Output info

This compute calculates a per-atom array with four columns, which can be accessed by indices 1–4 by any command that uses per-atom values from a compute as input. See the Howto output doc page for an overview of LAMMPS output options.

The per-atom array values will be in distance units.

This compute supports the refresh option as explained above, for use in conjunction with dump_modify refresh to generate incremental dump files.