| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2019 - 2025 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_hp_refinement_h |
| 16 |
#define dealii_hp_refinement_h |
| 17 |
|
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/base/std_cxx20/type_traits.h> |
| 22 |
#include <deal.II/base/template_constraints.h> |
| 23 |
|
| 24 |
#include <cmath> |
| 25 |
#include <functional> |
| 26 |
#include <vector> |
| 27 |
|
| 28 |
DEAL_II_NAMESPACE_OPEN |
| 29 |
|
| 30 |
|
| 31 |
// forward declarations |
| 32 |
#ifndef DOXYGEN |
| 33 |
template <typename Number> |
| 34 |
class Vector; |
| 35 |
|
| 36 |
template <int dim, int spacedim> |
| 37 |
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>)) |
| 38 |
class DoFHandler; |
| 39 |
#endif |
| 40 |
|
| 41 |
|
| 42 |
namespace hp |
| 43 |
{ |
| 44 |
/** |
| 45 |
* We supply adaptive methods to align computational resources with the |
| 46 |
* complexity of the numerical solution. Error estimates are an appropriate |
| 47 |
* means of determining where adjustments need to be made. |
| 48 |
* |
| 49 |
* However with hp-adaptivity, we have two ways to realize these adjustments: |
| 50 |
* For irregular solutions, h-adaptive methods which dynamically assign cell |
| 51 |
* sizes tend to reduce the approximation error, while for smooth solutions |
| 52 |
* p-adaptive methods are better suited in which function spaces will be |
| 53 |
* selected dynamically. This namespace collects tools to decide which type |
| 54 |
* of adaptive methods to apply. |
| 55 |
* |
| 56 |
* @note A formal description of the algorithms provided in this namespace |
| 57 |
* can be found in @cite fehling2020 . See in particular Section 3.2. |
| 58 |
* |
| 59 |
* <h3>Usage</h3> |
| 60 |
* |
| 61 |
* To successfully apply hp-adaptive methods, we recommend the following |
| 62 |
* workflow: |
| 63 |
* <ol> |
| 64 |
* <li> A suitable error estimate is the basis for any kind of adaptive method. |
| 65 |
* Similar to pure grid refinement, we will determine error estimates in the |
| 66 |
* usual way (i.e. KellyErrorEstimator) and mark cells for refinement or |
| 67 |
* coarsening (i.e. GridRefinement). |
| 68 |
* |
| 69 |
* Calling Triangulation::execute_coarsening_and_refinement() at this stage |
| 70 |
* will perform pure grid refinement as expected. |
| 71 |
* |
| 72 |
* <li> Once all refinement and coarsening flags have been distributed on the |
| 73 |
* mesh, we may determine if those qualify for p-adaptive methods. |
| 74 |
* Corresponding functions will set @p future_fe_indices on top of the |
| 75 |
* refinement and coarsening flags if they fulfil a certain criterion. |
| 76 |
* |
| 77 |
* In case of refinement, the superordinate element of the underlying |
| 78 |
* hp::FECollection will be assigned as the future finite element. |
| 79 |
* Correspondingly, the subordinate element will be selected for coarsening. |
| 80 |
* |
| 81 |
* Triangulation::execute_coarsening_and_refinement() will now supply both |
| 82 |
* h- and p-adaptive methods independently. |
| 83 |
* |
| 84 |
* <li> Right now, there may be cells scheduled for both h- and p-adaptation. |
| 85 |
* If we do not want to impose both methods at once, we need to decide which |
| 86 |
* one to pick for each cell individually and unambiguously. Since grid |
| 87 |
* refinement will be imposed by default and we only determine qualification |
| 88 |
* for p-adaptivity on top, we will always decide in favour of p-adaptive |
| 89 |
* methods. |
| 90 |
* |
| 91 |
* Calling Triangulation::execute_coarsening_and_refinement() will now perform |
| 92 |
* either h- or p-adaptive methods uniquely on each cell. |
| 93 |
* |
| 94 |
* <li> Up to this point, each cell knows its destiny in terms of adaptivity. |
| 95 |
* We can now move on to prepare all data structures to be transferred across |
| 96 |
* mesh changes. Previously set refinement and coarsening flags as well as |
| 97 |
* @p future_fe_indices will be used to update the data accordingly. |
| 98 |
* </ol> |
| 99 |
* |
| 100 |
* As an example, a realization of pure p-adaptive methods would look like the |
| 101 |
* following: |
| 102 |
* @code |
| 103 |
* // step 1: flag cells for refinement or coarsening |
| 104 |
* Vector<float> estimated_error_per_cell (triangulation.n_active_cells()); |
| 105 |
* KellyErrorEstimator<dim>::estimate( |
| 106 |
* hp_dof_handler, |
| 107 |
* QGauss<dim-1> (quadrature_points), |
| 108 |
* std::map<types::boundary_id, const Function<dim, Number> *>(), |
| 109 |
* solution, |
| 110 |
* estimated_error_per_cell); |
| 111 |
* GridRefinement::refine_and_coarsen_fixed_fraction(triangulation, |
| 112 |
* estimated_error_per_cell, |
| 113 |
* top_fraction, |
| 114 |
* bottom_fraction); |
| 115 |
* |
| 116 |
* // step 2: set future finite element indices on flagged cells |
| 117 |
* hp::Refinement::full_p_adaptivity(hp_dof_handler); |
| 118 |
* |
| 119 |
* // step 3: decide whether h- or p-adaptive methods will be supplied |
| 120 |
* hp::Refinement::force_p_over_h(hp_dof_handler); |
| 121 |
* |
| 122 |
* // step 4: prepare solutions to be transferred |
| 123 |
* ... |
| 124 |
* |
| 125 |
* triangulation.execute_coarsening_and_refinement(); |
| 126 |
* @endcode |
| 127 |
* |
| 128 |
* @ingroup hp |
| 129 |
*/ |
| 130 |
namespace Refinement |
| 131 |
{ |
| 132 |
/** |
| 133 |
* An alias that defines the characteristics of a function that can be used |
| 134 |
* as a comparison criterion for deciding whether to perform h- or |
| 135 |
* p-adaptation. |
| 136 |
* |
| 137 |
* Such functions take two numbers as arguments: The first one corresponds |
| 138 |
* to the provided criterion, while the other one conforms to the reference. |
| 139 |
* The result of the comparison will be returned as a boolean. |
| 140 |
*/ |
| 141 |
template <typename Number> |
| 142 |
using ComparisonFunction = |
| 143 |
std::function<bool(const Number &, const Number &)>; |
| 144 |
|
| 145 |
/** |
| 146 |
* @name Setting p-adaptivity flags |
| 147 |
* @{ |
| 148 |
*/ |
| 149 |
|
| 150 |
/** |
| 151 |
* Each cell flagged for h-refinement will also be flagged for p-refinement. |
| 152 |
* The same applies to coarsening. |
| 153 |
* |
| 154 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 155 |
* hp::Refinement::limit_p_level_difference() may change |
| 156 |
* refine and coarsen flags as well as future finite element indices. |
| 157 |
* Avoid calling them before this particular function. |
| 158 |
*/ |
| 159 |
template <int dim, int spacedim> |
| 160 |
void |
| 161 |
full_p_adaptivity(const DoFHandler<dim, spacedim> &dof_handler); |
| 162 |
|
| 163 |
/** |
| 164 |
* Adapt which finite element to use on cells that have been specifically |
| 165 |
* flagged for p-adaptation via the parameter @p p_flags. Future finite |
| 166 |
* elements will only be assigned if cells have been flagged for refinement |
| 167 |
* and coarsening beforehand. |
| 168 |
* |
| 169 |
* Each entry of the parameter @p p_flags needs to correspond to an active |
| 170 |
* cell. |
| 171 |
* |
| 172 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 173 |
* hp::Refinement::limit_p_level_difference() may change |
| 174 |
* refine and coarsen flags as well as future finite element indices. |
| 175 |
* Avoid calling them before this particular function. |
| 176 |
*/ |
| 177 |
template <int dim, int spacedim> |
| 178 |
void |
| 179 |
p_adaptivity_from_flags(const DoFHandler<dim, spacedim> &dof_handler, |
| 180 |
const std::vector<bool> &p_flags); |
| 181 |
|
| 182 |
/** |
| 183 |
* Adapt which finite element to use on cells whose criteria meet a certain |
| 184 |
* absolute threshold. |
| 185 |
* |
| 186 |
* For p-refinement and p-coarsening, two separate thresholds need to |
| 187 |
* provided via parameters @p p_refine_threshold and @p p_coarsen_threshold. |
| 188 |
* |
| 189 |
* We consider a cell for p-adaptivity if it is currently flagged for |
| 190 |
* refinement or coarsening and its criterion successfully compares to the |
| 191 |
* corresponding threshold. Let us be more specific on the default case: We |
| 192 |
* consider a cell for p-refinement if it is flagged for refinement and its |
| 193 |
* criterion is larger than or equal to the corresponding threshold. The |
| 194 |
* same applies for p-coarsening, but the cell's criterion must be lower |
| 195 |
* than or equal to the threshold. However, different compare function |
| 196 |
* objects can be supplied via the parameters @p compare_refine and |
| 197 |
* @p compare_coarsen to impose different decision strategies. |
| 198 |
* |
| 199 |
* Each entry of the parameter @p criteria needs to correspond to an active |
| 200 |
* cell. |
| 201 |
* |
| 202 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 203 |
* hp::Refinement::limit_p_level_difference() may change |
| 204 |
* refine and coarsen flags as well as future finite element indices. |
| 205 |
* Avoid calling them before this particular function. |
| 206 |
*/ |
| 207 |
template <int dim, typename Number, int spacedim> |
| 208 |
void |
| 209 |
p_adaptivity_from_absolute_threshold( |
| 210 |
const DoFHandler<dim, spacedim> &dof_handler, |
| 211 |
const Vector<Number> &criteria, |
| 212 |
const Number p_refine_threshold, |
| 213 |
const Number p_coarsen_threshold, |
| 214 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 215 |
&compare_refine = std::greater_equal<Number>(), |
| 216 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 217 |
&compare_coarsen = std::less_equal<Number>()); |
| 218 |
|
| 219 |
/** |
| 220 |
* Adapt which finite element to use on cells whose criteria meet a certain |
| 221 |
* threshold relative to the overall range of criterion values. |
| 222 |
* |
| 223 |
* The threshold will be determined for refined and coarsened cells |
| 224 |
* separately based on the currently set refinement markers. For each class |
| 225 |
* of cells, we determine the maximal and minimal values of all criteria and |
| 226 |
* determine the threshold by linear interpolation between these limits. |
| 227 |
* Parameters @p p_refine_fraction and @p p_refine_coarsen are used as |
| 228 |
* interpolation factors, where `0` corresponds to the minimal and `1` to |
| 229 |
* the maximal value. By default, mean values are considered as thresholds. |
| 230 |
* |
| 231 |
* We consider a cell for p-adaptivity if it is currently flagged for |
| 232 |
* refinement or coarsening and its criterion successfully compares to the |
| 233 |
* corresponding threshold. Let us be more specific on the default case: We |
| 234 |
* consider a cell for p-refinement if it is flagged for refinement and its |
| 235 |
* criterion is larger than or equal to the corresponding threshold. The |
| 236 |
* same applies for p-coarsening, but the cell's criterion must be lower |
| 237 |
* than or equal to the threshold. However, different compare function |
| 238 |
* objects can be supplied via the parameters @p compare_refine and |
| 239 |
* @p compare_coarsen to impose different decision strategies. |
| 240 |
* |
| 241 |
* Each entry of the parameter @p criteria needs to correspond to an active |
| 242 |
* cell. Parameters @p p_refine_fraction and @p p_coarsen_fraction need to be |
| 243 |
* in the interval $[0,1]$. |
| 244 |
* |
| 245 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 246 |
* hp::Refinement::limit_p_level_difference() may change |
| 247 |
* refine and coarsen flags as well as future finite element indices. |
| 248 |
* Avoid calling them before this particular function. |
| 249 |
*/ |
| 250 |
template <int dim, typename Number, int spacedim> |
| 251 |
void |
| 252 |
p_adaptivity_from_relative_threshold( |
| 253 |
const DoFHandler<dim, spacedim> &dof_handler, |
| 254 |
const Vector<Number> &criteria, |
| 255 |
const double p_refine_fraction = 0.5, |
| 256 |
const double p_coarsen_fraction = 0.5, |
| 257 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 258 |
&compare_refine = std::greater_equal<Number>(), |
| 259 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 260 |
&compare_coarsen = std::less_equal<Number>()); |
| 261 |
|
| 262 |
/** |
| 263 |
* Adapt which finite element to use on a given fraction of cells. |
| 264 |
* |
| 265 |
* Out of all cells flagged for a certain type of adaptation, be it |
| 266 |
* refinement or coarsening, we will determine a fixed number of cells among |
| 267 |
* this subset that will be flagged for the corresponding p-adaptive |
| 268 |
* variant. |
| 269 |
* |
| 270 |
* For each of both refinement and coarsening subsets, we will determine a |
| 271 |
* threshold based on the provided parameter @p criteria containing |
| 272 |
* indicators for every active cell. In the default case for refinement, all |
| 273 |
* cells with an indicator larger than or equal to the corresponding |
| 274 |
* threshold will be considered for p-refinement, while for coarsening all |
| 275 |
* cells with an indicator less than or equal to the matching threshold are |
| 276 |
* taken into account. However, different compare function objects can be |
| 277 |
* supplied via the parameters @p compare_refine and @p compare_coarsen to |
| 278 |
* impose different decision strategies. |
| 279 |
* |
| 280 |
* For refinement, the threshold will be associated with the cell that has |
| 281 |
* the @p p_refine_fraction times Triangulation::n_active_cells() largest |
| 282 |
* indicator, while it is the cell with the @p p_refine_coarsen times |
| 283 |
* Triangulation::n_active_cells() lowest indicator for coarsening. |
| 284 |
* |
| 285 |
* Each entry of the parameter @p criteria needs to correspond to an active |
| 286 |
* cell. Parameters @p p_refine_fraction and @p p_coarsen_fraction need to be |
| 287 |
* in the interval $[0,1]$. |
| 288 |
* |
| 289 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 290 |
* hp::Refinement::limit_p_level_difference() may change |
| 291 |
* refine and coarsen flags as well as future finite element indices. |
| 292 |
* Avoid calling them before this particular function. |
| 293 |
*/ |
| 294 |
template <int dim, typename Number, int spacedim> |
| 295 |
void |
| 296 |
p_adaptivity_fixed_number( |
| 297 |
const DoFHandler<dim, spacedim> &dof_handler, |
| 298 |
const Vector<Number> &criteria, |
| 299 |
const double p_refine_fraction = 0.5, |
| 300 |
const double p_coarsen_fraction = 0.5, |
| 301 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 302 |
&compare_refine = std::greater_equal<Number>(), |
| 303 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 304 |
&compare_coarsen = std::less_equal<Number>()); |
| 305 |
|
| 306 |
/** |
| 307 |
* Adapt which finite element to use on cells based on the regularity of the |
| 308 |
* (unknown) analytical solution. |
| 309 |
* |
| 310 |
* With an approximation of the local Sobolev regularity index $k_K$, |
| 311 |
* we may assess to which finite element space our local solution on cell |
| 312 |
* $K$ belongs. Since the regularity index is only an estimate, we won't |
| 313 |
* use it to assign the finite element space directly, but rather consider |
| 314 |
* it as an indicator for adaptation. If a cell is flagged for refinement, |
| 315 |
* we will perform p-refinement once it satisfies |
| 316 |
* $k_K > p_{K,\text{super}}$, where $p_{K,\text{super}}$ is |
| 317 |
* the polynomial degree of the finite element superordinate to the |
| 318 |
* currently active element on cell $K$. In case of coarsening, the |
| 319 |
* criterion $k_K < p_{K,\text{sub}}$ has to be met, with |
| 320 |
* $p_{K,\text{sub}}$ the degree of the subordinate element. |
| 321 |
* |
| 322 |
* Each entry of the parameter @p sobolev_indices needs to correspond |
| 323 |
* to an active cell. |
| 324 |
* |
| 325 |
* For more theoretical details see @cite ainsworth1998hp . |
| 326 |
* |
| 327 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 328 |
* hp::Refinement::limit_p_level_difference() may change |
| 329 |
* refine and coarsen flags as well as future finite element indices. |
| 330 |
* Avoid calling them before this particular function. |
| 331 |
*/ |
| 332 |
template <int dim, typename Number, int spacedim> |
| 333 |
void |
| 334 |
p_adaptivity_from_regularity(const DoFHandler<dim, spacedim> &dof_handler, |
| 335 |
const Vector<Number> &sobolev_indices); |
| 336 |
|
| 337 |
/** |
| 338 |
* Adapt which finite element to use on each cell based on how its criterion |
| 339 |
* relates to a reference. |
| 340 |
* |
| 341 |
* We consider a cell for p-adaptivity if it is currently flagged for |
| 342 |
* refinement or coarsening and its criterion successfully compares to the |
| 343 |
* corresponding reference. Other than functions |
| 344 |
* p_adaptivity_from_absolute_threshold() and |
| 345 |
* p_adaptivity_from_relative_threshold(), compare function objects have to |
| 346 |
* be provided explicitly via the parameters @p compare_refine and |
| 347 |
* @p compare_coarsen. |
| 348 |
* |
| 349 |
* Each entry of the parameters @p criteria and @p references needs to |
| 350 |
* correspond to an active cell. |
| 351 |
* |
| 352 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 353 |
* hp::Refinement::limit_p_level_difference() may change |
| 354 |
* refine and coarsen flags as well as future finite element indices. |
| 355 |
* Avoid calling them before this particular function. |
| 356 |
*/ |
| 357 |
template <int dim, typename Number, int spacedim> |
| 358 |
void |
| 359 |
p_adaptivity_from_reference( |
| 360 |
const DoFHandler<dim, spacedim> &dof_handler, |
| 361 |
const Vector<Number> &criteria, |
| 362 |
const Vector<Number> &references, |
| 363 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 364 |
&compare_refine, |
| 365 |
const ComparisonFunction<std_cxx20::type_identity_t<Number>> |
| 366 |
&compare_coarsen); |
| 367 |
|
| 368 |
/** |
| 369 |
* @} |
| 370 |
*/ |
| 371 |
|
| 372 |
/** |
| 373 |
* @name Error prediction |
| 374 |
* @{ |
| 375 |
*/ |
| 376 |
|
| 377 |
/** |
| 378 |
* Predict how the current @p error_indicators will adapt after refinement |
| 379 |
* and coarsening were to happen on the provided @p dof_handler, and write its |
| 380 |
* results to @p predicted_errors. Each entry of @p error_indicators and |
| 381 |
* @p predicted_errors corresponds to an active cell on the underlying |
| 382 |
* Triangulation, thus each container has to be of size |
| 383 |
* Triangulation::n_active_cells(). The errors are interpreted to be |
| 384 |
* measured in the energy norm; this assumption enters the rate of |
| 385 |
* convergence that is used in the prediction. The $l_2$-norm of the output |
| 386 |
* argument @p predicted_errors corresponds to the predicted global error |
| 387 |
* after adaptation. |
| 388 |
* |
| 389 |
* For p-adaptation, the local error is expected to converge exponentially |
| 390 |
* with the polynomial degree of the assigned finite element. Each increase |
| 391 |
* or decrease of the degree will thus change its value by a user-defined |
| 392 |
* control parameter @p gamma_p. |
| 393 |
* |
| 394 |
* For h-adaptation, we expect the local error $\eta_K$ on cell $K$ to be |
| 395 |
* proportional to $(h_K)^{p_K}$ in the energy norm, where $h_K$ denotes the |
| 396 |
* cell diameter and $p_K$ the polynomial degree of the currently assigned |
| 397 |
* finite element on cell $K$. |
| 398 |
* |
| 399 |
* During h-coarsening, the finite elements on siblings may be |
| 400 |
* different, and their parent cell will be assigned to their least |
| 401 |
* dominating finite element that belongs to its most general child. Thus, |
| 402 |
* we will always interpolate on an enclosing finite element space. |
| 403 |
* Additionally assuming that the finite elements on the cells to be |
| 404 |
* coarsened are sufficient to represent the solution correctly (e.g. at |
| 405 |
* least quadratic basis functions for a quadratic solution), we are |
| 406 |
* confident to say that the error will not change by sole interpolation on |
| 407 |
* the larger finite element space. |
| 408 |
* |
| 409 |
* For p-adaptation, the local error is expected to converge exponentially |
| 410 |
* with the polynomial degree of the assigned finite element. Each increase |
| 411 |
* or decrease of the degree will thus change its value by a user-defined |
| 412 |
* control parameter @p gamma_p. The assumption of exponential convergence |
| 413 |
* is only valid if both h- and p-adaptive methods are combined in a sense |
| 414 |
* that they are both utilized throughout a mesh, but do not have to be |
| 415 |
* applied both on a cell simultaneously. |
| 416 |
* |
| 417 |
* The prediction algorithm is formulated as follows with control parameters |
| 418 |
* @p gamma_p, @p gamma_h and @p gamma_n that may be used to influence |
| 419 |
* prediction for each adaptation type individually. The results for each |
| 420 |
* individual cell are stored in the @p predicted_errors output argument. |
| 421 |
* <table> |
| 422 |
* <tr><th>Adaptation type <th colspan="2">Prediction formula |
| 423 |
* <tr><td>no adaptation |
| 424 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 425 |
* \gamma_\text{n}$ |
| 426 |
* <td>$\gamma_\text{n} \in (0,\infty)$ |
| 427 |
* <tr><td>p-adaptation |
| 428 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 429 |
* \gamma_\text{p}^{(p_{K,\text{future}} - p_K)}$ |
| 430 |
* <td>$\gamma_\text{p} \in (0,1)$ |
| 431 |
* <tr><td>hp-refinement |
| 432 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 433 |
* \gamma_\text{h} \, 0.5^{p_{K,\text{future}}} \, |
| 434 |
* \gamma_\text{p}^{(p_{K,\text{future}} - p_{K})}$ |
| 435 |
* <td rowspan="2">$\gamma_\text{h} \in (0,\infty)$ |
| 436 |
* <tr><td>hp-coarsening |
| 437 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 438 |
* (\gamma_\text{h} \, 0.5^{p_{K,\text{future}}})^{-1} \, |
| 439 |
* \gamma_\text{p}^{(p_{K,\text{future}} - p_{K})}$ |
| 440 |
* </table> |
| 441 |
* |
| 442 |
* On basis of the refinement history, we use the predicted error estimates |
| 443 |
* to decide how cells will be adapted in the next adaptation step. |
| 444 |
* Comparing the predicted error from the previous adaptation step to the |
| 445 |
* error estimates of the current step allows us to justify whether our |
| 446 |
* previous choice of adaptation was justified, and lets us decide how to |
| 447 |
* adapt in the next one. |
| 448 |
* |
| 449 |
* We thus have to transfer the predicted error from the old to the adapted |
| 450 |
* mesh. When transferring the predicted error to the adapted mesh, make |
| 451 |
* sure to configure your CellDataTransfer object with |
| 452 |
* AdaptationStrategies::Refinement::l2_norm() as a refinement strategy and |
| 453 |
* AdaptationStrategies::Coarsening::l2_norm() as a coarsening strategy. |
| 454 |
* This ensures that the $l_2$-norm of the predict errors is preserved on |
| 455 |
* both meshes. |
| 456 |
* |
| 457 |
* In this context, we assume that the local error on a cell to be h-refined |
| 458 |
* will be divided equally on all of its $n_{K_c}$ children, whereas local |
| 459 |
* errors on siblings will be summed up on the parent cell in case of |
| 460 |
* h-coarsening. This assumption is often not satisfied in practice: For |
| 461 |
* example, if a cell is at a corner singularity, then the one child cell |
| 462 |
* that ends up closest to the singularity will inherit the majority of the |
| 463 |
* remaining error -- but this function can not know where the singularity |
| 464 |
* will be, and consequently assumes equal distribution. |
| 465 |
* |
| 466 |
* Incorporating the transfer from the old to the adapted mesh, the complete |
| 467 |
* error prediction algorithm reads as follows: |
| 468 |
* <table> |
| 469 |
* <tr><th>Adaptation type <th colspan="2">Prediction formula |
| 470 |
* <tr><td>no adaptation |
| 471 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 472 |
* \gamma_\text{n}$ |
| 473 |
* <td>$\gamma_\text{n} \in (0,\infty)$ |
| 474 |
* <tr><td>p-adaptation |
| 475 |
* <td>$\eta_{K,\text{pred}} = \eta_{K} \, |
| 476 |
* \gamma_\text{p}^{(p_{K,\text{future}} - p_K)}$ |
| 477 |
* <td>$\gamma_\text{p} \in (0,1)$ |
| 478 |
* <tr><td>hp-refinement |
| 479 |
* <td>$\left( \eta_{K_c,\text{pred}} \right)^2 = n_{K_c}^{-1} |
| 480 |
* \left( \eta_{K_p} \, |
| 481 |
* \gamma_\text{h} \, 0.5^{p_{K_c,\text{future}}} \, |
| 482 |
* \gamma_\text{p}^{(p_{K_c,\text{future}} - p_{K_p})} \right)^2 |
| 483 |
* \quad \forall K_c \text{ children of } K_p$ |
| 484 |
* <td rowspan="2">$\gamma_\text{h} \in (0,\infty)$ |
| 485 |
* <tr><td>hp-coarsening |
| 486 |
* <td>$\left( \eta_{K_p,\text{pred}} \right)^2 = \sum\limits_{K_c} |
| 487 |
* \left( \eta_{K_c} \, |
| 488 |
* (\gamma_\text{h} \, 0.5^{p_{K_p,\text{future}}})^{-1} \, |
| 489 |
* \gamma_\text{p}^{(p_{K_p,\text{future}} - p_{K_c})} \right)^2 |
| 490 |
* \quad \forall K_c \text{ children of } K_p$ |
| 491 |
* </table> |
| 492 |
* |
| 493 |
* With these predicted error estimates, we are capable of adapting the |
| 494 |
* finite element on cells based on their refinement history or rather the |
| 495 |
* predicted change of their error estimates. |
| 496 |
* |
| 497 |
* If a cell is flagged for adaptation, we want to perform p-adaptation once |
| 498 |
* the associated error indicators $\eta_{K}$ on cell $K$ satisfy |
| 499 |
* $\eta_{K} < \eta_{K,\text{pred}}$, where the subscript $\text{pred}$ |
| 500 |
* denotes the predicted error. This corresponds to our assumption of |
| 501 |
* smoothness being correct, else h-adaptation is applied. We achieve this |
| 502 |
* with the function hp::Refinement::p_adaptivity_from_reference() and a |
| 503 |
* function object `std::less<Number>()` for both comparator parameters. |
| 504 |
* |
| 505 |
* Also with an alternative strategy, we can determine the fractions of |
| 506 |
* cells to be h- and p-adapted among all cells to be adapted. For this, use |
| 507 |
* hp::Refinement::p_adaptivity_fixed_number() with criteria |
| 508 |
* $(\eta_{K,\text{pred}} - \eta_{K})$. |
| 509 |
* |
| 510 |
* For the very first adaptation step in either case, the user needs to |
| 511 |
* decide whether h- or p-adaptation is supposed to happen. An h-step will |
| 512 |
* be applied with $\eta_{K,\text{pred}} = 0$, whereas |
| 513 |
* $\eta_{K,\text{pred}} = \infty$ ensures a p-step. The latter may be |
| 514 |
* realized with `std::numeric_limits::infinity()`. |
| 515 |
* |
| 516 |
* The following code snippet demonstrates how to impose hp-adaptivity based |
| 517 |
* on refinement history in an application: |
| 518 |
* @code |
| 519 |
* // [initialization...] |
| 520 |
* Vector<float> predicted_error_per_cell(triangulation.n_active_cells()); |
| 521 |
* for(unsigned int i = 0; i < triangulation.n_active_cells(); ++i) |
| 522 |
* predicted_error_per_cell[i] = std::numeric_limits<float>::infinity(); |
| 523 |
* |
| 524 |
* // [during each refinement step...] |
| 525 |
* // set h-adaptivity flags |
| 526 |
* Vector<float> estimated_error_per_cell(triangulation.n_active_cells()); |
| 527 |
* KellyErrorEstimator::estimate(...); |
| 528 |
* GridRefinemet::refine_and_coarsen_fixed_{number|fraction}(...); |
| 529 |
* |
| 530 |
* // set p-adaptivity flags |
| 531 |
* hp::Refinement::p_adaptivity_from_reference( |
| 532 |
* hp_dof_handler, |
| 533 |
* estimated_error_per_cell, |
| 534 |
* predicted_error_per_cell, |
| 535 |
* std::less<float>(), |
| 536 |
* std::less<float>()); |
| 537 |
* hp::Refinement::{choose|force}_p_over_h(hp_dof_handler); |
| 538 |
* |
| 539 |
* // predict error for the subsequent adaptation |
| 540 |
* triangulation.prepare_coarsening_and_refinement(); |
| 541 |
* hp::Refinement::predict_error( |
| 542 |
* hp_dof_handler, |
| 543 |
* estimated_error_per_cell, |
| 544 |
* predicted_error_per_cell); |
| 545 |
* |
| 546 |
* // perform adaptation |
| 547 |
* CellDataTransfer<dim, spacedim, Vector<float>> cell_data_transfer( |
| 548 |
* triangulation, |
| 549 |
* &AdaptationStrategies::Refinement::l2_norm<dim, spacedim, float>, |
| 550 |
* &AdaptationStrategies::Coarsening::l2_norm<dim, spacedim, float>); |
| 551 |
* cell_data_transfer.prepare_coarsening_and_refinement(); |
| 552 |
* |
| 553 |
* triangulation.execute_coarsening_and_refinement(); |
| 554 |
* |
| 555 |
* Vector<float> transferred_errors(triangulation.n_active_cells()); |
| 556 |
* cell_data_transfer.unpack(predicted_error_per_cell, transferred_errors); |
| 557 |
* predicted_error_per_cell = std::move(transferred_errors); |
| 558 |
* @endcode |
| 559 |
* |
| 560 |
* For more theoretical details see @cite melenk2001hp , where the default |
| 561 |
* parameters for this function come from as well, i.e. |
| 562 |
* $\gamma_\text{p}^2 = 0.4$, $\gamma_\text{h}^2 = 4$, |
| 563 |
* $\gamma_\text{n}^2 = 1$. |
| 564 |
* |
| 565 |
* If you are working with parallel::distributed::Triangulation objects, you |
| 566 |
* need to pay special attention. Here, p4est determines the details of grid |
| 567 |
* refinement, and consequently, it yields more reliable and trustworthy |
| 568 |
* results when we determine the predicted errors during the adaptation |
| 569 |
* process. We can do exactly this by attaching this function to the signal |
| 570 |
* Triangulation::Signals::post_p4est_refinement, which is triggered after |
| 571 |
* p4est got refined, but before data is prepared for transfer. Refinement |
| 572 |
* and coarsening flags of the Triangulation object need to be matched with |
| 573 |
* the already refined p4est oracle using |
| 574 |
* parallel::distributed::TemporarilyMatchRefineFlags. Thus, a construct |
| 575 |
* like the following is necessary to correctly predict errors in parallel |
| 576 |
* distributed applications. |
| 577 |
* @code |
| 578 |
* Vector<float> predicted_errors; |
| 579 |
* triangulation.signals.post_p4est_refinement.connect([&]() { |
| 580 |
* const parallel::distributed::TemporarilyMatchRefineFlags<dim> |
| 581 |
* refine_modifier(triangulation); |
| 582 |
* predicted_errors.reinit(triangulation.n_active_cells()); |
| 583 |
* hp::Refinement::predict_error(dof_handler, |
| 584 |
* error_indicators, |
| 585 |
* predicted_errors); |
| 586 |
* }); |
| 587 |
* @endcode |
| 588 |
* The container <code>predicted_errors</code> then needs to follow the |
| 589 |
* usual parallel::distributed::CellDataTransfer workflow. |
| 590 |
* |
| 591 |
* @note We want to predict the error by how adaptation will actually happen. |
| 592 |
* Thus, this function needs to be called after |
| 593 |
* Triangulation::prepare_coarsening_and_refinement() and |
| 594 |
* hp::Refinement::limit_p_level_difference(). |
| 595 |
*/ |
| 596 |
template <int dim, typename Number, int spacedim> |
| 597 |
void |
| 598 |
predict_error(const DoFHandler<dim, spacedim> &dof_handler, |
| 599 |
const Vector<Number> &error_indicators, |
| 600 |
Vector<Number> &predicted_errors, |
| 601 |
const double gamma_p = std::sqrt(0.4), |
| 602 |
const double gamma_h = 2., |
| 603 |
const double gamma_n = 1.); |
| 604 |
|
| 605 |
/** |
| 606 |
* @} |
| 607 |
*/ |
| 608 |
|
| 609 |
/** |
| 610 |
* @name Decide between h- and p-adaptivity |
| 611 |
* @{ |
| 612 |
*/ |
| 613 |
|
| 614 |
/** |
| 615 |
* Choose p-adaptivity over h-adaptivity in any case. |
| 616 |
* |
| 617 |
* Removes all refine and coarsen flags on cells that have a |
| 618 |
* @p future_fe_index assigned. |
| 619 |
* |
| 620 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 621 |
* hp::Refinement::limit_p_level_difference() may change |
| 622 |
* refine and coarsen flags as well as future finite element indices. |
| 623 |
* Avoid calling them before this particular function. |
| 624 |
*/ |
| 625 |
template <int dim, int spacedim> |
| 626 |
void |
| 627 |
force_p_over_h(const DoFHandler<dim, spacedim> &dof_handler); |
| 628 |
|
| 629 |
/** |
| 630 |
* Choose p-adaptivity over h-adaptivity whenever it is invoked on all |
| 631 |
* related cells. |
| 632 |
* |
| 633 |
* In case of refinement, information about finite elements will be |
| 634 |
* inherited. Thus we will prefer p-refinement over h-refinement whenever |
| 635 |
* desired, i.e. clear the refine flag and supply a corresponding |
| 636 |
* @p future_fe_index. |
| 637 |
* |
| 638 |
* However for coarsening, we follow a different approach. Flagging a cell |
| 639 |
* for h-coarsening does not ultimately mean that it will be coarsened. Only |
| 640 |
* if a cell and all of its siblings are flagged, they will be merged into |
| 641 |
* their parent cell. If we consider p-coarsening on top, we must decide for |
| 642 |
* all siblings together how they will be coarsened. We distinguish between |
| 643 |
* three different cases: |
| 644 |
* <ol> |
| 645 |
* <li> Not all siblings flagged for coarsening: p-coarsening. |
| 646 |
* <br> |
| 647 |
* We keep the @p future_fe_indices and clear the coarsen flags |
| 648 |
* on all siblings. |
| 649 |
* <li> All siblings flagged for coarsening, but not all for |
| 650 |
* p-adaptation: h-coarsening. |
| 651 |
* <br> |
| 652 |
* We keep the coarsen flags and clear all @p future_fe_indices |
| 653 |
* on all siblings. |
| 654 |
* <li> All siblings flagged for coarsening and p-adaptation: p-coarsening. |
| 655 |
* <br> |
| 656 |
* We keep the @p future_fe_indices and clear the coarsen flags |
| 657 |
* on all siblings. |
| 658 |
* </ol> |
| 659 |
* |
| 660 |
* @note The function Triangulation::prepare_coarsening_and_refinement() |
| 661 |
* will clean up all h-coarsening flags if they are not shared among |
| 662 |
* all siblings. In the hp-case, we need to bring forward this decision: |
| 663 |
* If the cell will not be coarsened, but qualifies for p-adaptivity, |
| 664 |
* we have to set all flags accordingly. So this function anticipates |
| 665 |
* the decision that Triangulation::prepare_coarsening_and_refinement() |
| 666 |
* would have made later on. |
| 667 |
* |
| 668 |
* @note Triangulation::prepare_coarsening_and_refinement() and |
| 669 |
* hp::Refinement::limit_p_level_difference() may change |
| 670 |
* refine and coarsen flags as well as future finite element indices. |
| 671 |
* Avoid calling them before this particular function. |
| 672 |
*/ |
| 673 |
template <int dim, int spacedim> |
| 674 |
void |
| 675 |
choose_p_over_h(const DoFHandler<dim, spacedim> &dof_handler); |
| 676 |
|
| 677 |
/** |
| 678 |
* @} |
| 679 |
*/ |
| 680 |
|
| 681 |
/** |
| 682 |
* @name Optimize p-level distribution |
| 683 |
* @{ |
| 684 |
*/ |
| 685 |
|
| 686 |
/** |
| 687 |
* Limit p-level differences between neighboring cells. |
| 688 |
* |
| 689 |
* Essentially does to future FE indices what |
| 690 |
* Triangulation::prepare_coarsening_and_refinement() does to refinement |
| 691 |
* flags. |
| 692 |
* |
| 693 |
* In detail, this function limits the level difference of neighboring cells |
| 694 |
* and thus smooths the overall function space. Future FE indices will be |
| 695 |
* raised (and never lowered) so that the level difference to neighboring |
| 696 |
* cells is never larger than @p max_difference. |
| 697 |
* |
| 698 |
* Multiple FE hierarchies might have been registered via |
| 699 |
* hp::FECollection::set_hierarchy(). This function operates on only one |
| 700 |
* hierarchy, namely the one that contains the FE index @p contains_fe_index. |
| 701 |
* Cells with future FE indices that are not part of the corresponding |
| 702 |
* hierarchy will be ignored. |
| 703 |
* |
| 704 |
* The function can optionally be called before performing adaptation with |
| 705 |
* Triangulation::execute_coarsening_and_refinement(). It is not necessary |
| 706 |
* to call this function, nor will it be automatically invoked in any part |
| 707 |
* of the library (contrary to its Triangulation counterpart). |
| 708 |
* |
| 709 |
* On cells that will be h-coarsened, we enforce the difference criterion as |
| 710 |
* if it is already a parent cell. That means, we set the level of all |
| 711 |
* siblings to the highest one among them. In that case, all sibling cells |
| 712 |
* need to have the h-coarsening flags set terminally via |
| 713 |
* Triangulation::prepare_coarsening_and_refinement() beforehand. Otherwise |
| 714 |
* an assertion will be triggered. |
| 715 |
* |
| 716 |
* Returns whether any future FE indices have been changed by this function. |
| 717 |
*/ |
| 718 |
template <int dim, int spacedim> |
| 719 |
bool |
| 720 |
limit_p_level_difference(const DoFHandler<dim, spacedim> &dof_handler, |
| 721 |
const unsigned int max_difference = 1, |
| 722 |
const unsigned int contains_fe_index = 0); |
| 723 |
|
| 724 |
/** |
| 725 |
* @} |
| 726 |
*/ |
| 727 |
} // namespace Refinement |
| 728 |
} // namespace hp |
| 729 |
|
| 730 |
|
| 731 |
DEAL_II_NAMESPACE_CLOSE |
| 732 |
|
| 733 |
#endif // dealii_hp_refinement_h |