lammps/doc/fix_rigid.txt

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

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

:line

fix rigid command :h3
fix rigid/nve command :h3
fix rigid/nvt command :h3

[Syntax:]

fix ID group-ID style bodystyle args keyword values ... :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
style = {rigid} or {rigid/nve} or {rigid/nvt} :l
bodystyle = {single} or {molecule} or {group} :l
  {single} args = none
  {molecule} args = none
  {group} args = N groupID1 groupID2 ...
    N = # of groups
    groupID1, groupID2, ... = list of N group IDs :pre

zero or more keyword/value pairs may be appended :l
keyword = {temp} or {press} or {tparam} or {pparam} or {force} or {torque} :l
  {temp} values = Tstart Tstop Tperiod
    Tstart,Tstop = desired temperature at start/stop of run (temperature units)
    Tdamp = temperature damping parameter (time units)
  {tparam} values = Tchain Titer Torder
    Tchain = length of Nose/Hoover thermostat chain
    Titer = number of thermostat iterations performed
    Torder = 3 or 5 = Yoshida-Suzuki integration parameters
  {force} values = M xflag yflag zflag
    M = which rigid body from 1-Nbody (see asterisk form below)
    xflag,yflag,zflag = off/on if component of center-of-mass force is active
  {torque} values = M xflag yflag zflag
    M = which rigid body from 1-Nbody (see asterisk form below)
    xflag,yflag,zflag = off/on if component of center-of-mass torque is active :pre
:ule

[Examples:]

fix 1 clump rigid single
fix 1 clump rigid single force 1 off off on
fix 1 polychains rigid/nvt molecule temp 1.0 1.0 5.0
fix 1 polychains rigid molecule force 1*5 off off off force 6*10 off off on
fix 2 fluid rigid group 3 clump1 clump2 clump3 torque * off off off :pre

[Description:]

Treat one or more sets of atoms as independent rigid bodies.  This
means that each timestep the total force and torque on each rigid body
is computed as the sum of the forces and torques on its constituent
particles and the coordinates, velocities, and orientations of the
atoms in each body are updated so that the body moves and rotates as a
single entity.

Examples of large rigid bodies are a large colloidal particle, or
portions of a large biomolecule such as a protein.

Example of small rigid bodies are patchy nanoparticles, such as those
modeled in "this paper"_#Zhang by Sharon Glotzer's group, clumps of
granular particles, lipid molecules consiting of one or more point
dipoles connected to other spheroids or ellipsoids, and coarse-grain
models of nano or colloidal particles consisting of a small number of
constituent particles.  Note that the "fix shake"_fix_shake.html
command can also be used to rigidify small molecules of 2, 3, or 4
atoms, e.g. water molecules.  That fix treats the constituent atoms as
point masses.

These fixes also update the positions and velocities of the atoms in
each rigid body via time integration.  The {rigid} and {rigid/nve}
styles do this via constant NVE integration.  The only difference is
that the {rigid} style uses an integration technique based on
Richardson iterations.  The {rigid/nve} style uses the methods
described in the paper by "Miller"_#Miller, which are thought to
provide better energy conservation than an iterative approach.

The {rigid/nvt} style performs constant NVT integration using a
Nose/Hoover thermostat with chains as described originally in
"(Hoover)"_#Hoover and "(Martyna)"_#Martyna, which thermostats both
the translational and rotational degrees of freedom of the rigid
bodies.  The rigid-body algorithm used by {rigid/nvt} is described in
the paper by "Kamberaj"_#Kamberaj.

IMPORTANT NOTE: You should not update the atoms in rigid bodies via
other time-integration fixes (e.g. nve, nvt, npt), or you will be
integrating their motion more than once each timestep.

