Debian Codegraph @

include/deal.II/base/parsed_convergence_table.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_base_parsed_convergence_table_h
16 #define dealii_base_parsed_convergence_table_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/convergence_table.h>
21 #include <deal.II/base/function.h>
22 #include <deal.II/base/function_parser.h>
23 #include <deal.II/base/quadrature_lib.h>
24
25 #include <deal.II/dofs/dof_handler.h>
26
27 #include <deal.II/fe/mapping.h>
28
29 #include <deal.II/grid/tria.h>
30
31 #include <deal.II/lac/vector.h>
32
33 #include <deal.II/numerics/vector_tools_integrate_difference.h>
34
35 #include <set>
36 #include <string>
37 #include <vector>
38
39
40 DEAL_II_NAMESPACE_OPEN
41
42 #ifndef DOXYGEN
43 class ParameterHandler;
44 #endif
45
46 /**
47 * @brief The ParsedConvergenceTable class
48 *
49 * This class simplifies the construction of convergence tables, reading the
50 * options for the generation of the table from a parameter file. It provides a
51 * series of methods that can be used to compute the error given a reference
52 * exact solution, or the difference between two numerical solutions, or any
53 * other custom computation of the error, given via std::function objects.
54 *
55 * An example usage of this class is given by
56 * @code
57 * ParsedConvergenceTable table;
58 *
59 * ParameterHandler prm;
60 * table.add_parameters(prm);
61 *
62 * for (unsigned int i = 0; i < n_cycles; ++i)
63 * {
64 * ... // do some computations
65 * table.error_from_exact(dof_handler, solution, exact_solution);
66 * }
67 * table.output_table(std::cout);
68 * @endcode
69 *
70 * The above code constructs a ParsedConvergenceTable that works for
71 * scalar problems, and will produce an error table with `H1_norm`, `L2_norm`,
72 * and `Linfty_norm` norms of the error.
73 *
74 * Whenever a call to the methods error_from_exact() or difference() is made,
75 * the instance of this class inspects its parameters, computes all norms
76 * specified by the parameter given at construction time, possibly modified
77 * via a parameter file, computes all extra column entries specified using the
78 * method add_extra_column(), and writes one row of the convergence table.
79 *
80 * Once you have finished with the computations, a call to output_table() will
81 * generate a formatted convergence table on the provided stream, and to the
82 * file (if any) specified in the parameter file.
83 *
84 * With a small modification, the same code can be used to estimate the errors
85 * of mixed or multi-physics problems, e.g.:
86 * @code
87 * using namespace VectorTools;
88 * ParsedConvergenceTable table({"u,u,p"},{{H1_norm, L2_norm}, {L2_norm}});
89 *
90 * ParameterHandler prm;
91 * table.add_parameters(prm);
92 *
93 * for (unsigned int i = 0; i < n_cycles; ++i)
94 * {
95 * ... // do some computations
96 * table.error_from_exact(dof_handler, solution, exact_solution);
97 * }
98 * table.output_table(std::cout);
99 * @endcode
100 *
101 * The above code assumes that you are solving a Stokes problem with three
102 * components. Two components for the vector velocity field `u`, and one
103 * component for the pressure field `p`, and will produce an error
104 * table with `H1` and `L2` norm of the error in the velocity field (first two,
105 * components) and `L2` error in the pressure field.
106 *
107 * You may also call `table.output_table()` without arguments, to write the
108 * table only to the file specified in the parameter file.
109 *
110 * By calling the method add_parameters() passing a ParameterHandler object,
111 * the following options will be defined in the given ParameterHandler object
112 * (in the current level of the ParameterHandler object, i.e., whatever level
113 * you have entered with the ParameterHandler::enter_subsection() method),
114 * and can be modified at run time through a parameter file:
115 * @code
116 * set Enable computation of the errors = true
117 * set Error file name =
118 * set Error precision = 3
119 * set Exponent for p-norms = 2
120 * set Extra columns = dofs, cells
121 * set List of error norms to compute = Linfty_norm, L2_norm, H1_norm
122 * set Rate key = dofs
123 * set Rate mode = reduction_rate_log2
124 * @endcode
125 *
126 * When using this class, please cite @cite SartoriGiulianiBardelloni-2018-a.
127 */
128 class ParsedConvergenceTable
129 {
130 public:
131 /**
132 * Minimal constructor for ParsedConvergenceTable objects.
133 *
134 * The number of components must match the number of components of the
135 * finite element space that is used to compute the errors. If
136 * a component name is repeated, than it is interpreted as a vector field,
137 * and the errors of the repeated components are grouped together.
138 *
139 * The size of the vector @p list_of_error_norms must match the number of
140 * unique component names, and may contain zero or more comma separated
141 * identifiers for the norm to compute for each component (see the
142 * documentation of VectorTools::NormType for the available options).
143 *
144 * For example, the following constructor
145 * @code
146 * using namespace VectorTools;
147 * ParsedConvergenceTable table({"u", "v", "v"},
148 * {{Linfty_norm}, {L2_norm, H1_norm}});
149 * @endcode
150 * would produce (if the parameter file is left untouched) a table similar to
151 * @code
152 * cells dofs u_Linfty_norm v_L2_norm v_H1_norm
153 * 4 9 1.183e-01 - 5.156e-02 - 2.615e-01 -
154 * 16 25 3.291e-02 2.50 1.333e-02 2.65 1.272e-01 1.41
155 * 64 81 8.449e-03 2.31 3.360e-03 2.34 6.313e-02 1.19
156 * 256 289 2.126e-03 2.17 8.418e-04 2.18 3.150e-02 1.09
157 * 1024 1089 5.325e-04 2.09 2.106e-04 2.09 1.574e-02 1.05
158 * @endcode
159 *
160 * See the other constructor for a documentation of all the parameters you can
161 * change.
162 *
163 * @param component_names Specify the names of the components;
164 * @param list_of_error_norms Specify what error norms to compute for each
165 * unique component name.
166 */
167 ParsedConvergenceTable(
168 const std::vector<std::string> &component_names = {"u"},
169 const std::vector<std::set<VectorTools::NormType>> &list_of_error_norms = {
170 {VectorTools::H1_norm, VectorTools::L2_norm, VectorTools::Linfty_norm}});
171
172 /**
173 * Full constructor for ParsedConvergenceTable.
174 *
175 * @param component_names Names of the components. Repeated consecutive
176 * names are interpreted as components of a vector valued field;
177 * @param list_of_error_norms Specify what error norms to compute for each
178 * unique component name;
179 * @param exponent The exponent to use in p-norms;
180 * @param extra_columns Extra columns to add. These may be "cells" or "dofs";
181 * @param rate_key Specify the extra column by which we will compute the
182 * error rates. This key can either be one of "cells" or "dofs", or, if you
183 * add extra columns to the table via the method add_extra_column(), it may
184 * be one of the extra columns you added;
185 * @param rate_mode Specify the rate mode to use when computing error rates.
186 * This maybe either "reduction_rate", "reduction_rate_log2", or "none". See
187 * the documentation of ConvergenceTable::RateMode for an explanation of how
188 * each of this mode behaves;
189 * @param error_file_name Name of error output file (with extension txt,
190 * gpl, tex, or org). If different from the empty string, than
191 * output_table() also writes in this file in the format deduced from its
192 * extension;
193 * @param precision How many digits to use when writing the error;
194 * @param compute_error Control whether the filling of the table is enabled
195 * or not. This flag may be used to disable at run time any error computation;
196 *
197 * The parameters you specify with this constructor can be written to a
198 * ParameterHandler object by calling the add_parameters() method. Once you
199 * call the add_parameters() method, the following options will be defined in
200 * the given ParameterHandler object, and the parameters of the instance of
201 * this class will follow the modification you make to the ParameterHandler
202 * object at run time:
203 * @code
204 * # Listing of Parameters
205 * # ---------------------
206 * # When set to false, no computations are performed.
207 * set Enable computation of the errors = true
208 *
209 * # Set this to a filename with extension .txt, .gpl, .org, or .tex to enable
210 * # writing the convergence table to a file.
211 * set Error file name =
212 *
213 * # Number of digits to use when printing the error.
214 * set Error precision = 3
215 *
216 * # Extra columns to add to the table. Available options are dofs and cells.
217 * set Extra columns = dofs, cells
218 *
219 * # The exponent to use when computing p-norms.
220 * set Exponent for p-norms = 2
221 *
222 * # Each component is separated by a semicolon and each norm by a comma. See
223 * # the documentation of VectorTools::NormType for a list of implemented
224 * # norms. If you want to skip a component, leave its entry empty.
225 * set List of error norms to compute = Linfty_norm, L2_norm, H1_norm
226 *
227 * # Key to use when computing convergence rates. If this is set to a
228 * # column that is not present, or to none, then no error rates are computed.
229 * set Rate key = dofs
230 *
231 * # What type of error rate to compute. Available options are
232 * # reduction_rate_log2, reduction_rate, and none.
233 * set Rate mode = reduction_rate_log2
234 * @endcode
235 */
236 ParsedConvergenceTable(
237 const std::vector<std::string> &component_names,
238 const std::vector<std::set<VectorTools::NormType>> &list_of_error_norms,
239 const double exponent,
240 const std::set<std::string> &extra_columns,
241 const std::string &rate_key,
242 const std::string &rate_mode,
243 const std::string &error_file_name,
244 const unsigned int precision,
245 const bool compute_error);
246
247 /**
248 * Attach all the parameters in this class to entries of the parameter
249 * handler @p prm. Whenever the content of @p prm changes, the parameters
250 * of this class will be updated.
251 */
252 void
253 add_parameters(ParameterHandler &prm);
254
255 /**
256 * Add a row to the error table, containing the error between @p solution and
257 * the @p exact function, in the norm(s) specified in the parameter file.
258 *
259 * If you specify a @p weight function during this call, then this is used
260 * to compute weighted errors. The weight function can be either a scalar
261 * function (which will be used for all components), or a vector function.
262 * When it is a vector function, an assertion is triggered if the number of
263 * components does not coincide with the number of components of the
264 * underlying finite element space.
265 */
266 template <int dim, int spacedim, typename VectorType>
267 void
268 error_from_exact(const DoFHandler<dim, spacedim> &vspace,
269 const VectorType &solution,
270 const Function<spacedim> &exact,
271 const Function<spacedim> *weight = nullptr);
272
273 /**
274 * Same as above, with a different mapping.
275 */
276 template <int dim, int spacedim, typename VectorType>
277 void
278 error_from_exact(const Mapping<dim, spacedim> &mapping,
279 const DoFHandler<dim, spacedim> &vspace,
280 const VectorType &solution,
281 const Function<spacedim> &exact,
282 const Function<spacedim> *weight = nullptr);
283
284 /**
285 * Add an additional column (with name @p column_name) to the table, by invoking
286 * the function @p custom_function, when calling error_from_exact() or
287 * difference().
288 *
289 * You can call this method as many times as you want. If @p column_name was
290 * already used in a previous call, then calling this method with the same
291 * name will overwrite whatever function you had previously specified. If
292 * you use a lambda function for this call, make sure that the variables used
293 * internally in the lambda function remain valid until the call to
294 * error_from_exact() or difference().
295 *
296 * Make sure you add all extra columns before the first call to
297 * error_from_exact() or difference(). Adding additional columns to the
298 * convergence table after you already started filling the table will trigger
299 * an exception.
300 *
301 * This method may be used, for example, to compute the error w.r.t. to
302 * time step increments in time, for example:
303 * @code
304 * using namespace VectorTools;
305 * ParsedConvergenceTable table({"u"}, {{L2_norm}});
306 *
307 * double dt = .5;
308 * auto dt_function = [&]() {
309 * return dt;
310 * };
311 *
312 * table.add_extra_column("dt", dt_function, false);
313 *
314 * for (unsigned int i = 0; i < n_cycles; ++i)
315 * {
316 * // ... compute solution at the current dt
317 *
318 * table.error_from_exact(dof_handler, solution, exact_solution);
319 * dt /= 2.0;
320 * }
321 * table.output_table(std::cout);
322 * @endcode
323 * will produce a table similar to
324 * @code
325 * dt u_L2_norm
326 * 5.000e-1 5.156e-02 -
327 * 2.500e-2 1.333e-02 2.65
328 * 1.250e-2 3.360e-03 2.34
329 * 6.250e-3 8.418e-04 2.18
330 * @endcode
331 * provided that you use the following parameter file (only non default
332 * entries are shown here):
333 * @code
334 * set Extra columns =
335 * set List of error norms to compute = L2_norm
336 * set Rate key = dt
337 * @endcode
338 *
339 *
340 * @param column_name Name of the column to add;
341 * @param custom_function %Function that will be called to fill the given
342 * entry. You need to make sure that the scope of this function is valid
343 * up to the call to error_from_exact() or difference();
344 * @param compute_rate If set to true, then this column will be included in
345 * the list of columns for which error rates are computed. You may want to set
346 * this to false if you want to compute error rates with respect to this
347 * column. In this case, you should also specify @p column_name as the rate
348 * key in the parameter file.
349 */
350 void
351 add_extra_column(const std::string &column_name,
352 const std::function<double()> &custom_function,
353 const bool compute_rate = true);
354
355 /**
356 * Difference between two solutions in the same vector space.
357 */
358 template <int dim, int spacedim, typename VectorType>
359 void
360 difference(const DoFHandler<dim, spacedim> &,
361 const VectorType &,
362 const VectorType &,
363 const Function<spacedim> *weight = nullptr);
364
365 /**
366 * Same as above, with a non default mapping.
367 */
368 template <int dim, int spacedim, typename VectorType>
369 void
370 difference(const Mapping<dim, spacedim> &mapping,
371 const DoFHandler<dim, spacedim> &,
372 const VectorType &,
373 const VectorType &,
374 const Function<spacedim> *weight = nullptr);
375
376 /**
377 * Write the error table to the @p out stream (in text format), and
378 * (possibly) to the file stream specified in the parameters (with the format
379 * deduced from the file name extension).
380 */
381 void
382 output_table(std::ostream &out);
383
384 /**
385 * Write the error table to the file stream specified in the parameters.
386 *
387 * If the "Error file name" option in the parameter file is set to the empty
388 * string, no output is written.
389 */
390 void
391 output_table();
392
393 private:
394 /**
395 * Add rates to the output table.
396 */
397 void
398 prepare_table_for_output();
399
400 /**
401 * Names of the solution components.
402 */
403 const std::vector<std::string> component_names;
404
405 /**
406 * Same as above, but containing repeated component names only once.
407 */
408 const std::vector<std::string> unique_component_names;
409
410 /**
411 * Masks for each unique component name.
412 */
413 const std::vector<ComponentMask> unique_component_masks;
414
415 /**
416 * Additional methods to call when adding rows to the table.
417 */
418 std::map<std::string, std::pair<std::function<double()>, bool>>
419 extra_column_functions;
420
421 /**
422 * Type of error to compute per components.
423 */
424 std::vector<std::set<VectorTools::NormType>> norms_per_unique_component;
425
426 /**
427 * Exponent to use in p-norm types.
428 */
429 double exponent;
430
431 /**
432 * The actual table
433 */
434 ConvergenceTable table;
435
436 /**
437 * Extra columns to add to the table.
438 */
439 std::set<std::string> extra_columns;
440
441 /**
442 * The name of column with respect to which we compute convergence rates.
443 */
444 std::string rate_key;
445
446 /**
447 * Reduction rate mode. See ConvergenceTable::RateMode for a documentation.
448 */
449 std::string rate_mode;
450
451 /**
452 * The precision used to output the table.
453 */
454 unsigned int precision;
455
456 /**
457 * Filename to use when writing to file.
458 */
459 std::string error_file_name;
460
461 /**
462 * Compute the error. If this is false, all methods that perform the
463 * computation of the error are disabled and don't do anything.
464 */
465 bool compute_error;
466 };
467
468
469
470 #ifndef DOXYGEN
471 // ============================================================
472 // Template functions
473 // ============================================================
474 template <int dim, int spacedim, typename VectorType>
475 void
476 ParsedConvergenceTable::difference(const DoFHandler<dim, spacedim> &dh,
477 const VectorType &solution1,
478 const VectorType &solution2,
479 const Function<spacedim> *weight)
480 {
481 AssertThrow(solution1.size() == solution2.size(),
482 ExcDimensionMismatch(solution1.size(), solution2.size()));
483 VectorType solution(solution1);
484 solution -= solution2;
485 error_from_exact(
486 dh,
487 solution,
488 Functions::ConstantFunction<spacedim>(0.0, component_names.size()),
489 weight);
490 }
491
492
493
494 template <int dim, int spacedim, typename VectorType>
495 void
496 ParsedConvergenceTable::difference(const Mapping<dim, spacedim> &mapping,
497 const DoFHandler<dim, spacedim> &dh,
498 const VectorType &solution1,
499 const VectorType &solution2,
500 const Function<spacedim> *weight)
501 {
502 AssertThrow(solution1.size() == solution2.size(),
503 ExcDimensionMismatch(solution1.size(), solution2.size()));
504 VectorType solution(solution1);
505 solution -= solution2;
506 error_from_exact(
507 mapping,
508 dh,
509 solution,
510 Functions::ConstantFunction<spacedim>(0.0, component_names.size()),
511 weight);
512 }
513
514
515
516 template <int dim, int spacedim, typename VectorType>
517 void
518 ParsedConvergenceTable::error_from_exact(const DoFHandler<dim, spacedim> &dh,
519 const VectorType &solution,
520 const Function<spacedim> &exact,
521 const Function<spacedim> *weight)
522 {
523 error_from_exact(get_default_linear_mapping(dh.get_triangulation()),
524 dh,
525 solution,
526 exact,
527 weight);
528 }
529
530
531
532 template <int dim, int spacedim, typename VectorType>
533 void
534 ParsedConvergenceTable::error_from_exact(const Mapping<dim, spacedim> &mapping,
535 const DoFHandler<dim, spacedim> &dh,
536 const VectorType &solution,
537 const Function<spacedim> &exact,
538 const Function<spacedim> *weight)
539 {
540 const auto n_components = component_names.size();
541
542 if (compute_error)
543 {
544 AssertDimension(exact.n_components, n_components);
545 AssertDimension(dh.get_fe().n_components(), n_components);
546
547 const types::global_cell_index n_active_cells =
548 dh.get_triangulation().n_global_active_cells();
549 const unsigned int n_dofs = dh.n_dofs();
550
551 for (const auto &col : extra_columns)
552 if (col == "cells")
553 {
554 table.add_value("cells", n_active_cells);
555 table.set_tex_caption("cells", "\\# cells");
556 table.set_tex_format("cells", "r");
557 }
558 else if (col == "dofs")
559 {
560 table.add_value("dofs", n_dofs);
561 table.set_tex_caption("dofs", "\\# dofs");
562 table.set_tex_format("dofs", "r");
563 }
564
565 // A vector of zero std::functions with n_components components
566 const std::vector<std::function<double(const Point<spacedim> &)>>
567 zero_components(n_components,
568 [](const Point<spacedim> &) { return 0.0; });
569
570 // The default weight function, with n_components components
571 std::vector<std::function<double(const Point<spacedim> &)>>
572 weight_components(n_components,
573 [](const Point<spacedim> &) { return 1.0; });
574
575 if (weight != nullptr)
576 {
577 if (weight->n_components == 1)
578 {
579 for (auto &f : weight_components)
580 f = [&](const Point<spacedim> &p) { return weight->value(p); };
581 }
582 else
583 {
584 AssertDimension(weight->n_components, n_components);
585 for (unsigned int i = 0; i < n_components; ++i)
586 weight_components[i] = [&](const Point<spacedim> &p) {
587 return weight->value(p, i);
588 };
589 }
590 }
591
592 for (unsigned int i = 0; i < norms_per_unique_component.size(); ++i)
593 {
594 std::map<VectorTools::NormType, double> errors;
595
596 const auto &norms = norms_per_unique_component[i];
597 const auto &mask = unique_component_masks[i];
598
599 // Simple case first
600 if (norms.empty())
601 continue;
602
603 auto components_expr = zero_components;
604 for (unsigned int j = 0; j < n_components; ++j)
605 if (mask[j] == true)
606 components_expr[j] = weight_components[j];
607
608 FunctionFromFunctionObjects<spacedim> select_component(
609 components_expr);
610
611 Vector<float> difference_per_cell(
612 dh.get_triangulation().n_global_active_cells());
613
614 QGauss<dim> q_gauss((dh.get_fe().degree + 1) * 2);
615
616 for (const auto &norm : norms)
617 {
618 difference_per_cell = 0;
619 VectorTools::integrate_difference(mapping,
620 dh,
621 solution,
622 exact,
623 difference_per_cell,
624 q_gauss,
625 norm,
626 &select_component,
627 exponent);
628
629 errors[norm] = VectorTools::compute_global_error(
630 dh.get_triangulation(), difference_per_cell, norm, exponent);
631
632 std::string name = unique_component_names[i] + "_" +
633 Patterns::Tools::to_string(norm);
634 std::string latex_name = "$\\| " + unique_component_names[i] +
635 " - " + unique_component_names[i] +
636 "_h \\|_{" +
637 Patterns::Tools::to_string(norm) + "}$";
638
639 table.add_value(name, errors[norm]);
640 table.set_precision(name, precision);
641 table.set_scientific(name, true);
642 table.set_tex_caption(name, latex_name);
643 }
644 }
645
646 for (const auto &extra_col : extra_column_functions)
647 {
648 const double custom_error = extra_col.second.first();
649
650 std::string name = extra_col.first;
651 table.add_value(name, custom_error);
652 table.set_precision(name, precision);
653 table.set_scientific(name, true);
654 }
655 }
656 }
657
658 #endif
659
660 DEAL_II_NAMESPACE_CLOSE
661
662 #endif