Entity Identifier Translation

Overview

The IdTranslator class is primarily used to translate user defined entity identifiers (user name space), such as node and element numbers, to a 1 based sequential entity index name space. It is a common feature of commercial finite element analysis systems to allow user defined node and element numbers of arbitrary magnitude and order. It is useful to be able to quickly translate the user defined identifier to an index for quick lookup of entity properties in linear data structures. The computational burden of translating between user defined entity identifiers and entity indices is only performed during user input/output operations such as displaying node numbers on a graphics display or reading element connectivity from an input deck. The IdTranslator class performs this mapping from entity identifier to entity index as well as the reverse mapping from index to identifier. Memory requirements for the translation are optimized dependent upon the properties of the identifiers.

The IdTranslator class can also be used to store sets of nodes and elements, including element entities such as element faces and edges. Functions are provided to store and query for set names, integer identifier, etc. The functions associated with a IdTranslator object are the following.

Definition
- define() - Define initial number of entities
- inquire() - Inquire of number of entities
Set, manipulate and query entity identifiers and indices
- clear() - Clear all identifiers for all entities
- count() - Count number of defined identifiers
- setEquivalentId() - Set equivalent id
- sweepEquivalentIds() - Sweep equivalent ids
- renumberEquivalentIds() - Renumber equivalent ids
- createFromGroup() - Convert Group object
- getEntityIndex() - Get entity index given identifier
- getEntityIndices() - Get entity indices given identifiers
- getAllIndices() - Get all entity indices given identifier
- indexCount() - Get number of entity indices given identifier
- match() - Check for matching IdTranslator objects
- addId() - Add entity identifier
- addThroughByIds() - Add list of entity identifiers
- setElementEntity() - Set entity face or edge number
- getElementEntity() - Get entity face or edge number
- getElementEntities() - Get entity face or edge numbers
- setEntityType() - Set entity number type
- getEntityType() - Get entity number type
- setId() - Set entity identifier
- getId() - Get entity identifier given index
- getIds() - Get entity identifiers given indices
- unique() - Generate unique identifiers
- append() - Append another IdTranslator object
General functions
- getErrorCode() - Return IdTranslator object error flag
- copy() - Copy a IdTranslator
- setName() - Set name string
- getName() - Get name string
- setFiniteElementSpecificType() - Set finite element specific type
- getFiniteElementSpecificType() - Get finite element specific type
- setFiniteElementType() - Set finite element type
- getFiniteElementType() - Get finite element type
- print() - Print object contents

Define the total number of entities using define(). If the exact number of entities to be entered is known then call define() with the proper number otherwise make an initial estimate (0 is allowed) and the IdTranslator object will adjust memory dynamically as required.

Next the index-identifier mapping must be defined. Use a call to setId() for each entity identifier. The order in which the indices are defined is immaterial. Identifiers may be mapped to indices either one at a time or in a set using getEntityIndex() and getEntityIndices() respectively. Use getId() and getIds() to map indices to identifiers. The index-identifier mapping may be changed at any time using setId(), however before the reverse mapping may be queried using getEntityIndex() and getEntityIndices(), the IdTranslator object must analyze the index-identifier mapping which is a potentially computationally expensive operation. If there are entities with duplicate identifiers then the functions indexCount() and getAllIndices() may be used to get a list of entities which share a given identifier.

The IdTranslator object may be used to store and query node and element and element face and edge sets. Each element face or edge is characterized by the element identifier and face or edge number. In the case of element face and edge sets, use the function setElementEntity() to set the face or edge number associated with an element. The element identifier must have been previously defined for an index using setId(). Note that if several element faces or edges are to be set for a single element, an index with the element identifier must be specified first for each face or edge.

As an option, the IdTranslator object can be used to store and query auxiliary set information. Use setEntityType() and getEntityType() to store the entity type (node or element) and subtype (none, face, edge). The functions setFiniteElementType() and setFiniteElementSpecificType() are designed to store the element type, ELEMENT_TYPE and element specific, ELEMENT_SPECIFIC_TYPE associations which may characterize the set. Use getFiniteElementType() and getFiniteElementSpecificType() to query this information. This auxiliary information has no effect on the operation of the IdTranslator object, it is only for the user to store and query.

The IdTranslator object may also be used to manage identifier equivalencing using the functions clear(), setEquivalentId(), sweepEquivalentIds() and renumberEquivalentIds(). The IdTranslator object should be initially cleared (all identifiers set to zero) using clear(). Identifier equivalences are then entered pair by pair using setEquivalentId(). After the last equivalenced pair are entered, sweep the equivalences using sweepEquivalentIds(). This function will ensure that all equivalenced identifiers point to the lowest common equivalenced index. The lowest common equivalenced identifiers and all other index identifiers will be zero. Use renumberEquivalentIds() to renumber all the identifiers starting from one.

The createFromGroup() function may be used to convert the set of active entity flags in a Group object to an ordered list of identifiers in an IdTranslator object.

As a convenience, a name string may be associated with the IdTranslator object using setName().

