define_group command

Purpose

Command to define a particle group.

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

define_group keyword/value pairs

The following general keyword/value pairs are allowed:

Keywords	Description
id	obligatory; user-assigned name for the particle group
initialize	no keyword; default if no other group style is used
delete	no keyword, identical to the delete_group command

The following keyword/value pairs control the contents of the particle group (NB: these group styles are mutually exclusive):

Keywords	Description
condition	double quoted logical condition
materials	list of material names
particle_ids	list of particle_ids to add to the particle_group
region	ID of region
all_in	optional keyword for region-based groups available options: yes and no
subtract	base_group group-id operand_groups list group-id: ID of the group of particles before subtraction list: list of group of particles to subtract
union	list of group of particles to include in the union
intersect	list of group of particles to include in the intersect

The following keyword/value pairs control the behaviour of the particle group:

Keywords	Description
update_every_time	time interval between two consecutive group updates units: [time]; default: write_every_time value
accumulative	available options: yes and no default: no
static	available options: yes and no default: no
verbose	available options: yes and no default: yes

Examples

define_group id groupA
define_group id groupA delete
define_group id edge region regstrip
define_group id edge region edge_reg all_in yes
define_group id water materials {fluid, wet_fluid}
define_group id sub_group particle_ids {10,25,50}
define_group id low_ids condition "id <= 150"
define_group id low_ids condition "id <= 150 && Temp > 200"
define_group id high_vx condition "abs(vx) > 3"
define_group id hienergy condition "eng > 0" update_every_time 0.01
define_group id boundary subtract base_group all operand_groups {a2, a3}
define_group id boundary union {lower, upper}
define_group id boundary intersect {upper, flow}
define_group id tempGroup condition "Temp > 200" update_every_time 0.01 verbose no accumulative yes
define_group id tempGroup condition "Temp < 300" static yes

Description

This command defines a collection of particles as belonging to a (particle) group` known by id (obligatory keyword). The group id can then be used in other commands such as fix, compute, dump, or velocity to make them act on those particles only. A group with the ID all is preredefined, which contains all particles (it cannot be deleted). If the group ID already exists, the group command adds the specified particles to the group. An empty group can be created by the initialize style, which is also the default if no style is defined. If the particle_template command with the particle_group keyword is used, the group needs to be accumulative to prevent a group reset with every group update. Therefore, Aspherix® will set the group to be accumulative automatically during the execution of the the particle_template command (a message about this change will be shown).

The delete style removes the named group and un-assigns all particles that were assigned to that group. An alternative is to use the delete_group command. 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 command (fix, compute or dump).

The contents of the group is controlled by exactly one of the following keywords: condition, materials, particle_ids, region, intersect, subtract, and union.

The condition style evaluates a logical condition to determine which particles to add to the group. It must be a valid right hand side for a per-particle style variable. If the condition evaluates to true for a particle, then that particle is added to the specified group. Per-particle variables can specify formulas that include thermodynamic quantities, per-particle values such as particle coordinates, or per-particle quantities calculated by computes, fixes, or other variables. They can also include Boolean logic, where 2 numeric values are compared to yield true or false. Therefore, the condition style is a general way to flag specific particles to include or exclude from a group.

The materials and particle_ids expect a list with one or more materials or particle IDs, respectively. The listed values are added to the group.

The region style puts all particles in the region volume into the group. The region style also accepts an optional all_in keyword. This keyword controls whether only the particle center (all_in off, default) or the whole particle (all_in yes) needs to be inside the region in order to be added to the group.

The intersect style takes a list of two or more existing group names as arguments. Particles that belong to every one of the listed groups are added to the specified group. The subtract style requires two additional keywords: base_group (one group) and operand_groups (a list of group). All particles that belong to the base_group, but not to any of the operand_groups are added to the specified group. The union style takes a list of one or more existing group names as arguments. All particles that belong to any of the listed groups are added to the specified group.

The behaviour of the group is controlled by the following keywords: update_every_time, accumulative, static, and verbose. By default a group is dynamic, and the time interval between two consecutive group updates is determined by the update_every_time value. If not defined by the user, the write_every_time value will be used. By default accumulative no is used, which resets the whole group before performing the update. With accumulative yes, particles can only be added to the group during an update and any existing particles will remain a member of the group (even if they do not longer obey the initial rule that defined the group). To define a group as static, static yes should be used. Note that it is not allowed to use update_every_time and static yes at the same time. If the group is static, the particles remain assigned to the group even in they later do not obey the initial rule used to define the group (p.a. do not obey the condition, move out of the region volume, etc.). If a group is dynamic the initial rule is applied update_every_time. Note that this might lead to unexpected results when a command expects the group to remain static during the simulation. By default information about group inititalization / updates is printed to the log file and/or screen. This can be disabled by verbose no.

Restrictions

There can be no more than 32 groups defined at one time, including all (and a few internally created groups). Dynamic groups might lead to unexpected results when a command expects the group to remain static / is accumulative during the simulation.

Related commands

delete_group, region, group (legacy)