Debian Codegraph @

include/deal.II/base/convergence_table.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_convergence_table_h
16 #define dealii_convergence_table_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/table_handler.h>
23 #include <deal.II/base/types.h>
24
25 #include <ostream>
26 #include <string>
27
28
29 DEAL_II_NAMESPACE_OPEN
30
31
32 /**
33 * The ConvergenceTable class is an application to the TableHandler class and
34 * stores some convergence data, such as residuals of the cg-method, or some
35 * evaluated <i>L<sup>2</sup></i>-errors of discrete solutions, etc, and
36 * evaluates convergence rates or orders.
37 *
38 * The already implemented #RateMode's are #reduction_rate, where the
39 * convergence rate is the quotient of two following rows, and
40 * #reduction_rate_log2, that evaluates the order of convergence. These
41 * standard evaluations are useful for global refinement, for local refinement
42 * this may not be an appropriate method, as the convergence rates should be
43 * set in relation to the number of cells or the number of DoFs. The
44 * implementations of these non-standard methods is left to a user.
45 *
46 * For example, the number of cells may be added to the table by
47 * calling `add_value("n cells", n_cells)`. The number of DoFs may be
48 * added to the table by calling `add_value("n dofs", n_dofs)`. Of course,
49 * one can also add more kinds of information by calling
50 * add_value() with other arguments. In any case, before the output of the table
51 * the functions evaluate_convergence_rates() and
52 * evaluate_all_convergence_rates() may be called.
53 *
54 * There are two possibilities of how to evaluate the convergence rates of
55 * multiple columns in the same RateMode.
56 * <ol>
57 * <li> call evaluate_convergence_rates() for all wanted columns
58 * <li> call omit_column_from_convergence_rate_evaluation() for all columns
59 * for which this evaluation is not desired and then
60 * evaluate_all_convergence_rates() to evaluate the convergence rates of all
61 * columns that have not been flagged for omission.
62 * </ol>
63 *
64 * A detailed discussion of this class can also be found in the step-7 and
65 * step-13 example programs. It is also used in step-74.
66 *
67 * @ingroup textoutput
68 */
69 class ConvergenceTable : public TableHandler
70 {
71 public:
72 /**
73 * Constructor.
74 */
75 ConvergenceTable() = default;
76
77 /**
78 * Rate in relation to the rows.
79 */
80 enum RateMode
81 {
82 /**
83 * Do not do anything.
84 */
85 none,
86 /**
87 * Quotient of values in the previous row and in this row.
88 */
89 reduction_rate,
90 /**
91 * Logarithm of #reduction_rate to the base 2 representing the order of
92 * convergence when halving the grid size, e.g. from h to h/2.
93 */
94 reduction_rate_log2
95 };
96
97 /**
98 * Evaluate the convergence rates of the data column
99 * <tt>data_column_key</tt> due to the #RateMode in relation to the
100 * reference column <tt>reference_column_key</tt>. Be sure that the value
101 * types of the table entries of the data column and the reference data
102 * column is a number, i.e. double, float, (unsigned) int, and so on.
103 *
104 * As this class has no information on the space dimension upon which the
105 * reference column vs. the value column is based upon, it needs to be
106 * passed as last argument to this method. The <i>default dimension for the
107 * reference column</i> is 2, which is appropriate for the number of cells
108 * in 2d. If you work in 3d, set the number to 3. If the reference column is
109 * $1/h$, remember to set the dimension to 1 also when working in 3d to get
110 * correct rates.
111 *
112 * The new rate column and the data column will be merged to a supercolumn.
113 * The tex caption of the supercolumn will be (by default) the same as the
114 * one of the data column. This may be changed by using the
115 * <tt>set_tex_supercaption (...)</tt> function of the base class
116 * TableHandler.
117 *
118 * This method behaves in the following way:
119 *
120 * If RateMode is reduction_rate, then the computed output is $
121 * \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $ where $k$ is the reference column (no
122 * dimension dependence!).
123 *
124 * If RateMode is reduction_rate_log2, then the computed output is $ dim
125 * \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} $.
126 *
127 * This is useful, for example, if we use as reference key the number of
128 * degrees of freedom or better, the number of cells. Assuming that the
129 * error is proportional to $ C (1/\sqrt{k})^r $ in 2d, then this method
130 * will produce the rate $r$ as a result. For general dimension, as
131 * described by the last parameter of this function, the formula needs to be
132 * $ C (1/\sqrt[dim]{k})^r $.
133 *
134 * @note Since this function adds columns to the table after several rows
135 * have already been filled, it switches off the auto fill mode of the
136 * TableHandler base class. If you intend to add further data with auto
137 * fill, you will have to re-enable it after calling this function.
138 */
139 void
140 evaluate_convergence_rates(const std::string &data_column_key,
141 const std::string &reference_column_key,
142 const RateMode rate_mode,
143 const unsigned int dim = 2);
144
145
146 /**
147 * Evaluate the convergence rates of the data column
148 * <tt>data_column_key</tt> due to the #RateMode. Be sure that the value
149 * types of the table entries of the data column is a number, i.e. double,
150 * float, (unsigned) int, and so on.
151 *
152 * The new rate column and the data column will be merged to a supercolumn.
153 * The tex caption of the supercolumn will be (by default) the same as the
154 * one of the data column. This may be changed by using the
155 * set_tex_supercaption() function of the base class TableHandler.
156 *
157 * @note Since this function adds columns to the table after several rows
158 * have already been filled, it switches off the auto fill mode of the
159 * TableHandler base class. If you intend to add further data with auto
160 * fill, you will have to re-enable it after calling this function.
161 */
162 void
163 evaluate_convergence_rates(const std::string &data_column_key,
164 const RateMode rate_mode);
165
166 /**
167 * Omit this column <tt>key</tt> (not supercolumn!) from the evaluation of
168 * the convergence rates of `all' columns (see the following two functions).
169 *
170 * The Column::flag==1 is reserved for omitting the column from convergence
171 * rate evaluation.
172 */
173 void
174 omit_column_from_convergence_rate_evaluation(const std::string &key);
175
176 /**
177 * Evaluate convergence rates due to the <tt>rate_mode</tt> in relation to
178 * the reference column <tt>reference_column_key</tt>. This function
179 * evaluates the rates of ALL columns except of the columns that are to be
180 * omitted (see previous function) and except of the columns that are
181 * previously evaluated rate columns. This function allows to evaluate the
182 * convergence rate for almost all columns of a table without calling
183 * evaluate_convergence_rates() for each column separately.
184 *
185 * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
186 * wanted to be omitted in the evaluation of the convergence rates. Hence
187 * they should omitted by calling the
188 * omit_column_from_convergence_rate_evaluation().
189 */
190 void
191 evaluate_all_convergence_rates(const std::string &reference_column_key,
192 const RateMode rate_mode);
193
194 /**
195 * Evaluate convergence rates due to the <tt>rate_mode</tt>. This function
196 * evaluates the rates of ALL columns except of the columns that are to be
197 * omitted (see previous function) and except of the columns that are
198 * previously evaluated rate columns. This function allows to evaluate the
199 * convergence rate for almost all columns of a table without calling
200 * evaluate_convergence_rates() for each column separately.
201 *
202 * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
203 * wanted to be omitted in the evaluation of the convergence rates. Hence
204 * they should omitted by calling the
205 * omit_column_from_convergence_rate_evaluation().
206 */
207 void
208 evaluate_all_convergence_rates(const RateMode rate_mode);
209
210 /**
211 * @addtogroup Exceptions
212 * @{
213 */
214
215 /**
216 * Exception
217 */
218 DeclException1(ExcRateColumnAlreadyExists,
219 std::string,
220 << "Rate column <" << arg1 << "> does already exist.");
221 /** @} */
222 };
223
224
225 DEAL_II_NAMESPACE_CLOSE
226
227 #endif