Debian Codegraph @

include/deal.II/numerics/vector_tools_common.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 2023 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_vector_tools_common_h
16 #define dealii_vector_tools_common_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/patterns.h>
22
23 DEAL_II_NAMESPACE_OPEN
24
25 namespace VectorTools
26 {
27 /**
28 * Denote which norm/integral is to be computed by the
29 * integrate_difference() function on each cell and compute_global_error()
30 * for the whole domain.
31 * Let $f:\Omega \rightarrow \mathbb{R}^c$ be a finite element function
32 * with $c$ components where component $c$ is denoted by $f_c$ and $\hat{f}$
33 * be the reference function (the @p fe_function and @p exact_solution
34 * arguments to integrate_difference()). Let $e_c = \hat{f}_c - f_c$
35 * be the difference or error between the two. Further,
36 * let $w:\Omega \rightarrow \mathbb{R}^c$ be the @p weight function of integrate_difference(), which is
37 * assumed to be equal to one if not supplied. Finally, let $p$ be the
38 * @p exponent argument (for $L_p$-norms).
39 *
40 * In the following,we denote by $E_K$ the local error computed by
41 * integrate_difference() on cell $K$, whereas $E$ is the global error
42 * computed by compute_global_error(). Note that integrals are
43 * approximated by quadrature in the usual way:
44 * @f[
45 * \int_A f(x) dx \approx \sum_q f(x_q) \omega_q.
46 * @f]
47 * Similarly for suprema over a cell $T$:
48 * @f[
49 * \sup_{x\in T} |f(x)| dx \approx \max_q |f(x_q)|.
50 * @f]
51 */
52 enum NormType
53 {
54 /**
55 * The function or difference of functions is integrated on each cell $K$:
56 * @f[
57 * E_K
58 * = \int_K \sum_c (\hat{f}_c - f_c) \, w_c
59 * = \int_K \sum_c e_c \, w_c
60 * @f]
61 * and summed up to get
62 * @f[
63 * E = \sum_K E_K
64 * = \int_\Omega \sum_c (\hat{f}_c - f_c) \, w_c
65 * @f]
66 * or, for $w \equiv 1$:
67 * @f[
68 * E = \int_\Omega (\hat{f} - f)
69 * = \int_\Omega e.
70 * @f]
71 *
72 * Note: This differs from what is typically known as
73 * the mean of a function by a factor of $\frac{1}{|\Omega|}$. To
74 * compute the mean you can also use compute_mean_value(). Finally,
75 * pay attention to the sign: if $\hat{f}=0$, this will compute the
76 * negative of the mean of $f$.
77 */
78 mean,
79
80 /**
81 * The absolute value of the function is integrated:
82 * @f[
83 * E_K = \int_K \sum_c |e_c| \, w_c
84 * @f]
85 * and
86 * @f[
87 * E = \sum_K E_K = \int_\Omega \sum_c |e_c| w_c,
88 * @f]
89 * or, for $w \equiv 1$:
90 * @f[
91 * E = \| e \|_{L^1}.
92 * @f]
93 */
94 L1_norm,
95
96 /**
97 * The square of the function is integrated and the square root of the
98 * result is computed on each cell:
99 * @f[
100 * E_K = \sqrt{ \int_K \sum_c e_c^2 \, w_c }
101 * @f]
102 * and
103 * @f[
104 * E = \sqrt{\sum_K E_K^2} = \sqrt{ \int_\Omega \sum_c e_c^2 \, w_c }
105 * @f]
106 * or, for $w \equiv 1$:
107 * @f[
108 * E = \sqrt{ \int_\Omega e^2 }
109 * = \| e \|_{L^2}
110 * @f]
111 */
112 L2_norm,
113
114 /**
115 * The absolute value to the $p$-th power is integrated and the $p$-th
116 * root is computed on each cell. The exponent $p$ is the @p
117 * exponent argument of integrate_difference() and compute_mean_value():
118 * @f[
119 * E_K = \left( \int_K \sum_c |e_c|^p \, w_c \right)^{1/p}
120 * @f]
121 * and
122 * @f[
123 * E = \left( \sum_K E_K^p \right)^{1/p}
124 * @f]
125 * or, for $w \equiv 1$:
126 * @f[
127 * E = \| e \|_{L^p}.
128 * @f]
129 */
130 Lp_norm,
131
132 /**
133 * The maximum absolute value of the function:
134 * @f[
135 * E_K = \sup_K \max_c |e_c| \, w_c
136 * @f]
137 * and
138 * @f[
139 * E = \max_K E_K
140 * = \sup_\Omega \max_c |e_c| \, w_c
141 * @f]
142 * or, for $w \equiv 1$:
143 * @f[
144 * E = \sup_\Omega \|e\|_\infty = \| e \|_{L^\infty}.
145 * @f]
146 */
147 Linfty_norm,
148
149 /**
150 * #L2_norm of the gradient:
151 * @f[
152 * E_K = \sqrt{ \int_K \sum_c (\nabla e_c)^2 \, w_c }
153 * @f]
154 * and
155 * @f[
156 * E = \sqrt{\sum_K E_K^2} = \sqrt{ \int_\Omega \sum_c (\nabla e_c)^2 \,
157 * w_c }
158 * @f]
159 * or, for $w \equiv 1$:
160 * @f[
161 * E = \| \nabla e \|_{L^2}.
162 * @f]
163 */
164 H1_seminorm,
165
166 /**
167 * #L2_norm of the divergence of a vector field. The function $f$ is
168 * expected to have $c \geq \text{dim}$ components and the first @p dim
169 * will be used to compute the divergence:
170 * @f[
171 * E_K = \sqrt{ \int_K \left( \sum_c \frac{\partial e_c}{\partial x_c} \,
172 * \sqrt{w_c} \right)^2 }
173 * @f]
174 * and
175 * @f[
176 * E = \sqrt{\sum_K E_K^2}
177 * = \sqrt{ \int_\Omega \left( \sum_c \frac{\partial e_c}{\partial x_c}
178 * \, \sqrt{w_c} \right)^2 }
179 * @f]
180 * or, for $w \equiv 1$:
181 * @f[
182 * E = \| \nabla \cdot e \|_{L^2}.
183 * @f]
184 */
185 Hdiv_seminorm,
186
187 /**
188 * The square of this norm is the square of the #L2_norm plus the square
189 * of the #H1_seminorm:
190 * @f[
191 * E_K = \sqrt{ \int_K \sum_c (e_c^2 + (\nabla e_c)^2) \, w_c }
192 * @f]
193 * and
194 * @f[
195 * E = \sqrt{\sum_K E_K^2} = \sqrt{ \int_\Omega \sum_c (e_c^2 + (\nabla
196 * e_c)^2) \, w_c }
197 * @f]
198 * or, for $w \equiv 1$:
199 * @f[
200 * E = \left( \| e \|_{L^2}^2 + \| \nabla e \|_{L^2}^2 \right)^{1/2}.
201 * @f]
202 */
203 H1_norm,
204
205 /**
206 * #Lp_norm of the gradient:
207 * @f[
208 * E_K = \left( \int_K \sum_c |\nabla e_c|^p \, w_c \right)^{1/p}
209 * @f]
210 * and
211 * @f[
212 * E = \left( \sum_K E_K^p \right)^{1/p}
213 * = \left( \int_\Omega \sum_c |\nabla e_c|^p \, w_c \right)^{1/p}
214 * @f]
215 * or, for $w \equiv 1$:
216 * @f[
217 * E = \| \nabla e \|_{L^p}.
218 * @f]
219 */
220 W1p_seminorm,
221
222 /**
223 * The same as the #H1_norm but using <i>L<sup>p</sup></i>:
224 * @f[
225 * E_K = \left( \int_K \sum_c (|e_c|^p + |\nabla e_c|^p) \, w_c
226 * \right)^{1/p}
227 * @f]
228 * and
229 * @f[
230 * E = \left( \sum_K E_K^p \right)^{1/p}
231 * = \left( \int_\Omega \sum_c (|e_c|^p + |\nabla e_c|^p) \, w_c
232 * \right)^{1/p}
233 * @f]
234 * or, for $w \equiv 1$:
235 * @f[
236 * E = \left( \| e \|_{L^p}^p + \| \nabla e \|_{L^p}^p \right)^{1/p}.
237 * @f]
238 */
239 W1p_norm,
240
241 /**
242 * #Linfty_norm of the gradient:
243 * @f[
244 * E_K = \sup_K \max_c |\nabla e_c| \, w_c
245 * @f]
246 * and
247 * @f[
248 * E = \max_K E_K
249 * = \sup_\Omega \max_c |\nabla e_c| \, w_c
250 * @f]
251 * or, for $w \equiv 1$:
252 * @f[
253 * E = \| \nabla e \|_{L^\infty}.
254 * @f]
255 */
256 W1infty_seminorm,
257
258 /**
259 * The sum of #Linfty_norm and #W1infty_seminorm:
260 * @f[
261 * E_K = \sup_K \max_c |e_c| \, w_c + \sup_K \max_c |\nabla e_c| \, w_c.
262 * @f]
263 * The global norm is not implemented in compute_global_error(),
264 * because it is impossible to compute the sum of the global
265 * norms from the values $E_K$. As a work-around, you can compute the
266 * global #Linfty_norm and #W1infty_seminorm separately and then add them
267 * to get (with $w \equiv 1$):
268 * @f[
269 * E = \| e \|_{L^\infty} + \| \nabla e \|_{L^\infty}.
270 * @f]
271 */
272 W1infty_norm
273 };
274
275 /**
276 * Exception
277 */
278 DeclExceptionMsg(ExcPointNotAvailableHere,
279 "The given point is inside a cell of a "
280 "parallel::distributed::Triangulation that is not "
281 "locally owned by this processor.");
282 } // namespace VectorTools
283
284 // Make sure we can use NormType with Patterns.
285 namespace Patterns
286 {
287 namespace Tools
288 {
289 template <>
290 struct Convert<VectorTools::NormType, void>
291 {
292 /**
293 * Return the Correct pattern for NormType.
294 */
295 static std::unique_ptr<Patterns::PatternBase>
296 to_pattern()
297 {
298 return std::make_unique<Patterns::Selection>(
299 "mean|L1_norm|L2_norm|Lp_norm|"
300 "Linfty_norm|H1_seminorm|Hdiv_seminorm|"
301 "H1_norm|W1p_seminorm|W1p_norm|"
302 "W1infty_seminorm|W1infty_norm");
303 }
304
305
306
307 /**
308 * Convert a NormType to a string.
309 */
310 static std::string
311 to_string(const VectorTools::NormType &s,
312 const Patterns::PatternBase &p =
313 *Convert<VectorTools::NormType>::to_pattern())
314 {
315 std::string str;
316 if (s == VectorTools::mean)
317 str = "mean";
318 else if (s == VectorTools::L1_norm)
319 str = "L1_norm";
320 else if (s == VectorTools::L2_norm)
321 str = "L2_norm";
322 else if (s == VectorTools::Lp_norm)
323 str = "Lp_norm";
324 else if (s == VectorTools::Linfty_norm)
325 str = "Linfty_norm";
326 else if (s == VectorTools::H1_seminorm)
327 str = "H1_seminorm";
328 else if (s == VectorTools::Hdiv_seminorm)
329 str = "Hdiv_seminorm";
330 else if (s == VectorTools::H1_norm)
331 str = "H1_norm";
332 else if (s == VectorTools::W1p_seminorm)
333 str = "W1p_seminorm";
334 else if (s == VectorTools::W1infty_seminorm)
335 str = "W1infty_seminorm";
336 else if (s == VectorTools::W1infty_norm)
337 str = "W1infty_norm";
338 else if (s == VectorTools::W1p_norm)
339 str = "W1p_norm";
340 else
341 {
342 AssertThrow(false, ExcMessage("Didn't recognize a norm type."));
343 }
344 AssertThrow(p.match(str), ExcInternalError());
345 return str;
346 }
347
348
349 /**
350 * Convert a string to a NormType.
351 */
352 static VectorTools::NormType
353 to_value(const std::string &str,
354 const Patterns::PatternBase &p =
355 *Convert<VectorTools::NormType>::to_pattern())
356 {
357 VectorTools::NormType norm = VectorTools::mean;
358 AssertThrow(p.match(str),
359 ExcMessage(
360 "String " + str +
361 " cannot be converted to VectorTools::NormType"));
362
363 if (str == "mean")
364 norm = VectorTools::mean;
365 else if (str == "L1_norm")
366 norm = VectorTools::L1_norm;
367 else if (str == "L2_norm")
368 norm = VectorTools::L2_norm;
369 else if (str == "Lp_norm")
370 norm = VectorTools::Lp_norm;
371 else if (str == "Linfty_norm")
372 norm = VectorTools::Linfty_norm;
373 else if (str == "H1_seminorm")
374 norm = VectorTools::H1_seminorm;
375 else if (str == "Hdiv_seminorm")
376 norm = VectorTools::Hdiv_seminorm;
377 else if (str == "H1_norm")
378 norm = VectorTools::H1_norm;
379 else if (str == "W1p_seminorm")
380 norm = VectorTools::W1p_seminorm;
381 else if (str == "W1infty_seminorm")
382 norm = VectorTools::W1infty_seminorm;
383 else if (str == "W1infty_norm")
384 norm = VectorTools::W1infty_norm;
385 else if (str == "W1p_norm")
386 norm = VectorTools::W1p_norm;
387 else
388 {
389 AssertThrow(false, ExcMessage("Didn't recognize a norm type."));
390 }
391 return norm;
392 }
393 };
394 } // namespace Tools
395 } // namespace Patterns
396
397 DEAL_II_NAMESPACE_CLOSE
398
399 #endif // dealii_vector_tools_common_h