From: Wolfgang Bangerth Date: Tue, 11 Jul 2017 21:22:22 +0000 (-0600) Subject: Clarify that namespace GridRefinement is about *marking*, not *refinement*. X-Git-Tag: v9.0.0-rc1~1426^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0f7fbb47b53743b7042c9cf0609da3c51f473189;p=dealii.git Clarify that namespace GridRefinement is about *marking*, not *refinement*. --- diff --git a/include/deal.II/distributed/grid_refinement.h b/include/deal.II/distributed/grid_refinement.h index e090a18c48..31fd44ed0a 100644 --- a/include/deal.II/distributed/grid_refinement.h +++ b/include/deal.II/distributed/grid_refinement.h @@ -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 refine the triangulation, but only + * mark cells for refinement or coarsening. 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 diff --git a/include/deal.II/grid/grid_refinement.h b/include/deal.II/grid/grid_refinement.h index a55e9fc77e..d88942358c 100644 --- a/include/deal.II/grid/grid_refinement.h +++ b/include/deal.II/grid/grid_refinement.h @@ -29,15 +29,19 @@ template 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 refine the triangulation, but only + * mark cells for refinement or coarsening. 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 @@ -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::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 bulk criterion or Dö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,