"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

fix poems command :h3

Syntax:

fix ID group-ID poems keyword values modelType keyword :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
poems = style name of this fix command :l
keyword = {group} or {file} or {molecule} :l
  {group} values = list of group IDs
  {molecule} values = none
  {file} values = filename :pre
modelType = segment joint model :l
keyword = {SFJ} or {SF} :l
  {SFJ} = Spherrical Flexible Joint
  {SJ}  = Spherical Joint :pre
:ule

[Examples:]

fix 3 fluid poems group clump1 clump2 clump3
fix 3 fluid poems file cluster.list 
fix 1 all poems file data/segments_joints.poems modelType SFJ :pre

[Description:]

Treats one or more sets of atoms as coupled rigid segment. A list of 
rigid segments joint tegether making up one system; Several list of 
rigid segments compose several system. This means that in one system
at each timestep the total force and torque on each rigid segment is
computed and the coordinates and velocities of the atoms are updated
so that the collection of segments move as a coupled set.  This can be
useful for treating a large biomolecule as a collection of connected,
coarse-grained particles.

The coupling, associated motion constraints, and time integration is
performed by the software package "Parallelizable Open source
Efficient Multibody Software (POEMS)"_poems which computes the
constrained rigid-segment motion of articulated (jointed) multibody
systems "(Anderson)"_#Anderson.  POEMS was written and is distributed
by Prof Kurt Anderson, his graduate student Rudranarayan Mukherjee,
and other members of his group at Rensselaer Polytechnic Institute
(RPI).  Rudranarayan developed the original POEMS interface.  For
copyright information on POEMS and other details, please refer to the
documents in the poems directory distributed with LIGGGHTS(R)-PUBLIC.

:link(poems,http://www.rpi.edu/~anderk5/lab)

This fix updates the positions and velocities of the rigid atoms with
a constant-energy time integration, so you should not update the same
atoms via other fixes (e.g. nve, nvt, npt, temp/rescale, langevin).

Each segment must have a non-degenerate inertia tensor, which means if
must contain at least 3 non-collinear atoms.  Which atoms are in which
segments can be defined via several options.

For option {group}, each of the listed groups is treated as a rigid
segment.  Note that only atoms that are also in the fix group are
included in each rigid segment.

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

For option {file}, sets of atoms are read from the specified file and
each set is treated as a rigid segment.  Each line of the file specifies
a rigid segment in the following format:

ID type atom1-ID atom2-ID atom3-ID ...

ID as an integer from 1 to M (the number of rigid segments).  Type is
any integer; it is not used by the fix poems command.  The remaining
arguments are IDs of atoms in the rigid segment, each typically from 1 to
N (the number of atoms in the system).  Only atoms that are also in
the fix group are included in each rigid segment.  Blank lines and lines
that begin with '#' are skipped.

A connection between a pair of rigid segments is inferred if one atom is
common to both segments.  The POEMS solver treats that atom as a
spherical joint (SJ) or spherical flexible joint (SFJ) with 3 degrees of freedom.  
Currently, a collection of segments can only be connected by joints as 
a linear chain.  The entire collection of rigid segments can represent 
one or more chains (one or more systems).  Other
connection topologies (tree, ring) are not allowed, but will be added
later.  Note that if no joints exist, it is more efficient to use the
"fix rigid"_fix_rigid.html command to simulate the system.

When the poems fix is defined, it will print out statistics on the
total # of clusters, segments, joints, atoms involved.  A cluster in
this context means a set of rigid segments connected by joints.

For computational efficiency, you should turn off pairwise and bond
interactions within each rigid segment, as they no longer contribute to
the motion.  The "neigh_modify exclude" and "delete_bonds" commands
can be used to do this if each rigid segment is a group.

For computational efficiency, you should only define one fix poems
which includes all the desired rigid segments. LIGGGHTS(R)-PUBLIC will allow
multiple poems fixes to be defined, but it is more expensive.

The degrees-of-freedom removed by coupled rigid segments are accounted
for in temperature and pressure computations.  Similarly, the rigid
segment contribution to the pressure virial is also accounted for.  The
latter is only correct if forces within the segments have been turned
off, and there is only a single fix poems defined.

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

No information about this fix is written to "binary restart
files"_restart.html.  None of the "fix_modify"_fix_modify.html options
are relevant to this fix.  No global or per-atom quantities are stored
by this fix for access by various "output
commands"_Section_howto.html#howto_8.  No parameter of this fix can
be used with the {start/stop} keywords of the "run"_run.html command.
This fix is not invoked during "energy minimization"_minimize.html.

[Restrictions:]

This fix is part of the POEMS package.  It is only enabled if LIGGGHTS(R)-PUBLIC
was built with that package, which also requires the POEMS library be
built and linked with LIGGGHTS(R)-PUBLIC.  See the "Making
LIGGGHTS(R)-PUBLIC"_Section_start.html#start_3 section for more info.

[Related commands:]

"fix rigid"_fix_rigid.html, "delete_bonds"_delete_bonds.html,
"neigh_modify"_neigh_modify.html exclude

[Default:] none

:line

:link(Anderson)
[(Anderson)] Anderson, Mukherjee, Critchley, Ziegler, and Lipton
"POEMS: Parallelizable Open-source Efficient Multibody Software ",
Engineering With Computers (2006). ("link to
paper"_http://dx.doi.org/10.1007/s00366-006-0026-x)
