[Dune] Changes during constification - Renaming?

[Thimo Neubauer]

Hi,

during the refactoring of Dune found some naming problems which we
would like to fix:

Traits -> codim or nothing

  Types reported by datastructures are currently in a "Traits"-struct,
  sometimes parametrized by the codimension. First of all the name is
  incorrect (normally used to map a type to something that expresses a
  feature of this type) and secondly it's unneeded in most
  datastructures. We clearly favour
  
    Entity::HierarchicIterator

  over

    Entity::Traits::HierarchicIterator

  There are some subtleties in the instantiation of the template
  classes which force us to offer a struct with the types sometimes
  (which I guess was the initial reason for the Traits-struct) but we
  think that we should hide those problems from the user.

  Additionally for the types depending on a codim the Trais can be
  renamed to codim which yields

    Grid::codim<0>::LevelIterator
  
  which is pretty nice :)

Element::mydimension

  There is a bit of confusion about weather template parameters are
  the dimension of the created object or the grid dimension. We
  renamed them a bit (especially in element) and created the enum
  "mydimension" so that it's perfectly clear that Element::dimension
  is the grid-dimension

IntersectionIterator::outer_normal

  currently there are the methods unit_outer_normal (quite clear) and
  outer_normal, which reports a normal vector scaled for easy
  integration. We changed this to 

    outer_normal               any normal the grid can report, length 
                               not known (e.g. if only direction of
                               flow needs to be checked)

    unit_outer_normal          normal scaled to length 1 (for flow value)

    integration_outer_normal   for integration, named after
                               "integration_element" 

Entity<0>::father_relative_local -> geometryInFather

   clearly tell that an Element is returned and that it reports the
   entities position inside the father

Entity<0>::hasChildren

   is only used for the LeafIterator, is it? A programmer could expect
   a method to travel to children when there are any. Therefore we
   propose to change

     Entity<0>::hasChildren  ->  isLeaf

   and invert the return value.

Entity<dim>::father and local

   The method names are a bit confusing: logically, one would
   interpret the grid-cell whose corner you are in as the father of
   the vertex. Instead, the method returns the father of the grid
   cell. We decided to put this into the method names by changing

      father   ->   ownersFather
      local    ->   positionInOwnersFather
 
   Granted, those names aren't perfect but at least it's quite clear
   what they return.

Last but not least we would like to rename the type "Element" to
"Geometry": this is what this type represents, it would be the logical
return value for methods like geometry() and talking about grid cells
aka grid elements gets to be less confusing :)

All substitutions but the last one are already used in our
"const-refactoring-1"-branch, you're invited to have a look :) 

We will show you the two major ways of visiting the other branch so
that you don't have to read the [CENSORED] CVS-docs:

Directly checking out the branch:

  cvs -d :ext:blah at hal...:/var/lib/cvs checkout -r const-refactoring-1 dune

Move a normal checkout to the branch:

  cvs update -r const-refactoring-1

Warning! cvs will try to preserve your local modifications during the
switch! You'll most probably get collisions when there are
non-committed changes!

Change a const-refactoring-1 to the normal branch:

  cvs update -A


That's it for now, we'll be happy to hear your opinions about the
proposed changes.

Cheers

   Christian & Thimo