Entity Sets (Group)

Overview

The Group class maintains lists of active entities such as elements and nodes and child entities such as element faces and edges. The terms “element” and “node” will be used as generic terms in place of “cell” and “vertex” which are typically used in reference to block structured grids.

Users of a Group object may set or query for active entities. The Group class also supports Boolean operations so that entity subsets may be combined, intersected, copied, etc. Normally the active entities in a Group object are set by a function in another class such as getFaceGroup() in the Mesh class. The functions associated with a Group object are the following.

• Definition
  • define() - Define parent and child entities
  • inquire() - Inquire parent and child entities
• Set, manipulate and query active entities
  • isNodeActive() - Query for active node
  • isElementActive() - Query for active element
  • isElementEntityActive() - Query for active element edge or face
  • all() - Set all entities active
  • clear() - Set all entities inactive
  • complement() - Reverse entity activities
  • count() - Count active entities
  • createFromIdTranslator() - Convert IdTranslator object
  • initializeIndexIteration() - Initialize NextIndex function
  • nextIndex() - Get next active entity index
  • setIndex() - Set entity as active or inactive
  • getIndex() - Get entity activity by index
  • setIndices() - Set entities as active or inactive
  • entityFlagSetCount() - Get number of entity flags by index
  • setEntityFlag() - Set entity flag by index and number
  • getEntityFlag() - Get entity flag by index and number
  • setName() - Set name string
  • getName() - Get name string
  • setType() - Set type
  • getType() - Get type
  • setSpecificType() - Set specific type
  • getSpecificType() - Get specific type
• General functions
  • getErrorCode() - Get error code
  • copy() - Copy a Group

Define parent and child entity types and parent entity size with define() . Currently allowable entity types are parent element and node, and child face and edge. The child entity type is optional. The following four combinations are permitted (1) element, (2) element face, (3) element edge, and (4) node. If the exact number of parent entities to be entered into a Group object is unknown, then make an initial estimate, (0 is allowed), and call define() with that estimate. The Group object will adjust memory dynamically if required.

The actual data structures used to hold active entity flags are private to the Group object. The user accesses active entities in a Group using a suite of functions. These functions fall into three basic categories, (1) query for the activity flags of a particular entity by index, (2) query for the activity flag of a particular entity by index and edge or face number, (3) query for the index of the “next” active entity.

The activity flags which are returned for basic element and node entities, using getIndex() for example, are returned as the low order bit in an integer data type. For non polygonal or polyhedral finite element shapes the flags for element faces are returned encoded as the low order 6 bits in an integer. Each bit set indicates that the associated element face (numbered 1 to 6 in a hexahedron for example) is active. The flags for element edges are returned encoded as the low order 12 bits in an integer. Each bit set indicates that the associated element edge (numbered 1 to 12 in a hexahedron for example) is active. For polygonal and polyhedral shapes (POLYGON and POLYHEDRON) the integer activity index only encodes the activity flags for the first 32 edges or faces. The function getEntityFlag() has been designed to query any activity flag individually by index and edge or face number.

The functions isNodeActive(), isElementActive() , and isElementEntityActive() are designed to test for activity flag(s) and return the flag as the return value of the function.

Boolean and other Operations on Group objects may be performed using all(), clear(), copy() and complement(). The createFromIdTranslator() function may be used to convert an ordered list of identifiers in an IdTranslator object into a set of active entity flags in a Group object.

As a convenience, a name string may be associated with the Group object using setName(). The functions setType(), getType() and setSpecificType() , getSpecificType() may be used to set useful integer data which describe the general and specific types of the group. These integers are usually set to the values associated with the element associations ELEMENT_TYPE and ELEMENT_SPECIFIC_TYPE respectively.

Class Members Descriptions

The currently available Group enumerations and functions are described in detail in this section.

class Group

Object for Entity Sets management.

Public Types

enum class Operation

Group operation type for combining or modifying groups.

Values:

enumerator SET

