Debian Codegraph @

include/deal.II/hp/refinement.h

raw
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