iRel proposal: removing non-one-to-one relation functions

[James Porter]

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