Merge branch 'documentation/marking' into 'master'

Documentation/marking

I tried to come up with a description what the classes `ErrorFractionMarkingStrategy` and `FractionalMarkingStrategy` do and where the differences lie.

Additional changes might be: 
 - Rename the `fraction`(input) variable to e.g. `elementFraction` resp. `errorFraction` to distinguish the two functionalities.
 - Fix the difference in file name and class name (_Strategy_-suffix).

See merge request !8

dune/fufem/estimators/errorfractionmarking.hh

@@ -48,6 +48,15 @@ class ErrorFractionMarkingStrategy
                          GridType& grid,
                          double fraction);
 
+        /**
+         * \brief Sorts the errors associated to all subentities of all grids
+         * and marks all those elements (for refimenent) that have a subentity
+         * among the top percentage.
+         * \param refinementIndicator For each grid, the errors associated with
+         * its entities are provided here.
+         * \param fraction Specifies the fraction of the error to be taken into
+         * account for refinement.
+         */
         static void mark(const std::vector<RefinementIndicator<GridType>* >& refinementIndicator,
                          const std::vector<GridType*>& grids,
                          double fraction);
@@ -90,7 +99,7 @@ mark(const std::vector<RefinementIndicator<GridType>*>& refinementIndicators,
     std::vector<Dune::BitSetVector<1> > refineIndex(grids.size());
 
     // we need to sum the error indicators up
-    double sumGridErrorSquared = 0.0;
+    double totalError = 0.0;
 
     for (size_t i=0; i<grids.size(); ++i)
     {
@@ -109,7 +118,7 @@ mark(const std::vector<RefinementIndicator<GridType>*>& refinementIndicators,
             const Dune::ReferenceElement<double,dim>& refElement
                 = Dune::ReferenceElements<double, dim>::general(e.type());
 
-            // Compute the maximum indicator of any subentity of this element
+            // Compute the indicator of any subentity of this element
             for (int codim=0; codim<=dim; ++codim)
             {
                 for (int entity=0; entity<refElement.size(codim); ++entity)
@@ -119,7 +128,7 @@ mark(const std::vector<RefinementIndicator<GridType>*>& refinementIndicators,
                     {
                         // map error indicator values to entity index and sum them up
                         double errorIndicator = (*refinementIndicators[i]).value(e, codim, entity);
-                        sumGridErrorSquared += errorIndicator;
+                        totalError += errorIndicator;
                         errorMap.insert(std::pair<double, std::pair<int,int> >(errorIndicator, std::pair<int,int>(i, entityIndex)));
                         entityProcessed[entityIndex][0] = true;
                     }
@@ -138,7 +147,7 @@ mark(const std::vector<RefinementIndicator<GridType>*>& refinementIndicators,
         {
             refineIndex[e.second.first][e.second.second][0] = true;
             refinedError += e.first;
-            if (refinedError >= sumGridErrorSquared*fraction)
+            if (refinedError >= totalError*fraction)
               break;
         }
     }
@@ -153,7 +162,7 @@ mark(const std::vector<RefinementIndicator<GridType>*>& refinementIndicators,
             const Dune::ReferenceElement<double,dim>& refElement
                 = Dune::ReferenceElements<double, dim>::general(e.type());
 
-            // Compute the maximum indicator of any subentity of this element
+            // Determine if the element is marked to refinement by any of its subentities
             bool refineElement = false;
             for (int codim=0; (codim<=dim) and not(refineElement); ++codim)
             {

dune/fufem/estimators/fractionalmarking.hh

@@ -15,6 +15,7 @@
 
 #include <dune/fufem/estimators/refinementindicator.hh>
 
+//! \brief See static method @mark for details.
 template <class GridType, class field_type = double>
 class FractionalMarkingStrategy
 {
@@ -40,6 +41,17 @@ public:
                      const std::vector<GridType*>& grids,
                      field_type fraction);
 
+    /**
+     * \brief Sorts the elements of all grids according to the maximal error
+     * associated with any of its subentities and marks the top percentage of
+     * those (for refinement).
+     * \param refinementIndicator For each grid, the errors associated with its
+     * entities are provided here.
+     * \param fraction Specifies the total number of elements to be refined in
+     * terms of percentage/100 of all elements of all grids.
+     */
+    // TODO: IMHO the implementation does not provide a mechanism that prevents
+    // refining elements where all associated errors are zero.
     static void mark(const std::vector<std::shared_ptr<RefinementIndicator<GridType> > >& refinementIndicator,
                      const std::vector<GridType*>& grids,
                      field_type fraction);