From 7eb557c47f4e30fca963529a03c8241b7beb476c Mon Sep 17 00:00:00 2001 From: Marc Fehling Date: Mon, 29 Jul 2019 22:13:11 -0600 Subject: [PATCH] Doc: Reviewed documentation for hp::Refinement. --- include/deal.II/hp/refinement.h | 94 +++++++++++++++++---------------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/include/deal.II/hp/refinement.h b/include/deal.II/hp/refinement.h index 68217654db..3f9893906a 100644 --- a/include/deal.II/hp/refinement.h +++ b/include/deal.II/hp/refinement.h @@ -40,16 +40,16 @@ namespace hp * complexity of the numerical solution. Error estimates are an appropriate * means of determining where adjustments need to be made. * - * However with hp adaptivity, we have two ways to realize these adjustments: - * For irregular solutions, h adaptive methods which dynamically assign cell - * sizes tend to reduce the approximation error, while for smooth solutions p - * adaptive methods are better suited in which function spaces will be + * However with hp-adaptivity, we have two ways to realize these adjustments: + * For irregular solutions, h-adaptive methods which dynamically assign cell + * sizes tend to reduce the approximation error, while for smooth solutions + * p-adaptive methods are better suited in which function spaces will be * selected dynamically. This namespace collects tools to decide which type * of adaptive methods to apply. * *

Usage

* - * To successfully apply hp adaptive methods, we recommend the following + * To successfully apply hp-adaptive methods, we recommend the following * workflow: *
    *
  1. A suitable error estimate is the basis for any kind of adaptive method. @@ -61,7 +61,7 @@ namespace hp * will perform pure grid refinement as expected. * *
  2. Once all refinement and coarsening flags have been distributed on the - * mesh, we may determine if those qualify for p adaptive methods. + * mesh, we may determine if those qualify for p-adaptive methods. * Corresponding functions will set @p future_fe_indices on top of the * refinement and coarsening flags if they fulfil a certain criterion. * @@ -69,26 +69,26 @@ namespace hp * hp::FECollection will be assigned as the future finite element. * Correspondingly, the subordinate element will be selected for coarsening. * - * Triangulation::execute_coarsening_and_refinement() will now supply both h - * and p adaptive methods independently. + * Triangulation::execute_coarsening_and_refinement() will now supply both + * h- and p-adaptive methods independently. * - *
  3. Right now, there may be cells scheduled for both h and p adaptation. + *
  4. Right now, there may be cells scheduled for both h- and p-adaptation. * If we do not want to impose both methods at once, we need to decide which * one to pick for each cell individually and unambiguously. Since grid * refinement will be imposed by default and we only determine qualification - * for p adaptivity on top, we will always decide in favour of p adaptive + * for p-adaptivity on top, we will always decide in favour of p-adaptive * methods. * * Calling Triangulation::execute_coarsening_and_refinement() will now perform - * either h or p adaptive methods uniquely on each cell. + * either h- or p-adaptive methods uniquely on each cell. * - *
  5. Up to this point, each cell knows its destiny in terms of adaptivity + *
  6. Up to this point, each cell knows its destiny in terms of adaptivity. * We can now move on to prepare all data structures to be transferred across * mesh changes. Previously set refinement and coarsening flags as well as * @p future_fe_indices will be used to update the data accordingly. *
