iRel.h interface update [was iRel proposal: removing non-one-to-one relation functions]

[Mark Shephard]

I was under the impression there were more than that agreed to so that 
fast mesh entity to geometric model relations could be efficiently 
supported. Seegyoung will review and provide more specific feed back to 
indicate if things are set or if they are not to indicate what the 
issues are. Fabien will provide comments with respect to supporting iFields.

On 10/26/10 7:58 PM, Tim Tautges wrote:
>
>
> On 10/26/2010 06:39 PM, Mark Shephard wrote:
>> Tim,
>>
>> Based on this email list it does not appear that the changes listed
>> include the additions that we had the two rounds of discussion (that Jim
>> was not part of) and agreement that the needed changes would be made.
>>
>
> Can you tell me which ones are missing? I thought we'd gotten them all,
> or listed the missing ones and why they're not there yet.
>
> - tim
>
>> If those changes have been made please let us know exactly where they
>> are accounted for since until we have those additions looking at other
>> items will not make sense.
>>
>> Mark
>>
>> On 10/26/10 7:02 PM, James Porter wrote:
>>> I've committed a new version of iRel.h taking into account the recent
>>> discussion (*not* including my non-one-to-one proposal). Be warned,
>>> there are a lot of changes by line, since I fixed the indentation on the
>>> comments to be consistent with iMesh.h and iGeom.h as well as documented
>>> in/out parameters. I'd upload those in separate revisions, but SVN
>>> doesn't play nicely with merging histories between repos, and it'd be a
>>> lot of work to do manually.
>>>
>>> Here's a rundown of what's changed (names in parens indicate who made
>>> the suggestion):
>>>
>>> * (Porter, J) Replace iRel_LAST_ERROR with iRel_getDescription and
>>> iRel_getErrorType for consistency with iMesh/iGeom
>>> * (RPI) __iRel_LASSO_HPP__ is now _ITAPS_iRel
>>> * (RPI) Includes iBase.h instead of iGeom.h/iMesh.h
>>> * (RPI) Documented argument types (in, out, inout)
>>> * (Porter, J; RPI) Cleaned up comment formatting, fixed out-of-date or
>>> inaccurate comments (remove is_set comments from infer functions)
>>> * (Porter, J) Uses of "Relation" to refer to a PairHandle are now "Pair"
>>>
>>> Stuff I didn't do (and why):
>>>
>>> * (Porter, J) Define iBase_EntityIterator in iBase.h
>>> This would have effects on iMesh and iGeom, so I left it aside for
>>> now.
>>> * (RPI) How to work with iBase_EntityIterator
>>> Nothing to do currently. Right now you'd just use the iMesh or iGeom
>>> functions as appropriate. This needs some discussion if it's going to
>>> change, otherwise it could just be documented in iBase.h, where
>>> iBase_EntityIterator belongs.
>>> * (RPI) Change iRel_newRel -> iRel_create (likewise for dtor -> destroy)
>>> Not much sense in doing this until iMesh/iGeom do it.
>>> * (RPI) Missing iRel_get(Ent|Set)SetArrRelation
>>> I'm arguing against all functions like this anyway, so I left them out
>>> until we decide on that to do there.
>>> * (RPI) Missing switch_order from iRel_setEntEntRelation and friends
>>> This argument isn't necessary to make these functions work. If people
>>> really see a use for them, we can add them, but it wasn't obvious to
>>> me that this was the way to go. This would need discussion, I think.
>>>
>>> I think that's everything.
>>>
>>> - Jim
>>>
>>>
>>> On Tue, 2010-10-26 at 13:50 -0400, Mark Shephard wrote:
>>>> As was stated previously, we are still waiting for Tim to provide the
>>>> up-dated iRel.h documentation to reflect the things discussed at the
>>>> bootcamp that are needed by implementations other than MOAB. These
>>>> items
>>>> have been agreed to (twice now) but still not included in iRel.h. Until
>>>> those items are settled it does not make sense to consider other
>>>> changes
>>>> that may influence the things we are waiting for.
>>>>
>>>> Tim - When with the updated iRel.h file be provided? If you can not get
>>>> to it, there are others that could likely edit the iRel.h to reflect
>>>> the
>>>> things that were agreed to at the boot camp.
>>>>
>>>> Mark
>>>>
>>>>
>>>> On 10/26/10 1:39 PM, James Porter wrote:
>>>>> I haven't seen any responses to this. I'm hoping this is because no
>>>>> one
>>>>> has a problem with it. I'll give it a few more days for comments,
>>>>> but if
>>>>> no one pipes up, I'll make the proposed changes.
>>>>>
>>>>> - Jim
>>>>>
>>>>> On Mon, 2010-10-04 at 14:55 -0500, James Porter wrote:
>>>>>> Currently in iRel, there are a handful of functions to get/set
>>>>>> relations
>>>>>> that aren't one-to-one (e.g. iRel_getEntEntArrRelation). It's my
>>>>>> understanding that these are only meant to work in, say, Entity<->Set
>>>>>> relations, and that the entity array returned is the contents of
>>>>>> the set
>>>>>> related to the entity on the left side. That is, it's equivalent to
>>>>>> calling iRel_getEntSetRelation and then i(Mesh|Geom)_getEntities on
>>>>>> the
>>>>>> set you get back.
>>>>>>
>>>>>> I propose that these functions be removed. Here's why:
>>>>>>
>>>>>> Note 1: most of this is based on my discussion with Tim Tautges and
>>>>>> our
>>>>>> implementation, Lasso, so hopefully I'm not just misinterpreting the
>>>>>> spec.
>>>>>>
>>>>>> Note 2: I use "left-" and "right-" prefixes to denote which side of
>>>>>> the
>>>>>> relation an entity or set is on.
>>>>>>
>>>>>> 1) Problems with setting relations
>>>>>>
>>>>>> The biggest problem with these functions is in setting relations.
>>>>>> What
>>>>>> you're actually doing is updating the contents of the related set to
>>>>>> contain those new elements. That is, if left-ent A is related to
>>>>>> right-set B, setting a relation between A and [C,D,...,Z] (where
>>>>>> C-Z are
>>>>>> right-ents) actually inserts C-Z into B. That's certainly not what
>>>>>> I'd
>>>>>> expect initially; I would expect iRel to only affect stuff in its own
>>>>>> area (e.g. relation tags set on each interface). It gets worse
>>>>>> because
>>>>>> it's not clear what you should do when the set B doesn't exist
>>>>>> (throw an
>>>>>> error? create a new set? Lasso does the former, currently).
>>>>>>
>>>>>> This also presents further problems because there's no corresponding
>>>>>> iRel_setEntSetArrRelation function, even though a set could be
>>>>>> contained
>>>>>> in a set just as easily as an entity.
>>>>>>
>>>>>> 2) Confusion about iRel's capabilities
>>>>>>
>>>>>> iRel really creates one-to-one (possibly asymmetric) relations, but
>>>>>> these functions seem to imply that one-to-many or even many-to-many
>>>>>> relationships are possible. This is not, as far as I can tell, the
>>>>>> intention.
>>>>>>
>>>>>> 3) Not that useful
>>>>>>
>>>>>> In most cases, these functions only save a single line of code. If
>>>>>> you're trying to be truly generic (i.e. you don't know what the
>>>>>> set-side
>>>>>> interface is), it's a little more complicated, but not much.
>>>>>>
>>>>>> 4) Hurts clarity of Python interfaces
>>>>>>
>>>>>> This is a mostly selfish reason, since I'm the developers of the
>>>>>> ITAPS
>>>>>> Python interfaces, but if all relation functions are one-to-one, I'm
>>>>>> able to simplify the Python iRel interface's functions to
>>>>>> "getRelation"
>>>>>> and "setRelation", since I know a priori the type of element that
>>>>>> should
>>>>>> be returned when you call getRelation.
>>>>>>
>>>>>> - Jim
>>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>
>>
>