"LIGGGHTS(R)-PUBLIC WWW Site"_liws - "LIGGGHTS(R)-PUBLIC Documentation"_ld - "LIGGGHTS(R)-PUBLIC Commands"_lc :c

:link(liws,http://www.cfdem.com)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

velocity command :h3

[Syntax:]

velocity group-ID style args keyword value ... :pre

group-ID = ID of group of atoms whose velocity will be changed :ulb,l
style = {set} or {ramp} or {zero} :l
  {set} args = vx vy vz
    vx,vy,vz = velocity value or NULL (velocity units)
    any of vx,vy,vz van be a variable (see below)
  {setAngular} args = angularmx angularmy angularmz
    angularmx,angularmy,angularmz = angular momentum value or NULL (angular mometum units)
    any of angularmx,angularmy,angularmz van be a variable (see below)
  {ramp} args = vdim vlo vhi dim clo chi
    vdim = {vx} or {vy} or {vz}
    vlo,vhi = lower and upper velocity value (velocity units)
    dim = {x} or {y} or {z}
    clo,chi = lower and upper coordinate bound (distance units)
  {zero} arg = {linear} or {angular}
    {linear} = zero the linear momentum
    {angular} = zero the angular momentum :pre

zero or more keyword/value pairs may be appended :l
keyword = {dist} or {sum} or {mom} or {rot} or {loop} or {units} :l
  {dist} value = {uniform} or {gaussian}
  {sum} value = {no} or {yes}
  {mom} value = {no} or {yes}
  {rot} value = {no} or {yes}
  {loop} value = {all} or {local} or {geom}
  {rigid} value = fix-ID
    fix-ID = ID of rigid body fix
  {units} value = {box} or {lattice} :pre
:ule

[Examples:]

velocity border set NULL 4.0 v_vz sum yes units box
velocity all zero linear :pre

[Description:]

Set or change the velocities of a group of atoms in one of several
styles.  For each style, there are required arguments and optional
keyword/value parameters.  Not all options are used by each style.
Each option has a default as listed below.

The {set} style sets the velocities of all atoms in the group to the
specified values.  If any component is specified as NULL, then it is
not set.  Any of the vx,vy,vz velocity components can be specified as
an equal-style or atom-style "variable"_variable.html.  If the value
is a variable, it should be specified as v_name, where name is the
variable name.  In this case, the variable will be evaluated, and its
value used to determine the velocity component.

The {setAngular} is simular to {set}, however, sets the angular 
momentum.

Equal-style variables can specify formulas with various mathematical
functions, and include "thermo_style"_thermo_style.html command
keywords for the simulation box parameters or other parameters.

Atom-style variables can specify the same formulas as equal-style
variables but can also include per-atom values, such as atom
coordinates.  Thus it is easy to specify a spatially-dependent
velocity field.

The {ramp} style makekes velocities ramped
uniformly from vlo to vhi are applied to dimension vx, or vy, or vz.
The value assigned to a particular atom depends on its relative
coordinate value (in dim) from clo to chi.  For the example above, an
atom with y-coordinate of 10 (1/4 of the way from 5 to 25), would be
assigned a x-velocity of 1.25 (1/4 of the way from 0.0 to 5.0).  Atoms
outside the coordinate bounds (less than 5 or greater than 25 in this
case), are assigned velocities equal to vlo or vhi (0.0 or 5.0 in this
case).

The {zero} style adjusts the velocities of the group of atoms so that
the aggregate linear or angular momentum is zero.  No other changes
are made to the velocities of the atoms.  If the {rigid} option is
specified (see below), then the zeroing is performed on individual
rigid bodies, as defined by the "fix rigid or fix
rigid/small"_fix_rigid.html commands.  In other words, zero linear
will set the linear momentum of each rigid body to zero, and zero
angular will set the angular momentum of each rigid body to zero.
This is done by adjusting the velocities of the atoms in each rigid
body.

For all styles, no atoms are assigned z-component velocities if the
simulation is 2d; see the "dimension"_dimension.html command.

:line

The keyword/value option pairs are used in the following ways by the
various styles.


The {sum} option is used by all styles, except {zero}.  The new
velocities will be added to the existing ones if sum = yes, or will
replace them if sum = no.

The {mom} and {rot} options are used by {create}.  If mom = yes, the
linear momentum of the newly created ensemble of velocities is zeroed;
if rot = yes, the angular momentum is zeroed.

:line

The {loop} option is used by {create} in the following ways.

If loop = all, then each processor loops over all atoms in the
simulation to create velocities, but only stores velocities for atoms
it owns.  This can be a slow loop for a large simulation.  If atoms
were read from a data file, the velocity assigned to a particular atom
will be the same, independent of how many processors are being used.
This will not be the case if atoms were created using the
"create_atoms"_create_atoms.html command, since atom IDs will likely
be assigned to atoms differently.

If loop = local, then each processor loops over only its atoms to
produce velocities.  The random number seed is adjusted to give a
different set of velocities on each processor.  This is a fast loop,
but the velocity assigned to a particular atom will depend on which
processor owns it.  Thus the results will always be different when a
simulation is run on a different number of processors.

If loop = geom, then each processor loops over only its atoms.  For
each atom a unique random number seed is created, based on the atom's
xyz coordinates.  A velocity is generated using that seed.  This is a
fast loop and the velocity assigned to a particular atom will be the
same, independent of how many processors are used.  However, the set
of generated velocities may be more correlated than if the {all} or
{local} options are used.

Note that the {loop geom} option will not necessarily assign identical
velocities for two simulations run on different machines.  This is
because the computations based on xyz coordinates are sensitive to
tiny differences in the double-precision value for a coordinate as
stored on a particular machine.

:line

The {rigid} option only has meaning when used with the {zero} style.
It allows specification of a fix-ID for one of the "rigid-body
fix"_fix_rigid.html variants which defines a set of rigid bodies.  The
zeroing of linear or angular momentum is then performed for each rigid
body defined by the fix, as described above.

The {units} option is used by {set}, {setAngular} and {ramp}.  If units = box,
the velocities and coordinates specified in the velocity command are
in the standard units described by the "units"_units.html command
(e.g. Angstroms/fmsec for real units).  If units = lattice, velocities
are in units of lattice spacings per time (e.g. spacings/fmsec) and
coordinates are in lattice spacings.  The "lattice"_lattice.html
command must have been previously used to define the lattice spacing.

[Restrictions:] none

[Related commands:]

"fix shake"_fix_shake.html, "lattice"_lattice.html

[Default:]

The option defaults are dist = uniform, sum = no, mom = yes, rot = no,
 style on group-ID, loop = all, and units = box.  The
rigid option is not defined by default.
