doc/src/velocity.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 velocity command :h3
  10
  11 [Syntax:]
  12
  13 velocity group-ID style args keyword value ... :pre
  14
  15 group-ID = ID of group of atoms whose velocity will be changed :ulb,l
  16 style = {create} or {set} or {scale} or {ramp} or {zero} :l
  17   {create} args = temp seed
  18     temp = temperature value (temperature units)
  19     seed = random # seed (positive integer)
  20   {set} args = vx vy vz
  21     vx,vy,vz = velocity value or NULL (velocity units)
  22     any of vx,vy,vz van be a variable (see below)
  23   {scale} arg = temp
  24     temp = temperature value (temperature units)
  25   {ramp} args = vdim vlo vhi dim clo chi
  26     vdim = {vx} or {vy} or {vz}
  27     vlo,vhi = lower and upper velocity value (velocity units)
  28     dim = {x} or {y} or {z}
  29     clo,chi = lower and upper coordinate bound (distance units)
  30   {zero} arg = {linear} or {angular}
  31     {linear} = zero the linear momentum
  32     {angular} = zero the angular momentum :pre
  33
  34 zero or more keyword/value pairs may be appended :l
  35 keyword = {dist} or {sum} or {mom} or {rot} or {temp} or {bias} or {loop} or {units} :l
  36   {dist} value = {uniform} or {gaussian}
  37   {sum} value = {no} or {yes}
  38   {mom} value = {no} or {yes}
  39   {rot} value = {no} or {yes}
  40   {temp} value = temperature compute ID
  41   {bias} value = {no} or {yes}
  42   {loop} value = {all} or {local} or {geom}
  43   {rigid} value = fix-ID
  44     fix-ID = ID of rigid body fix
  45   {units} value = {box} or {lattice} :pre
  46 :ule
  47
  48 [Examples:]
  49
  50 velocity all create 300.0 4928459 rot yes dist gaussian
  51 velocity border set NULL 4.0 v_vz sum yes units box
  52 velocity flow scale 300.0
  53 velocity flow ramp vx 0.0 5.0 y 5 25 temp mytemp
  54 velocity all zero linear :pre
  55
  56 [Description:]
  57
  58 Set or change the velocities of a group of atoms in one of several
  59 styles.  For each style, there are required arguments and optional
  60 keyword/value parameters.  Not all options are used by each style.
  61 Each option has a default as listed below.
  62
  63 The {create} style generates an ensemble of velocities using a random
  64 number generator with the specified seed as the specified temperature.
  65
  66 The {set} style sets the velocities of all atoms in the group to the
  67 specified values.  If any component is specified as NULL, then it is
  68 not set.  Any of the vx,vy,vz velocity components can be specified as
  69 an equal-style or atom-style "variable"_variable.html.  If the value
  70 is a variable, it should be specified as v_name, where name is the
  71 variable name.  In this case, the variable will be evaluated, and its
  72 value used to determine the velocity component.  Note that if a
  73 variable is used, the velocity it calculates must be in box units, not
  74 lattice units; see the discussion of the {units} keyword below.
  75
  76 Equal-style variables can specify formulas with various mathematical
  77 functions, and include "thermo_style"_thermo_style.html command
  78 keywords for the simulation box parameters or other parameters.
  79
  80 Atom-style variables can specify the same formulas as equal-style
  81 variables but can also include per-atom values, such as atom
  82 coordinates.  Thus it is easy to specify a spatially-dependent
  83 velocity field.
  84
  85 The {scale} style computes the current temperature of the group of
  86 atoms and then rescales the velocities to the specified temperature.
  87
  88 The {ramp} style is similar to that used by the "compute
  89 temp/ramp"_compute_temp_ramp.html command.  Velocities ramped
  90 uniformly from vlo to vhi are applied to dimension vx, or vy, or vz.
  91 The value assigned to a particular atom depends on its relative
  92 coordinate value (in dim) from clo to chi.  For the example above, an
  93 atom with y-coordinate of 10 (1/4 of the way from 5 to 25), would be
  94 assigned a x-velocity of 1.25 (1/4 of the way from 0.0 to 5.0).  Atoms
  95 outside the coordinate bounds (less than 5 or greater than 25 in this
  96 case), are assigned velocities equal to vlo or vhi (0.0 or 5.0 in this
  97 case).
  98
  99 The {zero} style adjusts the velocities of the group of atoms so that
 100 the aggregate linear or angular momentum is zero.  No other changes
 101 are made to the velocities of the atoms.  If the {rigid} option is
 102 specified (see below), then the zeroing is performed on individual
 103 rigid bodies, as defined by the "fix rigid or fix
 104 rigid/small"_fix_rigid.html commands.  In other words, zero linear
 105 will set the linear momentum of each rigid body to zero, and zero
 106 angular will set the angular momentum of each rigid body to zero.
 107 This is done by adjusting the velocities of the atoms in each rigid
 108 body.
 109
 110 All temperatures specified in the velocity command are in temperature
 111 units; see the "units"_units.html command.  The units of velocities and
 112 coordinates depend on whether the {units} keyword is set to {box} or
 113 {lattice}, as discussed below.
 114
 115 For all styles, no atoms are assigned z-component velocities if the
 116 simulation is 2d; see the "dimension"_dimension.html command.
 117
 118 :line
 119
 120 The keyword/value options are used in the following ways by the
 121 various styles.
 122
 123 The {dist} keyword is used by {create}.  The ensemble of generated
 124 velocities can be a {uniform} distribution from some minimum to
 125 maximum value, scaled to produce the requested temperature.  Or it can
 126 be a {gaussian} distribution with a mean of 0.0 and a sigma scaled to
 127 produce the requested temperature.
 128
 129 The {sum} keyword is used by all styles, except {zero}.  The new
 130 velocities will be added to the existing ones if sum = yes, or will
 131 replace them if sum = no.
 132
 133 The {mom} and {rot} keywords are used by {create}.  If mom = yes, the
 134 linear momentum of the newly created ensemble of velocities is zeroed;
 135 if rot = yes, the angular momentum is zeroed.
 136
 137 *line
 138
 139 If specified, the {temp} keyword is used by {create} and {scale} to
 140 specify a "compute"_compute.html that calculates temperature in a
 141 desired way, e.g. by first subtracting out a velocity bias, as
 142 discussed in "Section 6.16"_Section_howto.html#howto_16 of the doc
 143 pages.  If this keyword is not specified, {create} and {scale}
 144 calculate temperature using a compute that is defined internally as
 145 follows:
 146
 147 compute velocity_temp group-ID temp :pre
 148
 149 where group-ID is the same ID used in the velocity command. i.e. the
 150 group of atoms whose velocity is being altered.  This compute is
 151 deleted when the velocity command is finished.  See the "compute
 152 temp"_compute_temp.html command for details.  If the calculated
 153 temperature should have degrees-of-freedom removed due to fix
 154 constraints (e.g. SHAKE or rigid-body constraints), then the
 155 appropriate fix command must be specified before the velocity command
 156 is issued.
 157
 158 The {bias} keyword with a {yes} setting is used by {create} and
 159 {scale}, but only if the {temp} keyword is also used to specify a
 160 "compute"_compute.html that calculates temperature in a desired way.
 161 If the temperature compute also calculates a velocity bias, the the
 162 bias is subtracted from atom velocities before the {create} and
 163 {scale} operations are performed.  After the operations, the bias is
 164 added back to the atom velocities.  See "Section
 165 6.16"_Section_howto.html#howto_16 of the doc pages for more discussion
 166 of temperature computes with biases.  Note that the velocity bias is
 167 only applied to atoms in the temperature compute specified with the
 168 {temp} keyword.
 169
 170 As an example, assume atoms are currently streaming in a flow
 171 direction (which could be separately initialized with the {ramp}
 172 style), and you wish to initialize their thermal velocity to a desired
 173 temperature.  In this context thermal velocity means the per-particle
 174 velocity that remains when the streaming velocity is subtracted.  This
 175 can be done using the {create} style with the {temp} keyword
 176 specifying the ID of a "compute temp/ramp"_compute_temp_ramp.html or
 177 "compute temp/profile"_compute_temp_profile.html command, and the
 178 {bias} keyword set to a {yes} value.
 179
 180 :line
 181
 182 The {loop} keyword is used by {create} in the following ways.
 183
 184 If loop = all, then each processor loops over all atoms in the
 185 simulation to create velocities, but only stores velocities for atoms
 186 it owns.  This can be a slow loop for a large simulation.  If atoms
 187 were read from a data file, the velocity assigned to a particular atom
 188 will be the same, independent of how many processors are being used.
 189 This will not be the case if atoms were created using the
 190 "create_atoms"_create_atoms.html command, since atom IDs will likely
 191 be assigned to atoms differently.
 192
 193 If loop = local, then each processor loops over only its atoms to
 194 produce velocities.  The random number seed is adjusted to give a
 195 different set of velocities on each processor.  This is a fast loop,
 196 but the velocity assigned to a particular atom will depend on which
 197 processor owns it.  Thus the results will always be different when a
 198 simulation is run on a different number of processors.
 199
 200 If loop = geom, then each processor loops over only its atoms.  For
 201 each atom a unique random number seed is created, based on the atom's
 202 xyz coordinates.  A velocity is generated using that seed.  This is a
 203 fast loop and the velocity assigned to a particular atom will be the
 204 same, independent of how many processors are used.  However, the set
 205 of generated velocities may be more correlated than if the {all} or
 206 {local} keywords are used.
 207
 208 Note that the {loop geom} keyword will not necessarily assign
 209 identical velocities for two simulations run on different machines.
 210 This is because the computations based on xyz coordinates are
 211 sensitive to tiny differences in the double-precision value for a
 212 coordinate as stored on a particular machine.
 213
 214 :line
 215
 216 The {rigid} keyword only has meaning when used with the {zero} style.
 217 It allows specification of a fix-ID for one of the "rigid-body
 218 fix"_fix_rigid.html variants which defines a set of rigid bodies.  The
 219 zeroing of linear or angular momentum is then performed for each rigid
 220 body defined by the fix, as described above.
 221
 222 The {units} keyword is used by {set} and {ramp}.  If units = box,
 223 the velocities and coordinates specified in the velocity command are
 224 in the standard units described by the "units"_units.html command
 225 (e.g. Angstroms/fmsec for real units).  If units = lattice, velocities
 226 are in units of lattice spacings per time (e.g. spacings/fmsec) and
 227 coordinates are in lattice spacings.  The "lattice"_lattice.html
 228 command must have been previously used to define the lattice spacing.
 229
 230 :line
 231
 232 [Restrictions:]
 233
 234 Assigning a temperature via the {create} style to a system with "rigid
 235 bodies"_fix_rigid.html or "SHAKE constraints"_fix_shake.html may not
 236 have the desired outcome for two reasons.  First, the velocity command
 237 can be invoked before all of the relevant fixes are created and
 238 initialized and the number of adjusted degrees of freedom (DOFs) is
 239 known.  Thus it is not possible to compute the target temperature
 240 correctly.  Second, the assigned velocities may be partially canceled
 241 when constraints are first enforced, leading to a different
 242 temperature than desired.  A workaround for this is to perform a "run
 243 0"_run.html command, which insures all DOFs are accounted for
 244 properly, and then rescale the temperature to the desired value before
 245 performing a simulation.  For example:
 246
 247 velocity all create 300.0 12345
 248 run 0                             # temperature may not be 300K
 249 velocity all scale 300.0          # now it should be :pre
 250
 251 [Related commands:]
 252
 253 "fix rigid"_fix_rigid.html, "fix shake"_fix_shake.html,
 254 "lattice"_lattice.html
 255
 256 [Default:]
 257
 258 The keyword defaults are dist = uniform, sum = no, mom = yes, rot =
 259 no, bias = no, loop = all, and units = lattice.  The temp and rigid
 260 keywords are not defined by default.