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

[James Porter]

On Thu, 2010-10-28 at 03:12 -0400, seol at scorec.rpi.edu wrote:
> From what we discussed in the bootcamp, the way of removing the relation (use case: removing classification) is still
> missing. Mark B. proposed to add iRel_removeXXXXRelation.

Sounds reasonable, though for consistency with tags/sets, I guess it'd
be iRel_rmv(XYZ)Relation.

> > * (RPI) Change iRel_newRel -> iRel_create (likewise for dtor -> destroy)
> >   Not much sense in doing this until iMesh/iGeom do it.
> 
> If I am not mistaken, this issue has been ratified (conclusion: YES)

Ok, I have the notes from the meeting now, so I can start making the
changes that I missed earlier.

> > * (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.
> 
> To the best of my remembrance, we agreed to add iRel_getEntSetArr and iRel_getSetSetArr in the bootcamp.

In the notes, it says that the decision was that we'd remove
iRel_set(Ent|Set)SetArrRelation (note that this is "set" not "get").

> > * (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.
> 
> Among 24 iRel_set/get functions, the eight functions don't have switch_order argument to determine the "relation side".
> Incompleteness could be interpreted in either of two: "relation side" was accidentally missed from the eight functions
> or the necessity of "relation side" is not clear yet. If neither is the case, let's discuss.

The reason I didn't add switch_order to those, and presumably the reason
that they weren't there before is that one can set a one-to-one relation
without bothering to define the order. That is, there are both
iRel_setEntSetRelation and iRel_setSetEntRelation, whereas there's no
iRel_setEntArrEntRelation (but there is the reverse).

This assumes that an explicit call to a set relation function implies
that the relation is symmetric. Even with "Both"-type relations, I don't
think this is a problem, but that would require a pretty long
digression, so I'm avoiding it for now.

> In addition to the above, I propose some wordsmithing idea:
> 1. change "int *ierr" to "int *err" for consistency with other interface

Sounds reasonable.

> I checked iMesh and iRel. Most of iMesh/iRel functions do have "int *err" at the end of arg list, but some (not
> many) don't. Do we have any conventions for the order of args?

If you're talking about what I think you're talking about, this is due
to the calling conventions of Fortran functions, where string length for
an arg is appended to the end of the function parameter list. (I think.)
If you want this to change, you'll have to convince everyone that
wrappers are the way to go for Fortran support (you won't find any
arguments from me).

> 3. We defined the enumeration type "RelationType". To represent "relation type", we use "integer" type instead of
> "RelationType". Here I see two options:
> 
>    #1. change "int ent_or_set" to "RelationType type"
>    #2. remove the enumeration type "RelationType" since it's no use

The ITAPS interfaces use ints instead of enums to maintain ABI
compatibility since the size of an enum is not defined by the standard*.
Whether this is important or not is a different question, though. (I for
one doubt the necessity of this.)

* Ok, technically the size of an int isn't defined either beyond minimum
ranges, but at least ints are generally guaranteed to be the same size
on a given platform.

> 4. adding "EntArr" to "Relation Type" and removing iRel_getEntSetIter & iRel_getEntArrSetIterArr
> 
>    CURRENT Relation Type: Ent, Set, Both (Ent&Set)
>    NEW: Ent, Set, Both (Ent&Set), EntArr

Assuming we end up agreeing that directly encoding one-to-many
relationships in iRel (instead of relying on iMesh/iGeom to give us this
though sets and/or iterators), I don't think this is a good way to go
about doing it as it's really just a hack to work around implementations
that don't support sets. A clearer and more general-purpose way to do
this would be to add another property representing the cardinality of
the relation, that is, one-to-one, one-to-many, and so on.

Don't take the above suggestion as endorsement, though. As the
maintainer of (currently) the only iRel implementation, I should note
that doing this (either your way or mine) will significantly increase
the complexity and decrease the potential for interoperability** of iRel
unless the iMesh and iGeom specs are updated as well. In Lasso's case
anyway, doing this interoperably would require variable-length tags (and
possibly a way of serializing other implementations' handles).

I've discussed some of these options before with Tim Tautges, and what
you're proposing is not a small change by any means. It may require
rethinking large portions of the iRel specification (e.g. asymmetry),
which may not be entirely bad, as the draft specification is more than a
bit sparse in some areas. (I'm sure people have ideas about how they
think it should work, but it would be good to ensure we're all on the
same page here.)

** Between different implementations of ITAPS interfaces

> This avails non set-dominant impementation to support "iRel" effectively without interfering set-dominant
> implementation and not against neither of "interchangeability" and "interoperability".

I must confess that my knowledge of other ITAPS implementations is
limited, but are you suggesting that a) you wouldn't support the
set-based functions in iRel at all, or b) that you'd support them, but
they wouldn't be the optimal way of working with data in your
implementation?

If we're talking about (a) here, this is a pretty optimistic view,
perhaps overly so. Clearly, if one implementation supports a given
function and the other does not (e.g. a "set-dominant" interface doesn't
fully support arrays or an "array-dominant" interface doesn't support
sets), that function is by definition not interchangeable. For
MOAB/CGM/Lasso, this problem is academic, since MOAB and CGM support
both set- and array-based operation (and Lasso will too, however it ends
up looking), but for other implementations, this could be more serious
issue. In practice, this would mean that you'd be unable to use many of
the tools we write that target ITAPS interfaces.

If we're talking about (b), see my discussion above on relation
cardinality.

- Jim