doc/src/fix_poems.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 fix poems :h3
  10
  11 Syntax:
  12
  13 fix ID group-ID poems keyword values :pre
  14
  15 ID, group-ID are documented in "fix"_fix.html command :ulb,l
  16 poems = style name of this fix command :l
  17 keyword = {group} or {file} or {molecule} :l
  18   {group} values = list of group IDs
  19   {molecule} values = none
  20   {file} values = filename :pre
  21 :ule
  22
  23 [Examples:]
  24
  25 fix 3 fluid poems group clump1 clump2 clump3
  26 fix 3 fluid poems file cluster.list :pre
  27
  28 [Description:]
  29
  30 Treats one or more sets of atoms as coupled rigid bodies.  This means
  31 that each timestep the total force and torque on each rigid body is
  32 computed and the coordinates and velocities of the atoms are updated
  33 so that the collection of bodies move as a coupled set.  This can be
  34 useful for treating a large biomolecule as a collection of connected,
  35 coarse-grained particles.
  36
  37 The coupling, associated motion constraints, and time integration is
  38 performed by the software package "Parallelizable Open source
  39 Efficient Multibody Software (POEMS)"_poems which computes the
  40 constrained rigid-body motion of articulated (jointed) multibody
  41 systems "(Anderson)"_#Anderson.  POEMS was written and is distributed
  42 by Prof Kurt Anderson, his graduate student Rudranarayan Mukherjee,
  43 and other members of his group at Rensselaer Polytechnic Institute
  44 (RPI).  Rudranarayan developed the LAMMPS/POEMS interface.  For
  45 copyright information on POEMS and other details, please refer to the
  46 documents in the poems directory distributed with LAMMPS.
  47
  48 :link(poems,http://www.rpi.edu/~anderk5/lab)
  49
  50 This fix updates the positions and velocities of the rigid atoms with
  51 a constant-energy time integration, so you should not update the same
  52 atoms via other fixes (e.g. nve, nvt, npt, temp/rescale, langevin).
  53
  54 Each body must have a non-degenerate inertia tensor, which means if
  55 must contain at least 3 non-collinear atoms.  Which atoms are in which
  56 bodies can be defined via several options.
  57
  58 For option {group}, each of the listed groups is treated as a rigid
  59 body.  Note that only atoms that are also in the fix group are
  60 included in each rigid body.
  61
  62 For option {molecule}, each set of atoms in the group with a different
  63 molecule ID is treated as a rigid body.
  64
  65 For option {file}, sets of atoms are read from the specified file and
  66 each set is treated as a rigid body.  Each line of the file specifies
  67 a rigid body in the following format:
  68
  69 ID type atom1-ID atom2-ID atom3-ID ...
  70
  71 ID as an integer from 1 to M (the number of rigid bodies).  Type is
  72 any integer; it is not used by the fix poems command.  The remaining
  73 arguments are IDs of atoms in the rigid body, each typically from 1 to
  74 N (the number of atoms in the system).  Only atoms that are also in
  75 the fix group are included in each rigid body.  Blank lines and lines
  76 that begin with '#' are skipped.
  77
  78 A connection between a pair of rigid bodies is inferred if one atom is
  79 common to both bodies.  The POEMS solver treats that atom as a
  80 spherical joint with 3 degrees of freedom.  Currently, a collection of
  81 bodies can only be connected by joints as a linear chain.  The entire
  82 collection of rigid bodies can represent one or more chains.  Other
  83 connection topologies (tree, ring) are not allowed, but will be added
  84 later.  Note that if no joints exist, it is more efficient to use the
  85 "fix rigid"_fix_rigid.html command to simulate the system.
  86
  87 When the poems fix is defined, it will print out statistics on the
  88 total # of clusters, bodies, joints, atoms involved.  A cluster in
  89 this context means a set of rigid bodies connected by joints.
  90
  91 For computational efficiency, you should turn off pairwise and bond
  92 interactions within each rigid body, as they no longer contribute to
  93 the motion.  The "neigh_modify exclude" and "delete_bonds" commands
  94 can be used to do this if each rigid body is a group.
  95
  96 For computational efficiency, you should only define one fix poems
  97 which includes all the desired rigid bodies.  LAMMPS will allow
  98 multiple poems fixes to be defined, but it is more expensive.
  99
 100 The degrees-of-freedom removed by coupled rigid bodies are accounted
 101 for in temperature and pressure computations.  Similarly, the rigid
 102 body contribution to the pressure virial is also accounted for.  The
 103 latter is only correct if forces within the bodies have been turned
 104 off, and there is only a single fix poems defined.
 105
 106 [Restart, fix_modify, output, run start/stop, minimize info:]
 107
 108 No information about this fix is written to "binary restart
 109 files"_restart.html.  None of the "fix_modify"_fix_modify.html options
 110 are relevant to this fix.  No global or per-atom quantities are stored
 111 by this fix for access by various "output
 112 commands"_Section_howto.html#howto_15.  No parameter of this fix can
 113 be used with the {start/stop} keywords of the "run"_run.html command.
 114 This fix is not invoked during "energy minimization"_minimize.html.
 115
 116 [Restrictions:]
 117
 118 This fix is part of the POEMS package.  It is only enabled if LAMMPS
 119 was built with that package, which also requires the POEMS library be
 120 built and linked with LAMMPS.  See the "Making
 121 LAMMPS"_Section_start.html#start_3 section for more info.
 122
 123 [Related commands:]
 124
 125 "fix rigid"_fix_rigid.html, "delete_bonds"_delete_bonds.html,
 126 "neigh_modify"_neigh_modify.html exclude
 127
 128 [Default:] none
 129
 130 :line
 131
 132 :link(Anderson)
 133 [(Anderson)] Anderson, Mukherjee, Critchley, Ziegler, and Lipton
 134 "POEMS: Parallelizable Open-source Efficient Multibody Software ",
 135 Engineering With Computers (2006). ("link to
 136 paper"_http://dx.doi.org/10.1007/s00366-006-0026-x)