Reference documentation for deal.II version Git f982bbb689 2019-09-17 15:49:08 -0400
hp::Refinement Namespace Reference

## Functions

template<int dim, int spacedim>
void full_p_adaptivity (const hp::DoFHandler< dim, spacedim > &dof_handler)

template<int dim, int spacedim>
void p_adaptivity_from_flags (const hp::DoFHandler< dim, spacedim > &dof_handler, const std::vector< bool > &p_flags)

template<int dim, typename Number , int spacedim>
void p_adaptivity_from_threshold (const hp::DoFHandler< dim, spacedim > &dof_handler, const Vector< Number > &smoothness_indicators, const double p_refine_fraction=0.5, const double p_coarsen_fraction=0.5)

template<int dim, typename Number , int spacedim>
void p_adaptivity_from_regularity (const hp::DoFHandler< dim, spacedim > &dof_handler, const Vector< Number > &sobolev_indices)

template<int dim, typename Number , int spacedim>
void p_adaptivity_from_prediction (const hp::DoFHandler< dim, spacedim > &dof_handler, const Vector< Number > &error_indicators, const Vector< Number > &predicted_errors)

Error prediction
template<int dim, typename Number , int spacedim>
void predict_error (const hp::DoFHandler< dim, spacedim > &dof_handler, const Vector< Number > &error_indicators, Vector< Number > &predicted_errors, const double gamma_p=std::sqrt(0.1), const double gamma_h=1., const double gamma_n=1.)

Decide between h- and p-adaptivity
template<int dim, int spacedim>
void force_p_over_h (const hp::DoFHandler< dim, spacedim > &dof_handler)

template<int dim, int spacedim>
void choose_p_over_h (const hp::DoFHandler< dim, spacedim > &dof_handler)

## Detailed Description

We supply adaptive methods to align computational ressources with the 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 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 workflow:

1. A suitable error estimate is the basis for any kind of adaptive method. Similar to pure grid refinement, we will determine error estimates in the usual way (i.e. KellyErrorEstimator) and mark cells for refinement or coarsening (i.e. GridRefinement).

Calling Triangulation::execute_coarsening_and_refinement() at this stage 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. Corresponding functions will set future_fe_indices on top of the refinement and coarsening flags if they fulfil a certain criterion.

In case of refinement, the superordinate element of the underlying 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.

3. 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 methods.

Calling Triangulation::execute_coarsening_and_refinement() will now perform either h- or p-adaptive methods uniquely on each cell.

4. 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 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 following:

// step 1: flag cells for refinement or coarsening
Vector<float> estimated_error_per_cell (triangulation.n_active_cells());
solution,
estimated_error_per_cell);
estimated_error_per_cell,
top_fraction,
bottom_fraction);
// step 2: set future finite element indices on flagged cells
// step 3: decide whether h- or p-adaptive methods will be supplied
// step 4: prepare solutions to be transferred
...
triangulation.execute_coarsening_and_refinement();

## Function Documentation

template<int dim, int spacedim>
 void hp::Refinement::full_p_adaptivity ( const hp::DoFHandler< dim, spacedim > & dof_handler )

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() may change refine and coarsen flags, which will ultimately change the results of this function.

Setting p adaptivity flags

Definition at line 39 of file refinement.cc.

template<int dim, int spacedim>
 void hp::Refinement::p_adaptivity_from_flags ( const hp::DoFHandler< dim, spacedim > & dof_handler, const std::vector< bool > & p_flags )

Adapt the finite element on cells that have been specifically flagged for p-adaptation via the parameter p_flags. Future finite elements will only be assigned if cells have been flagged for refinement and coarsening beforehand.

Each entry of the parameter p_flags needs to correspond to an active cell.

Note
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Definition at line 51 of file refinement.cc.

template<int dim, typename Number , int spacedim>
 void hp::Refinement::p_adaptivity_from_threshold ( const hp::DoFHandler< dim, spacedim > & dof_handler, const Vector< Number > & smoothness_indicators, const double p_refine_fraction = 0.5, const double p_coarsen_fraction = 0.5 )

Adapt the finite element on cells whose smoothness indicators meet a certain threshold.

The threshold will be chosen for refined and coarsened cells individually. For each class of cells, we determine the maximal and minimal values of the smoothness indicators and determine the threshold by linear interpolation between these limits. Parameters p_refine_fraction and p_refine_coarsen are used as interpolation 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 its smoothness indicator is larger than the corresponding threshold. The same applies for p-coarsening, but the cell's indicator must be lower than the threshold.

Each entry of the parameter smoothness_indicators needs to correspond to an active cell. Parameters p_refine_fraction and p_coarsen_fraction need to be in the interval $$[0,1]$$.

Note
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Definition at line 87 of file refinement.cc.

template<int dim, typename Number , int spacedim>
 void hp::Refinement::p_adaptivity_from_regularity ( const hp::DoFHandler< dim, spacedim > & dof_handler, const Vector< Number > & sobolev_indices )

Adapt the finite element on cells based on the regularity of the (unknown) analytical solution.

With an approximation of the local Sobolev regularity index $$k_K$$, we may assess to which finite element space our local solution on cell $$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 $$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 criterion $$k_K < p_{K,\text{sub}}$$ has to be met, with $$p_{K,\text{sub}}$$ the degree of the subordinate element.

Each entry of the parameter sobolev_indices needs to correspond to an active cell.

For more theoretical details see

