[petsc-users] orientation semantics for DMPlex

[Geoffrey Irving]

On Fri, Nov 22, 2013 at 3:08 AM, Matthew Knepley <knepley at gmail.com> wrote:
> On Thu, Nov 21, 2013 at 8:12 PM, Geoffrey Irving <irving at naml.us> wrote:
>>
>> What are the orientation semantics of DMPlex?  I figured if I listed
>> the edges of each triangle in counterclockwise order it would come out
>> right, but it appears to be right for some triangles and wrong for
>> others.  Do I always have to call DMPlexSetConeOrientation?
>>
>> Unfortunately, I haven't yet grasped the documentation for
>> DMPlexSetConeOrientation.
>
> This is because I have kept changing my mind. There is the way it is, and
> the way I want it to be now. So, the way it is:
>
>   All cone arrows have an orientation attached. This indicates the order in
> which the _next_ cone (of that cone point) should be read out. The order
> is cyclic. A positive integer p means "start from vertex p instead of 0". A
> negative integer q means "start from -(q+1) and go backward".

Can't the order only be meaningfully described as cyclic only if the
child element has dimension 2 (triangles) where the element boundary
is topologically S^1?  A cyclic order doesn't make any sense for
tetrahedra (boundary S^2) or for segments (S^1), both of which have
trivial fundamental group.  If I have a triangle (0 1 2) pointing to
child segment (0 1), wouldn't orientation values 0 and -1 refer to the
same traversal?

Since only one bit is ideally conveyed here, namely the sign of the
permutation required to reorient the child to match the parent, would
it be better to have orientations be PetscBool?  Is it too late for
that kind of API change?

> The important thing to remember here is that this is ordering only the cone
> points, and is composed with higher level ordering when reading out the
> full closure is 3D. I have considered changing the semantics for negative
> values to start at -(coneSize-q+1) since then negation does what you think
> it should (go backwards from the guy just before), but then all the routines
> needs to know the coneSize which is not great.
>
> The reason that your example does not work is that triangles on opposite sides
> of an edge must have the opposite orientation for that edge. For example, an
> edge e = {v0, v1} lies between two triangles. Now the cone of e will always come
> out {v0, v1}. In triangle 0 that is fine, but in triangle 1 it needs to be {v1, v0} if all
> triangles are oriented counter-clockwise, so we need orientation -2 for that edge
> in the cone of triangle 1.

Thanks, I should be good to go.  It might be useful to have a
consistency checking routine for users to run to make sure their
custom created DMPlex is valid.

Geoffrey