Groups

A Command Word or A Keyword

The term group may appear as a command word. Consider:

clump group       geometry polygon group       flowknot group
fracture group       structure beam group       etc.

The term may also be one of the keywords available in a command. See, for instance:

clump create       geometry copy       block generate
rblock cut       structure cable create       etc.

Whether in a command or as a keyword, the functionality is the same: when used, group tags all target objects of the current command with a label (a group name) that can subsequently be used with range in other commands.

Users familiar with previous versions of the program will recognize this functionality as the old GROUP command. However, in common commands in the new syntax, the c group commands are utilities for listing or renaming groups and slots. Creating and managing group memberships are handled by object commands that provide the group logic as needed—as either command word or keyword.

Group Logic

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, objects may be assigned 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.

Group Rules

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

• an object may be assigned only one group name in a given slot
• a group name always has a slot assignment
• a group name assigned to a slot in an object will overwrite any previous group name assigned to that slot

Relative to the second item, note that it is possible to assign a group name to an object without designating a slot. However, in that case the group is automatically assigned to the built-in slot ‘default’.

The third item underscores 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 (see model range create) have similarities, but there are critical differences. A range is always a set of criteria for selecting a set of objects, therefore:

• the objects it selects may be different at different times, depending on the behavior of the model and the definition of the range, and
• a named range can be applied to different types of objects.

A group is a set of objects that have a common slot-group assignment. Therefore:

• a group will always indicate the same specific set of objects of a specific type and 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 and slots in the program deliver two principle capabilities: the ability to organize like objects in user-defined collections, and the ability to establish multiple collections (up to 128).

One possible reason for some confusion about groups and slots is that the terms “group” and “slot” imply that there are “things” involved: a “bucket”-like container (the group) holds objects (zones, balls, block faces, etc.), which is in turn held in another container object (the slot). However, slots/groups are just tags that are written into the data structure of an object. There is no “object” representation of the group or slot within the program.

Any object has a number of built-in paired property-value data that constitute that object: ID = 32; Position-X = 4.33; # sides = 6; and so forth. These are built into the definition of the object, meaning the values may change (and do), but the properties with which they are associated cannot be changed.

Slots and groups are more of the same, with one critical difference: groups and slots belong to a “user-defined” area of the object where the user may define (and change) both parts: the property (the slot) component and the value (the group) component. Within this space, there is one built-in slot, named “default”, that is not susceptible to user action (it can be neither removed nor renamed). This slot is where any group will go if it is created without a corresponding slot assignment.

Figure 1: At left the “household thing” object described above is represented, with no group assignments; at right the group-slot assignments proposed above have been made.

The figure provides a visual rationale for the first and second rules above. Assigning more than one group name to an object in a slot would be ambiguous, and a group sans slot name is impossible.