# Group

A group is a label applied to an object as means of categorization. Imagine that you have three household things consisting of a chair, a rug, and a painting. One might wish to categorize these things by their resting location (floor, floor and wall, respectively) or by their their purpose (to sit on, to stand on and to look at, respectively). Each object can be described by a number of attributes and, by undertaking such categorization, it is possible to ask questions about the set. For instance, we may wish to query the set of household objects to find the things whose resting location is floor (i.e., chair and rug).

The group logic is the tool used in FLAC3D to categorize model objects. One can think of a group slot as being a meaningful name corresponding to the attribute in question (i.e., resting_location or purpose in the example above). The group name, on the other hand, is the value the attribute takes for the object. For instance, the chair belongs to group floor in slot resting_location, meaning its resting location is on the floor. Chair also belongs to group to_sit_on in slot purpose, meaning the purpose of the chair is to sit on. In fact, in a model, any number of group names may be specified, and up to 128 different slot names may be used.

To shift to a geomechanical context, one might wish to undertake a staged excavation sequence where each step consists of removing parts of the model successively. Using the group logic, one can imagine creating group slots named stage1, stage2, etc. corresponding to each stage of the excavation. Within stage1 of excavation there could be objects belonging to groups first, second, etc. This gives the user a way to remove the first, second, etc. parts of the model in stage1, the first, second, etc. parts of the model in stage2, and so on.

The objects are “members” of the group and will persist so until a subsequent command either removes them from the group, removes the group itself, or assigns them to a different group in the specified slot. Contrast this with a range, which, used at different times in a model, might return different objects with location falling in a specific range, for instance. Groups may be removed, though this does not cause their member objects to be removed or deleted from the model. Commands may assign groups based on various criteria as a command operation proceeds.

As explained above, groups are always a combination of two components: the group slot, and the group name. For convenience, it is easy to assign objects to a group name without specifying a slot. In such cases, the default slot assignment is used. For any “unslotted” group, the default slot assignment is the slot named Default.

The cardinal points to keep in mind when working with groups are:

• groups must be composed of like objects; however, slots may contain groups that contain different types of objects
• an object may belong to only one group within a given slot
• a group name can only be used once per slot
• a group must be in a slot; if a slot is not assigned when the group is created, the group is automatically assigned to slot named default
• group-slot assignments adhere to the program’s command-overwrite logic: an object assignment to a group in a given slot will be overwritten if that object is later assigned to another group in the same slot. However, if the latter group assignment occurs in a new or different slot, overwriting does not occur.

The last point illustrates the need for slots: they provide a way to put the same object into different groups without conflict, allowing for rather complex intersections of named objects to be achieved.

Consider the following explicit example using scalar objects for explanatory purposes.

data scalar group "one" slot "main" range id 1,5
data scalar group "two" slot "main" range id 1,10
data scalar group "three" slot "main" range id 1,5
data scalar group "two" slot "mane" range id 6,10


Once processed, we have:

• no scalars are assigned group “one” in slot “main” (the assignment made in the first line is overwritten by the assignment in the second line)
• scalars with id 6-10 are assigned group “two” in slot “main”
• scalars with id 1-5 are assigned group “three” in slot “main”
• scalars with id 6-10 are assigned group “two” in slot “mane”

The scalars with id 6-10 are in two groups that have the same name (“two”). However, the two groups are in different slots (“main” and “mane”), so there is no conflict over group membership nor over the group name.

One more example is presented to demonstrate how multiple group assignments can be used effectively, with an intersection, to remove an object.

data scalar create (1,0,0)
data scalar create (5,0,0)
data scalar create (10,0,0)
data scalar group "left-most" slot "position1" range position-x 1,5
data scalar group "right-most" slot "position2" range position-x 5,10
data scalar delete range group "left-most" and "right-most"


The first three lines create three scalars at different locations. The next two lines assign group names to the left-most and right-most sets of scalars. Finally, the central scalar is deleted as it belongs to both the “left-most” and “right-most” slots, using the group range element.

Alternate Syntax

The typical formulation of the group name and the group slot assignment takes the form group "groupname" slot "slotname", as appears here.

data scalar group "groupname" slot "slotname" range position-x 100 2000


However, a valid alternate construction is slotname = groupname. With this construction the command above takes the form

data scalar group "slotname = groupname" range position-x 100 2000


where slotname is the slot assignment and groupname is the group name. Quotation marks are required, but spaces at the equals sign (if present) are ignored.

Data Hierarchies

Certain data structures are related to each other through a hierarchy. For example, in the geometry logic points are connected to edges, which are themselves connected to polygons. In FLAC3D grid points are connected to faces which are connected to zones.

By default, in most cases when a data type participates in a hierarchy the group logic will automatically move up the hierarchy when checking for group matches. So if the logic is checking that a geometry node is in the group Fred, it will find a match if that node is directly part of that group or if an edge or a polygon connected to that node is part of that group.

The group logic will never move down the hierarchy, so it will never find a polygon as a member of group Fred unless the polygon itself is directly a member of that group. Even if every edge and node of the polygon is a member of the group.

This affects the group range element and the .isgroup family of FISH intrinsics. The by keyword can be used in the range element to restrict this behavior.

Groups vs. Named Ranges

The group and the named range have similarities, but there is a critical difference. A range is always a set of criteria for selecting a set of objects, and it may return different results at different times, depending on the behavior of the model and the definition of the range. Also, a named range can be applied to different types objects. A group is always a collection of a specific set of objects of a specific type that will change only if group members are deleted or if they are overwritten to a new group in the same slot (see above).

Another Way of Looking At It

Groups in the program provide a logic that delivers two principle capabilities: the ability to organize like objects in a user-defined sort order, and the ability to define multiple such sort orders (up to 255).

The group logic is made up of groups and slots. As a group is a “container” of like objects, a slot is a “container” of groups (note the groups in a slot do not have to contain like objects). Any group will, of necessity, belong to one (and only one) slot. A physical analogy here may be of use.

Given a set of forms (like objects), a person might want to file them in folders (groups) alphabetized by last name (sort order). These folders are then put into a file drawer (slot). Should the person want to have these objects sorted by a second criteria (alphabetized by first name , for instance, or by zip code, or…), the forms are duplicated, a second set of folders (groups) are created and stored in a second drawer (second slot). In the physical world, continually duplicating the object set to achieve different sort orders would be cumbersome, labor-inflating, and error-prone. However, in computer software it is easy, so much so that every object type in the program can be sorted this way up to 255 times!