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
/**
- * 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ö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
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
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örfler marking,
/**
- * 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
* $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]
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,
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,