itaps-parallel getVtxCoordIndex

[Jason Kraftcheck]

Lori A. Diachin wrote:
> Hi All,
> 
> I came across an issue with the getVtxCoordIndex function while I was
> testing my finite element solver code with the GRUMMP implementation of
> iMesh.  In talking it over with Carl, we realized that we had very
> different interpretations of what should be returned from the function
> and that the documentation was unclear.  So we are pinging the group for
> feedback so that we can clarify the documentation and ensure that
> implementations are compliant...
> 
> In particular, I am attempting to request the vertices associated with
> triangular faces and so I set the requested_entity_type to FACE,
> requested_entity_topology to TRIANGLE, and entity_adjacency_type to
> VERTEX.  I expect to get back 3 indices per face so that the offset
> array is set to 0,3,6,...  This is how it's implemented in 'simple
> mesh'.  I do not use the entity_adjacency_type argument for much of
> anything.

Given that interpretation, what would you expect for
  requested_entity_topology = TRIANGLE
  entity_adjacency_type = EDGE
?

> 
> Carl had a different interpretation of the spec.  As he understands it, 
> getVtkCoordIndex first grabs a bunch of adjacent entities, then makes a
> list of the vertex indices for the verts of -those- entities.  So for my
> request above, he returns individual vertices as the requested adjacency
> type and sets the offset array to 0,1,2,3,....   To get the information
> I want, he changes the arguments so that the entity_adjacency_type is
> FACE to get faces adjacent to TRIANGLES..
> 
> Thoughts on these interpretations?  We need to be sure that the
> documentation (user guide and man pages are both vague on this) and
> compliance test codes are clear on this.
> 

It seems to me that this function is designed to traverse (up to) two levels
of adjacencies:
  requested_entity_(type|topology) -> entity_adjacency_type
 and
  entity_adjacency_type -> vertex

So the question would seem to be:  Does the offset list correspond to the
offsets for the first- or second-level adjacency query?  A partial answer is
to strive not to return meaningless information.  If either of the adjacency
steps is a no-op (same types), then the offset list should contain the
offsets for the other query.  But a) that might break general-purpose
higher-level code that expects a consistent behavior regardless of its input
entity types and b) that still doesn't address what happens when both
adjacency steps are not no-ops.

What is the expected behavior for higher-order elements?  Do we return only
the corner vertices or all nodes?  If it is the former, then we could drop
the offset list entirely, as it is implied by the entity type.  Or if we
retain it then it should be the offsets for the first level of adjacencies
because the second level is specified only by the type (no option to specify
by topology) and therefore the offset amount is constant for most entity
types (everything except poly(hedr|g)on.)

- jason