@article{Houston2005,
author = {Houston, Paul and S{\"u}li, Endre},
title = {A note on the design of hp-adaptive finite element
methods for elliptic partial differential equations},
journal = {{Computer Methods in Applied Mechanics and Engineering}},
volume = {194},
number = {2},
pages = {229--243},
publisher = {Elsevier},
year = {2005},
doi = {10.1016/j.cma.2004.04.009}
}
Note
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Definition at line 187 of file refinement.cc.

template<int dim, typename Number , int spacedim>
 void hp::Refinement::p_adaptivity_from_prediction ( const hp::DoFHandler< dim, spacedim > & dof_handler, const Vector< Number > & error_indicators, const Vector< Number > & predicted_errors )

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}$$ 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.

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 error_indicators and predicted_errors needs to correspond to an active cell.

For more theoretical details see

@article{Melenk2001,
author = {Melenk, Jens Markus and Wohlmuth, Barbara I.},
title = {{On residual-based a posteriori error estimation
in hp-FEM}},
journal = {{Advances in Computational Mathematics}},
volume = {15},
number = {1},
pages = {311--331},
publisher = {Springer US},
year = {2001},
doi = {10.1023/A:1014268310921}
}
Note
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Definition at line 238 of file refinement.cc.

## ◆ predict_error()

template<int dim, typename Number , int spacedim>
 void hp::Refinement::predict_error ( const hp::DoFHandler< dim, spacedim > & dof_handler, const Vector< Number > & error_indicators, Vector< Number > & predicted_errors, const double gamma_p = std::sqrt(0.1), const double gamma_h = 1., const double gamma_n = 1. )

Predict how the current error_indicators will adapt after refinement and coarsening has happened on the provided dof_handler, and write its results to predicted_errors. Each entry of error_indicators and predicted_errors corresponds to an active cell on the underlying Triangulation, thus each container has to be of size Triangulation::n_active_cells(). The errors are interpreted to be measured in the energy norm; this assumption enters the rate of convergence that is used in the prediction. The predicted_errors output argument has one entry per current cell, with the $$2^d$$ values for each cell that will be coarsened away equal, and with the value stored on a cell to be refined interpreted as applying to each of the future children.

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 on cell $$K$$. Here, we assume that the finite element will not change in the adaptation process so that $$p_K = \text{const}$$. However during coarsening, the finite elements on siblings may be different, and their parent cell will be assigned to their least dominating finite element that belongs to its most general child. Thus, we will always interpolate on an enclosing finite element space. Additionaly assuming that the finite elements on the cells to be coarsened are sufficient to represent the solution correctly (e.g. at least quadratic basis functions for a quadratic solution), we are confident to say that the error will not change by sole interpolation on the larger finite element space.

Further, the function assumes that the local error on a cell that will be refined, will lead to errors on the $$2^{dim}$$ children that are all equal, whereas local errors on siblings will be summed up on the parent cell in case of coarsening. This assumption is often not satisfied in practice: For example, if a cell is at a corner singularity, then the one child cell that ends up closest to the singularity will inherit the majority of the remaining error – but this function can not know where the singularity will be, and consequently assumes equal distribution.

When transferring the predicted error to the coarsened mesh, make sure to configure your CellDataTransfer object with CoarseningStrategies::sum() as a coarsening strategy.

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 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.

The prediction algorithm is formulated as follows with control parameters gamma_p, gamma_h and gamma_n that may be used to influence prediction for each adaptation type individually.

Adaptation type Prediction formula
no adaptation $$\eta_{K,\text{pred}} = \eta_{K} \, \gamma_\text{n}$$ $$\gamma_\text{n} \in (0,\infty)$$
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 $$\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 $$\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$$

For more theoretical details see

@article{Melenk2001,
author = {Melenk, Jens Markus and Wohlmuth, Barbara I.},
title = {{On residual-based a posteriori error estimation
in hp-FEM}},
journal = {{Advances in Computational Mathematics}},
volume = {15},
number = {1},
pages = {311--331},
publisher = {Springer US},
year = {2001},
doi = {10.1023/A:1014268310921}
}
Note
This feature is currently only implemented for isotropic refinement.
We want to predict the error by how adaptation will actually happen. Thus, this function needs to be called after Triangulation::prepare_for_coarsening_and_refinement().

Error prediction

Definition at line 268 of file refinement.cc.

## ◆ force_p_over_h()

template<int dim, int spacedim>
 void hp::Refinement::force_p_over_h ( const hp::DoFHandler< dim, spacedim > & dof_handler )

Choose p-adaptivity over h-adaptivity in any case.

Removes all refine and coarsen flags on cells that have a future_fe_index assigned.

Note
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Decide between h and p adaptivity

Definition at line 337 of file refinement.cc.

## ◆ choose_p_over_h()

template<int dim, int spacedim>
 void hp::Refinement::choose_p_over_h ( const hp::DoFHandler< dim, spacedim > & dof_handler )

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 desired, i.e. clear the refine flag and supply a corresponding 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 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 all siblings together how they will be coarsened. We distinguish between three different cases:

1. Not all siblings flagged for coarsening: p-coarsening
We keep the future_fe_indices and clear the coarsen flags on all siblings.
2. All siblings flagged for coarsening, but not all for p-adaptation: h-coarsening
We keep the coarsen flags and clear all future_fe_indices on all siblings.
3. All siblings flagged for coarsening and p-adaptation: p-coarsening
We keep the 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 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, we have to set all flags accordingly. So this function anticipates the decision that Triangulation::prepare_coarsening_and_refinement() would have made later on.
Preceeding calls of Triangulation::prepare_for_coarsening_and_refinement() may change refine and coarsen flags, which will ultimately change the results of this function.

Definition at line 351 of file refinement.cc.