group command

Syntax

group ID style args
  • ID = user-defined name of the group
  • style = delete or region or type or id or molecule or variable or subtract or union or intersect
delete = no args
region args = region-ID
type or id or molecule
  args = list of one or more atom types, atom IDs, or molecule IDs
    any entry in list can be a sequence formatted as A:B or A:B:C where
    A = starting index, B = ending index,
    C = increment between indices, 1 if not specified
  args = logical value
    logical = "<" or "<=" or ">" or ">=" or "==" or "!="
    value = an atom type or atom ID or molecule ID (depending on style)
  args = logical value1 value2
    logical = "<>"
    value1,value2 = atom types or atom IDs or molecule IDs (depending on style)
variable args  = variable-ID
subtract args = two or more group IDs
union args = one or more group IDs
intersect args = two or more group IDs
initialize args = no args

Examples

group edge region regstrip
group water type 3 4
group sub id 10 25 50
group sub id 10 25 50 500:1000
group sub id 100:10000:10
group sub id <= 150
group polyA molecule <> 50 250
group hienergy variable eng
group boundary subtract all a2 a3
group boundary union lower upper
group boundary intersect upper flow
group boundary delete

Description

Identify a collection of atoms as belonging to a group. The group ID can then be used in other commands such as fix, compute, dump, or velocity to act on those atoms together.

If the group ID already exists, the group command adds the specified atoms to the group.

The delete style removes the named group and un-assigns all atoms that were assigned to that group. Since there is a restriction (see below) that no more than 32 groups can be defined at any time, the delete style allows you to remove groups that are no longer needed, so that more can be specified. You cannot delete a group if it has been used to define a current fix or compute or dump.

The region style puts all atoms in the region volume into the group. Note that this is a static one-time assignment. The atoms remain assigned (or not assigned) to the group even in they later move out of the region volume.

The type, id, and molecule styles put all atoms with the specified atom types, atom IDs, or molecule IDs into the group. These 3 styles can use arguments specified in one of two formats.

The first format is a list of values (types or IDs). For example, the 2nd command in the examples above puts all atoms of type 3 or 4 into the group named water. Each entry in the list can be a colon-separated sequence A:B or A:B:C, as in two of the examples above. A “sequence” generates a sequence of values (types or IDs), with an optional increment. The first example with 500:1000 has the default increment of 1 and would add all atom IDs from 500 to 1000 (inclusive) to the group sub, along with 10,25,50 since they also appear in the list of values. The second example with 100:10000:10 uses an increment of 10 and would thus would add atoms IDs 100,110,120, ... 9990,10000 to the group sub.

The second format is a logical followed by one or two values (type or ID). The 7 valid logicals are listed above. All the logicals except <> take a single argument. The 3rd example above adds all atoms with IDs from 1 to 150 to the group named sub. The logical <> means “between” and takes 2 arguments. The 4th example above adds all atoms belonging to molecules with IDs from 50 to 250 (inclusive) to the group named polyA.

The variable style evaluates a variable to determine which atoms to add to the group. It must be an atom-style variable previously defined in the input script. If the variable evaluates to a non-zero value for a particular atom, then that atom is added to the specified group.

Atom-style variables can specify formulas that include thermodynamic quantities, per-atom values such as atom coordinates, or per-atom quantities calculated by computes, fixes, or other variables. They can also include Boolean logic where 2 numeric values are compared to yield a 1 or 0 (effectively a true or false). Thus using the variable style, is a general way to flag specific atoms to include or exclude from a group.

For example, these lines define a variable “eatom” that calculates the potential energy of each atom and includes it in the group if its potential energy is above the threshhold value -3.0.

compute         1 all pe/atom
compute         2 all reduce sum c_1
thermo_style    custom step temp pe c_2
run             0
variable        eatom atom "c_1 > -3.0"
group           hienergy variable eatom

Note that these lines

compute         2 all reduce sum c_1
thermo_style    custom step temp pe c_2
run             0

are necessary to insure that the “eatom” variable is current when the group command invokes it. Because the eatom variable computes the per-atom energy via the pe/atom compute, it will only be current if a run has been performed which evaluated pairwise energies, and the pe/atom compute was actually invoked during the run. Printing the thermodyanmic info for compute 2 insures that this is the case, since it sums the pe/atom compute values (in the reduce compute) to output them to the screen. See the “Variable Accuracy” section of the variable doc page for more details on insuring that variables are current when they are evaluated between runs.

The subtract style takes a list of two or more existing group names as arguments. All atoms that belong to the 1st group, but not to any of the other groups are added to the specified group.

The union style takes a list of one or more existing group names as arguments. All atoms that belong to any of the listed groups are added to the specified group.

The intersect style takes a list of two or more existing group names as arguments. Atoms that belong to every one of the listed groups are added to the specified group.

The initialize style creates a new empty group if it does not already exist. This is in particular useful in combination with particletemplates to allow separate integrators for different groups.

A group with the ID all is predefined. All atoms belong to this group. This group cannot be deleted.

Restrictions

There can be no more than 32 groups defined at one time, including “all”.

Default

All atoms belong to the “all” group.