Debian Codegraph @

include/deal.II/numerics/error_estimator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2024 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_error_estimator_h
16 #define dealii_error_estimator_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/function.h>
23
24 #include <deal.II/fe/component_mask.h>
25
26 #include <deal.II/lac/read_vector.h>
27
28 #include <map>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declarations
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
36 class DoFHandler;
37 template <int, int>
38 class Mapping;
39 template <int>
40 class Quadrature;
41
42 namespace hp
43 {
44 template <int>
45 class QCollection;
46
47 template <int, int>
48 class MappingCollection;
49 } // namespace hp
50 #endif
51
52
53 /**
54 * Implementation of the error indicator by Kelly, De S. R. Gago, Zienkiewicz
55 * and Babuska (see @cite KGZB83) and its modification for the hp-FEM. This
56 * error indicator tries to approximate the error per cell by integration of the
57 * jump of the gradient of the solution along the faces of each cell. It can be
58 * understood as a gradient recovery estimator; see the survey of Ainsworth
59 * and Oden, "A Posteriori Error Estimation in Finite Element Analysis"
60 * (Wiley, 2000) for a complete discussion.
61 *
62 * In the original Kelly error estimator, the contribution of each face to the
63 * cell error is scaled with the cell diagonal. In the modified version,
64 * however, we employ a scaling factor which depends on the face diagonal and
65 * polynomial degrees of the adjacent elements. The choice between the two is
66 * done by means of the enumerator, defined within the class.
67 *
68 * @note In spite of the name, Kelly estimator is not truly an a posteriori
69 * error estimator, even if applied to the Poisson problem only. It gives good
70 * hints for mesh refinement, but the estimate is not to be trusted. For
71 * higher order trial spaces the integrals computed here tend to zero faster
72 * than the error itself, thus ruling out the values as error estimators.
73 * However, the modified version discussed below can be utilised to obtain the
74 * reliable error estimator by adding the residual (volume) part.
75 *
76 * The error estimator really only estimates the error for the generalized
77 * Poisson equation $-\nabla\cdot a(x) \nabla u = f$ with either Dirichlet
78 * boundary conditions or generalized Neumann boundary conditions involving
79 * the conormal derivative $a\frac{du}{dn} = g$.
80 *
81 * The error estimator returns a vector of estimated errors per cell which can
82 * be used to feed the GridRefinement::refine_and_coarsen_fixed_fraction(),
83 * GridRefinement::refine_and_coarsen_fixed_number(), and similar functions.
84 * This vector contains elements of data type @p float, rather than @p double,
85 * since accuracy is not important in the current context.
86 *
87 *
88 * <h3>Implementation</h3>
89 *
90 * In principle, the implementation of the error estimation is simple: let
91 * @f[
92 * \eta_K^2
93 * =
94 * \sum_{F\in\partial K}
95 * c_F \int_{\partial K_F} \jump{a \frac{\partial u_h}{\partial n}}^2
96 * @f]
97 * be the error estimator for cell $K$. $\jump{\cdot}$ denotes the jump of the
98 * function in square brackets at the face, and $c_F$ is a factor discussed
99 * below. This is the general form of the interface terms of the error
100 * estimator derived by Kelly et al. in the paper referenced above. The overall
101 * error estimate is then computed as
102 * @f[
103 * \eta^2 = \sum_K \eta_K^2
104 * @f]
105 * so that $\eta \approx \|\nabla (u-u_h)\|$ for the Laplace equation. The
106 * functions of this class compute a vector of values that corresponds to
107 * $\eta_K$ (i.e., the square root of the quantity above).
108 *
109 * In the paper of Ainsworth $ c_F=\frac {h_K}{24} $, but this factor is a bit
110 * esoteric, stemming from interpolation estimates and stability constants which
111 * may hold for the Poisson problem, but may not hold for more general
112 * situations. Alternatively, we consider the case when $c_F=\frac {h_F}{2p_F}$,
113 * where $h_F$ is the diameter of the face and $p_F=max(p^+,p^-)$ is the maximum
114 * polynomial degree of adjacent elements; or $c_F=h_K$. The choice between
115 * these factors is done by means of the enumerator, provided as the last
116 * argument in all functions.
117 *
118 * To perform the integration, use is made of the FEFaceValues and
119 * FESubfaceValues classes. The integration is performed by looping over all
120 * cells and integrating over faces that are not yet treated. This way we
121 * avoid integration on faces twice, once for each time we visit one of the
122 * adjacent cells. In a second loop over all cells, we sum up the
123 * contributions of the faces (which are the integrated square of the jumps
124 * times some factor) of each cell and take the square root.
125 *
126 * The integration is done using a quadrature formula on the face
127 * provided by the caller of the estimate() functions declared by this
128 * class. For linear trial functions (FE_Q(1)), QGauss with two points
129 * or even the QMidpoint rule might actually suffice. For higher order
130 * elements, it is necessary to utilize higher order quadrature
131 * formulae with `fe.degree+1` Gauss points.
132 *
133 * We store the contribution of each face in a @p map, as provided by the C++
134 * standard library, with the iterator pointing to that face being the key
135 * into the map. When looping the second time over all cells, we have to sum
136 * up the contributions of the faces and take the square root. For the Kelly
137 * estimator, the multiplication with $\frac {h_K}{24}$ is done in the second
138 * loop. By doing so we avoid problems to decide with which $h_K$ to multiply,
139 * that of the cell on the one or that of the cell on the other side of the
140 * face. Whereas for the hp-estimator the @p map stores integrals multiplied
141 * by $\frac {h_F}{2p_F}$, which are then summed in the second loop.
142 *
143 * $h_K$ ($h_F$) is taken to be the greatest length of the diagonals of the cell
144 * (face). For more or less uniform cells (faces) without deformed angles,
145 * this coincides with the diameter of the cell (face).
146 *
147 *
148 * <h3>Vector-valued functions</h3>
149 *
150 * If the finite element field for which the error is to be estimated is
151 * vector-valued, i.e. the finite element has more than one component, then
152 * all the above can be applied to all or only some components at the same
153 * time. The main function of this class takes a list of flags denoting the
154 * components for which components the error estimator is to be applied; by
155 * default, it is a list of only @p trues, meaning that all variables shall be
156 * treated.
157 *
158 * In case the different components of a field have different physical meaning
159 * (for example velocity and pressure in the Stokes equations), it would be
160 * senseless to use the same coefficient for all components. In that case, you
161 * can pass a function with as many components as there are components in the
162 * finite element field and each component of the error estimator will then be
163 * weighted by the respective component in this coefficient function. In the
164 * other case, when all components have the same meaning (for example the
165 * displacements in Lam&eacute;'s equations of elasticity), you can specify a
166 * scalar coefficient which will then be used for all components.
167 *
168 *
169 * <h3>Boundary values</h3>
170 *
171 * If the face is at the boundary, i.e. there is no neighboring cell to which
172 * the jump in the gradient could be computed, there are two possibilities:
173 * <ul>
174 * <li> The face belongs to a Dirichlet boundary. Then the face is not
175 * considered, which can be justified looking at a dual problem technique and
176 * should hold exactly if the boundary can be approximated exactly by the
177 * finite element used (i.e. it is a linear boundary for linear finite
178 * elements, quadratic for isoparametric quadratic elements, etc). For
179 * boundaries which can not be exactly approximated, one should consider the
180 * difference $z-z_h$ on the face, $z$ being a dual problem's solution which
181 * is zero at the true boundary and $z_h$ being an approximation, which in
182 * most cases will be zero on the numerical boundary. Since on the numerical
183 * boundary $z$ will not be zero in general, we would get another term here,
184 * but this one is neglected for practical reasons, in the hope that the error
185 * made here will tend to zero faster than the energy error we wish to
186 * estimate.
187 *
188 * Though no integration is necessary, in the list of face contributions we
189 * store a zero for this face, which makes summing up the contributions of the
190 * different faces to the cells easier.
191 *
192 * <li> The face belongs to a Neumann boundary. In this case, the
193 * contribution of the face $F\in\partial K$ looks like \f[ n_F\int_F
194 * \left|g-a\frac{\partial u_h}{\partial n}\right|^2 ds \f] where $g$ is the
195 * Neumann boundary function, $n_F=\frac {h_K}{24}$ and $n_F=\frac {h_F}{p}$ for
196 * the Kelly and hp-estimator, respectively. If the finite element is
197 * vector-valued, then obviously the function denoting the Neumann boundary
198 * conditions needs to be vector-valued as well.
199 *
200 * <li> No other boundary conditions are considered.
201 * </ul>
202 *
203 * In practice, if you have Robin boundary conditions or are too lazy to
204 * accurately describe Neumann values, then this is rarely an issue: if you
205 * don't say anything in the map about a particular part of the boundary then
206 * the Kelly indicator will simply assume that the solution is correct on that
207 * part of the boundary and not touch it. Of course, if you have a
208 * Neumann or Robin boundary, that isn't quite true, there is going to be a
209 * difference between the normal derivative of the numerical solution and the
210 * Neumann values these normal derivatives should equal. So if we simply
211 * ignore those parts of the boundary, we'll underestimate the error. In
212 * practice, this rarely appears to be a problem -- you may not refine the
213 * cell this time around but you'll probably refine it in the next refinement
214 * step and everything is good again. After all, for all problems but the
215 * Laplace equation, the Kelly indicator is only an indicator, not an
216 * estimator, and so the values it computes are not exact error
217 * representations anyway.
218 *
219 *
220 * <h3>Handling of hanging nodes</h3>
221 *
222 * The integration along faces with hanging nodes is quite tricky, since one
223 * of the elements has to be shifted one level up or down. See the
224 * documentation for the FESubFaceValues class for more information about
225 * technical issues regarding this topic.
226 *
227 * In practice, since we integrate over each face only once, we do this when we
228 * are on the coarser one of the two cells adjacent to a subface (a subface is
229 * defined to be the child of a face; seen from the coarse cell, it is a
230 * subface, while seen from the refined cell it is one of its faces). The
231 * reason is that finding neighborship information is a bit easier then, but
232 * that's all practical reasoning, nothing fundamental.
233 *
234 * Since we integrate from the coarse side of the face, we have the parent
235 * face readily at hand and store the result of the integration over that
236 * parent face (being the sum of the integrals along the subfaces) in the
237 * abovementioned map of integrals as well. This consumes some memory more
238 * than needed, but makes the summing up of the face contributions to the
239 * cells easier, since then we have the information from all faces of all
240 * cells at hand and need not think about explicitly determining whether a
241 * face was refined or not. The same applies for boundary faces, see above.
242 *
243 *
244 * <h3>Multiple solution vectors</h3>
245 *
246 * In some cases, one would like to
247 * compute the error estimates for several solution vectors on the same grid
248 * at once, with the same coefficients, boundary condition object, etc, for
249 * example for the solutions on several successive time steps. One could then
250 * call the functions of this class several times for each solution. However,
251 * the largest factor in the computation of the error estimates (in terms of
252 * computing time) is initialization of FEFaceValues and FESubFaceValues
253 * objects, and iterating through all faces and subfaces. If the solution
254 * vectors live on the same grid, this effort can be reduced significantly by
255 * treating all solution vectors at the same time, initializing the
256 * FEFaceValues objects only once per cell and for all solution vectors at
257 * once, and also only looping through the triangulation only once. For this
258 * reason, besides the @p estimate function in this class that takes a single
259 * input vector and returns a single output vector, there is also a function
260 * that accepts several in- and output vectors at the same time.
261 *
262 * @ingroup numerics
263 */
264 template <int dim, int spacedim = dim>
265 class KellyErrorEstimator
266 {
267 public:
268 /**
269 * The enum type given to the class functions to decide on the scaling
270 * factors of the face integrals.
271 */
272 enum Strategy
273 {
274 //! Kelly error estimator with the factor $\frac {h_K}{24}$.
275 cell_diameter_over_24 = 0,
276 //! the boundary residual estimator with the factor $\frac {h_F}{2
277 //! max(p^+,p^-)}$.
278 face_diameter_over_twice_max_degree,
279 //! Kelly error estimator with the factor $h_K$.
280 cell_diameter
281 };
282
283 /**
284 * Implementation of the error estimator described above. You may give a
285 * coefficient, but there is a default value which denotes the constant
286 * coefficient with value one. The coefficient function may either be a
287 * scalar one, in which case it is used for all components of the finite
288 * element, or a vector-valued one with as many components as there are in
289 * the finite element; in the latter case, each component is weighted by the
290 * respective component in the coefficient.
291 *
292 * You might give a list of components you want to evaluate, in case the
293 * finite element used by the DoFHandler object is vector-valued. You then
294 * have to set those entries to true in the bit-vector @p component_mask
295 * (see
296 * @ref GlossComponentMask
297 * ) for which the respective component is to be used in the error
298 * estimator. The default is to use all components, which is done by either
299 * providing a bit-vector with all-set entries, or an empty bit-vector.
300 *
301 * The @p subdomain_id parameter indicates whether we shall compute
302 * indicators for all cells (in case its value is the default,
303 * <tt>numbers::invalid_unsigned_int</tt>), or only for the cells belonging
304 * to a certain subdomain with the given indicator. The latter case is used
305 * for parallel computations where all processor nodes have the global grid
306 * stored, and could well compute all the indicators for all cells
307 * themselves, but where it is more efficient to have each process compute
308 * only indicators for the cells it owns, and have them exchange the
309 * resulting information afterwards. This is in particular true for the case
310 * where meshes are very large and computing indicators for @em every cell
311 * is too expensive, while computing indicators for only local cells is
312 * acceptable. Note that if you only ask for the indicators of a certain
313 * subdomain to be computed, you must nevertheless make sure that this
314 * function has access to the correct node values of @em all degrees of
315 * freedom. This is since the function needs to access DoF values on
316 * neighboring cells as well, even if they belong to a different subdomain.
317 *
318 * The @p material_id parameter has a similar meaning: if not set to its
319 * default value (which is numbers::invalid_material_id), it means that
320 * indicators will only be computed for cells with this particular material
321 * id.
322 *
323 * The @p n_threads parameter used to indicate the number of threads to be
324 * used to compute the error estimator. This parameter is now ignored, with
325 * the number of threads determined automatically. The parameter is retained
326 * for compatibility with old versions of the library.
327 *
328 * The @p strategy parameter is used to choose the scaling factor for the
329 * integral over cell's faces.
330 *
331 * @note If the DoFHandler object given as an argument to this function
332 * builds on a parallel::distributed::Triangulation, this function skips
333 * computations on all cells that are not locally owned. In that case, the
334 * only valid value for the subdomain_id argument (besides the invalid
335 * value) is the subdomain id that is associated with the currently
336 * processor, as reported by
337 * parallel::distributed::Triangulation::locally_owned_subdomain(). Even
338 * though nothing is computed on cells that we don't locally own, the error
339 * indicator vector must still have a length equal to the number of active
340 * cell in the mesh as reported by
341 * parallel::distributed::Triangulation::n_locally_owned_active_cells().
342 */
343 template <typename Number>
344 static void
345 estimate(
346 const Mapping<dim, spacedim> &mapping,
347 const DoFHandler<dim, spacedim> &dof,
348 const Quadrature<dim - 1> &quadrature,
349 const std::map<types::boundary_id, const Function<spacedim, Number> *>
350 &neumann_bc,
351 const ReadVector<Number> &solution,
352 Vector<float> &error,
353 const ComponentMask &component_mask = {},
354 const Function<spacedim> *coefficients = nullptr,
355 const unsigned int n_threads = numbers::invalid_unsigned_int,
356 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
357 const types::material_id material_id = numbers::invalid_material_id,
358 const Strategy strategy = cell_diameter_over_24);
359
360 /**
361 * Call the @p estimate function, see above, with
362 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
363 */
364 template <typename Number>
365 static void
366 estimate(
367 const DoFHandler<dim, spacedim> &dof,
368 const Quadrature<dim - 1> &quadrature,
369 const std::map<types::boundary_id, const Function<spacedim, Number> *>
370 &neumann_bc,
371 const ReadVector<Number> &solution,
372 Vector<float> &error,
373 const ComponentMask &component_mask = {},
374 const Function<spacedim> *coefficients = nullptr,
375 const unsigned int n_threads = numbers::invalid_unsigned_int,
376 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
377 const types::material_id material_id = numbers::invalid_material_id,
378 const Strategy strategy = cell_diameter_over_24);
379
380 /**
381 * Same function as above, but accepts more than one solution vector and
382 * returns one error vector for each solution vector. For the reason of
383 * existence of this function, see the general documentation of this class.
384 *
385 * Since we do not want to force the user of this function to copy around
386 * their solution vectors, the ArrayView of solution vectors takes pointers to
387 * the solutions, rather than being a vector of vectors. This makes it
388 * simpler to have the solution vectors somewhere in memory, rather than to
389 * have them collected somewhere special. (Note that it is not possible to
390 * construct of vector of references, so we had to use a vector of
391 * pointers.)
392 */
393 template <typename Number>
394 static void
395 estimate(
396 const Mapping<dim, spacedim> &mapping,
397 const DoFHandler<dim, spacedim> &dof,
398 const Quadrature<dim - 1> &quadrature,
399 const std::map<types::boundary_id, const Function<spacedim, Number> *>
400 &neumann_bc,
401 const ArrayView<const ReadVector<Number> *> &solutions,
402 ArrayView<Vector<float> *> &errors,
403 const ComponentMask &component_mask = {},
404 const Function<spacedim> *coefficients = nullptr,
405 const unsigned int n_threads = numbers::invalid_unsigned_int,
406 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
407 const types::material_id material_id = numbers::invalid_material_id,
408 const Strategy strategy = cell_diameter_over_24);
409
410 /**
411 * Call the @p estimate function, see above, with
412 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
413 */
414 template <typename Number>
415 static void
416 estimate(
417 const DoFHandler<dim, spacedim> &dof,
418 const Quadrature<dim - 1> &quadrature,
419 const std::map<types::boundary_id, const Function<spacedim, Number> *>
420 &neumann_bc,
421 const ArrayView<const ReadVector<Number> *> &solutions,
422 ArrayView<Vector<float> *> &errors,
423 const ComponentMask &component_mask = {},
424 const Function<spacedim> *coefficients = nullptr,
425 const unsigned int n_threads = numbers::invalid_unsigned_int,
426 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
427 const types::material_id material_id = numbers::invalid_material_id,
428 const Strategy strategy = cell_diameter_over_24);
429
430
431 /**
432 * Equivalent to the set of functions above, except that this one takes a
433 * mapping and quadrature collection for hp-finite element dof handlers.
434 */
435 template <typename Number>
436 static void
437 estimate(
438 const hp::MappingCollection<dim, spacedim> &mapping,
439 const DoFHandler<dim, spacedim> &dof,
440 const hp::QCollection<dim - 1> &quadrature,
441 const std::map<types::boundary_id, const Function<spacedim, Number> *>
442 &neumann_bc,
443 const ReadVector<Number> &solution,
444 Vector<float> &error,
445 const ComponentMask &component_mask = {},
446 const Function<spacedim> *coefficients = nullptr,
447 const unsigned int n_threads = numbers::invalid_unsigned_int,
448 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
449 const types::material_id material_id = numbers::invalid_material_id,
450 const Strategy strategy = cell_diameter_over_24);
451
452
453 /**
454 * Equivalent to the set of functions above, except that this one takes a
455 * quadrature collection for hp-finite element dof handlers.
456 *
457 * @deprecated Use the version of this function which takes a
458 * hp::MappingCollection instead.
459 */
460 template <typename Number>
461 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
462 "Use the version of this function which takes a hp::MappingCollection instead.")
463 static void estimate(
464 const Mapping<dim, spacedim> &mapping,
465 const DoFHandler<dim, spacedim> &dof,
466 const hp::QCollection<dim - 1> &quadrature,
467 const std::map<types::boundary_id, const Function<spacedim, Number> *>
468 &neumann_bc,
469 const ReadVector<Number> &solution,
470 Vector<float> &error,
471 const ComponentMask &component_mask = {},
472 const Function<spacedim> *coefficients = nullptr,
473 const unsigned int n_threads = numbers::invalid_unsigned_int,
474 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
475 const types::material_id material_id = numbers::invalid_material_id,
476 const Strategy strategy = cell_diameter_over_24);
477
478
479 /**
480 * Equivalent to the set of functions above, except that this one takes a
481 * quadrature collection for hp-finite element dof handlers.
482 */
483 template <typename Number>
484 static void
485 estimate(
486 const DoFHandler<dim, spacedim> &dof,
487 const hp::QCollection<dim - 1> &quadrature,
488 const std::map<types::boundary_id, const Function<spacedim, Number> *>
489 &neumann_bc,
490 const ReadVector<Number> &solution,
491 Vector<float> &error,
492 const ComponentMask &component_mask = {},
493 const Function<spacedim> *coefficients = nullptr,
494 const unsigned int n_threads = numbers::invalid_unsigned_int,
495 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
496 const types::material_id material_id = numbers::invalid_material_id,
497 const Strategy strategy = cell_diameter_over_24);
498
499
500 /**
501 * Equivalent to the set of functions above, except that this one takes a
502 * mapping and quadrature collection for hp-finite element dof handlers.
503 */
504 template <typename Number>
505 static void
506 estimate(
507 const hp::MappingCollection<dim, spacedim> &mapping,
508 const DoFHandler<dim, spacedim> &dof,
509 const hp::QCollection<dim - 1> &quadrature,
510 const std::map<types::boundary_id, const Function<spacedim, Number> *>
511 &neumann_bc,
512 const ArrayView<const ReadVector<Number> *> &solutions,
513 ArrayView<Vector<float> *> &errors,
514 const ComponentMask &component_mask = {},
515 const Function<spacedim> *coefficients = nullptr,
516 const unsigned int n_threads = numbers::invalid_unsigned_int,
517 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
518 const types::material_id material_id = numbers::invalid_material_id,
519 const Strategy strategy = cell_diameter_over_24);
520
521
522 /**
523 * Equivalent to the set of functions above, except that this one takes a
524 * quadrature collection for hp-finite element dof handlers.
525 *
526 * @deprecated Use the version of this function which takes a
527 * hp::MappingCollection instead.
528 */
529 template <typename Number>
530 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
531 "Use the version of this function which takes a hp::MappingCollection instead.")
532 static void estimate(
533 const Mapping<dim, spacedim> &mapping,
534 const DoFHandler<dim, spacedim> &dof,
535 const hp::QCollection<dim - 1> &quadrature,
536 const std::map<types::boundary_id, const Function<spacedim, Number> *>
537 &neumann_bc,
538 const ArrayView<const ReadVector<Number> *> &solutions,
539 ArrayView<Vector<float> *> &errors,
540 const ComponentMask &component_mask = {},
541 const Function<spacedim> *coefficients = nullptr,
542 const unsigned int n_threads = numbers::invalid_unsigned_int,
543 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
544 const types::material_id material_id = numbers::invalid_material_id,
545 const Strategy strategy = cell_diameter_over_24);
546
547
548 /**
549 * Equivalent to the set of functions above, except that this one takes a
550 * quadrature collection for hp-finite element dof handlers.
551 */
552 template <typename Number>
553 static void
554 estimate(
555 const DoFHandler<dim, spacedim> &dof,
556 const hp::QCollection<dim - 1> &quadrature,
557 const std::map<types::boundary_id, const Function<spacedim, Number> *>
558 &neumann_bc,
559 const ArrayView<const ReadVector<Number> *> &solutions,
560 ArrayView<Vector<float> *> &errors,
561 const ComponentMask &component_mask = {},
562 const Function<spacedim> *coefficients = nullptr,
563 const unsigned int n_threads = numbers::invalid_unsigned_int,
564 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
565 const types::material_id material_id = numbers::invalid_material_id,
566 const Strategy strategy = cell_diameter_over_24);
567
568 /**
569 * Exception
570 */
571 DeclExceptionMsg(ExcInvalidComponentMask,
572 "You provided a ComponentMask argument that is invalid. "
573 "Component masks need to be either default constructed "
574 "(in which case they indicate that every component is "
575 "selected) or need to have a length equal to the number "
576 "of vector components of the finite element in use "
577 "by the DoFHandler object. In the latter case, at "
578 "least one component needs to be selected.");
579 /**
580 * Exception
581 */
582 DeclExceptionMsg(
583 ExcInvalidCoefficient,
584 "If you do specify the argument for a (possibly "
585 "spatially variable) coefficient function for this function, "
586 "then it needs to refer to a coefficient that is either "
587 "scalar (has one vector component) or has as many vector "
588 "components as there are in the finite element used by "
589 "the DoFHandler argument.");
590 /**
591 * Exception
592 */
593 DeclException3(ExcInvalidBoundaryFunction,
594 types::boundary_id,
595 int,
596 int,
597 << "You provided a function map that for boundary indicator "
598 << arg1 << " specifies a function with " << arg2
599 << " vector components. However, the finite "
600 "element in use has "
601 << arg3
602 << " components, and these two numbers need to match.");
603 /**
604 * Exception
605 */
606 DeclException2(ExcIncompatibleNumberOfElements,
607 int,
608 int,
609 << "The number of input vectors, " << arg1
610 << " needs to be equal to the number of output vectors, "
611 << arg2
612 << ". This is not the case in your call of this function.");
613 /**
614 * Exception
615 */
616 DeclExceptionMsg(ExcNoSolutions,
617 "You need to specify at least one solution vector as "
618 "input.");
619 };
620
621
622
623 /**
624 * This is a specialization of the general template for 1d. The implementation
625 * is sufficiently different for 1d to justify this specialization. The basic
626 * difference between 1d and all other space dimensions is that in 1d, there
627 * are no faces of cells, just the vertices between line segments, so we have
628 * to compute the jump terms differently. However, this class offers exactly
629 * the same public functions as the general template, so that a user will not
630 * see any difference.
631 */
632 template <int spacedim>
633 class KellyErrorEstimator<1, spacedim>
634 {
635 public:
636 /**
637 * The enum type given to the class functions to decide on the scaling
638 * factors of the face integrals.
639 */
640 enum Strategy
641 {
642 //! Kelly error estimator with the factor $\frac {h_K}{24}$.
643 cell_diameter_over_24 = 0,
644 //! the boundary residual estimator with the factor $\frac {h_F}{2
645 //! max(p^+,p^-)}$.
646 face_diameter_over_twice_max_degree,
647 //! Kelly error estimator with the factor $h_K$.
648 cell_diameter
649 };
650
651
652
653 /**
654 * Implementation of the error estimator described above. You may give a
655 * coefficient, but there is a default value which denotes the constant
656 * coefficient with value one. The coefficient function may either be a
657 * scalar one, in which case it is used for all components of the finite
658 * element, or a vector-valued one with as many components as there are in
659 * the finite element; in the latter case, each component is weighted by the
660 * respective component in the coefficient.
661 *
662 * You might give a list of components you want to evaluate, in case the
663 * finite element used by the DoFHandler object is vector-valued. You then
664 * have to set those entries to true in the bit-vector @p component_mask for
665 * which the respective component is to be used in the error estimator. The
666 * default is to use all components, which is done by either providing a
667 * bit-vector with all-set entries, or an empty bit-vector. All the other
668 * parameters are as in the general case used for 2d and higher.
669 *
670 * The parameter n_threads is no longer used and will be ignored.
671 * Multithreading is not presently implemented for 1d, but we retain the
672 * respective parameter for compatibility with the function signature in the
673 * general case.
674 */
675 template <typename Number>
676 static void
677 estimate(
678 const Mapping<1, spacedim> &mapping,
679 const DoFHandler<1, spacedim> &dof,
680 const Quadrature<0> &quadrature,
681 const std::map<types::boundary_id, const Function<spacedim, Number> *>
682 &neumann_bc,
683 const ReadVector<Number> &solution,
684 Vector<float> &error,
685 const ComponentMask &component_mask = {},
686 const Function<spacedim> *coefficient = nullptr,
687 const unsigned int n_threads = numbers::invalid_unsigned_int,
688 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
689 const types::material_id material_id = numbers::invalid_material_id,
690 const Strategy strategy = cell_diameter_over_24);
691
692
693
694 /**
695 * Call the @p estimate function, see above, with
696 * <tt>mapping=MappingQ1<1>()</tt>.
697 */
698 template <typename Number>
699 static void
700 estimate(
701 const DoFHandler<1, spacedim> &dof,
702 const Quadrature<0> &quadrature,
703 const std::map<types::boundary_id, const Function<spacedim, Number> *>
704 &neumann_bc,
705 const ReadVector<Number> &solution,
706 Vector<float> &error,
707 const ComponentMask &component_mask = {},
708 const Function<spacedim> *coefficients = nullptr,
709 const unsigned int n_threads = numbers::invalid_unsigned_int,
710 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
711 const types::material_id material_id = numbers::invalid_material_id,
712 const Strategy strategy = cell_diameter_over_24);
713
714
715
716 /**
717 * Same function as above, but accepts more than one solution vectors and
718 * returns one error vector for each solution vector. For the reason of
719 * existence of this function, see the general documentation of this class.
720 *
721 * Since we do not want to force the user of this function to copy around
722 * their solution vectors, the vector of solution vectors takes pointers to
723 * the solutions, rather than being a vector of vectors. This makes it
724 * simpler to have the solution vectors somewhere in memory, rather than to
725 * have them collected somewhere special. (Note that it is not possible to
726 * construct of vector of references, so we had to use a vector of
727 * pointers.)
728 */
729 template <typename Number>
730 static void
731 estimate(
732 const Mapping<1, spacedim> &mapping,
733 const DoFHandler<1, spacedim> &dof,
734 const Quadrature<0> &quadrature,
735 const std::map<types::boundary_id, const Function<spacedim, Number> *>
736 &neumann_bc,
737 const ArrayView<const ReadVector<Number> *> &solutions,
738 ArrayView<Vector<float> *> &errors,
739 const ComponentMask &component_mask = {},
740 const Function<spacedim> *coefficients = nullptr,
741 const unsigned int n_threads = numbers::invalid_unsigned_int,
742 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
743 const types::material_id material_id = numbers::invalid_material_id,
744 const Strategy strategy = cell_diameter_over_24);
745
746
747
748 /**
749 * Call the @p estimate function, see above, with
750 * <tt>mapping=MappingQ1<1>()</tt>.
751 */
752 template <typename Number>
753 static void
754 estimate(
755 const DoFHandler<1, spacedim> &dof,
756 const Quadrature<0> &quadrature,
757 const std::map<types::boundary_id, const Function<spacedim, Number> *>
758 &neumann_bc,
759 const ArrayView<const ReadVector<Number> *> &solutions,
760 ArrayView<Vector<float> *> &errors,
761 const ComponentMask &component_mask = {},
762 const Function<spacedim> *coefficients = nullptr,
763 const unsigned int n_threads = numbers::invalid_unsigned_int,
764 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
765 const types::material_id material_id = numbers::invalid_material_id,
766 const Strategy strategy = cell_diameter_over_24);
767
768
769
770 /**
771 * Equivalent to the set of functions above, except that this one takes a
772 * mapping and quadrature collection for hp-finite element dof handlers.
773 */
774 template <typename Number>
775 static void
776 estimate(
777 const hp::MappingCollection<1, spacedim> &mapping,
778 const DoFHandler<1, spacedim> &dof,
779 const hp::QCollection<0> &quadrature,
780 const std::map<types::boundary_id, const Function<spacedim, Number> *>
781 &neumann_bc,
782 const ReadVector<Number> &solution,
783 Vector<float> &error,
784 const ComponentMask &component_mask = {},
785 const Function<spacedim> *coefficients = nullptr,
786 const unsigned int n_threads = numbers::invalid_unsigned_int,
787 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
788 const types::material_id material_id = numbers::invalid_material_id,
789 const Strategy strategy = cell_diameter_over_24);
790
791
792
793 /**
794 * Equivalent to the set of functions above, except that this one takes a
795 * quadrature collection for hp-finite element dof handlers.
796 *
797 * @deprecated Use the version of this function which takes a
798 * hp::MappingCollection instead.
799 */
800 template <typename Number>
801 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
802 "Use the version of this function which takes a hp::MappingCollection instead.")
803 static void estimate(
804 const Mapping<1, spacedim> &mapping,
805 const DoFHandler<1, spacedim> &dof,
806 const hp::QCollection<0> &quadrature,
807 const std::map<types::boundary_id, const Function<spacedim, Number> *>
808 &neumann_bc,
809 const ReadVector<Number> &solution,
810 Vector<float> &error,
811 const ComponentMask &component_mask = {},
812 const Function<spacedim> *coefficients = nullptr,
813 const unsigned int n_threads = numbers::invalid_unsigned_int,
814 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
815 const types::material_id material_id = numbers::invalid_material_id,
816 const Strategy strategy = cell_diameter_over_24);
817
818
819
820 /**
821 * Equivalent to the set of functions above, except that this one takes a
822 * quadrature collection for hp-finite element dof handlers.
823 */
824 template <typename Number>
825 static void
826 estimate(
827 const DoFHandler<1, spacedim> &dof,
828 const hp::QCollection<0> &quadrature,
829 const std::map<types::boundary_id, const Function<spacedim, Number> *>
830 &neumann_bc,
831 const ReadVector<Number> &solution,
832 Vector<float> &error,
833 const ComponentMask &component_mask = {},
834 const Function<spacedim> *coefficients = nullptr,
835 const unsigned int n_threads = numbers::invalid_unsigned_int,
836 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
837 const types::material_id material_id = numbers::invalid_material_id,
838 const Strategy strategy = cell_diameter_over_24);
839
840
841
842 /**
843 * Equivalent to the set of functions above, except that this one takes a
844 * mapping and quadrature collection for hp-finite element dof handlers.
845 */
846 template <typename Number>
847 static void
848 estimate(
849 const hp::MappingCollection<1, spacedim> &mapping,
850 const DoFHandler<1, spacedim> &dof,
851 const hp::QCollection<0> &quadrature,
852 const std::map<types::boundary_id, const Function<spacedim, Number> *>
853 &neumann_bc,
854 const ArrayView<const ReadVector<Number> *> &solutions,
855 ArrayView<Vector<float> *> &errors,
856 const ComponentMask &component_mask = {},
857 const Function<spacedim> *coefficients = nullptr,
858 const unsigned int n_threads = numbers::invalid_unsigned_int,
859 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
860 const types::material_id material_id = numbers::invalid_material_id,
861 const Strategy strategy = cell_diameter_over_24);
862
863
864
865 /**
866 * Equivalent to the set of functions above, except that this one takes a
867 * quadrature collection for hp-finite element dof handlers.
868 *
869 * @deprecated Use the version of this function which takes a
870 * hp::MappingCollection instead.
871 */
872 template <typename Number>
873 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
874 "Use the version of this function which takes a hp::MappingCollection instead.")
875 static void estimate(
876 const Mapping<1, spacedim> &mapping,
877 const DoFHandler<1, spacedim> &dof,
878 const hp::QCollection<0> &quadrature,
879 const std::map<types::boundary_id, const Function<spacedim, Number> *>
880 &neumann_bc,
881 const ArrayView<const ReadVector<Number> *> &solutions,
882 ArrayView<Vector<float> *> &errors,
883 const ComponentMask &component_mask = {},
884 const Function<spacedim> *coefficients = nullptr,
885 const unsigned int n_threads = numbers::invalid_unsigned_int,
886 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
887 const types::material_id material_id = numbers::invalid_material_id,
888 const Strategy strategy = cell_diameter_over_24);
889
890
891
892 /**
893 * Equivalent to the set of functions above, except that this one takes a
894 * quadrature collection for hp-finite element dof handlers.
895 */
896 template <typename Number>
897 static void
898 estimate(
899 const DoFHandler<1, spacedim> &dof,
900 const hp::QCollection<0> &quadrature,
901 const std::map<types::boundary_id, const Function<spacedim, Number> *>
902 &neumann_bc,
903 const ArrayView<const ReadVector<Number> *> &solutions,
904 ArrayView<Vector<float> *> &errors,
905 const ComponentMask &component_mask = {},
906 const Function<spacedim> *coefficients = nullptr,
907 const unsigned int n_threads = numbers::invalid_unsigned_int,
908 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id,
909 const types::material_id material_id = numbers::invalid_material_id,
910 const Strategy strategy = cell_diameter_over_24);
911
912
913
914 /**
915 * Exception
916 */
917 DeclExceptionMsg(ExcInvalidComponentMask,
918 "You provided a ComponentMask argument that is invalid. "
919 "Component masks need to be either default constructed "
920 "(in which case they indicate that every component is "
921 "selected) or need to have a length equal to the number "
922 "of vector components of the finite element in use "
923 "by the DoFHandler object. In the latter case, at "
924 "least one component needs to be selected.");
925
926 /**
927 * Exception
928 */
929 DeclExceptionMsg(
930 ExcInvalidCoefficient,
931 "If you do specify the argument for a (possibly "
932 "spatially variable) coefficient function for this function, "
933 "then it needs to refer to a coefficient that is either "
934 "scalar (has one vector component) or has as many vector "
935 "components as there are in the finite element used by "
936 "the DoFHandler argument.");
937
938 /**
939 * Exception
940 */
941 DeclException3(ExcInvalidBoundaryFunction,
942 types::boundary_id,
943 int,
944 int,
945 << "You provided a function map that for boundary indicator "
946 << arg1 << " specifies a function with " << arg2
947 << " vector components. However, the finite "
948 "element in use has "
949 << arg3
950 << " components, and these two numbers need to match.");
951
952 /**
953 * Exception
954 */
955 DeclException2(ExcIncompatibleNumberOfElements,
956 int,
957 int,
958 << "The number of input vectors, " << arg1
959 << " needs to be equal to the number of output vectors, "
960 << arg2
961 << ". This is not the case in your call of this function.");
962
963 /**
964 * Exception
965 */
966 DeclExceptionMsg(ExcNoSolutions,
967 "You need to specify at least one solution vector as "
968 "input.");
969 };
970
971
972 DEAL_II_NAMESPACE_CLOSE
973
974 #endif