[Dune] New subentity numbering

[Sven Marnach]

Hi,

yesterday, Peter, Christian, Oliver and me discussed a bit about the
new subentity numbering.

I spent several days "renumbering" the dune-pdelab code.  After
tedious renaming and some tricky debugging, the code works again --
and does the same as before.  I did not really get the feeling of
having achieved anything -- the code just does the same as before.

This raises the question: What is the use of the renumbering after
all, especially from a DUNE user's point of view?  If we release the
next version of DUNE, we must tell the users that they have to put a
serious amount of time and energy into making their code do the same
as before, without any discernible advantage.  Hmm.

We ourselves already spent quite some time for this transition, but
there is still a lot of code out there which is not ported to the new
numbering, and we did not release a DUNE version with the new
numbering.  Things are not beyond remedy up to now.

Is it really impossible to rewrite the generic geometry stuff in a way
that it preserves the old numbering, at least for simplices and cubes?
The cubes were generated generically before, so this should still be
possible.  And I don't see any reason why it should not be possible
for the simplices.  Prisms and pyramids would probably still need
renumbering, but they are rarely used anyway.  And the effort needed
to adapt the generic geometry implementation is almost certainly less
than the effort needed to port the remaining code.  (Of course we
should have done this right from the start.  It would have saved me
renumbering PDElab.  Well, we didn't.)

There are other problems about the transition.  The documenatation is
really incomplete.  Just an example from the documentation of the
Mapper class:

template<int cc>
int map (const typename G::Traits::template Codim<0>::Entity &e, int i) const
    Map subentity i of codim cc of a codim 0 entity to array index.

int map (const typename G::Traits::template Codim<0>::Entity &e, int i, unsigned int codim) const
    Map subentity i of codim cc of a codim 0 entity to array index.

Not a single word about the differences, nor about which is the old
and which is the new method, and that it is dangerous to mix the use
of old and new methods.  Furthermore, 95 % of the code in
grid/genericgeometry is without any documentation (not even
comments!).  Even parts of the code that are meant to be directly used
by DUNE users are lacking any documentation (for example
GenericReferenceElements).  And finally, the transition page itself is
all but complete (for example, no word about the orientation changes
of subentities).

To be clear about this:  I really like that we have generic geometries
now -- they facilitate new grid implementations and reduce code
duplication.  But I can't see any advantages of the new numbering, and
I would like to have documentation for the generic geometry code.

Greetings from Heidelberg,
    Sven