Set/replace group contents.

enumerator INSERT

Insert/add to group.

enumerator REMOVE

Remove from group.

enumerator MASK

Apply mask operation.

Public Functions

ErrorCode getErrorCode()

Return the current ErrorCode of the Group object.

Returns: ErrorCode - The current error code, or NONE if no error.

Status define(int entityCount, EntityType entityType, EntityType entitySubtype)

Specify the number of parent entities and type of parent and child entities. A child entity type may be specified if element faces or element edges are to be managed by the group. If purely elements or nodes are to be managed by the group, then entitySubtype should be set to NONE . This function call initializes all entities to be inactive.

See Also inquire()

Errors

• VALUE is generated if entityCount is non positive.
• ENUM is generated if an improper entityType and entitySubtype association is specified.

Parameters:

• entityCount – Number of parent entities
• entityType – EntityType Type of parent entity
  • ELEMENT
  • NODE
• entitySubtype – EntityType Type of child entity
  • NONE
  • FACE
  • EDGE

Returns:

Status

Status inquire(int *entityCount, EntityType *entityType, EntityType *entitySubtype)

Inquire of defined number of parent entities and type of parent and child entities. The value of entityCount is the maximum index referenced by define() or setIndex() .

See Also define()

Parameters:

• entityCount – [out] Number of parent entities
• entityType – [out] EntityType Type of parent entity
• entitySubtype – [out] EntityType Type of child entity

Returns:

Status

Status setIndex(int entityIndex, int flag)

Set activity of the entity specified by index. For basic node and element entities (no child type is specified) the activity is simply specified by the low order bit in flag. For element face entities, the activity is specified by the low order 6 bits in flag, one bit for each element face. For element edge entities, the activity is specified by the low order 12 bits in flag, one bit for each element edge.

See Also getIndex() , setIndices()

Errors

VALUE is generated if an improper entityIndex is specified.

Parameters:

• entityIndex – Index of entity to set activity
• flag – Activity flag(s) of entity

Returns:

Status

Status setIndices(int count, int entityIndices[], int flag)

Set activity of the entities specified by entityIndices. The function setIndex() is called for each index in entityIndices.

See Also setIndex()

Errors

VALUE is generated if an improper entry of entityIndices is specified.

Parameters:

• count – Number of indices
• entityIndices – Indices of entities to set activity
• flag – Activity flag(s) of entities

Returns:

Status

Status getIndex(int entityIndex, int *flag)

Get the activity flag of the entity specified by index.

See Also setIndex()

Parameters:

• entityIndex – Index of entity
• flag – [out] Activity flag(s) of entity

Returns:

Status

Status setEntityFlag(int entityIndex, int entityNumber, int flag)

Set the activity flag of a specific element edge or face.

See Also getEntityFlag() , entityFlagSetCount()

Errors

VALUE is generated if an improper entityIndex or entityNumber is specified.

Parameters:

• entityIndex – Index of entity to set activity flag
• entityNumber – Element edge or face number
• flag – Activity flag of entity

Returns:

Status

Status getEntityFlag(int entityIndex, int entityNumber, int *flag)

Get the activity flag of a specific element edge or face.

See Also setEntityFlag()

Parameters:

• entityIndex – Index of entity
• entityNumber – Element edge or face number
• flag – [out] Activity flag of entity

Returns:

Status

Status entityFlagSetCount(int entityIndex, int *entityNumberCount, int *entityNumberMaxCount)

Return the number of activity flags and the maximum activity flag set at an element edge or face.

See Also setEntityFlag()

Errors

VALUE is generated if an improper entityIndex is specified.

Parameters:

• entityIndex – Index of entity
• entityNumberCount – [out] Number of set element edges or faces
• entityNumberMaxCount – [out] Maximum element edge or face set

Returns:

Status

int isNodeActive(int nodeIndex)

Query for the activity flag for a node. Note that the return value is 1 if the Group object is NULL.