IMPORTANT NOTE: These fixes are overkill if you simply want to hold a
collection of atoms stationary or have them move with a constant
velocity.  A simpler way to hold atoms stationary is to not include
those atoms in your time integration fix.  E.g. use "fix 1 mobile nve"
instead of "fix 1 all nve", where "mobile" is the group of atoms that
you want to move.  You can move atoms with a constant velocity by
assigning them an initial velocity (via the "velocity"_velocity.html
command), setting the force on them to 0.0 (via the "fix
setforce"_fix_setforce.html command), and integrating them as usual
(e.g. via the "fix nve"_fix_nve.html command).

:line

The constituent particles within a rigid body can be point particles
(the default in LAMMPS) or finite-size particles, such as spheroids
and ellipsoids.  See the "shape"_shape.html command and "atom_style
granular"_atom_style.html for more details on these kinds of
particles.  Finite-size particles contribute differently to the moment
of inertia of a rigid body than do point particles.  Finite-size
particles can also experience torque (e.g. due to "frictional granular
interactions"_pair_gran.html) and have an orientation.  These
contributions are accounted for by these fixes.

Forces between particles within a body do not contribute to the
external force or torque on the body.  Thus for computational
efficiency, you may wish to turn off pairwise and bond interactions
between particles within each rigid body.  The "neigh_modify
exclude"_neigh_modify.html and "delete_bonds"_delete_bonds.html
commands are used to do this.  For finite-size particles this also
means the particles can be highly overlapped when creating the rigid
body.

:line

Each body must have two or more atoms.  An atom can belong to at most
one rigid body.  Which atoms are in which bodies can be defined via
several options.

For bodystyle {single} the entire fix group of atoms is treated as one
rigid body.

For bodystyle {molecule}, each set of atoms in the fix group with a
different molecule ID is treated as a rigid body.

For bodystyle {group}, each of the listed groups is treated as a
separate rigid body.  Only atoms that are also in the fix group are
included in each rigid body.

By default, each rigid body is acted on by other atoms which induce an
external force and torque on its center of mass, causing it to
translate and rotate.  Components of the external center-of-mass force
and torque can be turned off by the {force} and {torque} keywords.
This may be useful if you wish a body to rotate but not translate, or
vice versa, or if you wish it to rotate or translate continuously
unaffected by interactions with other particles.  Note that if you
expect a rigid body not to move or rotate by using these keywords, you
must insure its initial center-of-mass translational or angular
velocity is 0.0.  Otherwise the initial translational or angular
momentum the body has will persist.

An xflag, yflag, or zflag set to {off} means turn off the component of
force of torque in that dimension.  A setting of {on} means turn on
the component, which is the default.  Which rigid body(s) the settings
apply to is determined by the first argument of the {force} and
{torque} keywords.  It can be an integer M from 1 to Nbody, where
Nbody is the number of rigid bodies defined.  A wild-card asterisk can
be used in place of, or in conjunction with, the M argument to set the
flags for multiple rigid bodies.  This takes the form "*" or "*n" or
"n*" or "m*n".  If N = the number of rigid bodies, then an asterisk
with no numeric values means all bodies from 1 to N.  A leading
asterisk means all bodies from 1 to n (inclusive).  A trailing
asterisk means all bodies from n to N (inclusive).  A middle asterisk
means all types from m to n (inclusive).  Note that you can use the
{force} or {torque} keywords as many times as you like.  If a
particular rigid body has its component flags set multiple times, the
settings from the final keyword are used.

For computational efficiency, you may wish to turn off pairwise and
bond interactions within each rigid body, as they no longer contribute
to the motion.  The "neigh_modify exclude"_neigh_modify.html and
"delete_bonds"_delete_bonds.html commands are used to do this.

For computational efficiency, you should typically define one fix
rigid which includes all the desired rigid bodies.  LAMMPS will allow
multiple rigid fixes to be defined, but it is more expensive.

:line

As stated above, the {rigid} and {rigid/nve} styles perform constant
NVE time integration.  Thus the {temp}, {press}, and {tparam} keywords
cannot be used with these styles.

The {rigid/nvt} style performs constant NVT time integration, using a
temperature it computes for the rigid bodies which includes their
translational and rotational motion.  The {temp} keyword must be used
with this style.  The desired temperature at each timestep is a ramped
value during the run from {Tstart} to {Tstop}.  The {Tdamp} parameter
is specified in time units and determines how rapidly the temperature
is relaxed.  For example, a value of 100.0 means to relax the
temperature in a timespan of (roughly) 100 time units (tau or fmsec or
psec - see the "units"_units.html command).

Nose/Hoover chains are used in conjunction with this thermostat.  The
{tparam} keyword can optionally be used to change the chain settings
used.  {Tchain} is the number of thermostats in the Nose Hoover chain.
This value, along with {Tdamp} can be varied to dampen undesirable
oscillations in temperature that can occur in a simulation.  As a rule
of thumb, increasing the chain length should lead to smaller
oscillations.

There are alternate ways to thermostat a system of rigid bodies.  You
can use "fix langevin"_fix_langevin.html to treat the system as
effectively immersed in an implicit solvent, e.g. a Brownian dynamics
model.  For hybrid systems with both rigid bodies and solvent
particles, you can thermostat only the solvent particles that surround
one or more rigid bodies by appropriate choice of groups in the
compute and fix commands for temperature and thermostatting.  The
solvent interactions with the rigid bodies should then effectively
thermostat the rigid body temperature as well.

:line

If you use a "temperature compute"_compute.html with a group that
includes particles in rigid bodies, the degrees-of-freedom removed by
each rigid body are accounted for in the temperature (and pressure)
computation, but only if the temperature group includes all the
particles in a particular rigid body.

A 3d rigid body has 6 degrees of freedom (3 translational, 3
rotational), except for a collection of point particles lying on a
straight line, which has only 5, e.g a dimer.  A 2d rigid body has 3
degrees of freedom (2 translational, 1 rotational).

IMPORTANT NOTE: You may wish to explicitly subtract additional
degrees-of-freedom if you use the {force} and {torque} keywords to
eliminate certain motions of one or more rigid bodies.  LAMMPS does
not do this automatically.

The rigid body contribution to the pressure of the system (virial) is
also accounted for by this fix.

IMPORTANT NOTE: The periodic image flags of atoms in rigid bodies are
altered so that the rigid body can be reconstructed correctly when it
straddles periodic boundaries.  The atom image flags are not
incremented/decremented as they would be for non-rigid atoms as the
rigid body crosses periodic boundaries.  This means you cannot
interpret them as you normally would.  For example, the image flag
values written to a "dump file"_dump.html will be different than they
would be if the atoms were not in a rigid body.  Likewise the "compute
msd"_compute_msd.html will not compute the expected mean-squared
displacement for such atoms if the body moves across periodic
boundaries.  It also means that if you have bonds between a pair of
rigid bodies and the bond straddles a periodic boundary, you cannot
use the "replicate"_replicate.html command to increase the system
size.  Note that this fix does define image flags for each rigid body,
which are incremented when the rigid body crosses a periodic boundary
in the usual way.  These image flags have the same meaning as atom
images (see the "dump" command) and can be accessed and output as
described below.

:line

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about the {rigid} and {rigid/nve} fixes are written to
"binary restart files"_restart.html.  For style {rigid/nvt} the state
of the Nose/Hoover thermostat is written to "binary restart
files"_restart.html.  See the "read_restart"_read_restart.html command
for info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.

The "fix_modify"_fix_modify.html {energy} option is supported by the
rigid/nvt fix to add the energy change induced by the thermostatting
to the system's potential energy as part of "thermodynamic
output"_thermo_style.html.

The rigid/nvt fix computes a global scalar which can be accessed by
various "output commands"_Section_howto.html#4_15.  The scalar value
calculated by the rigid/nvt fix is "extensive".  The scalar is the
cumulative energy change due to the thermostatting the fix performs.

All of these fixes compute a global array of values which can be
accessed by various "output commands"_Section_howto.html#4_15.  The
number of rows in the array is equal to the number of rigid bodies.
The number of columns is 15.  Thus for each rigid body, 12 values are
stored: the xyz coords of the center of mass (COM), the xyz components
of the COM velocity, the xyz components of the force acting on the
COM, the xyz components of the torque acting on the COM, and the xyz
image flags of the COM, which have the same meaning as image flags for
atom positions (see the "dump" command).  The force and torque values
in the array are not affected by the {force} and {torque} keywords in
the fix rigid command; they reflect values before any changes are made
by those keywords.

The ordering of the rigid bodies (by row in the array) is as follows.
For the {single} keyword there is just one rigid body.  For the
{molecule} keyword, the bodies are ordered by ascending molecule ID.
For the {group} keyword, the list of group IDs determines the ordering
of bodies.

The array values calculated by these fixes are "intensive", meaning
they are independent of the number of atoms in the simulation.

No parameter of these fixes can be used with the {start/stop} keywords
of the "run"_run.html command.  These fixes are not invoked during
"energy minimization"_minimize.html.

[Restrictions:]

These fixes performs an MPI_Allreduce each timestep that is
proportional in length to the number of rigid bodies.  Hence they will
not scale well in parallel if large numbers of rigid bodies are
simulated.

If the atoms in a single rigid body initially straddle a periodic
boundary, the input data file must define the image flags for each
atom correctly, so that LAMMPS can "unwrap" the atoms into a valid
rigid body.

[Related commands:]

"delete_bonds"_delete_bonds.html, "neigh_modify"_neigh_modify.html
exclude

[Default:]

The option defaults are force * on on on and torque * on on on,
meaning all rigid bodies are acted on by center-of-mass force and
torque.  Also Tchain = 10, Titer = 1, Torder = 3.

:line

:link(Hoover)
[(Hoover)] Hoover, Phys Rev A, 31, 1695 (1985).

:link(Kamberaj)
[(Kamberaj)] Kamberaj, Low, Neal, J Chem Phys, 122, 224114 (2005).

:link(Martyna)
[(Martyna)] Martyna, Klein, Tuckerman, J Chem Phys, 97, 2635 (1992);
Martyna, Tuckerman, Tobias, Klein, Mol Phys, 87, 1117.

:link(Miller)
[(Miller)] Miller, Eleftheriou, Pattnaik, Ndirango, and Newns, 
J Chem Phys, 116, 8649 (2002).

:link(Zhang)
[(Zhang)] Zhang, Glotzer, Nanoletters, 4, 1407-1413 (2004).