Debian Codegraph @

include/deal.II/base/discrete_time.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_discrete_time_h
16 #define dealii_discrete_time_h
17
18 #include <deal.II/base/config.h>
19
20 #include <cstddef>
21
22
23 DEAL_II_NAMESPACE_OPEN
24
25 /**
26 * This class provides a means to keep track of the simulation time in a
27 * time-dependent simulation. It manages stepping forward from a start time
28 * $T_{\text{start}}$ to an end time $T_{\text{end}}$. It also allows adjusting
29 * the time step size during the simulation. This class provides the necessary
30 * interface to be incorporated in any time-dependent simulation.
31 * The usage of this class is demonstrated in step-19 (and step-83) as well as
32 * step-21.
33 *
34 * This class provides a number of invariants that are guaranteed to be
35 * true at all times.
36 *
37 * * The current simulation time is within the closed interval between the
38 * start time and the end time ($T_{\text{start}} \le t \le T_{\text{end}}$).
39 * * Whenever time is incremented, the step size is positive ($dt > 0$).
40 * In other words, time advances in strictly ascending order
41 * ($m < n \Leftrightarrow t_m < t_n$).
42 *
43 * The model this class follows is that one sets a *desired* time step length
44 * either through the constructor or using set_desired_next_step_size()
45 * function. This step size will then be used in all following calls to the
46 * advance_time() function, but may be adjusted slightly towards the end of the
47 * simulation to ensure that the simulation time hits the end time exactly. The
48 * adjustment is useful for the following reasons:
49 *
50 * Let's say that you loop over all of the time steps by using a `for` loop
51 * @code
52 * for (DiscreteTime time(0., 1., 0.3);
53 * time.is_at_end() == false;
54 * time.advance_time())
55 * {
56 * // Insert simulation code here
57 * }
58 * @endcode
59 * or, if you like this better, the equivalent `while` loop:
60 * @code
61 * DiscreteTime time(0., 1., 0.3);
62 * while (time.is_at_end() == false)
63 * {
64 * // Insert simulation code here
65 *
66 * time.advance_time();
67 * }
68 * @endcode
69 *
70 * In the above example the time starts at $T_{\text{start}} = 0$ until
71 * $T_{\text{end}}=1$. Assuming the time step $dt = 0.3$ is not modified inside
72 * the loop, the time is advanced from $t = 0$ to $t = 0.3$, $t = 0.6$, $t =
73 * 0.9$ and finally it reaches the end time at $t = 1.0$. Here, the final step
74 * size needs to be reduced from its desired value of 0.3 to $dt = 0.1$ in order
75 * to ensure that we finish the simulation exactly at the specified end time. In
76 * fact, you should assume that not only the last time step length may be
77 * adjusted, but also previously ones -- for example, this class may take the
78 * liberty to spread the decrease in time step size out over several time steps
79 * and increment time from $t=0$, to $0.3$, $0.6$, $0.8$, and finally
80 * $t=T_{\text{end}}=1$ to avoid too large a change in time step size from one
81 * step to another.
82 *
83 * The other situation in which the time step needs to be adjusted (this time to
84 * slightly larger values) is if a time increment falls just short of the final
85 * time. Imagine, for example, a similar situation as above, but with different
86 * end time:
87 * @code
88 * for (DiscreteTime time(0., 1.21, 0.3);
89 * time.is_at_end() == false;
90 * time.advance_time())
91 * {
92 * // Insert simulation code here
93 * }
94 * @endcode
95 * Here, the time step from $t=0.9$ to $t=1.2$ falls just short of the final
96 * time $T_{\text{end}}=1.21$. Instead of following up with a very small step of
97 * length $dt=0.01$, the class stretches the last time step (or last time steps)
98 * slightly to reach the desired end time.
99 *
100 * The examples above make clear that the time step size given to this class is
101 * only a *desired* step size. You can query the actual time step size using the
102 * get_next_step_size() function.
103 *
104 *
105 * ### Details of time-stepping
106 *
107 * Since time is marched forward in a discrete manner in our simulations, we
108 * need to discuss how we increment time. During time stepping we enter two
109 * separate alternating regimes in every step.
110 *
111 * * The **snapshot** stage (the **current** stage, the **consistent**
112 * stage): In this part of the algorithm, we are at $t = t_n$ and all
113 * quantities of the simulation (displacements, strains, temperatures, etc.)
114 * are up-to-date for $t = t_n$. In this stage, *current time* refers to
115 * $t_n$, *next time* refers to $t_{n+1}$, *previous time* refers to
116 * $t_{n-1}$. The other useful notation quantities are the *next* time step
117 * size $t_{n+1} - t_n$ and *previous* time step size $t_n - t_{n-1}$. In
118 * this stage, it is a perfect occasion to generate text output using print
119 * commands within the user's code. Additionally, post-processed outputs can
120 * be prepared here, which can then later be viewed by visualization programs
121 * such as `Tecplot`, `Paraview`, and `VisIt`. Additionally, during the
122 * snapshot stage, the code can assess the quality of the previous step and
123 * decide whether it wants to increase or decrease the time step size. The
124 * step size for the next time step can be modified here, by calling
125 * set_desired_next_step_size().
126 * * The **update** stage (the **transition** stage, the **inconsistent**
127 * stage): In this section of the program, the internal state of the
128 * simulation is getting updated from $t_n$ to $t_{n+1}$. All of the
129 * variables need to be updated one by one, the step number is incremented,
130 * the time is incremented by $dt = t_{n+1} - t_n$, and time-integration
131 * algorithms are used to update the other simulation quantities. In the
132 * middle of this stage, some variables have been updated to $t_{n+1}$ but
133 * other variables still represent their value at $t_n$. Thus, we call this
134 * the inconsistent stage, requiring that no post-processing output related
135 * to the state variables take place within it. The state variables, namely
136 * those related to time, the solution field and any internal variables, are
137 * not synchronized and then get updated one by one. In general, the order of
138 * updating variables is arbitrary, but some care should be taken if there
139 * are interdependencies between them. For example, if some variable such as
140 * $x$ depends on the calculation of another variable such as $y$, then $y$
141 * must be updated before $x$ can be updated.
142 *
143 * The question arises whether time should be incremented before updating
144 * state quantities. Multiple possibilities exist, depending on program and
145 * formulation requirements, and possibly the programmer's preferences:
146 * * Time is incremented *before* the rest of the updates. In this case, even
147 * though time is incremented to $t_{n+1}$, not all variables are updated
148 * yet. During this update phase, $dt$ equals the *previous* time step
149 * size. *Previous* means that it is referring to the $dt$ of the
150 * `advance_time()` command that was performed previously. In the
151 * following example code, we are assuming that `a` and `b` are two state
152 * variables that need to be updated in this time step.
153 * @code
154 * time.advance_time();
155 * new_a = update_a(a, b, time.get_previous_step_size());
156 * b = update_b(a, b, time.get_previous_step_size());
157 * a = new_a;
158 * @endcode
159 * Here, the code starts in a consistent state, but once advance_time()
160 * is called, the time variable, `a`, and `b` are no longer consistent
161 * with each other until after the last statement. At that point,
162 * the variables are all consistent again.
163 * * Time is incremented from $t_n$ to $t_{n+1}$ *after* all variables have
164 * already been updated for $t_{n+1}$. During the update stage, $dt$ is
165 * denoted as the *next* time step size. *Next* means that $dt$ of the
166 * step corresponds to the `advance_time()` command that will happen
167 * subsequently.
168 * @code
169 * new_a = update_a(a, b, time.get_next_step_size());
170 * b = update_b(a, b, time.get_next_step_size());
171 * a = new_a;
172 * time.advance_time();
173 * @endcode
174 * * Time is incremented in the middle of the other updates: In this case
175 * $dt$ would correspond to *next* or *previous* depending of whether it
176 * is used before or after the call to `advance_time()`.
177 * @code
178 * new_a = update_a(a, b, time.get_next_step_size());
179 * time.advance_time();
180 * b = update_b(a, b, time.get_previous_step_size());
181 * a = new_a;
182 * @endcode
183 *
184 * One thing to note is that, during the update phase, $dt$ is referred to
185 * either **next** or **previous** time step size, depending on whether
186 * advance_time() has been called yet. The notion of *current* time
187 * step size is ill-defined. In fact, in the update stage the definition of
188 * every variable depends on whether it has been updated yet or not, hence the
189 * name **the inconsistent stage**.
190 *
191 * The following code snippet shows the code sections for the snapshot stage
192 * and the update stage in the context of a complete time-dependent
193 * simulation. This code follows the coding conventions incorporated in the
194 * tutorial examples. Note that even though this example is written in the
195 * format of a `for` loop, it can equivalently be written as a `while` or
196 * `do while` loop (as shown in step-21).
197 * @code
198 * // pre-processing/setup stage {
199 * make_grid();
200 * setup_system();
201 * for (DiscreteTime time(0., 1., 0.1); // } end pre-processing/setup stage
202 * time.is_at_end() == false;
203 * time.advance_time()) // part of the update stage, runs at
204 * // the end of the loop body
205 * {
206 * // snapshot stage {
207 * const double time_of_simulation = time.get_next_time();
208 * const double timestep_size = time.get_next_step_size();
209 *
210 * std::cout
211 * << "Timestep: " << time.get_step_number() << " -- "
212 * << "Solving for the solution at "
213 * << "t = " << time_of_simulation << " with "
214 * << "dt = " << timestep_size << '.' << std::endl;
215 * // } end snapshot stage
216 *
217 * // update stage {
218 * assemble_system(time_of_simulation, timestep_size);
219 * solve();
220 * update_solutions();
221 * // } end update stage
222 *
223 * // snapshot stage {
224 * output_results(time_of_solution);
225 *
226 * // propose a new timestep size if need be
227 * // time.set_desired_next_step_size(...);
228 * // } end snapshot stage
229 * }
230 * @endcode
231 * The `run()` function in step-19 shows a very similar example where the call
232 * to advance_time() ends the update stage and is followed by generating
233 * graphical output with the then-current time.
234 */
235 class DiscreteTime
236 {
237 public:
238 /**
239 * Constructor.
240 *
241 * @param[in] start_time The time at the start of the simulation.
242 *
243 * @param[in] end_time The time at the end of the simulation.
244 *
245 * @param[in] desired_start_step_size A desired step size for incrementing
246 * time for the first step. It is not guaranteed that this value will be
247 * actually used as the size of the first step, as discussed in the
248 * introduction.
249 *
250 * @pre @p desired_start_step_size must be non-negative.
251 *
252 * @note @p desired_start_step_size is an optional parameter. If it is not
253 * provided or it is specified as zero, it indicates that the
254 * desired size for the time step will be calculated at a different location
255 * in the code. In this case, the created object cannot increment time until
256 * the step size is changed by calling set_desired_next_step_size().
257 */
258 DiscreteTime(const double start_time,
259 const double end_time,
260 const double desired_start_step_size = 0.);
261
262 /**
263 * Return the current time.
264 */
265 double
266 get_current_time() const;
267
268 /**
269 * Return the next time that we would reach if we were to advance the time
270 * by one step.
271 *
272 * @note If the simulation is at the end time, this method returns the
273 * end time.
274 */
275 double
276 get_next_time() const;
277
278 /**
279 * Return the time we were at before `advance_time()` was called last time.
280 *
281 * @note If the simulation is at the start time, this method returns the
282 * start time.
283 */
284 double
285 get_previous_time() const;
286
287 /**
288 * Return the start time.
289 */
290 double
291 get_start_time() const;
292
293 /**
294 * Return the end of the time interval.
295 * The final time step ends exactly at this point. This exact floating-point
296 * equality is very important because it allows us to equality-compare
297 * current time with end time and decide whether we have reached the end of
298 * the simulation.
299 */
300 double
301 get_end_time() const;
302
303 /**
304 * Return whether no step has taken place yet.
305 */
306 bool
307 is_at_start() const;
308
309 /**
310 * Return whether time has reached the end time.
311 */
312 bool
313 is_at_end() const;
314
315 /**
316 * Return the size of the step from current time step to the
317 * next. As discussed in the introduction to the class, this is the
318 * *actual* time step, and may differ from the *desired* time step
319 * set in the constructor or through the
320 * set_desired_next_step_size() function.
321 *
322 * @note If the simulation is at the end time, this method returns zero.
323 */
324 double
325 get_next_step_size() const;
326
327 /**
328 * Return the step size of the previous step.
329 *
330 * @note If the simulation is at the start time, this method returns zero.
331 */
332 double
333 get_previous_step_size() const;
334
335 /**
336 * Return the number of times the simulation time has been incremented.
337 * Return zero when the simulation is at the start time.
338 */
339 unsigned int
340 get_step_number() const;
341
342 /**
343 * Set the *desired* value of the next time step size. By calling this
344 * method, we are indicating the next time advance_time() is called, we
345 * would like @p time_step_size to be used to advance the simulation time.
346 * However, if the step is too large such that the next
347 * simulation time exceeds the end time, the step size is truncated.
348 * Additionally, if the step size is such that the next simulation time
349 * approximates the end time (but falls just slightly short of it), the step
350 * size is adjusted such that the next simulation time exactly matches the
351 * end time.
352 */
353 void
354 set_desired_next_step_size(const double time_step_size);
355
356 /**
357 * Set the *actual* value of the next time step size. By calling this
358 * method, we are indicating the next time advance_time() is called,
359 * @p time_step_size is to be used to advance the simulation time.
360 *
361 * @note The difference between set_next_step_size() and
362 * set_desired_next_step_size() is that the former uses the provided $dt$
363 * exactly without any adjustment, but produces an
364 * error (in debug mode) if $dt$ is not in the acceptable range.
365 * Generally, set_desired_next_step_size() is the preferred method because
366 * it can adjust the $dt$ intelligently, based on $T_{\text{end}}$.
367 * @pre $0 < dt \le T_{\text{end}} - t$.
368 */
369 void
370 set_next_step_size(const double time_step_size);
371
372 /**
373 * Advance the current time based on the value of the current step.
374 * If you want to adjust the next time step size, call the method
375 * set_desired_next_step_size() before calling this method.
376 * If you call this function repeatedly, the time
377 * is increased with the same step size until it reaches the end
378 * time. See the documentation of set_desired_next_step_size() for
379 * explanation of the rules for automatic adjustment of the step size.
380 *
381 * @pre Current time must be smaller than the end time. The object cannot
382 * advance time if it is already at the end time. This rule is created to
383 * avoid the creation of an infinite loop when advance_time() is called
384 * inside a loop.
385 *
386 * @pre The time step size must be nonzero. If the step size is currently
387 * zero, change it by calling set_desired_next_step_size() before calling
388 * advance_time().
389 */
390 void
391 advance_time();
392
393 /**
394 * Set the current time equal to start time and set the step size to the
395 * initial step size.
396 */
397 void
398 restart();
399
400 /**
401 * Determine an estimate for the memory consumption (in bytes) of this
402 * object.
403 */
404 std::size_t
405 memory_consumption() const;
406
407 /**
408 * Write or read the data of this object to or from a stream for the purpose
409 * of serialization using the [BOOST serialization
410 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
411 *
412 * This function is used in step-83.
413 */
414 template <class Archive>
415 void
416 serialize(Archive &ar, const unsigned int version);
417
418 private:
419 /**
420 * The beginning of the time interval.
421 */
422 double start_time;
423
424 /**
425 * The end of the time interval.
426 */
427 double end_time;
428
429 /**
430 * The current time.
431 */
432 double current_time;
433
434 /**
435 * The time at the next step.
436 *
437 * @note Internally, the next simulation time is stored instead of the
438 * current step size. For example, when the method
439 * set_desired_next_step_size() is called, it computes the appropriate next
440 * simulation time and stores it. When advance_time() is called, the
441 * current_time is replaced by next_time. This choice for the internal state
442 * allows for simpler code and ensures than when we call advance_time() at
443 * the last step, the floating-point value of the time exactly matches the
444 * end time.
445 */
446 double next_time;
447
448 /**
449 * The previous time.
450 */
451 double previous_time;
452
453 /**
454 * The size of the first step.
455 */
456 double start_step_size;
457
458 /**
459 * The step number i.e. the number of times the simulation time ha been
460 * incremented.
461 */
462 unsigned int step_number;
463 };
464
465
466 /*---------------------- Inline functions ------------------------------*/
467
468
469 inline double
470 DiscreteTime::get_start_time() const
471 {
472 return start_time;
473 }
474
475
476
477 inline double
478 DiscreteTime::get_end_time() const
479 {
480 return end_time;
481 }
482
483
484
485 inline bool
486 DiscreteTime::is_at_start() const
487 {
488 return step_number == 0;
489 }
490
491
492
493 inline bool
494 DiscreteTime::is_at_end() const
495 {
496 return current_time == end_time;
497 }
498
499
500
501 inline double
502 DiscreteTime::get_next_step_size() const
503 {
504 return next_time - current_time;
505 }
506
507
508
509 inline double
510 DiscreteTime::get_previous_step_size() const
511 {
512 return current_time - previous_time;
513 }
514
515
516
517 inline double
518 DiscreteTime::get_current_time() const
519 {
520 return current_time;
521 }
522
523
524
525 inline double
526 DiscreteTime::get_next_time() const
527 {
528 return next_time;
529 }
530
531
532
533 inline double
534 DiscreteTime::get_previous_time() const
535 {
536 return previous_time;
537 }
538
539
540
541 inline unsigned int
542 DiscreteTime::get_step_number() const
543 {
544 return step_number;
545 }
546
547
548
549 template <class Archive>
550 inline void
551 DiscreteTime::serialize(Archive &ar, const unsigned int)
552 {
553 ar &start_time;
554 ar &end_time;
555 ar &current_time;
556 ar &next_time;
557 ar &previous_time;
558 ar &start_step_size;
559 ar &step_number;
560 }
561
562 DEAL_II_NAMESPACE_CLOSE
563
564 #endif