]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Clarify that namespace GridRefinement is about *marking*, not *refinement*. 4602/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Tue, 11 Jul 2017 21:22:22 +0000 (15:22 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Wed, 12 Jul 2017 15:11:01 +0000 (09:11 -0600)
include/deal.II/distributed/grid_refinement.h
include/deal.II/grid/grid_refinement.h

index e090a18c48f783d470104ef5aeb4141e4433a264..31fd44ed0a3a1faf1f6083b72695ec74f13e06db 100644 (file)
@@ -31,10 +31,16 @@ namespace parallel
   namespace distributed
   {
     /**
-     * Collection of functions controlling refinement and coarsening of
-     * parallel::distributed::Triangulation objects. This namespace provides
-     * similar functionality to the dealii::GridRefinement namespace, except
-     * that it works for meshes that are parallel and distributed.
+     * This namespace provides a collection of functions that aid in refinement
+     * and coarsening of triangulations. Despite the name of the namespace, the
+     * functions do not actually <i>refine</i> the triangulation, but only
+     * <i>mark cells for refinement or coarsening</i>. In other words, they
+     * perform the "mark" part of the typical "solve-estimate-mark-refine"
+     * cycle of the adaptive finite element loop.
+     *
+     * In contrast to the functions in namespace dealii::GridRefinement,
+     * the functions in the current namespace are intended for distributed
+     * meshes, i.e., objects of type parallel::distributed::Triangulation.
      *
      * @ingroup grid
      * @author Wolfgang Bangerth, 2009
index a55e9fc77ec71b766c6671e1ef721ce43804444c..d88942358cf6c79ea76e4f04b4dba9718cc10b37 100644 (file)
@@ -29,15 +29,19 @@ template <int dim, int spacedim> class Triangulation;
 
 
 /**
- * Collection of functions controlling refinement and coarsening of
- * Triangulation objects.
+ * This namespace provides a collection of functions that aid in refinement
+ * and coarsening of triangulations. Despite the name of the namespace, the
+ * functions do not actually <i>refine</i> the triangulation, but only
+ * <i>mark cells for refinement or coarsening</i>. In other words, they
+ * perform the "mark" part of the typical "solve-estimate-mark-refine"
+ * cycle of the adaptive finite element loop.
  *
  * The functions in this namespace form two categories. There are the
  * auxiliary functions refine() and coarsen(). More important for users are
  * the other functions, which implement refinement strategies, as being found
  * in the literature on adaptive finite element methods. For mathematical
  * discussion of these methods, consider works by D&ouml;rfler, Morin,
- * Nochetto, Rannacher, Stevenson and many more.
+ * Nochetto, Rannacher, Stevenson, and others.
  *
  * @ingroup grid
  * @author Wolfgang Bangerth, Thomas Richter, Guido Kanschat 1998, 2000, 2009
@@ -83,7 +87,8 @@ namespace GridRefinement
                                              const double        bottom_fraction_of_cells);
 
   /**
-   * This function provides a refinement strategy with predictable growth in
+   * This function provides a strategy to mark cells for refinement and
+   * coarsening with the goal of providing predictable growth in
    * the size of the mesh by refining a given fraction of all cells.
    *
    * The function takes a vector of refinement @p criteria and two values
@@ -155,7 +160,8 @@ namespace GridRefinement
    const unsigned int          max_n_cells = std::numeric_limits<unsigned int>::max());
 
   /**
-   * This function provides a refinement strategy controlling the reduction of
+   * This function provides a strategy to mark cells for refinement and
+   * coarsening with the goal of controlling the reduction of
    * the error estimate.
    *
    * Also known as the <b>bulk criterion</b> or D&ouml;rfler marking,
@@ -221,7 +227,8 @@ namespace GridRefinement
 
 
   /**
-   * Refine the triangulation by flagging certain cells to reach a grid that
+   * This function flags cells of a triangulation for refinement with the
+   * aim to reach a grid that
    * is optimal with respect to an objective function that tries to balance
    * reducing the error and increasing the numerical cost when the mesh is
    * refined. Specifically, this function makes the assumption that if you
@@ -257,8 +264,8 @@ namespace GridRefinement
    * $m$ cells that will be refined. Note that $N(m)$ is an increasing
    * function of $m$ whereas $\eta^\text{exp}(m)$ is a decreasing function.
    *
-   * This function then tries to find that number $m$ of cells to refine for
-   * which the objective function
+   * This function then tries to find that number $m$ of cells to mark for
+   * refinement for which the objective function
    * @f[
    *   J(m) = N(m)^{\text{order}/d} \eta^\text{exp}(m)
    * @f]
@@ -299,7 +306,7 @@ namespace GridRefinement
                                const unsigned int          order=2);
 
   /**
-   * Flag all mesh cells for which the value in @p criteria exceeds @p
+   * Mark all mesh cells for which the value in @p criteria exceeds @p
    * threshold for refinement, but only flag up to @p max_to_mark cells.
    *
    * The vector @p criteria contains a nonnegative value for each active cell,
@@ -319,7 +326,7 @@ namespace GridRefinement
                const unsigned int          max_to_mark = numbers::invalid_unsigned_int);
 
   /**
-   * Flag all mesh cells for which the value in @p criteria is less than @p
+   * Mark all mesh cells for which the value in @p criteria is less than @p
    * threshold for coarsening.
    *
    * The vector @p criteria contains a nonnegative value for each active cell,

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.