Class Members Descriptions

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

class IdTranslator

Object for Entity Identifier Translation.

Public Types

enum class CountType

Count type.

Values:

enumerator MAX_INDEX: Maximum index set.

enumerator INDICES_COUNT: Number of non-zero identifiers.

enumerator UNIQUE_COUNT: Number of unique identifiers.

enum class DefinitionOperationType

Definition operation types.

Values:

enumerator THROUGH: Through operation.

enumerator BY: By operation.

Public Functions

HOOPS_CAE_EXTERN ErrorCode getErrorCode ()

Return the current ErrorCode of the IdTranslator object.

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

HOOPS_CAE_EXTERN Status define (int entityCount)

Specify the number of entities. If the number of entities to be set in the IdTranslator object is not known, make a good initial guess if possible (0 is acceptable) and the IdTranslator object will adjust memory dynamically as required. If the exact number of entities is known, then enter this number and memory reallocations will be minimized. This function call initializes all identifiers to zero.

See Also setId , getId

Parameters:	indexCount – Number of indices indices – Array of entity indices ids – [out] Array of entity identifiers
Returns:	Status

HOOPS_CAE_EXTERN Status setElementEntity (int index, int entityNumber)

Set element face or edge number of the entity specified by index. The element identifier associated with index must have been previously set using setId .

See Also getElementEntity , getElementEntities

Errors

VALUE is generated if an index not previously defined.
OPERATION is generated if the identifier associated with index is zero.
MEMORY is generated if a memory allocation failure occurs.

Parameters:	index – Index of entity to set identifier entityNumber – Element face or edge number
Returns:	Status

HOOPS_CAE_EXTERN Status getElementEntity (int index, int *entityNumber)

Get a single element face or edge number associated with an index as an output argument.

See Also setElementEntity , getElementEntities

Parameters:	index – Index of entity entityNumber – [out] Element face or edge number
Returns:	Status

HOOPS_CAE_EXTERN Status getElementEntities (int indexCount, int indices[], int entityNumbers[])

Get a set of element face or edge numbers associated with a set of indices.

See Also setElementEntity , getElementEntity

Parameters:	indexCount – Number of indices indices – Array of entity indices entityNumbers – [out] Array of element face or edge numbers
Returns:	Status

HOOPS_CAE_EXTERN Status addId (int id)

Add identifier at the next highest index.

Errors: MEMORY is generated if a memory allocation failure occurs.

Parameters:	id – Entity identifier
Returns:	Status

HOOPS_CAE_EXTERN Status addThroughByIds (int count, int list[])

Add a list of identifiers at the next highest index. The list consists of a series of positive integer identifiers with optional “through”, THROUGH , and “by”, BY entries. For example, the following list of length num=11,

5,7,THROUGH,11,20,25,THROUGH,29,BY,2,3

generates the following series of identifiers.

5,7,8,9,10,11,20,25,27,29,3

Errors

MEMORY is generated if a memory allocation failure occurs.
VALUE if an improper THROUGH-BY syntax is encountered.

Parameters:	count – Number of entries in list list – Entity list
Returns:	Status

HOOPS_CAE_EXTERN Status setEquivalentId (int index, int id)

Set equivalenced identifier of the entity specified by index. The function clear must be called before the first equivalenced identifier is specified. After all equivalences are specified, the function sweepEquivalentIds must be called to process the equivalences so that all equivalenced identifiers point to the lowest common equivalenced index.

See Also sweepEquivalentIds , renumberEquivalentIds

Errors

VALUE is generated if an index less than 1 is specified.
MEMORY is generated if a memory allocation failure occurs.
OPERATION is generated if an equivalenced identifier is unable to be set. This error will occur if the function clear is not initially called before the first equivalenced identifier is specified.

Parameters:	index – Index of entity to set identifier id – Entity identifier
Returns:	Status

HOOPS_CAE_EXTERN Status sweepEquivalentIds ()

Sweep and process equivalenced identifiers so that all equivalenced identifiers point to the lowest common equivalenced index. The lowest common equivalenced identifiers and all other index identifiers will be zero.

See Also setEquivalentId , renumberEquivalentIds

Returns:	Status

HOOPS_CAE_EXTERN Status renumberEquivalentIds (int *count)

Renumber equivalenced identifiers starting from one. This function is called after sweepEquivalentIds . All identifiers will now be nonzero. The function returns the number of unique identifiers assigned.

See Also setEquivalentId , sweepEquivalentIds

Parameters:	count – [out] Number of unique ids
Returns:	Status

HOOPS_CAE_EXTERN Status setUserId (int id)

Set an optional IdTranslator user identifier.

Parameters:	entityType – `EntityType` of parent entity `ELEMENT` `NODE` entitySubtype – `EntityType` of child entity `FACE` `EDGE`
Returns:	Status

Parameters:	toCheck – IdTranslator object to check against flag – [out] Match flag (1 if match, 0 if no match)
Returns:	Status

Entity Identifier Translation

Overview

Class Members Descriptions

Hello! I'm HOOPSY