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

[James Porter]

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