doc/src/displace_atoms.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 displace_atoms command :h3
  10
  11 [Syntax:]
  12
  13 displace_atoms group-ID style args keyword value ... :pre
  14
  15 group-ID = ID of group of atoms to displace :ulb,l
  16 style = {move} or {ramp} or {random} or {rotate} :l
  17   {move} args = delx dely delz
  18     delx,dely,delz = distance to displace in each dimension (distance units)
  19     any of delx,dely,delz can be a variable (see below)
  20   {ramp} args = ddim dlo dhi dim clo chi
  21     ddim = {x} or {y} or {z}
  22     dlo,dhi = displacement distance between dlo and dhi (distance units)
  23     dim = {x} or {y} or {z}
  24     clo,chi = lower and upper bound of domain to displace (distance units)
  25   {random} args = dx dy dz seed
  26     dx,dy,dz = random displacement magnitude in each dimension (distance units)
  27     seed = random # seed (positive integer)
  28   {rotate} args = Px Py Pz Rx Ry Rz theta
  29     Px,Py,Pz = origin point of axis of rotation (distance units)
  30     Rx,Ry,Rz = axis of rotation vector
  31     theta = angle of rotation (degrees) :pre
  32
  33 zero or more keyword/value pairs may be appended :l
  34   keyword = {units}
  35     value = {box} or {lattice} :pre
  36 :ule
  37
  38 [Examples:]
  39
  40 displace_atoms top move 0 -5 0 units box
  41 displace_atoms flow ramp x 0.0 5.0 y 2.0 20.5 :pre
  42
  43 [Description:]
  44
  45 Displace a group of atoms.  This can be used to move atoms a large
  46 distance before beginning a simulation or to randomize atoms initially
  47 on a lattice.  For example, in a shear simulation, an initial strain
  48 can be imposed on the system.  Or two groups of atoms can be brought
  49 into closer proximity.
  50
  51 The {move} style displaces the group of atoms by the specified 3d
  52 displacement vector.  Any of the 3 quantities defining the vector
  53 components can be specified as an equal-style or atom-style
  54 "variable"_variable.html.  If the value is a variable, it should be
  55 specified as v_name, where name is the variable name.  In this case,
  56 the variable will be evaluated, and its value(s) used for the
  57 displacement(s).  The scale factor implied by the {units} keyword will
  58 also be applied to the variable result.
  59
  60 Equal-style variables can specify formulas with various mathematical
  61 functions, and include "thermo_style"_thermo_style.html command
  62 keywords for the simulation box parameters and timestep and elapsed
  63 time.  Atom-style variables can specify the same formulas as
  64 equal-style variables but can also include per-atom values, such as
  65 atom coordinates or per-atom values read from a file.  Note that if
  66 the variable references other "compute"_compute.html or "fix"_fix.html
  67 commands, those values must be up-to-date for the current timestep.
  68 See the "Variable Accuracy" section of the "variable"_variable.html
  69 doc page for more details.
  70
  71 The {ramp} style displaces atoms a variable amount in one dimension
  72 depending on the atom's coordinate in a (possibly) different
  73 dimension.  For example, the second example command displaces atoms in
  74 the x-direction an amount between 0.0 and 5.0 distance units.  Each
  75 atom's displacement depends on the fractional distance its y
  76 coordinate is between 2.0 and 20.5.  Atoms with y-coordinates outside
  77 those bounds will be moved the minimum (0.0) or maximum (5.0) amount.
  78
  79 The {random} style independently moves each atom in the group by a
  80 random displacement, uniformly sampled from a value between -dx and
  81 +dx in the x dimension, and similarly for y and z.  Random numbers are
  82 used in such a way that the displacement of a particular atom is the
  83 same, regardless of how many processors are being used.
  84
  85 The {rotate} style rotates each atom in the group by the angle {theta}
  86 around a rotation axis {R} = (Rx,Ry,Rz) that goes thru a point {P} =
  87 (Px,Py,Pz).  The direction of rotation for the atoms around the
  88 rotation axis is consistent with the right-hand rule: if your
  89 right-hand thumb points along {R}, then your fingers wrap around the
  90 axis in the direction of positive theta.
  91
  92 If the defined "atom_style"_atom_style.html assigns an orientation to
  93 each atom ("atom styles"_atom_style.html ellipsoid, line, tri, body),
  94 then that property is also updated appropriately to correspond to the
  95 atom's rotation.
  96
  97 Distance units for displacements and the origin point of the {rotate}
  98 style are determined by the setting of {box} or {lattice} for the
  99 {units} keyword.  {Box} means distance units as defined by the
 100 "units"_units.html command - e.g. Angstroms for {real} units.
 101 {Lattice} means distance units are in lattice spacings.  The
 102 "lattice"_lattice.html command must have been previously used to
 103 define the lattice spacing.
 104
 105 :line
 106
 107 NOTE: Care should be taken not to move atoms on top of other atoms.
 108 After the move, atoms are remapped into the periodic simulation box if
 109 needed, and any shrink-wrap boundary conditions (see the
 110 "boundary"_boundary.html command) are enforced which may change the
 111 box size.  Other than this effect, this command does not change the
 112 size or shape of the simulation box.  See the
 113 "change_box"_change_box.html command if that effect is desired.
 114
 115 NOTE: Atoms can be moved arbitrarily long distances by this command.
 116 If the simulation box is non-periodic and shrink-wrapped (see the
 117 "boundary"_boundary.html command), this can change its size or shape.
 118 This is not a problem, except that the mapping of processors to the
 119 simulation box is not changed by this command from its initial 3d
 120 configuration; see the "processors"_processors.html command.  Thus, if
 121 the box size/shape changes dramatically, the mapping of processors to
 122 the simulation box may not end up as optimal as the initial mapping
 123 attempted to be.
 124
 125 :line
 126
 127 [Restrictions:]
 128
 129 For a 2d simulation, only rotations around the a vector parallel to
 130 the z-axis are allowed.
 131
 132 [Related commands:]
 133
 134 "lattice"_lattice.html, "change_box"_change_box.html,
 135 "fix move"_fix_move.html
 136
 137 [Default:]
 138
 139 The option defaults are units = lattice.