Parameters:nodeIndex – Index of node entity Returns:The activity flag for the node

int isElementActive(int elementIndex)

Query for the activity flag for an element. The flag is set if any element edge or face flag is set. Note that the return value is 1 if the Group object is NULL.

Parameters:elementIndex – Index of element entity Returns:The activity flag for the element

int isElementEntityActive(int elementEntityIndex, int elementEntityNumber)

Query for the activity flag for an element edge or face. Note that the return value is 1 if the Group object is NULL.

Parameters:

• elementEntityIndex – Index of element entity
• elementEntityNumber – Element edge or face number

Returns:

The activity flag for the element edge or face

Status setName(const char *name)

Set a name string. The name string can contain up to 81 characters including the terminating NULL. If the name is not specified it is returned as a single NULL character using getName() .

See Also getName()

Parameters:name – Name string Returns:Status

Status getName(char name[])

Get the name string.

See Also setName()

Parameters:name – [out] Name string Returns:Status

Status setType(int type)

Set a general type integer. If the type is not specified it is returned as zero using getType() .

See Also getType()

Parameters:type – Integer general type Returns:Status

Status getType(int *type)

Get the general type integer.

See Also setType()

Parameters:type – [out] Integer general type Returns:Status

Status setSpecificType(int type)

Set a specific type integer. If the specific type is not specified it is returned as zero using getSpecificType() .

See Also getSpecificType()

Parameters:type – Integer specific type Returns:Status

Status getSpecificType(int *type)

Get the specific type integer.

See Also setSpecificType()

Parameters:type – [out] Integer specific type Returns:Status

Status initializeIndexIteration()

Initialize the query sequence for active entities. Use this function to initialize, then subsequent calls to nextIndex() will return the index and activity flags of the next active entity. The next active entity is defined as the active entity with the next higher index from the entity index returned from the previous call to nextIndex() . The first call to nextIndex() after initializeIndexIteration() returns the active entity with the lowest index. Any calls to nextIndex() after the active entity with the highest index has been returned, will return a value of index = 0.

See Also nextIndex()

Returns:Status

Status nextIndex(int *index, int *flag)

Get the next active entity. Returns the index and activity flags of the next active entity. Any calls after the active entity with the highest index has been returned, will return a value of index = 0.

See Also initializeIndexIteration()

Parameters:

• index – [out] Index of entity
• flag – [out] Activity flag(s) of entity

Returns:

Status

Status clear()

Set all entities inactive (delete all entities) in the group.

See Also all() , complement()

Returns:Status

Status all()

Set all entities active in the group.

See Also clear() , complement()

Returns:Status

Status applyOperation(Operation operation, Group *source)

Perform Boolean operations on a group. The REMOVE operation deletes all active entities in source from the object. The INSERT operation inserts all active entities in source the object. The resultant object contains all the original active entities in the object plus the active entities in source. The MASK operation intersects the active entities in source with the object. The resultant object contains the original active entities in the object which were also in source. The SET operation sets or copies all active entities in source into the object. The resultant object is identical to source.

See Also complement()

Parameters:

• operation – Operation Type of Boolean operation to perform
• source – Source Group object

Returns:

Status

Status complement()

Take the complement of the group. All active entities become inactive and all inactive entities become active.

See Also all() , clear()

Returns:Status

Status count(int *parentCount, int *childCount)

Return the number of active parent entities and active child entities in the group.

Parameters:

• parentCount – [out] Number of active parent entities
• childCount – [out] Number of active child entities

Returns:

Status

Status createFromIdTranslator(IdTranslator *idtranslator)

Set the active indices of the IdTranslator object as consecutive entities in the Group object. The Group object is initially cleared by this function. The active indices in the IdTranslator are set as active entities.

Parameters:idtranslator – IdTranslator object Returns:Status

Status copy(Group *source)

Make a copy of a Group object. The private data from the source object is copied to this object. Any previous private data in this object is lost.

Parameters:source – Group object to copy from Returns:Status