* - * As an example, a realisation of pure p adaptive methods would look like the + * As an example, a realisation of pure p-adaptive methods would look like the * following: * @code * // step 1: flag cells for refinement or coarsening @@ -106,7 +106,7 @@ namespace hp * // step 2: set future finite element indices on flagged cells * hp::Refinement::full_p_adaptivity (hp_dof_handler); * - * // step 3: decide whether h or p adaptive methods will be supplied + * // step 3: decide whether h- or p-adaptive methods will be supplied * hp::Refinement::force_p_over_h (hp_dof_handler); * * // step 4: prepare solutions to be transferred @@ -121,12 +121,12 @@ namespace hp namespace Refinement { /** - * @name Setting p adaptivity flags + * @name Setting p-adaptivity flags * @{ */ /** - * Each cell flagged for h refinement will also be flagged for p refinement. + * Each cell flagged for h-refinement will also be flagged for p-refinement. * The same applies to coarsening. * * @note Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() @@ -139,7 +139,7 @@ namespace hp /** * Adapt the finite element on cells that have been specifically flagged for - * p adaptation via the parameter @p p_flags. Future finite elements will + * p-adaptation via the parameter @p p_flags. Future finite elements will * only be assigned if cells have been flagged for refinement and coarsening * beforehand. * @@ -167,9 +167,9 @@ namespace hp * factors, where `0` corresponds to the minimal and `1` to the maximal * value. By default, mean values are considered as thresholds. * - * We consider a cell for p refinement if it is flagged for refinement and + * We consider a cell for p-refinement if it is flagged for refinement and * its smoothness indicator is larger than the corresponding threshold. The - * same applies for p coarsening, but the cell's indicator must be lower + * same applies for p-coarsening, but the cell's indicator must be lower * than the threshold. * * Each entry of the parameter @p smoothness_indicators needs to correspond @@ -197,7 +197,7 @@ namespace hp * $K$ belongs. Since the regularity index is only an estimate, we won't * use it to assign the finite element space directly, but rather consider * it as an indicator for adaptation. If a cell is flagged for refinement, - * we will perform p refinement once it satisfies + * we will perform p-refinement once it satisfies * $k_K > p_{K,\text{super}}$, where $p_{K,\text{super}}$ is * the polynomial degree of the finite element superordinate to the * currently active element on cell $K$. In case of coarsening, the @@ -237,16 +237,17 @@ namespace hp * Adapt the finite element on cells based on their refinement history * or rather the predicted change of their error estimates. * - * If a cell is flagged for adaptation, we will perform p adaptation once - * the associated error indicators $\eta_{K}^2$ on cell $K$ satisfy - * $\eta_{K}^2 < \eta_{K,\text{pred}}^2$, where the subscript $\text{pred}$ + * If a cell is flagged for adaptation, we will perform p-adaptation once + * the associated error indicators $\eta_{K}$ on cell $K$ satisfy + * $\eta_{K} < \eta_{K,\text{pred}}$, where the subscript $\text{pred}$ * denotes the predicted error. This corresponds to our assumption of - * smoothness being correct, else h adaptation is supplied. + * smoothness being correct, else h-adaptation is supplied. * - * For the very first adapation step, the user needs to decide whether h or - * p adapatation is supposed to happen. An h-step will be applied with - * $\eta_{K,\text{pred} = 0$, whereas $\eta_{K,\text{pred} = \infty$ ensures - * a p-step. The latter may be realised with `std::numeric_limits::max()`. + * For the very first adaptation step, the user needs to decide whether h- + * or p-adaptation is supposed to happen. An h-step will be applied with + * $\eta_{K,\text{pred}} = 0$, whereas $\eta_{K,\text{pred}} = \infty$ + * ensures a p-step. The latter may be realised with + * `std::numeric_limits::max()`. * * Each entry of the parameter @p error_indicators and @p predicted_errors * needs to correspond to an active cell. @@ -295,7 +296,7 @@ namespace hp * Triangulation, thus each container has to be of size * Triangulation::n_active_cells(). * - * For h adaptation, we expect the local error $\eta_K$ on cell $K$ to be + * For h-adaptation, we expect the local error $\eta_K$ on cell $K$ to be * proportional to $(h_K)^{p_K}$ in the energy norm, where $h_K$ denotes the * cell diameter and $p_K$ the polynomial degree of the currently assigned * finite element. Here, we assume that the finite element will not change @@ -316,12 +317,13 @@ namespace hp * configure your CellDataTransfer object with * GridTools::CoarseningStrategies::sum() as a coarsening strategy. * - * For p adaptation, the local error is expected to converge exponentially + * For p-adaptation, the local error is expected to converge exponentially * with the polynomial degree of the assigned finite element. Each increase * or decrease of the degree will thus change its value by a user-defined * control parameter @p gamma_p. The assumption of exponential convergence - * is only valid if both h and p adaptive methods are combined. An exception - * is thrown if a cell is flagged for both h and p adaptation at once. + * is only valid if both h- and p-adaptive methods are combined. An + * exception is thrown if a cell is flagged for both h- and p-adaptation at + * once. * * The prediction algorithm is formulated as follows with control parameters * @p gamma_p, @p gamma_h and @p gamma_n that may be used to influence @@ -331,16 +333,16 @@ namespace hp * no adaptation * $\eta_{K,\text{pred}} = \eta_{K} \, \gamma_\text{n}$ * $\gamma_\text{n} \in (0,\infty)$ - * p adaptation + * p-adaptation * $\eta_{K,\text{pred}} = \eta_{K} \, * \gamma_\text{p}^{(p_{K,\text{future}} - p_K)}$ * $\gamma_\text{p} \in (0,1)$ - * h refinement + * h-refinement * $\eta_{K_c,\text{pred}} = \eta_{K} \, * \gamma_\text{h} \, 0.5^{p_K} \, 0.5^{\text{dim}} * \quad \forall K_c \text{ children of } K$ * $\gamma_\text{h} \in (0,\infty)$ - * h coarsening + * h-coarsening * $\eta_{K,\text{pred}} = \sum\limits_{K_c} \eta_{K_c} / * (\gamma_\text{h} \, 0.5^{p_{K_c}}) * \quad \forall K_c \text{ children of } K$ @@ -382,12 +384,12 @@ namespace hp */ /** - * @name Decide between h and p adaptivity + * @name Decide between h- and p-adaptivity * @{ */ /** - * Choose p adaptivity over h adaptivity in any case. + * Choose p-adaptivity over h-adaptivity in any case. * * Removes all refine and coarsen flags on cells that have a * @p future_fe_index assigned. @@ -401,37 +403,37 @@ namespace hp force_p_over_h(const hp::DoFHandler &dof_handler); /** - * Choose p adaptivity over h adaptivity whenever it is invoked on all + * Choose p-adaptivity over h-adaptivity whenever it is invoked on all * related cells. * * In case of refinement, information about finite elements will be - * inherited. Thus we will prefer p refinement over h refinement whenever + * inherited. Thus we will prefer p-refinement over h-refinement whenever * desired, i.e. clear the refine flag and supply a corresponding * @p future_fe_index. * * However for coarsening, we follow a different approach. Flagging a cell - * for h coarsening does not ultimately mean that it will be coarsened. Only + * for h-coarsening does not ultimately mean that it will be coarsened. Only * if a cell and all of its siblings are flagged, they will be merged into - * their parent cell. If we consider p coarsening on top, we must decide for + * their parent cell. If we consider p-coarsening on top, we must decide for * all siblings together how they will be coarsened. We distinguish between * three different cases: *
    - *
  1. Not all siblings flagged for coarsening: p coarsening
    + *
  2. Not all siblings flagged for coarsening: p-coarsening
    * We keep the @p future_fe_indices and clear the coarsen flags * on all siblings. *
  3. All siblings flagged for coarsening, but not all for - * p adaptation: h coarsening
    + * p-adaptation: h-coarsening
    * We keep the coarsen flags and clear all @p future_fe_indices * on all siblings. - *
  4. All siblings flagged for coarsening and p adaptation: p coarsening
    + *
  5. All siblings flagged for coarsening and p-adaptation: p-coarsening
    * We keep the @p future_fe_indices and clear the coarsen flags * on all siblings. *
* * @note The function Triangulation::prepare_coarsening_and_refinement() - * will clean up all h coarsening flags if they are not shared among + * will clean up all h-coarsening flags if they are not shared among * all siblings. In the hp case, we need to bring forward this decision: - * If the cell will not be coarsened, but qualifies for p adaptivity, + * If the cell will not be coarsened, but qualifies for p-adaptivity, * we have to set all flags accordingly. So this function anticipates * the decision that Triangulation::prepare_coarsening_and_refinement() * would have made later on. -- 2.39.5