Debian Codegraph @

include/deal.II/algorithms/timestep_control.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 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
16 #ifndef dealii_time_step_control_h
17 #define dealii_time_step_control_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/observer_pointer.h>
23
24 #include <deal.II/lac/vector_memory.h>
25
26 #include <cstdio>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 // Forward declaration
31 #ifndef DOXYGEN
32 class ParameterHandler;
33 #endif
34
35 namespace Algorithms
36 {
37 /**
38 * Control class for timestepping schemes. Its main task is determining the
39 * size of the next time step and the according point in the time interval.
40 * Additionally, it controls writing the solution to a file.
41 *
42 * The size of the next time step is determined as follows:
43 * <ol>
44 * <li> According to the strategy, the step size is tentatively added to the
45 * current time.
46 * <li> If the resulting time exceeds the final time of the interval, the
47 * step size is reduced in order to meet this time.
48 * <li> If the resulting time is below the final time by just a fraction of
49 * the step size, the step size is increased in order to meet this time.
50 * <li> The resulting step size is used from the current time.
51 * </ol>
52 *
53 * The variable @p print_step can be used to control the amount of output
54 * generated by the timestepping scheme.
55 *
56 * @note Many of the features of this class are available in DiscreteTime
57 * with a more modern interface and better programming guarantees. Consider
58 * using DiscreteTime instead of TimestepControl.
59 */
60 class TimestepControl : public EnableObserverPointer
61 {
62 public:
63 /**
64 * Constructor setting default values
65 */
66 TimestepControl(double start = 0.,
67 double final = 1.,
68 double tolerance = 1.e-2,
69 double start_step = 1.e-2,
70 double print_step = -1.,
71 double max_step = 1.);
72
73 /**
74 * Declare the control parameters for parameter handler.
75 */
76 static void
77 declare_parameters(ParameterHandler &param);
78
79 /**
80 * Read the control parameters from a parameter handler.
81 *
82 * This function also calls restart() to reset all other internal
83 * parameters of this class to their appropriate values based on
84 * the parameters just read.
85 */
86 void
87 parse_parameters(const ParameterHandler &param);
88
89 /**
90 * Return the left end of the time interval.
91 */
92 double
93 start() const;
94 /**
95 * Return the right end of the time interval. The control mechanism
96 * ensures that the final time step ends at this point.
97 */
98 double
99 final() const;
100 /**
101 * Return the tolerance value controlling the time steps.
102 */
103 double
104 tolerance() const;
105 /**
106 * Return the size of the current time step.
107 */
108 double
109 step() const;
110
111 /**
112 * Return the current time.
113 */
114 double
115 now() const;
116
117 /**
118 * Compute the size of the next step and return true if it differs from
119 * the current step size. Advance the current time by the new step size.
120 */
121 bool
122 advance();
123
124 /**
125 * Set start value.
126 */
127 void
128 start(double);
129 /**
130 * Set final time value.
131 */
132 void
133 final(double);
134 /**
135 * Set tolerance
136 */
137 void
138 tolerance(double);
139
140 /**
141 * Set size of the first step. This may be overwritten by the time
142 * stepping strategy.
143 *
144 * @param[in] step The size of the first step, which may be overwritten by
145 * the time stepping strategy.
146 */
147 void
148 start_step(const double step);
149
150 /**
151 * Set size of the maximum step size.
152 */
153 void
154 max_step(double);
155
156 /**
157 * Set now() equal to start(). Initialize step() and print() to their
158 * initial values.
159 */
160 void
161 restart();
162
163 /**
164 * Return true if this timestep should be written to disk.
165 */
166 bool
167 print();
168
169 private:
170 /**
171 * The beginning of the time interval.
172 */
173 double start_val;
174
175 /**
176 * The end of the time interval.
177 */
178 double final_val;
179
180 /**
181 * The tolerance value controlling the time steps.
182 */
183 double tolerance_val;
184
185 /**
186 * The size of the first step.
187 */
188 double start_step_val;
189
190 /**
191 * The maximum step size.
192 */
193 double max_step_val;
194
195 /**
196 * The minimum step size.
197 */
198 double min_step_val;
199
200 /**
201 * The size of the current time step. This may differ from @p step_val, if
202 * we aim at @p final_val.
203 */
204 double current_step_val;
205
206 /**
207 * The size of the current time step determined by the strategy. This may
208 * differ from @p current_step_val, if we aim at @p final_val.
209 */
210 double step_val;
211
212 /**
213 * The current time.
214 */
215 double now_val;
216
217 /**
218 * Determines the approximate time interval between generated outputs.
219 * If negative, output will be generated at all time steps.
220 */
221 double print_step;
222
223 /**
224 * If current time exceeds this value, it is time to generate the output.
225 */
226 double next_print_val;
227 };
228
229
230 inline double
231 TimestepControl::start() const
232 {
233 return start_val;
234 }
235
236
237 inline double
238 TimestepControl::final() const
239 {
240 return final_val;
241 }
242
243
244 inline double
245 TimestepControl::step() const
246 {
247 return current_step_val;
248 }
249
250
251 inline double
252 TimestepControl::tolerance() const
253 {
254 return tolerance_val;
255 }
256
257
258 inline double
259 TimestepControl::now() const
260 {
261 return now_val;
262 }
263
264
265 inline void
266 TimestepControl::start(double t)
267 {
268 start_val = t;
269 }
270
271
272 inline void
273 TimestepControl::final(double t)
274 {
275 final_val = t;
276 }
277
278
279 inline void
280 TimestepControl::tolerance(double t)
281 {
282 tolerance_val = t;
283 }
284
285
286 inline void
287 TimestepControl::start_step(const double t)
288 {
289 start_step_val = t;
290 }
291
292
293 inline void
294 TimestepControl::max_step(double t)
295 {
296 max_step_val = t;
297 }
298
299
300 inline void
301 TimestepControl::restart()
302 {
303 now_val = start_val;
304 step_val = start_step_val;
305 current_step_val = step_val;
306 if (print_step > 0.)
307 next_print_val = now_val + print_step;
308 else
309 next_print_val = now_val - 1.;
310 }
311
312 } // namespace Algorithms
313
314 DEAL_II_NAMESPACE_CLOSE
315
316 #endif