Summary of Proposed iRel v1.1 Modifications

Motivation

Viewing "Entity Array" as the content of "Set" resulted in the following issues in iRel v1.0.

[Issue #1] "iRel_getEntEntArrRelation is identical to calling iRel_getEntSetRelation and iMesh/iGeom_getEntities". Currently, when iRel_getEntEntArr is called on CGM/MOAB data, the entity array returned is the content of the set related to the entity. Correspondingly, iRel_setEntEntArrRelation is defined to update the content of the related set to contain new entities.

The specification is ambiguous if there's no set associated with the entity; return an error or create a new set.

[Issue #2] Relating one entity to many sets can be done by relating one entity to one set and have that set contain other sets. The problem arises on getting multiple sets related with the entity; it can be either by calling
  • iRel_getEntSetRelation and iMesh/iGeom_getEntSets
  • iRel_getEntEntArrRelation and iMesh/iGeom_getEntSets (INCONSISTENCY)

[Issue #3] For Entity-Both relation type, iRel implementation should support twelve possible combinations of two set functions, three get functions and two remove functions seamlessly. If get/set/rmv are not matching functions (e.g. calling iRel_getEntSetIterRelation, iRel_rmvEntSetRelation, and iRel_setEntEntArrRelation), the data conversions in-between get/rmv/set operations are inevitable.

Set functions Get functions Rmv functions
iRel_setEntEntArrRelation iRel_getEntEntArrRelation iRel_rmvEntEntArrRelation
iRel_setEntSetRelation iRel_getEntSetRelation iRel_rmvEntSetRelation
iRel_getEntSetIterRelation

[Issue #4] iRel relations are unique. In case of Set/Both relation type, iRel_setEntSetRelation resets a relationship (removing old relationship, adding the new one). Therefore, when we set the classification of newly created mesh entities during the mesh modification with set, mesh entity set to be related to the model entity shall contain all other mesh entities classified on the model entity as well as newly created entities and this way, reverse classification is always maintained up-to-date.

Changes in iRel v1.1

For the purpose of eliminating ambiguity and better service for certain interfaces with relation data stored in underlying implementation, the following are proposed in iRel v1.1.

  1. RelationType = {Entity, EntityArray, Set, Both}

iRel support "Entity Array" and "Set" for representing multiple data. Entity Array relation type is for convenient handling temporary c-array of entities to access the relation data stored at the implementation level.

  1. [Entity Array and Set are NOT interchangeable in API functions]
    • For a relation with Set, set/get functions with EntArr are not allowed (error is returned).
    • For a relation with EntArr, set/get functions with Set are not allowed (error is returned).
    • For Ent-Set/Both relation type, iMesh/iGeom_getEntities shall be used for getting entities in the set instead of iRel_getEntArrRelation.
    • Relating one entity to many sets can be done by relating one entity to one set and have that set contain other sets. Getting multiple sets related with the entity is done by calling iRel_getEntSetRelation and iMesh/iGeom_getEntSets. This cannot be done interchangeably by iRel_getEntArrRelation.
  1. [Relation Type "EntityArray - Set" is not allowed]
  2. [Remove iRel_getEntSetIterRelation and iRel_getEntArrSetIterArrRelation]
    Six functions are supported for each set/get/rmv relation function.
    • iRel_set/get/rmvEntEntRelation
    • iRel_set/get/rmvEntEntArrRelation
    • iRel_set/get/rmvEntArrEntRelation
    • iRel_set/get/rmvEntSetRelation
    • iRel_set/get/rmvSetEntRelation
    • iRel_set/get/rmvSetSetRelation

In case of Ent-EntityArray relation type, which uses C-array for holding entities temporarily in iRel, when an entity in entity array is deleted or modified, EntityArray will contain invalidated entity handle. To avoid invalidated entity handle in entity array while accessing/iterating the entity array through index and avoid memory allocation for temporary array in iRel, iRel_getEntEntArr uses iBase_EntityIterator instead of c-array of entities as argument, where iBase_EntityIterator is a wrapper of iterator implemented in underlying interfaces with "no invalidation with entity removal".

  1. For Entity Array relation type, relation type change function is not supported since the relation data between two interfaces are explicitly stored and maintained in underlying interfaces.
  1. In case of Entity-EntityArray, unique relationship rule (replacing the old entity array to new entity array for resetting relationship) is not applied to the relation between entity and entity array since entity array is not an object with status.
  1. In case of Entity-Both relation type, entity on Entity side doesn't maintain the up-to-date points to entities contained in set on Both side. Similarily, in Entity-Entity Array relation type, entity on Entity side doesn't have to maintain up-to-date point to entities on Entity Array side. However, it doesn't limit the functionality of iRel_getEntEntArrRelation. No matter what the points from entity on Entity side to entities on Entity Array are maintained up-to-date, iRel_getEntEntArrRelation should be able to return up-to-date information on the query.

Examples

For simple denotation, iRel v1.0 is the specification before Entity Array relation type proposal. iRel v1.1 is the specification with Entity Array proposal (the current document). For the comparison of iRel v1.0 and v1.1, two use cases were added.

  • 4.2.1: Classification/reverse classification with iRel v1.0
  • 4.2.2: Classification/reverse classification with iRel v1.1
  • 4.3.1: Edge swapping with iRel v1.0
  • 4.3.2: Edge swapping with iRel v1.1

Discussions

  1. Do we need a relation type Entity Array . Entity Array?
  2. Do we need api functions for multiple relation pair data association? E.g.
    • iRel_getEntArrEntArrRelation
    • iRel_getEntArrEntArrArrRelation
    • iRel_getEntArrArrEntArrRelation
    • iRel_getEntArrSetArrRelation
    • iRel_getSetArrEntArrRelation
    • iRel_getSetArrSetArrRelation
  1. In case of entity modification looping over the entity array or set, invalid entity handle in entity array will cause a problem no matter where the entity array/set is created in iMesh or iRel. Do we have agreed solution this?
  2. Some implementations won't be able to, or don't want to, efficiently maintain a relation like this in both directions. Is it fair to require maintaining relations up-to-date in only one way? The specification of Entity-Set seems to say yes (up-to-date relation from entity on Both side to Entity on Entity only). iRel v1.1 proposed to apply the same rule to Entity-Entity Array (up-to-date relation from entity on EntityArray side to Entity on Entity only)
  3. Is there a way for the application to know whether this is the case or not, or for the application to specify what they need updated and when.