Updated iRel.h with iterator support
Tim Tautges
tautges at mcs.anl.gov
Tue Feb 9 15:48:17 CST 2010
Exactly. So, given that, I think only the two additional functions will be sufficient. I just wanted to state the
assumption clearly, to explain why other functions weren't added too.
- tim
Mark Beall wrote:
> Tim,
>
> On the question of can you get the set from an iterator - the motivation
> for putting functions in iRel to get an iterator rather than a set was
> to avoid the overhead associated with creating "fake sets" for
> implementations that don't implement things as sets. Given that, it
> probably doesn't make sense to be able to ask the iterator for the set
> since that just reintroduces that issue.
>
> I hope to have some more time today or tomorrow to take a closer look at
> your changes.
>
> mark
>
> On Feb 5, 2010, at 11:09 AM, Tim Tautges wrote:
>
>> Hi all,
>> Attached is an updated header for iRel with iterator support.
>> There's one very important assumption I'm making which I'm not sure is
>> valid, and which I need input on: can one use an iterator to recover
>> the set it's iterating? Currently I don't see such a function. The
>> result is that very few iterator-based functions actually make sense
>> for iRel, namely 2 of them: getEntSetIterRelation and
>> getEntArrSetIterArrRelation.
>>
>> One other side effect of this change, and one which impacts both iGeom
>> and iMesh, is that we need an iBase_EntityIterator type, which before
>> now we didn't have. That shouldn't be a terribly difficult change for
>> most implementations.
>>
>> And, just writing the signatures for these functions reminded me just
>> how narrowly targeted these modifications are; for example, nowhere in
>> our interfaces do we consider the notion of iterating over sets stored
>> in a set. Thus, iterator-based functions in iRel will not be useful
>> here. It's also not clear what the semantics are for creating an
>> iterator over a set that contains sets. Does that iterator iterate
>> the entities contained in any sets?
>> You might ask who would ever want to do such a thing, but that's
>> exactly the question we should avoid asking when designing interfaces.
>>
>> - tim
>>
>> --
>> ================================================================
>> "You will keep in perfect peace him whose mind is
>> steadfast, because he trusts in you." Isaiah 26:3
>>
>> Tim Tautges Argonne National Laboratory
>> (tautges at mcs.anl.gov) (telecommuting from UW-Madison)
>> phone: (608) 263-8485 1500 Engineering Dr.
>> fax: (608) 263-4499 Madison, WI 53706
>>
>> #ifndef __iRel_LASSO_HPP__
>> #define __iRel_LASSO_HPP__
>>
>> #define IREL_MAJOR_VERSION 1
>> #define IREL_MINOR_VERSION 0
>>
>> /** \mainpage The ITAPS Relations Interface iRel
>> *
>> * Each ITAPS interface encapsulates functionality that "belongs"
>> * together, for example mesh or geometric model functionality. In
>> * some cases, however, data in several of these interfaces need to
>> * be related together. For example, a collection of mesh faces
>> * should be related to the geometric model face which they
>> * discretize. The ITAPS Relations interface accomplishes this in a
>> * way which allows the lower-level interfaces to remain
>> * independent.
>> *
>> * iRel defines relations as pairwise relations between entities
>> * or entity sets. Related entities can be in the same or different
>> * interfaces. A given relation is created for a given pair of
>> * interfaces and returned in the form of a \em Relation \em Handle.
>> * After a specific relation pair has been created, concrete
>> * relations for that pair can be assigned and retrieved for
>> * specific entities using set and get functions on the iRel
>> * interface. A given interface instance can appear in one or many
>> * relation pairs, each identified by the relation handle.
>> *
>> * \section Relation Types
>> *
>> * Relations are also distinguished by a pair of relation types.
>> * For each interface in a relation pair, a corresponding type
>> * indicates whether the relation applies to entities, entity sets,
>> * or both entities and sets in the corresponding interface in the
>> * pair. If only one of the interfaces in a given pair has a
>> * 'both'-type, entities and entity sets in that
>> * interface are each related to either entities or sets in the other
>> * interface in the pair. If both of the sides of a relation are of
>> * 'both'-type, entities and sets on one side of a relation point to
>> * sets on the other side.
>> *
>> * \section Argument Order
>> *
>> * Many functions in the iRel interface take as input two entities,
>> * or two lists of entities, along with a relation handle. For
>> * these functions, the entities or lists are assumed to be in the
>> * same order as the interfaces used to create that relation pair.
>> * For example, if a relation pair is created by calling:
>> * \code
>> * iRel_createRelation(instance, iface1, ent_or_set1, type1,
>> * iface2, ent_or_set2, type2,
>> * &relation_handle, &ierr)
>> * \endcode
>> * and relations set by calling
>> * \code
>> * iRel_setEntEntRelation(instance, relation_handle,
>> * ent1, is_set1, ent2, is_set2, &ierr)
>> * \endcode
>> * it is assumed that ent1 is contained in iface1 and ent2 in
>> * iface2.
>> *
>> * For functions taking only one entity or list as input, and
>> * returning an entity or list, an additional argument indicates
>> * whether the input entity or list belongs to the first or second
>> * interface in that relation pair.
>> *
>> */
>>
>> #include "iGeom.h"
>> #include "iMesh.h"
>> #include "iRel_protos.h"
>>
>> #ifdef __cplusplus
>>
>> extern "C"
>> {
>> #endif
>>
>> /**\brief Type used to store iRel interface handle
>> *
>> * Type used to store iRel interface handle
>> */
>> typedef void* iRel_Instance;
>>
>> /**\brief Type used to store references to relation pairs
>> *
>> * Type used to store references to relation pairs
>> */
>> typedef struct iRel_RelationHandle_Private* iRel_RelationHandle;
>>
>> /**\brief \enum IfaceType Enumerator specifying interface types
>> *
>> * Enumerator specifying interface types. This enumeration is
>> * necessary because functions to get entities of a given dimension
>> * are part of the higher-level interfaces (e.g. iGeom, iMesh) instead
>> * of iBase.
>> */
>> enum IfaceType
>> {iRel_IGEOM_IFACE = 0,
>> iRel_IMESH_IFACE,
>> iRel_IFIELD_IFACE,
>> iRel_IREL_IFACE};
>>
>> /**\brief \enum RelationType Enumerator specifying relation types
>> *
>> * Enumerator specifying relation types. A relation has two types,
>> one
>> * for each side of the relation.
>> */
>> enum RelationType
>> {iRel_ENTITY = 0,
>> iRel_SET,
>> iRel_BOTH};
>>
>> extern struct iBase_Error iRel_LAST_ERROR;
>>
>> /**\brief iRel_dtor Destroy the interface object
>> *
>> * Calls destructor on interface object
>> \param instance Interface object handle to destroy
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_dtor(iRel_Instance instance, int *ierr);
>>
>> /**\brief Create a relation pair between two interfaces
>> *
>> * Creates a relation pair between two interfaces, passing
>> * back a handle to the pair.
>> \param instance Interface instance
>> \param iface1 1st interface object in the relation pair
>> \param ent_or_set1 This relation relates entities (=0) or sets
>> (=1)
>> or both (=2) from 1st interface object
>> \param iface_type1 Type of 1st interface (0=iBase, 1=iGeom,
>> 2=iMesh,
>> 3=iField, 4=iRel)
>> \param iface2 2nd interface object in the relation pair
>> \param ent_or_set2 This relation relates entities (=0) or sets
>> (=1)
>> or both (=2) from 2nd interface object
>> \param iface_type2 Type of 2nd interface (0=iBase, 1=iGeom,
>> 2=iMesh,
>> 3=iField, 4=iRel)
>> \param *rel Pointer to relation handle, returned from function
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_createRelation (
>> iRel_Instance instance,
>> iBase_Instance iface1,
>> const int ent_or_set1,
>> const int iface_type1,
>> iBase_Instance iface2,
>> const int ent_or_set2,
>> const int iface_type2,
>> iRel_RelationHandle *rel,
>> int *ierr);
>>
>> /**\brief Get information for this relation handle
>> *
>> * Get information about the interfaces and relation type for this
>> * relation. Relation type for each side is passed back as integers,
>> * but values will be from RelationType enumeration.
>> \param instance Interface instance
>> \param rel Handle of relation pair being queried
>> \param *iface1 Side 1 instance for this relation
>> \param *type1 Relation type for side 1 of this relation
>> \param *iface2 Side 2 instance for this relation
>> \param *type2 Relation type for side 2 of this relation
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_getRelationInfo (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_Instance *iface1,
>> int *type1,
>> iBase_Instance *iface2,
>> int *type2,
>> int *ierr);
>>
>> /**\brief Destroy a relation pair
>> *
>> * Destroy the relation pair corresponding to the handle input
>> \param instance Interface instance
>> \param rel Handle of relation pair to destroy
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_destroyRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> int *ierr);
>>
>> /**\brief Get interfaces related to specified interface
>> *
>> * Get interfaces related to the specified interface
>> \param instance Interface instance
>> \param iface Specified interface
>> \param interfaces Pointer to array holding returned interfaces
>> related to specified interface
>> \param interfaces_allocated Pointer to allocated size of
>> interfaces list
>> \param interfaces_size Pointer to occupied size of interfaces list
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_getRelatedInterfaces (
>> iRel_Instance instance,
>> iBase_Instance iface,
>> iBase_Instance **interfaces,
>> int *interfaces_allocated,
>> int *interfaces_size,
>> int *ierr);
>>
>> /**\brief
>> *
>> *
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent1 1st entity of relation being set
>> \param ent2 2nd entity of relation being set
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_setEntEntRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> iBase_EntityHandle ent2,
>> int *ierr);
>> void iRel_setEntSetRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> iBase_EntitySetHandle entset2,
>> int *ierr);
>> void iRel_setSetEntRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> iBase_EntityHandle ent2,
>> int *ierr);
>> void iRel_setSetSetRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> iBase_EntitySetHandle entset2,
>> int *ierr);
>>
>> /**\brief Set a relation between an entity and several entities
>> *
>> * Set a relation between an entity and several entities. If either
>> is a set and that side of the relation is 'both'-type, set
>> relations
>> for individual entities in that set too.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent1 1st entity of relation being set
>> \param switch_order If non-zero, ent1 is related with iface2 and
>> ent_array_2 with iface1 of
>> specified relation, otherwise vica versa
>> \param ent_array_2 Entity(ies) to be related to ent1
>> \param num_entities Number of entities in ent_array_2
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_setEntEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntityHandle *ent_array_2,
>> int num_entities,
>> int *ierr);
>> void iRel_setSetEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> int switch_order,
>> iBase_EntityHandle *ent_array_2,
>> int num_entities,
>> int *ierr);
>> void iRel_setEntSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntitySetHandle *entset_array_2,
>> int num_entities,
>> int *ierr);
>> void iRel_setSetSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> int switch_order,
>> iBase_EntitySetHandle *entset_array_2,
>> int num_entities,
>> int *ierr);
>>
>> /**\brief Set relations between arrays of entities pairwise,
>> * ent_array_1[i]<->ent_array_2[i]
>> *
>> * Set relations between arrays of entities pairwise,
>> ent_array_1[i]<->ent_array_2[i]. If either array
>> contains sets and that side of the relation is 'both'-type,
>> set relations for individual entities in those sets too.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent_array_1 1st array of entities of relation being set
>> \param num_ent1 Number of entities in 1st array
>> \param ent_array_2 2nd array of entities of relation being set
>> \param num_ent2 Number of entities in 2nd array
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_setEntArrEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *ent_array_1,
>> int num_ent1,
>> iBase_EntityHandle *ent_array_2,
>> int num_ent2,
>> int *ierr);
>> void iRel_setEntArrSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *ent_array_1,
>> int num_ent1,
>> iBase_EntitySetHandle *entset_array_2,
>> int num_ent2,
>> int *ierr);
>> void iRel_setSetArrSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle *entset_array_1,
>> int num_ent1,
>> iBase_EntitySetHandle *entset_array_2,
>> int num_ent2,
>> int *ierr);
>>
>> /**\brief Get entity related to specified entity and relation handle
>> *
>> * Get entity related to specified entity and relation handle. Also
>> returns whether the related entity is an entity or a set.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent1 1st entity of relation being queried
>> \param switch_order 1st entity is related to 1st interface (=0)
>> or 2nd
>> interface (=1) of relation pair
>> \param *ent2 Pointer to entity related to ent1
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_getEntEntRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntityHandle *ent2,
>> int *ierr);
>> void iRel_getEntSetRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntitySetHandle *entset2,
>> int *ierr);
>> void iRel_getSetSetRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> int switch_order,
>> iBase_EntitySetHandle *entset2,
>> int *ierr);
>> void iRel_getEntSetIterRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntityIterator *entset2,
>> int *ierr);
>>
>>
>> /**\brief Get entities related to specified entity and relation
>> *
>> * Get entities related to specified entity and relation; returns
>> entity sets or contained entities, depending on relation type
>> (entity, set, or both).
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent1 1st entity of relation being queried
>> \param switch_order ent1 is related with 1st (=0) or 2nd (=1)
>> interface
>> of this relation pair
>> \param *ent_array_2 Pointer to array of entity handles returned
>> from function
>> \param *ent_array_2_allocated Pointer to allocated size of
>> ent_array_2
>> \param *ent_array_2_size Pointer to occupied size of ent_array_2
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_getEntEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle ent1,
>> int switch_order,
>> iBase_EntityHandle **ent_array_2,
>> int *ent_array_2_allocated,
>> int *ent_array_2_size,
>> int *ierr);
>> void iRel_getSetEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entset1,
>> int switch_order,
>> iBase_EntityHandle **ent_array_2,
>> int *ent_array_2_allocated,
>> int *ent_array_2_size,
>> int *ierr);
>>
>> /**\brief Get entities related to those in specified array and
>> relation, pairwise
>> *
>> * Get entities related to those in specified array and relation,
>> pairwise.
>> Returns sets or entities, depending on relation type and
>> entities in
>> ent_array_1.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param ent_array_1 Array of entities whose relations are being
>> queried
>> \param ent_array_1_size Number of entities in ent_array_1
>> \param switch_order Entities in ent_array_1 are related with
>> 1st (=0)
>> or 2nd (=1) interface of this relation pair
>> \param *ent_array_2 Pointer to array of entity handles returned
>> from function
>> \param *ent_array_2_allocated Pointer to allocated size of
>> ent_array_2
>> \param *ent_array_2_size Pointer to occupied size of ent_array_2
>> \param *offset Pointer to offset array; (*offset)[i] is index into
>> (*ent_array_2) of 1st relation of ent_array_1[i]
>> \param *offset_allocated Pointer to allocated size of offset
>> \param *offset_size Pointer to occupied size of offset
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_getEntArrEntArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *ent_array_1,
>> int ent_array_1_size,
>> int switch_order,
>> iBase_EntityHandle **ent_array_2,
>> int *ent_array_2_allocated,
>> int *ent_array_2_size,
>> int **offset,
>> int *offset_allocated,
>> int *offset_size,
>> int *ierr);
>> void iRel_getEntArrSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *ent_array_1,
>> int ent_array_1_size,
>> int switch_order,
>> iBase_EntitySetHandle **entset_array_2,
>> int *ent_array_2_allocated,
>> int *ent_array_2_size,
>> int *ierr);
>> void iRel_getSetArrSetArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle *entset_array_1,
>> int ent_array_1_size,
>> int switch_order,
>> iBase_EntitySetHandle **entset_array_2,
>> int *ent_array_2_allocated,
>> int *ent_array_2_size,
>> int *ierr);
>> void iRel_getEntArrSetIterArrRelation (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *ent_array_1,
>> int ent_array_1_size,
>> int switch_order,
>> iBase_EntityIterator **entiter,
>> int *entiter_allocated,
>> int *entiter_size,
>> int *ierr);
>>
>> /**\brief Infer relations between entities in specified pair of
>> interfaces
>> *
>> * Infer relations between entities in specified pair of
>> interfaces. The
>> criteria used to infer these relations depends on the
>> interfaces in
>> the pair, the iRel implementation, and the source of the data
>> in those
>> interfaces.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_inferAllRelations (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> int *ierr);
>>
>> /**\brief Infer relations and relation type between entities in
>> specified
>> * pair of interfaces
>> *
>> * Infer relations between entities in specified pair of
>> interfaces, and the
>> * relation type used by this iRel implementation. The
>> * criteria used to infer these relations depends on the interfaces in
>> * the pair, the iRel implementation, and the source of the data in
>> those
>> * interfaces.
>> * \param instance Interface instance
>> * \param rel Relation handle created by implementation
>> * \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_inferAllRelationsAndType (
>> iRel_Instance instance,
>> iRel_RelationHandle *rel,
>> int *ierr);
>>
>> /**\brief Infer relations corresponding to specified entity and
>> relation pair
>> *
>> * Infer relations corresponding to specified entity and relation
>> pair. The
>> criteria used to infer these relations depends on the
>> interfaces in
>> the pair, the iRel implementation, and the source of the data
>> in those
>> interfaces.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param entity Entity whose relations are being inferred
>> \param is_set Entity is a regular entity (=0) or a set (=1)
>> \param iface_no Entity corresponds to 1st (=0) or 2nd (=1)
>> interface
>> in relation pair
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_inferEntRelations (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle entity,
>> int iface_no,
>> int *ierr);
>> void iRel_inferSetRelations (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle entity_set,
>> int iface_no,
>> int *ierr);
>>
>> /**\brief Infer relations corresponding to specified entities and
>> relation pair
>> *
>> * Infer relations corresponding to specified entities and relation
>> pair. The
>> criteria used to infer these relations depends on the
>> interfaces in
>> the pair, the iRel implementation, and the source of the data
>> in those
>> interfaces.
>> \param instance Interface instance
>> \param rel Relation handle being queried
>> \param entities Array of entities whose relation are being
>> inferred
>> \param entities_size Number of entities in array
>> \param is_set Entities are regular entities (=0) or sets (=1)
>> \param iface_no Entities correspond to 1st (=0) or 2nd (=1)
>> interface
>> in relation pair
>> \param *ierr Pointer to error value, returned from function
>> */
>> void iRel_inferEntArrRelations (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntityHandle *entities,
>> int entities_size,
>> int iface_no,
>> int *ierr);
>> void iRel_inferSetArrRelations (
>> iRel_Instance instance,
>> iRel_RelationHandle rel,
>> iBase_EntitySetHandle *entity_sets,
>> int entities_size,
>> int iface_no,
>> int *ierr);
>>
>> /**\brief Create a new iRel instance
>> *
>> * Create a new iRel instance. Currently no options are implemented.
>> \param options Options for the implementation
>> \param *instance Interface instance
>> \param *ierr Pointer to error value, returned from function
>> \param options_len Length of options string
>> */
>> void iRel_newRel(const char *options,
>> iRel_Instance *instance,
>> int *ierr,
>> const int options_len);
>>
>> #ifdef __cplusplus
>> } /* extern "C" */
>> #endif
>>
>> #endif /* #ifndef __iRel_LASSO_HPP__ */
>>
>
>
--
================================================================
"You will keep in perfect peace him whose mind is
steadfast, because he trusts in you." Isaiah 26:3
Tim Tautges Argonne National Laboratory
(tautges at mcs.anl.gov) (telecommuting from UW-Madison)
phone: (608) 263-8485 1500 Engineering Dr.
fax: (608) 263-4499 Madison, WI 53706
More information about the tstt-interface
mailing list