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

ErrorCode getErrorCode()

Return the current ErrorCode of the IdTranslator object.

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

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 inquire()

Errors

VALUE is generated if entityCount is non positive.

Parameters:entityCount – Number of entities Returns:Status

Status inquire(int *entityCount)

Inquire of defined number of entities or the maximum index for which an identifier has been defined using setId() .

See Also define()

Parameters:entityCount – [out] Number of entities Returns:Status

Status setId(int index, int id)

Set identifier of the entity specified by index. The indices may be input in any order. Note that there is no error checking for the validity of the index input to the getId() and getIds() functions.

See Also getId() , getIds()

Errors

• VALUE is generated if an index less than 1 is specified.
• MEMORY is generated if a memory allocation failure occurs.

Parameters:

• index – Index of entity to set identifier
• id – Entity identifier

Returns:

Status

Status getId(int index, int *id)

Get a single identifier associated with an index as an output argument.

See Also setId() , getIds()

Parameters:

• index – Index of entity
• id – [out] Entity identifier

Returns:

Status

Status getIds(int indexCount, int indices[], int ids[])

Get a set of identifiers associated with a set of indices. The array arguments indices and ids may be safely used as the same array.

See Also setId() , getId()

Parameters:

• indexCount – Number of indices
• indices – Array of entity indices
• ids – [out] Array of entity identifiers

Returns:

Status

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

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

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

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

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

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

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

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

Status setUserId(int id)

Set an optional IdTranslator user identifier.

See Also getUserId()

Parameters:id – User identifier Returns:Status

Status getUserId(int *id)

Get the optional IdTranslator user identifier.

See Also setUserId()

Parameters:id – [out] User identifier Returns:Status

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 setFiniteElementType(ElementType type)

Specify the finite element type. The values are intended to be those supported by the element association ELEMENT_TYPE .

See Also getFiniteElementType()

Parameters:type – ElementType Returns:Status

Status getFiniteElementType(ElementType *type)

Get the finite element type.

See Also setFiniteElementType()

Parameters:type – [out] ElementType Returns:Status

Status setFiniteElementSpecificType(SpecificType type)

Specify the finite element specific type. The values are intended to be those supported by the element association ELEMENT_SPECIFIC_TYPE .

See Also getFiniteElementSpecificType()

Parameters:type – SpecificType Returns:Status

Status getFiniteElementSpecificType(SpecificType *type)

Get the finite element specific type.

See Also setFiniteElementSpecificType()

Parameters:type – [out] SpecificType Returns:Status

Status setEntityType(EntityType entityType, EntityType entitySubtype)

Specify the type of parent and child entities.

See Also getEntityType()

Errors

ENUM is generated if an improper entityType and entitySubtype association is specified.

Parameters:

• entityType – EntityType of parent entity
  • ELEMENT
  • NODE
• entitySubtype – EntityType of child entity
  • FACE
  • EDGE

Returns:

Status

Status getEntityType(EntityType *entityType, EntityType *entitySubtype)

Get the type of parent and child entities.

See Also setEntityType()

Parameters:

• entityType – [out] EntityType of parent entity
• entitySubtype – [out] EntityType of child entity

Returns:

Status

Status clear()

Clear identifiers for all defined indices to zero.

Returns:Status

Status append(IdTranslator *toAppend)

Append all defined identifiers from another IdTranslator object.

Errors

MEMORY is generated if a memory allocation failure occurs.

Parameters:toAppend – IdTranslator object to append Returns:Status

Status count(CountType type, int *count)

Return either the maximum index set, the number of positive identifiers or the number of unique identifiers which have been defined using setId() .

Parameters:

• type – Count of CountType to return
• count – [out] Number of indices

Returns:

Status

Status createFromGroup(Group *group)

Set the active indices of the Group object as consecutive identifiers in the IdTranslator object. The IdTranslator object is initially cleared by this function. The active indices in the Group are set as identifiers with indices incrementing from 1.

Parameters:group – Group object Returns:Status

Status unique(IdTranslator *source)

Set the positive unique identifiers in the source object into this object. This operation removes duplicate identifiers from an IdTranslator object. The identifiers are placed in this object in ascending order with indices incrementing from 1.

Parameters:source – Source IdTranslator object Returns:Status

Status getEntityIndex(int id, int *index)

Perform entity identifier to entity index translation for a single identifier. Any undefined identifiers return an index of zero.

See Also getEntityIndices()

Parameters:

• id – Entity identifier for which to return entity index
• index – [out] Entity index

Returns:

Status

Status getEntityIndices(int count, int ids[], int indices[])

Perform entity identifier to entity index translation for an array of identifiers. Any undefined identifiers return an index of zero. The array arguments ids and indices may be safely used as the same array.

See Also getEntityIndex()

Parameters:

• count – Number of entity id translations to perform
• ids – Array of entity ids for which to return entity indices
• indices – [out] Array of entity indices

Returns:

Status

Status indexCount(int id, int *num)

Determine the number of entities which share a given identifier. If no entities have the given identifier, count is returned as zero.

See Also getAllIndices()

Parameters:

• id – Entity identifier for which to return number of entity indices
• count – [out] Number of entity indices

Returns:

Status

Status getAllIndices(int id, int *count, int index[])

Get all entity indices which share a given identifier. The count of matching indices is returned. If no entities have the given identifier, count is returned as zero.

See Also indexCount()

Parameters:

• id – Entity identifier
• count – [out] Number of entity indices
• index – [out] Array of entity indices

Returns:

Status

Status match(IdTranslator *toCheck, int *flag)

Compare identifiers in this IdTranslator object with another IdTranslator object. If the identifiers match, flag is returned as 1, otherwise 0.

Parameters:

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

Returns:

Status

Status copy(IdTranslator *source)

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

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

Status print()

Print the IdTranslator object information to standard output.

Returns:Status