"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)

:line

compute displace/atom command :h3

[Syntax:]

compute ID group-ID displace/atom :pre

ID, group-ID are documented in "compute"_compute.html command :ulb,l
displace/atom = style name of this compute command :l
zero or more keyword/arg pairs may be appended :l
keyword = {refresh} :l
  {replace} arg = name of per-atom variable :pre

:ule

[Examples:]

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

[Description:]

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 3 elements of the vector are the dx,dy,dz displacements.
The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +
dz*dz).

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.

NOTE: Initial coordinates are stored in "unwrapped" form, by using the
image flags associated with each atom.  See the "dump
custom"_dump.html command for a discussion of "unwrapped" coordinates.
See the Atoms section of the "read_data"_read_data.html 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"_set.html command.

NOTE: If you want the quantities calculated by this compute to be
continuous when running from a "restart file"_read_restart.html, 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.

:line

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 :pre

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 :pre

The "dump_modify thresh"_dump_modify.html command will only output
atoms that have displaced more than 0.6 Angstroms 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"_variable.html 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"_dump_modify.html 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.

:line

[Output info:]

This compute calculates a per-atom array with 4 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"_Howto_output.html doc page
for an overview of LAMMPS output options.

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

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

[Restrictions:] none

[Related commands:]

"compute msd"_compute_msd.html, "dump custom"_dump.html, "fix
store/state"_fix_store_state.html

[Default:] none
