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

[Tim Tautges]

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
>>>>>
>>>>
>>>>
>>>
>>
>>
>
>

-- 
================================================================
"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