# fix poems command

Syntax:

    fix ID group-ID poems keyword values modelType keyword

- ID, group-ID are documented in fix command
- poems = style name of this fix command
- keyword = group or file or molecule

    group values = list of group IDs
    molecule values = none
    file values = filename

- modelType = segment joint model
- keyword = SFJ or SF

    SFJ = Spherrical Flexible Joint
    SJ  = Spherical Joint

## 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

## 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) which computes the constrained rigid-segment motion of articulated (jointed) multibody systems (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.

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 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. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during `energy minimization`.

## 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 for more info.

## Related commands

fix rigid, delete_bonds, neigh_modify exclude

Default: none

(Anderson) Anderson, Mukherjee, Critchley, Ziegler, and Lipton “POEMS: Parallelizable Open-source Efficient Multibody Software ”, Engineering With Computers (2006). (link to paper)