Debian Codegraph @

include/deal.II/numerics/time_dependent.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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 #ifndef dealii_time_dependent_h
16 #define dealii_time_dependent_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/observer_pointer.h>
24 #include <deal.II/base/template_constraints.h>
25
26 #include <utility>
27 #include <vector>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 // forward declarations
32 #ifndef DOXYGEN
33 class TimeStepBase;
34 template <typename number>
35 class Vector;
36 template <int dim, int spacedim>
37 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
38 class Triangulation;
39 #endif
40
41 /**
42 * This class provides an abstract interface to time dependent problems in
43 * that it addresses some of the most annoying aspects of this class of
44 * problems: data management. These problems frequently need large amounts of
45 * computer resources, most notably computing time, main memory and disk
46 * space. Main memory reduction is often the most pressing need, methods to
47 * implement it are almost always quite messy, though, quickly leading to code
48 * that stores and reloads data at places scattered all over the program, and
49 * which becomes unmaintainable sometimes. The present class tries to offer a
50 * more structured interface, albeit simple, which emerged in my mind after
51 * messing with my wave equation simulation for several months.
52 *
53 * The design of this class is mostly tailored for the solution of time
54 * dependent partial differential equations where the computational meshes may
55 * differ between each two timesteps and where the computations on each time
56 * step take a rather long time compared with the overhead of this class.
57 * Since no reference to the class of problems is made within this class, it
58 * is not restricted to PDEs, though, and it seems likely that a solver for
59 * large ordinary matrix differential equations may successfully use the same
60 * setup and therefore this class.
61 *
62 *
63 * <h3>Overview</h3>
64 *
65 * The general structure of a time dependent problem solver using a
66 * timestepping scheme is about the following: we have a collection of time
67 * step objects on which we solve our problem subsequently. In order to do so,
68 * we need knowledge of the data on zero or several previous timesteps (when
69 * using single or multiple step methods, that is) and maybe also some data of
70 * time steps ahead (for example the computational grid on these). Depending
71 * on the problem in question, a second loop over all timesteps may be done
72 * solving a dual problem, where the loop may run forward (one dual problem
73 * for each time step) or backward (using a global dual problem). Within one
74 * of these loops or using a separate loop, error estimators may be computed
75 * and the grids may be refined. Each of these loops are initiated by a call
76 * preparing each timestep object for the next loop, before actually starting
77 * the loop itself.
78 *
79 * We will denote a complete set of all these loops with the term "sweep".
80 * Since this library is mostly about adaptive methods, it is likely that the
81 * last loop within a sweep will generate refined meshes and that we will
82 * perform another sweep on these refined meshes. A total run will therefore
83 * often be a sequence of several sweeps. The global setup therefore looks
84 * like this:
85 * @verbatim
86 * for sweep=0 to n_sweeps-1
87 * {
88 * for i=0 to n_timesteps-1
89 * initialize timestep i for this sweep, e.g. for setting up
90 * data structures, creating temporary files, etc.
91 *
92 * for i=0 to n_timesteps-1
93 * prepare timestep i for loop 0
94 * for i=0 to n_timesteps-1
95 * perform loop 0 on timestep i (e.g. solve primal problem)
96 *
97 * for i=0 to n_timesteps-1
98 * prepare timestep i for loop 1
99 * for i=0 to n_timesteps-1
100 * perform loop 1 on timestep i (e.g. solve dual problem)
101 *
102 * for i=0 to n_timesteps-1
103 * prepare timestep i for loop 2
104 * for i=0 to n_timesteps-1
105 * perform loop 2 on timestep i (e.g. compute error information)
106 *
107 * ...
108 *
109 * for i=0 to n_timesteps-1
110 * notify timestep i of the end of the sweep, e.g. for cleanups,
111 * deletion of temporary files, etc.
112 * }
113 * @endverbatim
114 * The user may specify that a loop shall run forward or backward (the latter
115 * being needed for the solution of global dual problems, for example).
116 *
117 * Going from the global overview to a more local viewpoint, we note that when
118 * a loop visits one timestep (e.g. to solve the primal or dual problem, or to
119 * compute error information), we need information on this, one or more
120 * previous time steps and zero or more timesteps in the future. However,
121 * often it is not needed to know all information from these timesteps and it
122 * is often a computational requirement to delete data at the first possible
123 * time when it is no more needed. Likewise, data should be reloaded at the
124 * latest time possible.
125 *
126 * In order to facilitate these principles, the concept of waking up and
127 * letting sleep a time step object was developed. Assume we have a time
128 * stepping scheme which needs to look ahead one time step and needs the data
129 * of the last two time steps, the following pseudocode describes what the
130 * central loop function of this class will do when we move from timestep @p
131 * n-1 to timestep @p n:
132 * @verbatim
133 * wake up timestep n+1 with signal 1
134 * wake up timestep n with signal 0
135 * do computation on timestep n
136 * let timestep n sleep with signal 0
137 * let timestep n-1 sleep with signal 1
138 * let timestep n-2 sleep with signal 2
139 *
140 * move from n to n+1
141 * @endverbatim
142 * The signal number here denotes the distance of the timestep being sent the
143 * signal to the timestep where computations are done on. The calls to the @p
144 * wake_up and @p sleep functions with signal 0 could in principle be absorbed
145 * into the function doing the computation; we use these redundant signals,
146 * however, in order to separate computations and data management from each
147 * other, allowing to put all stuff around grid management, data reload and
148 * storage into one set of functions and computations into another.
149 *
150 * In the example above, possible actions might be: timestep <tt>n+1</tt>
151 * rebuilds the computational grid (there is a specialized class which can do
152 * this for you); timestep @p n builds matrices and sets solution vectors to
153 * the right size, maybe using an initial guess; then it does the computations;
154 * then it deletes the matrices since they are not needed by subsequent
155 * timesteps; timestep @p n-1 deletes those data vectors which are only needed
156 * by one timestep ahead; timestep @p n-2 deletes the remaining vectors and
157 * deletes the computational grid, somewhere storing information how to
158 * rebuild it eventually.
159 *
160 * From the given sketch above, it is clear that each time step object sees
161 * the following sequence of events:
162 * @verbatim
163 * wake up with signal 1
164 * wake up with signal 0
165 * do computation
166 * sleep with signal 0
167 * sleep with signal 1
168 * sleep with signal 2
169 * @endverbatim
170 * This pattern is repeated for each loop in each sweep.
171 *
172 * For the different loops within each sweep, the numbers of timesteps to look
173 * ahead (i.e. the maximum signal number to the @p wake_up function) and the
174 * look-behind (i.e. the maximum signal number to the @p sleep function) can
175 * be chosen separately. For example, it is usually only needed to look one
176 * time step behind when computing error estimation (in some cases, it may
177 * even be possible to not look ahead or back at all, in which case only
178 * signals zero will be sent), while one needs a look back of at least one for
179 * a timestepping method.
180 *
181 * Finally, a note on the direction of look-ahead and look-back is in place:
182 * look-ahead always refers to the direction the loop is running in, i.e. for
183 * loops running forward, @p wake_up is called for timestep objects with a
184 * greater time value than the one previously computed on, while @p sleep is
185 * called for timesteps with a lower time. If the loop runs in the opposite
186 * direction, e.g. when solving a global dual problem, this order is reversed.
187 *
188 *
189 * <h3>Implementation</h3>
190 *
191 * The main loop of a program using this class will usually look like the
192 * following one, taken modified from an application program that isn't
193 * distributed as part of the library:
194 * @code
195 * template <int dim>
196 * void TimeDependent_Wave<dim>::run_sweep (const unsigned int sweep_no)
197 * {
198 * start_sweep (sweep_no);
199 *
200 * solve_primal_problem ();
201 *
202 * if (compute_dual_problem)
203 * solve_dual_problem ();
204 *
205 * postprocess ();
206 *
207 * if (sweep_no != number_of_sweeps-1)
208 * refine_grids ();
209 *
210 * write_statistics ();
211 *
212 * end_sweep ();
213 * }
214 *
215 *
216 *
217 * template <int dim>
218 * void WaveProblem<dim>::run ()
219 * {
220 * for (unsigned int sweep=0; sweep<number_of_sweeps; ++sweep)
221 * timestep_manager.run_sweep (sweep);
222 * }
223 * @endcode
224 * Here, @p timestep_manager is an object of type TimeDependent_Wave<dim>, which
225 * is a class derived from TimeDependent. @p start_sweep, @p
226 * solve_primal_problem, @p solve_dual_problem, @p postprocess and @p
227 * end_sweep are functions inherited from this class. They all do a loop over
228 * all timesteps within this object and call the respective function on each
229 * of these objects. For example, here are two of the functions as they are
230 * implemented by the library:
231 * @code
232 * void TimeDependent::start_sweep (const unsigned int s)
233 * {
234 * sweep_no = s;
235 *
236 * // reset the number each time step has, since some time steps might have
237 * // been added since the last time we visited them.
238 * // also set the sweep we will process in the sequel
239 * for (unsigned int step=0; step<timesteps.size(); ++step)
240 * {
241 * timesteps[step]->set_timestep_no (step);
242 * timesteps[step]->set_sweep_no (sweep_no);
243 * }
244 *
245 * for (unsigned int step=0; step<timesteps.size(); ++step)
246 * timesteps[step]->start_sweep ();
247 * }
248 *
249 *
250 * void
251 * TimeDependent::solve_primal_problem ()
252 * {
253 * do_loop([](TimeStepBase *const time_step)
254 * { time_step->init_for_primal_problem(); },
255 * [](TimeStepBase *const time_step)
256 * { time_step->solve_primal_problem(); },
257 * timestepping_data_primal,
258 * forward);
259 * }
260 * @endcode
261 * The latter function shows rather clear how most of the loops are invoked
262 * (@p solve_primal_problem, @p solve_dual_problem, @p postprocess, @p
263 * refine_grids and @p write_statistics all have this form, where the latter
264 * two give functions of the derived timestep class, rather than from the base
265 * class). The function TimeStepBase::init_for_primal_problem and the
266 * respective ones for the other operations defined by that class are only
267 * used to store the type of operation which the loop presently performed will
268 * do.
269 *
270 * As can be seen, most of the work is done by the @p do_loop function of this
271 * class, which takes the addresses of two functions which are used to
272 * initialize all timestep objects for the loop and to actually perform some
273 * action. The next parameter gives some information on the look-ahead and
274 * look-back and the last one denotes in which direction the loop is to be
275 * run.
276 *
277 * Using lambda functions it is possible to do neat tricks, like the
278 * following in this case from the function @p refine_grids:
279 * @code
280 * ...
281 * compute the thresholds for refinement
282 * ...
283 *
284 * do_loop([](TimeStepBase_Tria<dim> *const time_step)
285 * { time_step->init_for_refinement(); },
286 * [=](TimeStepBase_Wave<dim> *const time_step)
287 * {
288 * time_step->solve_primal_problem(
289 * TimeStepBase_Tria<dim>::RefinementData (
290 * top_threshold, bottom_threshold)));
291 * },
292 * TimeDependent::TimeSteppingData (0,1),
293 * TimeDependent::forward);
294 * @endcode
295 * TimeStepBase_Wave<dim>::refine_grid is a function taking an argument, unlike
296 * all the other functions used above within the loops. However, in this special
297 * case the parameter was the same for all timesteps and known before the loop
298 * was started, so we fixed it and made a function object which to the outside
299 * world does not take parameters.
300 *
301 * Since it is the central function of this class, we finally present a
302 * stripped down version of the @p do_loop method, which is shown in order to
303 * provide a better understanding of the internals of this class. For brevity
304 * we have omitted the parts that deal with backward running loops as well as
305 * the checks whether wake-up and sleep operations act on timesteps outside
306 * <tt>0..n_timesteps-1</tt>.
307 * @code
308 * template <typename InitFunctionObject, typename LoopFunctionObject>
309 * void TimeDependent::do_loop (InitFunctionObject init_function,
310 * LoopFunctionObject loop_function,
311 * const TimeSteppingData &timestepping_data,
312 * const Direction direction)
313 * {
314 * // initialize the time steps for a round of this loop
315 * for (unsigned int step=0; step<n_timesteps; ++step)
316 * init_function (static_cast<typename InitFunctionObject::argument_type>
317 * (timesteps[step]));
318 *
319 * // wake up the first few time levels
320 * for (int step=-timestepping_data.look_ahead; step<0; ++step)
321 * for (int look_ahead=0;
322 * look_ahead<=timestepping_data.look_ahead;
323 * ++look_ahead)
324 * timesteps[step+look_ahead]->wake_up(look_ahead);
325 *
326 *
327 * for (unsigned int step=0; step<n_timesteps; ++step)
328 * {
329 * // first thing: wake up the timesteps ahead as necessary
330 * for (unsigned int look_ahead=0;
331 * look_ahead<=timestepping_data.look_ahead;
332 * ++look_ahead)
333 * timesteps[step+look_ahead]->wake_up(look_ahead);
334 *
335 *
336 * // actually do the work
337 * loop_function(
338 * static_cast<typename LoopFunctionObject::argument_type> (
339 * timesteps[step]));
340 *
341 * // let the timesteps behind sleep
342 * for (unsigned int look_back=0;
343 * look_back<=timestepping_data.look_back;
344 * ++look_back)
345 * timesteps[step-look_back]->sleep(look_back);
346 * }
347 *
348 * // make the last few timesteps sleep
349 * for (int step=n_timesteps;
350 * step<=n_timesteps+timestepping_data.look_back;
351 * ++step)
352 * for (int look_back=0;
353 * look_back<=timestepping_data.look_back;
354 * ++look_back)
355 * timesteps[step-look_back]->sleep(look_back);
356 * }
357 * @endcode
358 */
359 class TimeDependent
360 {
361 public:
362 /**
363 * Structure holding the two basic entities that control a loop over all
364 * time steps: how many time steps ahead of the present one we shall start
365 * waking up timestep objects and how many timesteps behind we shall call
366 * their @p sleep method.
367 */
368 struct TimeSteppingData
369 {
370 /**
371 * Constructor; see the different fields for a description of the meaning
372 * of the parameters.
373 */
374 TimeSteppingData(const unsigned int look_ahead,
375 const unsigned int look_back);
376
377 /**
378 * This denotes the number of timesteps the timestepping algorithm needs
379 * to look ahead. Usually, this number will be zero, since algorithms
380 * looking ahead can't act as timestepping schemes since they can't
381 * compute their data from knowledge of the past only and are therefore
382 * global in time.
383 *
384 * However, it may be necessary to look ahead in other circumstances, when
385 * not wanting to access the data of the next time step(s), but for
386 * example to know the next grid, the solution of a dual problem on the
387 * next time level, etc.
388 *
389 * Note that for a dual problem walking back in time, "looking ahead"
390 * means looking towards smaller time values.
391 *
392 * The value of this number determines, how many time steps ahead the time
393 * step manager start to call the @p wake_up function for each time step.
394 */
395 const unsigned int look_ahead;
396
397 /**
398 * This is the opposite variable to the above one. It denotes the number
399 * of time steps behind the present one for which we need to keep all data
400 * in order to do the computations on the present time level.
401 *
402 * For one step schemes (e.g. the Euler schemes, or the Crank-Nicolson
403 * scheme), this value will be one.
404 *
405 * The value of this number determines, how many time steps after having
406 * done computations on a time level the time step manager will call the @p
407 * sleep function for each time step.
408 */
409 const unsigned int look_back;
410 };
411
412 /**
413 * Enum offering the different directions in which a loop executed by @p
414 * do_loop may be run.
415 */
416 enum Direction
417 {
418 /**
419 * Go in the forward direction.
420 */
421 forward,
422 /**
423 * Go in the backward direction.
424 */
425 backward
426 };
427
428 /**
429 * Constructor.
430 */
431 TimeDependent(const TimeSteppingData &data_primal,
432 const TimeSteppingData &data_dual,
433 const TimeSteppingData &data_postprocess);
434
435
436 /**
437 * Destructor. This will delete the objects pointed to by the pointers given
438 * to the <tt>insert_*</tt> and @p add_timestep functions, i.e. it will
439 * delete the objects doing the computations on each time step.
440 */
441 virtual ~TimeDependent();
442
443 /**
444 * Add a timestep at any position. The position is a pointer to an existing
445 * time step object, or a null pointer denoting the end of the timestep
446 * sequence. If @p position is non-null, the new time step will be inserted
447 * before the respective element.
448 *
449 * Note that by giving an object to this function, the TimeDependent object
450 * assumes ownership of the object; it will therefore also take care of
451 * deletion of the objects its manages.
452 *
453 * There is another function, @p add_timestep, which inserts a time step at
454 * the end of the list.
455 *
456 * Note that this function does not change the timestep numbers stored
457 * within the other timestep objects, nor does it set the timestep number of
458 * this new timestep. This is only done upon calling the @p start_sweep
459 * function. In not changing the timestep numbers, it is simpler to operate
460 * on a space-time triangulation since one can always use the timestep
461 * numbers that were used in the previous sweep.
462 */
463 void
464 insert_timestep(const TimeStepBase *position, TimeStepBase *new_timestep);
465
466 /**
467 * Just like @p insert_timestep, but insert at the end.
468 *
469 * This mechanism usually will result in a set-up loop like this
470 * @code
471 * for (int i=0; i<N; ++i)
472 * manager.add_timestep(new MyTimeStep());
473 * @endcode
474 */
475 void
476 add_timestep(TimeStepBase *new_timestep);
477
478 /**
479 * Delete a timestep. This is only necessary to call, if you want to delete
480 * it between two sweeps; at the end of the lifetime of this object, care is
481 * taken automatically of deletion of the time step objects. Deletion of the
482 * object by the destructor is done through this function also.
483 *
484 * Note that this function does not change the timestep numbers stored
485 * within the other timestep objects. This is only done upon calling the @p
486 * start_sweep function. In not changing the timestep numbers, it is simpler
487 * to operate on a space-time triangulation since one can always use the
488 * timestep numbers that were used in the previous sweep.
489 */
490 void
491 delete_timestep(const unsigned int position);
492
493 /**
494 * Solve the primal problem; uses the functions @p init_for_primal_problem
495 * and @p solve_primal_problem of the TimeStepBase class through the @p
496 * do_loop function of this class.
497 *
498 * Look ahead and look back are determined by the @p
499 * timestepping_data_primal object given to the constructor.
500 */
501 void
502 solve_primal_problem();
503
504 /**
505 * Solve the dual problem; uses the functions @p init_for_dual_problem and
506 * @p solve_dual_problem of the TimeStepBase class through the @p do_loop
507 * function of this class.
508 *
509 * Look ahead and look back are determined by the @p timestepping_data_dual
510 * object given to the constructor.
511 */
512 void
513 solve_dual_problem();
514
515 /**
516 * Do a postprocessing round; uses the functions @p init_for_postprocessing
517 * and @p postprocess of the TimeStepBase class through the @p do_loop
518 * function of this class.
519 *
520 * Look ahead and look back are determined by the @p
521 * timestepping_data_postprocess object given to the constructor.
522 */
523 void
524 postprocess();
525
526 /**
527 * Do a loop over all timesteps, call the @p init_function at the beginning
528 * and the @p loop_function of each time step. The @p timestepping_data
529 * determine how many timesteps in front and behind the present one the @p
530 * wake_up and @p sleep functions are called.
531 *
532 * To see how this function work, note that the function @p
533 * solve_primal_problem only consists of the following call:
534 * @code
535 * do_loop([](TimeStepBase *const time_step)
536 * { time_step->init_for_primal_problem(); },
537 * [](TimeStepBase *const time_step)
538 * { time_step->solve_primal_problem(); },
539 * timestepping_data_primal,
540 * forward);
541 * @endcode
542 *
543 * Note also, that the given class from which the two functions are taken
544 * needs not necessarily be TimeStepBase, but it could also be a derived
545 * class, that is @p static_castable from a TimeStepBase. The function may
546 * be a virtual function (even a pure one) of that class, which should help
547 * if the actual class where it is implemented is one which is derived
548 * through virtual base classes and thus unreachable by @p static_cast from
549 * the TimeStepBase class.
550 *
551 * Instead of using the above form, you can equally well use
552 * <tt>[args...](X *const x){x->unary_function(args...);}</tt>
553 * which lets the @p do_loop function call the given function with the
554 * specified parameters.
555 */
556 template <typename InitFunctionObject, typename LoopFunctionObject>
557 void
558 do_loop(InitFunctionObject init_function,
559 LoopFunctionObject loop_function,
560 const TimeSteppingData &timestepping_data,
561 const Direction direction);
562
563
564 /**
565 * Initialize the objects for the next sweep. This function specifically
566 * does the following: assign each time level the number it presently has
567 * within the array (which may change, if time levels are inserted or
568 * deleted) and transmit the number of the present sweep to these objects.
569 *
570 * It also calls the @p start_sweep function of each time step object, after
571 * the numbers above are set.
572 *
573 * This function is virtual, so you may overload it. You should, however not
574 * forget to call this function as well from your overwritten version, at
575 * best at the beginning of your function since this is some kind of
576 * "constructor-like" function, which should be called bottom-up.
577 *
578 * The default implementation of this function calls @p start_sweep on all
579 * time step objects.
580 */
581 virtual void
582 start_sweep(const unsigned int sweep_no);
583
584 /**
585 * Analogous to the above function, calling @p end_sweep of each time step
586 * object. The same applies with respect to the @p virtualness of this
587 * function as for the previous one.
588 *
589 * @note This function does not guarantee that @p end_sweep is called for
590 * successive time steps successively, rather the order of time step objects
591 * for which the function is called is arbitrary. You should therefore not
592 * assume that that function has been called for previous time steps
593 * already. If in multithread mode, the @p end_sweep function of several
594 * time steps may be called at once, so you should use synchronization
595 * mechanisms if your program requires so.
596 */
597 virtual void
598 end_sweep();
599
600 /**
601 * Determine an estimate for the memory consumption (in bytes) of this
602 * object.
603 */
604 std::size_t
605 memory_consumption() const;
606
607 /**
608 * Exception.
609 */
610 DeclExceptionMsg(ExcInvalidPosition,
611 "You cannot insert a time step at the specified position.");
612
613 protected:
614 /**
615 * Vector holding pointers to the time level objects. This is the main data
616 * this object operates on. Note that this object takes possession of the
617 * objects pointed to by the pointers in this collection.
618 */
619 std::vector<ObserverPointer<TimeStepBase, TimeDependent>> timesteps;
620
621 /**
622 * Number of the present sweep. This is reset by the @p start_sweep function
623 * called at the outset of each sweep.
624 */
625 unsigned int sweep_no;
626
627 /**
628 * Some flags telling the @p solve_primal_problem function what to do. See
629 * the documentation of this struct for more information.
630 */
631 const TimeSteppingData timestepping_data_primal;
632
633 /**
634 * Some flags telling the @p solve_dual_problem function what to do. See the
635 * documentation of this struct for more information.
636 */
637 const TimeSteppingData timestepping_data_dual;
638
639 /**
640 * Some flags telling the @p postprocess function what to do. See the
641 * documentation of this struct for more information.
642 */
643 const TimeSteppingData timestepping_data_postprocess;
644
645 private:
646 /**
647 * Do the work of <tt>end_sweep()</tt> for some timesteps only. This is
648 * useful in multithread mode.
649 */
650 void
651 end_sweep(const unsigned int begin_timestep, const unsigned int end_timestep);
652 };
653
654
655
656 /**
657 * Base class for a time step in time dependent problems. This class provides
658 * barely more than the basic framework, defining the necessary virtual
659 * functions (namely @p sleep and @p wake_up), the interface to previous and
660 * following grids, and some functions to be called before a new loop over all
661 * time steps is started.
662 */
663 class TimeStepBase : public EnableObserverPointer
664 {
665 public:
666 /**
667 * Enum denoting the type of problem which will have to be solved next.
668 */
669 enum SolutionState
670 {
671 /**
672 * Solve the primal problem next.
673 */
674 primal_problem = 0x0,
675 /**
676 * Solve the dual problem next.
677 */
678 dual_problem = 0x1,
679 /**
680 * Perform postprocessing next.
681 */
682 postprocess = 0x2
683 };
684
685 /**
686 * Constructor. Does nothing here apart from setting the time.
687 */
688 TimeStepBase(const double time);
689
690 /**
691 * Destructor. At present, this does nothing.
692 */
693 virtual ~TimeStepBase() override = default;
694
695 /**
696 * The copy constructor is deleted to avoid shallow copies with unexpected
697 * behavior.
698 */
699 TimeStepBase(const TimeStepBase &) = delete;
700
701 /**
702 * The copy assignment operator is deleted to avoid shallow copies with
703 * unexpected behavior.
704 */
705 TimeStepBase &
706 operator=(const TimeStepBase &) = delete;
707
708 /**
709 * Reconstruct all the data that is needed for this time level to work. This
710 * function serves to reget all the variables and data structures to work
711 * again after they have been send to sleep some time before, or at the
712 * first time we visit this time level. In particular, it is used to
713 * reconstruct the triangulation, degree of freedom handlers, to reload data
714 * vectors in case they have been stored to disk, etc.
715 *
716 * The actual implementation of this function does nothing.
717 *
718 * Since this is an important task, you should call this function from your
719 * own function, should you choose to overload it in your own class (which
720 * likely is the case), preferably at the beginning so that your function
721 * can take effect of the triangulation already existing.
722 */
723 virtual void
724 wake_up(const unsigned int);
725
726 /**
727 * This is the opposite function to @p wake_up. It is used to delete data or
728 * save it to disk after they are no more needed for the present sweep.
729 * Typical kinds of data for this are data vectors, degree of freedom
730 * handlers, triangulation objects, etc. which occupy large amounts of
731 * memory and may therefore be externalized.
732 *
733 * By default, this function does nothing.
734 */
735 virtual void
736 sleep(const unsigned int);
737
738 /**
739 * This function is called each time before a new sweep is started. You may
740 * want to set up some fields needed in the course of the computations, and
741 * so on. You should take good care, however, not to install large objects,
742 * which should be deferred until the @p wake_up function is called.
743 *
744 * A typical action of this function would be sorting out names of temporary
745 * files needed in the process of solving, etc.
746 *
747 * At the time this function is called, the values of @p timestep_no, @p
748 * sweep_no and the pointer to the previous and next time step object
749 * already have their correct value.
750 *
751 * The default implementation of this function does nothing.
752 */
753 virtual void
754 start_sweep();
755
756 /**
757 * This is the analogous to the above function, but it is called at the end
758 * of a sweep. You will usually want to do clean-ups in this function, such
759 * as deleting temporary files and the like.
760 */
761 virtual void
762 end_sweep();
763
764 /**
765 * Before the primal problem is solved on each time level, this function is
766 * called (i.e. before the solution takes place on the first time level). By
767 * default, this function sets the @p next_action variable of this class.
768 * You may overload this function, but you should call this function within
769 * your own one.
770 */
771 virtual void
772 init_for_primal_problem();
773
774 /**
775 * Same as above, but called before a round of dual problem solves.
776 */
777 virtual void
778 init_for_dual_problem();
779
780 /**
781 * Same as above, but called before a round of postprocessing steps.
782 */
783 virtual void
784 init_for_postprocessing();
785
786 /**
787 * This function is called by the manager object when solving the primal
788 * problem on this time level is needed. It is called after the @p wake_up
789 * function was called and before the @p sleep function will be called.
790 * There is no default implementation for obvious reasons, so you have to
791 * overload this function.
792 */
793 virtual void
794 solve_primal_problem() = 0;
795
796 /**
797 * This function is called by the manager object when solving the dual
798 * problem on this time level is needed. It is called after the @p wake_up
799 * function was called and before the @p sleep function will be called.
800 * There is a default implementation doing plain nothing since some problems
801 * may not need solving a dual problem. However, it will abort the program
802 * when being called anyway, since then you should really overload the
803 * function.
804 */
805 virtual void
806 solve_dual_problem();
807
808 /**
809 * This function is called by the manager object when postprocessing this
810 * time level is needed. It is called after the @p wake_up function was
811 * called and before the @p sleep function will be called. There is a
812 * default implementation doing plain nothing since some problems may not
813 * need doing a postprocess step, e.g. if everything was already done when
814 * solving the primal problem. However, it will abort the program when being
815 * called anyway, since then you should really overload the function.
816 */
817 virtual void
818 postprocess_timestep();
819
820 /**
821 * Return the time value of this time step.
822 */
823 double
824 get_time() const;
825
826 /**
827 * Return the number of this time step. Note that this number may vary
828 * between different sweeps, if timesteps are added or deleted.
829 */
830 unsigned int
831 get_timestep_no() const;
832
833 /**
834 * Compute the time difference to the last time step. If this timestep is
835 * the first one, this function will result in an exception. Though this
836 * behavior seems a bit drastic, it is appropriate in most cases since if
837 * there is no previous time step you will need special treatment anyway and
838 * this way no invalid value is returned which could lead to wrong but
839 * unnoticed results of your computation. (The only sensible value to return
840 * in that case would not be zero, since valid computation can be done with
841 * that, but would be a denormalized value such as @p NaN. However, there is
842 * not much difference in finding that the results of a computation are all
843 * denormalized values or in getting an exception; in the latter case you at
844 * least get the exact place where your problem lies.)
845 */
846 double
847 get_backward_timestep() const;
848
849 /**
850 * Return the time difference to the next time step. With regard to the case
851 * that there is no next time step, the same applies as for the function
852 * above.
853 */
854 double
855 get_forward_timestep() const;
856
857 /**
858 * Determine an estimate for the memory consumption (in bytes) of this
859 * object.
860 *
861 * You will want to overload this function in derived classes to compute the
862 * amount memory used by the derived class, and add the result of this
863 * function to your result.
864 */
865 virtual std::size_t
866 memory_consumption() const;
867
868 protected:
869 /**
870 * Pointer to the previous time step object in the list.
871 */
872 const TimeStepBase *previous_timestep;
873
874 /**
875 * Pointer to the next time step object in the list.
876 */
877 const TimeStepBase *next_timestep;
878
879 /**
880 * Number of the sweep we are presently in. This number is reset by the time
881 * level manager before a sweep is started.
882 */
883 unsigned int sweep_no;
884
885 /**
886 * Number of the time step, counted from zero onwards. This number is reset
887 * at the start of each sweep by the time level manager, since some time
888 * steps may have been inserted or deleted after the previous sweep.
889 */
890 unsigned int timestep_no;
891
892 /**
893 * Discrete time this level operates on.
894 */
895 const double time;
896
897 /**
898 * Variable storing whether the solution of a primal or a dual problem is
899 * actual, or any of the other actions specified. This variable is set by
900 * the <tt>init_for_*</tt> functions.
901 */
902 unsigned int next_action;
903
904 private:
905 /**
906 * Reset the pointer to the previous time step; shall only be called by the
907 * time level manager object.
908 *
909 * This function is called at the set-up of the manager object and whenever
910 * a timestep is inserted or deleted.
911 */
912 void
913 set_previous_timestep(const TimeStepBase *previous);
914
915 /**
916 * Reset the pointer to the next time step; shall only be called by the time
917 * level manager object.
918 *
919 * This function is called at the set-up of the manager object and whenever
920 * a timestep is inserted or deleted.
921 */
922 void
923 set_next_timestep(const TimeStepBase *next);
924
925 /**
926 * Set the number this time step has in the list of timesteps. This function
927 * is called by the time step management object at the beginning of each
928 * sweep, to update information which may have changed due to addition or
929 * deletion of time levels.
930 */
931 void
932 set_timestep_no(const unsigned int step_no);
933
934 /**
935 * Set the number of the sweep we are presently in. This function is called
936 * by the time level management object at start-up time of each sweep.
937 */
938 void
939 set_sweep_no(const unsigned int sweep_no);
940
941 // make the manager object a friend
942 friend class TimeDependent;
943 };
944
945
946
947 /**
948 * Namespace in which some classes are declared that encapsulate flags for the
949 * TimeStepBase_Tria() class. These used to be local data types of that class,
950 * but some compilers choked on some aspects, so we put them into a namespace
951 * of their own.
952 */
953 namespace TimeStepBase_Tria_Flags
954 {
955 /**
956 * This structure is used to tell the TimeStepBase_Tria() class how grids
957 * should be handled. It has flags defining the moments where grids shall be
958 * re-made and when they may be deleted. Also, one variable states whether
959 * grids should be kept in memory or should be deleted between to uses to
960 * save memory.
961 */
962 template <int dim>
963 struct Flags
964 {
965 /**
966 * Default constructor; yields an exception, so is not really usable.
967 */
968 Flags();
969
970 /**
971 * Constructor; see the different fields for a description of the meaning
972 * of the parameters.
973 */
974 Flags(const bool delete_and_rebuild_tria,
975 const unsigned int wakeup_level_to_build_grid,
976 const unsigned int sleep_level_to_delete_grid);
977
978 /**
979 * This flag determines whether the @p sleep and @p wake_up functions
980 * shall delete and rebuild the triangulation. While for small problems,
981 * this is not necessary, for large problems it is indispensable to save
982 * memory. The reason for this is that there may be several hundred time
983 * levels in memory, each with its own triangulation, which may require
984 * large amounts if there are many cells on each. Having a total of
985 * 100.000.000 cells on all time levels taken together is not uncommon,
986 * which makes this flag understandable.
987 */
988 const bool delete_and_rebuild_tria;
989
990 /**
991 * This number denotes the parameter to the @p wake_up function at which
992 * it shall rebuild the grid. Obviously, it shall be less than or equal to
993 * the @p look_ahead number passed to the time step management object; if
994 * it is equal, then the grid is rebuilt the first time the @p wake_up
995 * function is called. If @p delete_and_rebuild_tria is @p false, this
996 * number has no meaning.
997 */
998 const unsigned int wakeup_level_to_build_grid;
999
1000 /**
1001 * This is the opposite flag to the one above: it determines at which call
1002 * to * @p sleep the grid shall be deleted.
1003 */
1004 const unsigned int sleep_level_to_delete_grid;
1005 };
1006
1007
1008
1009 /**
1010 * This structure is used to tell the TimeStepBase_Tria() class how grids
1011 * should be refined. Before we explain all the different variables, fist
1012 * some terminology:
1013 * <ul>
1014 * <li> Correction: after having flagged some cells of the triangulation for
1015 * following some given criterion, we may want to change the number of
1016 * flagged cells on this grid according to another criterion that the number
1017 * of cells may be only a certain fraction more or less then the number of
1018 * cells on the previous grid. This change of refinement flags will be
1019 * called "correction" in the sequel.
1020 * <li> Adaption: in order to make the change between one grid and the next
1021 * not to large, we may want to flag some additional cells on one of the two
1022 * grids such that there are not too grave differences. This process will be
1023 * called "adaption".
1024 * </ul>
1025 *
1026 *
1027 * <h3>Description of flags</h3>
1028 *
1029 * <ul>
1030 * <li> @p max_refinement_level: Cut the refinement of cells at a given
1031 * level. This flag does not influence the flagging of cells, so not more
1032 * cells on the coarser levels are flagged than usual. Rather, the flags are
1033 * all set, but when it comes to the actual refinement, the maximum
1034 * refinement level is truncated.
1035 *
1036 * This option is only really useful when you want to compare global
1037 * refinement with adaptive refinement when you don't want the latter to
1038 * refine more than the global refinement.
1039 *
1040 * <li> @p first_sweep_with_correction: When using cell number correction as
1041 * defined above, it may be worth while to start with this only in later
1042 * sweeps, not already in the first one. If this variable is zero, then
1043 * start with the first sweep, else with a higher one. The rationale for
1044 * only starting later is that we do not want to block the development of
1045 * grids at the beginning and only impose restrictions in the sweeps where
1046 * we start to be interested in the actual results of the computations.
1047 *
1048 * <li> @p min_cells_for_correction: If we want a more free process of grid
1049 * development, we may want to impose less rules for grids with few cells
1050 * also. This variable sets a lower bound for the cell number of grids where
1051 * corrections are to be performed.
1052 *
1053 * <li> @p cell_number_corridor_top: Fraction of the number of cells by
1054 * which the number of cells of one grid may be higher than that on the
1055 * previous grid. Common values are 10 per cent (i.e. 0.1). The naming of
1056 * the variable results from the goal to define a target corridor for the
1057 * number of cells after refinement has taken place.
1058 *
1059 * <li> @p cell_number_corridor_bottom: Fraction of the number of cells by
1060 * which the number of cells of one grid may be lower than that on the
1061 * previous grid. Common values are 5 per cent (i.e. 0.05). Usually this
1062 * number will be smaller than @p cell_number_corridor_top since an increase
1063 * of the number of cells is not harmful (though it increases the numerical
1064 * amount of work needed to solve the problem) while a sharp decrease may
1065 * reduce the accuracy of the final result even if the time steps computed
1066 * before the decrease were computed to high accuracy.
1067 *
1068 * Note however, that if you compute the dual problem as well, then the time
1069 * direction is reversed, so the two values defining the cell number
1070 * corridor should be about equal.
1071 *
1072 * <li> @p correction_relaxations: This is a list of pairs of number with
1073 * the following meaning: just as for @p min_cells_for_correction, it may be
1074 * worth while to reduce the requirements upon grids if the have few cells.
1075 * The present variable stores a list of cell numbers along with some values
1076 * which tell us that the cell number corridor should be enlarged by a
1077 * certain factor. For example, if this list was <tt>((100 5) (200 3) (500
1078 * 2))</tt>, this would mean that for grids with a cell number below 100,
1079 * the <tt>cell_number_corridor_*</tt> variables are to be multiplied by 5
1080 * before they are applied, for cell numbers below 200 they are to be
1081 * multiplied by 3, and so on.
1082 *
1083 * @p correction_relaxations is actually a vector of such list. Each entry
1084 * in this vector denotes the relaxation rules for one sweep. The last entry
1085 * defines the relaxation rules for all following sweeps. This scheme is
1086 * adopted to allow for stricter corrections in later sweeps while the
1087 * relaxations may be more generous in the first sweeps.
1088 *
1089 * There is a static variable @p default_correction_relaxations which you
1090 * can use as a default value. It is an empty list and thus defines no
1091 * relaxations.
1092 *
1093 * <li> @p cell_number_correction_steps: Usually, if you want the number of
1094 * cells to be corrected, the target corridor for the cell number is
1095 * computed and some additional cells are flagged or flags are removed. But
1096 * since the cell number resulting after flagging and deflagging can not be
1097 * easily computed, it will usually not be within the corridor. We therefore
1098 * need to iteratively get to our goal. Usually, three or four iterations
1099 * are needed, but using this variable, you can reduce the allowed number of
1100 * iterations; breaking the loop after two iterations yields good results
1101 * regularly. Setting the variable to zero will result in no correction
1102 * steps at all.
1103 *
1104 * <li> @p mirror_flags_to_previous_grid: If a cell on the present grid is
1105 * flagged for refinement, also flag the corresponding cell on the previous
1106 * grid. This is useful if, for example, error indicators are computed for
1107 * space-time cells, but are stored for the second grid only. Now, since the
1108 * first grid has the same contributions to the indicators as the second, it
1109 * may be useful to flag both if necessary. This is done if the present
1110 * variable is set.
1111 *
1112 * <li> @p adapt_grids: adapt the present grid to the previous one in the
1113 * sense defined above. What is actually done here is the following: if
1114 * going from the previous to the present grid would result in double
1115 * refinement or double coarsening of some cells, then we try to flag these
1116 * cells for refinement or coarsening such as to avoid the double step.
1117 * Obviously, more than double refinement of coarsening is also caught.
1118 *
1119 * Grid adaption can try to avoid such changes between two grids, but it can
1120 * never promise that they don't occur. This is because the next grid may
1121 * change the present one, but then again there may be jumps in refinement
1122 * level between the present and the previous one; this could only be
1123 * avoided by looping iteratively through all grids, back and forth, until
1124 * nothing changes anymore, which is obviously impossible if there are many
1125 * time steps with very large grids.
1126 * </ul>
1127 */
1128 template <int dim>
1129 struct RefinementFlags
1130 {
1131 /**
1132 * Typedef of a data type describing some relaxations of the correction
1133 * process. See the general description of this class for more
1134 * information.
1135 */
1136 using CorrectionRelaxations =
1137 std::vector<std::vector<std::pair<unsigned int, double>>>;
1138
1139 /**
1140 * Default values for the relaxations: no relaxations.
1141 */
1142 static CorrectionRelaxations default_correction_relaxations;
1143
1144 /**
1145 * Constructor. The default values are chosen such that almost no
1146 * restriction on the mesh refinement is imposed.
1147 */
1148 RefinementFlags(const unsigned int max_refinement_level = 0,
1149 const unsigned int first_sweep_with_correction = 0,
1150 const unsigned int min_cells_for_correction = 0,
1151 const double cell_number_corridor_top = (1 << dim),
1152 const double cell_number_corridor_bottom = 1,
1153 const CorrectionRelaxations &correction_relaxations =
1154 CorrectionRelaxations(),
1155 const unsigned int cell_number_correction_steps = 0,
1156 const bool mirror_flags_to_previous_grid = false,
1157 const bool adapt_grids = false);
1158
1159 /**
1160 * Maximum level of a cell in the triangulation of a time level. If it is
1161 * set to zero, then no limit is imposed on the number of refinements a
1162 * coarse grid cell may undergo. Usually, this field is used, if for some
1163 * reason you want to limit refinement in an adaptive process, for example
1164 * to avoid overly large numbers of cells or to compare with grids which
1165 * have a certain number of refinements.
1166 */
1167 const unsigned int max_refinement_level;
1168
1169 /**
1170 * First sweep to perform cell number correction steps on; for sweeps
1171 * before, cells are only flagged and no number-correction to previous
1172 * grids is performed.
1173 */
1174 const unsigned int first_sweep_with_correction;
1175
1176
1177 /**
1178 * Apply cell number correction with the previous time level only if there
1179 * are more than this number of cells.
1180 */
1181 const unsigned int min_cells_for_correction;
1182
1183 /**
1184 * Fraction by which the number of cells on a time level may differ from
1185 * the number on the previous time level (first: top deviation, second:
1186 * bottom deviation).
1187 */
1188 const double cell_number_corridor_top;
1189
1190 /**
1191 * @ref cell_number_corridor_top
1192 */
1193 const double cell_number_corridor_bottom;
1194
1195 /**
1196 * List of relaxations to the correction step.
1197 */
1198 const std::vector<std::vector<std::pair<unsigned int, double>>>
1199 correction_relaxations;
1200
1201 /**
1202 * Number of iterations to be performed to adjust the number of cells on a
1203 * time level to those on the previous one. Zero means: do no such
1204 * iteration.
1205 */
1206 const unsigned int cell_number_correction_steps;
1207
1208 /**
1209 * Flag all cells which are flagged on this timestep for refinement on the
1210 * previous one also. This is useful in case the error indicator was
1211 * computed by integration over time-space cells, but are now associated
1212 * to a grid on a discrete time level. Since the error contribution comes
1213 * from both grids, however, it is appropriate to refine both grids.
1214 *
1215 * Since the previous grid does not mirror the flags to the one before it,
1216 * this does not lead to an almost infinite growth of cell numbers. You
1217 * should use this flag with cell number correction switched on only,
1218 * however.
1219 *
1220 * Mirroring is done after cell number correction is done, but before grid
1221 * adaption, so the cell number on this grid is not noticeably influenced
1222 * by the cells flagged additionally on the previous grid.
1223 */
1224 const bool mirror_flags_to_previous_grid;
1225
1226 /**
1227 * Adapt this grid to the previous one.
1228 */
1229 const bool adapt_grids;
1230
1231 /**
1232 * Exception
1233 */
1234 DeclException1(ExcInvalidValue,
1235 double,
1236 << "The value " << arg1
1237 << " for the cell number corridor does not fulfill "
1238 "its natural requirements.");
1239 };
1240
1241
1242
1243 /**
1244 * Structure given to the actual refinement function, telling it which
1245 * thresholds to take for coarsening and refinement. The actual refinement
1246 * criteria are loaded by calling the virtual function @p
1247 * get_tria_refinement_criteria.
1248 */
1249 template <int dim>
1250 struct RefinementData
1251 {
1252 /**
1253 * Constructor
1254 */
1255 RefinementData(const double refinement_threshold,
1256 const double coarsening_threshold = 0);
1257
1258 /**
1259 * Threshold for refinement: cells having a larger value will be refined
1260 * (at least in the first round; subsequent steps of the refinement
1261 * process may flag other cells as well or remove the flag from cells with
1262 * a criterion higher than this threshold).
1263 */
1264 const double refinement_threshold;
1265
1266 /**
1267 * Same threshold for coarsening: cells with a smaller threshold will be
1268 * coarsened if possible.
1269 */
1270 const double coarsening_threshold;
1271
1272 /**
1273 * Exception
1274 */
1275 DeclException1(ExcInvalidValue,
1276 double,
1277 << "The value " << arg1
1278 << " for the cell refinement thresholds does not fulfill "
1279 "its natural requirements.");
1280 };
1281 } // namespace TimeStepBase_Tria_Flags
1282
1283
1284
1285 /**
1286 * Specialization of TimeStepBase which addresses some aspects of grid
1287 * handling. In particular, this class is thought to make handling of grids
1288 * available that are adaptively refined on each time step separately or with
1289 * a loose coupling between time steps. It also takes care of deleting and
1290 * rebuilding grids when memory resources are a point, through the @p sleep
1291 * and @p wake_up functions declared in the base class.
1292 *
1293 * In addition to that, it offers functions which do some rather hairy
1294 * refinement rules for time dependent problems, trying to avoid too much
1295 * change in the grids between subsequent time levels, while also trying to
1296 * retain the freedom of refining each grid separately. There are lots of
1297 * flags and numbers controlling this function, which might drastically change
1298 * the behavior of the function -- see the description of the flags for
1299 * further information.
1300 */
1301 template <int dim>
1302 class TimeStepBase_Tria : public TimeStepBase
1303 {
1304 public:
1305 /**
1306 * Typedef the data types of the TimeStepBase_Tria_Flags() namespace into
1307 * local scope.
1308 */
1309 using Flags = typename TimeStepBase_Tria_Flags::Flags<dim>;
1310 using RefinementFlags =
1311 typename TimeStepBase_Tria_Flags::RefinementFlags<dim>;
1312 using RefinementData = typename TimeStepBase_Tria_Flags::RefinementData<dim>;
1313
1314
1315 /**
1316 * Extension of the enum in the base class denoting the next action to be
1317 * done.
1318 */
1319 enum SolutionState
1320 {
1321 /**
1322 * Perform grid refinement next.
1323 */
1324 grid_refinement = 0x1000
1325 };
1326
1327
1328 /**
1329 * Default constructor. Does nothing but throws an exception. We need to
1330 * have such a constructor in order to satisfy the needs of derived classes,
1331 * which take this class as a virtual base class and don't need to call this
1332 * constructor of they are not terminal classes. The compiler would like to
1333 * know a constructor to call anyway since it can't know that the class is
1334 * not terminal.
1335 */
1336 TimeStepBase_Tria();
1337
1338 /**
1339 * Constructor. Takes a coarse grid from which the grids on this time level
1340 * will be derived and some flags steering the behavior of this object.
1341 *
1342 * The ownership of the coarse grid stays with the creator of this object.
1343 * However, it is locked from destruction to guarantee the lifetime of the
1344 * coarse grid is longer than it is needed by this object.
1345 *
1346 * You need to give the general flags structure to this function since it is
1347 * needed anyway; the refinement flags can be omitted if you do not intend
1348 * to call the refinement function of this class.
1349 */
1350 TimeStepBase_Tria(
1351 const double time,
1352 const Triangulation<dim, dim> &coarse_grid,
1353 const Flags &flags,
1354 const RefinementFlags &refinement_flags = RefinementFlags());
1355
1356 /**
1357 * Destructor. At present, this does not more than releasing the lock on the
1358 * coarse grid triangulation given to the constructor.
1359 */
1360 virtual ~TimeStepBase_Tria() override;
1361
1362 /**
1363 * Reconstruct all the data that is needed for this time level to work. This
1364 * function serves to reget all the variables and data structures to work
1365 * again after they have been send to sleep some time before, or at the
1366 * first time we visit this time level. In particular, it is used to
1367 * reconstruct the triangulation, degree of freedom handlers, to reload data
1368 * vectors in case they have been stored to disk, etc. By default, this
1369 * function rebuilds the triangulation if the respective flag has been set
1370 * to destroy it in the @p sleep function. It does so also the first time we
1371 * hit this function and @p wakeup_level equals
1372 * <tt>flags.wakeup_level_to_build_grid</tt>, independently of the value of
1373 * the mentioned flag. (Actually, it does so whenever the triangulation
1374 * pointer equals the Null pointer and the value of @p wakeup_level is
1375 * right.)
1376 *
1377 * Since this is an important task, you should call this function from your
1378 * own function, should you choose to overload it in your own class (which
1379 * likely is the case), preferably at the beginning so that your function
1380 * can take effect of the triangulation already existing.
1381 */
1382 virtual void
1383 wake_up(const unsigned int wakeup_level) override;
1384
1385 /**
1386 * This is the opposite function to @p wake_up. It is used to delete data or
1387 * save it to disk after they are no more needed for the present sweep.
1388 * Typical kinds of data for this are data vectors, degree of freedom
1389 * handlers, triangulation objects, etc. which occupy large amounts of
1390 * memory and may therefore be externalized.
1391 *
1392 * By default, if the user specified so in the flags for this object, the
1393 * triangulation is deleted and the refinement history is saved such that the
1394 * respective @p wake_up function can rebuild it. You should therefore call
1395 * this function from your overloaded version, preferably at the end so that
1396 * your function can use the triangulation as long as you need it.
1397 */
1398 virtual void
1399 sleep(const unsigned int) override;
1400
1401 /**
1402 * Do the refinement according to the flags passed to the constructor of
1403 * this object and the data passed to this function. For a description of
1404 * the working of this function refer to the general documentation of this
1405 * class.
1406 *
1407 * In fact, this function does not actually refine or coarsen the
1408 * triangulation, but only sets the respective flags. This is done because
1409 * usually you will not need the grid immediately afterwards but only in the
1410 * next sweep, so it suffices to store the flags and rebuild it the next
1411 * time we need it. Also, it may be that the next time step would like to
1412 * add or delete some flags, so we have to wait anyway with the use of this
1413 * grid.
1414 */
1415 void
1416 refine_grid(const RefinementData data);
1417
1418 /**
1419 * Respective init function for the refinement loop; does nothing in the
1420 * default implementation, apart from setting @p next_action to @p
1421 * grid_refinement but can be overloaded.
1422 */
1423 virtual void
1424 init_for_refinement();
1425
1426 /**
1427 * Virtual function that should fill the vector with the refinement criteria
1428 * for the present triangulation. It is used within the @p refine_grid
1429 * function to get the criteria for the present time step, since they can't
1430 * be passed through its argument when using the loop of the time step
1431 * management object.
1432 */
1433 virtual void
1434 get_tria_refinement_criteria(Vector<float> &criteria) const = 0;
1435
1436 /**
1437 * The refinement flags of the triangulation are stored in a local variable
1438 * thus allowing a restoration. The coarsening flags are also stored.
1439 */
1440 void
1441 save_refine_flags();
1442
1443 /**
1444 * Determine an estimate for the memory consumption (in bytes) of this
1445 * object.
1446 *
1447 * You will want to overload this function in derived classes to compute the
1448 * amount memory used by the derived class, and add the result of this
1449 * function to your result.
1450 */
1451 virtual std::size_t
1452 memory_consumption() const override;
1453
1454 /**
1455 * Exception
1456 */
1457 DeclExceptionMsg(ExcGridNotDeleted,
1458 "When calling restore_grid(), you must have previously "
1459 "deleted the triangulation.");
1460
1461 protected:
1462 /**
1463 * Triangulation used at this time level. Since this is something that every
1464 * time stepping scheme needs to have, we can safely put it into the base
1465 * class. Note that the triangulation is frequently deleted and rebuilt by
1466 * the functions @p sleep and @p wake_up to save memory, if such a behavior
1467 * is specified in the @p flags structure.
1468 */
1469 ObserverPointer<Triangulation<dim, dim>, TimeStepBase_Tria<dim>> tria;
1470
1471 /**
1472 * Pointer to a grid which is to be used as the coarse grid for this time
1473 * level. This pointer is set through the constructor; ownership remains
1474 * with the owner of this management object.
1475 */
1476 ObserverPointer<const Triangulation<dim, dim>, TimeStepBase_Tria<dim>>
1477 coarse_grid;
1478
1479 /**
1480 * Some flags about how this time level shall behave. See the documentation
1481 * of this struct to find out more about that.
1482 */
1483 const Flags flags;
1484
1485 /**
1486 * Flags controlling the refinement process; see the documentation of the
1487 * respective structure for more information.
1488 */
1489 const RefinementFlags refinement_flags;
1490
1491 private:
1492 /**
1493 * Vectors holding the refinement and coarsening flags of the different
1494 * sweeps on this time level. The vectors therefore hold the history of the
1495 * grid.
1496 */
1497 std::vector<std::vector<bool>> refine_flags;
1498
1499 /**
1500 * @ref refine_flags
1501 */
1502 std::vector<std::vector<bool>> coarsen_flags;
1503
1504 /**
1505 * Restore the grid according to the saved data. For this, the coarse grid
1506 * is copied and the grid is stepwise rebuilt using the saved flags.
1507 */
1508 void
1509 restore_grid();
1510 };
1511
1512
1513
1514 /*--------------------------- template functions ----------------------------*/
1515
1516 template <typename InitFunctionObject, typename LoopFunctionObject>
1517 void
1518 TimeDependent::do_loop(InitFunctionObject init_function,
1519 LoopFunctionObject loop_function,
1520 const TimeSteppingData &timestepping_data,
1521 const Direction direction)
1522 {
1523 // the following functions looks quite
1524 // disrupted due to the recurring switches
1525 // for forward and backward running loops.
1526 //
1527 // I chose to switch at every place where
1528 // it is needed, since it is so easy
1529 // to overlook something when you change
1530 // some code at one place when it needs
1531 // to be changed at a second place, here
1532 // for the other direction, also.
1533
1534 const unsigned int n_timesteps = timesteps.size();
1535
1536 // initialize the time steps for
1537 // a round of this loop
1538 for (unsigned int step = 0; step < n_timesteps; ++step)
1539 switch (direction)
1540 {
1541 case forward:
1542 init_function((&*timesteps[step]));
1543 break;
1544 case backward:
1545 init_function((&*timesteps[n_timesteps - step - 1]));
1546 break;
1547 };
1548
1549
1550 // wake up the first few time levels
1551 for (int step = -static_cast<int>(timestepping_data.look_ahead); step < 0;
1552 ++step)
1553 for (int look_ahead = 0;
1554 look_ahead <= static_cast<int>(timestepping_data.look_ahead);
1555 ++look_ahead)
1556 switch (direction)
1557 {
1558 case forward:
1559 if (step + look_ahead >= 0)
1560 timesteps[step + look_ahead]->wake_up(look_ahead);
1561 break;
1562 case backward:
1563 if (n_timesteps - (step + look_ahead) < n_timesteps)
1564 timesteps[n_timesteps - (step + look_ahead)]->wake_up(look_ahead);
1565 break;
1566 };
1567
1568
1569 for (unsigned int step = 0; step < n_timesteps; ++step)
1570 {
1571 // first thing: wake up the
1572 // timesteps ahead as necessary
1573 for (unsigned int look_ahead = 0;
1574 look_ahead <= timestepping_data.look_ahead;
1575 ++look_ahead)
1576 switch (direction)
1577 {
1578 case forward:
1579 if (step + look_ahead < n_timesteps)
1580 timesteps[step + look_ahead]->wake_up(look_ahead);
1581 break;
1582 case backward:
1583 if (n_timesteps > (step + look_ahead))
1584 timesteps[n_timesteps - (step + look_ahead) - 1]->wake_up(
1585 look_ahead);
1586 break;
1587 };
1588
1589
1590 // actually do the work
1591 switch (direction)
1592 {
1593 case forward:
1594 loop_function((&*timesteps[step]));
1595 break;
1596 case backward:
1597 loop_function((&*timesteps[n_timesteps - step - 1]));
1598 break;
1599 };
1600
1601 // let the timesteps behind sleep
1602 for (unsigned int look_back = 0; look_back <= timestepping_data.look_back;
1603 ++look_back)
1604 switch (direction)
1605 {
1606 case forward:
1607 if (step >= look_back)
1608 timesteps[step - look_back]->sleep(look_back);
1609 break;
1610 case backward:
1611 if (n_timesteps - (step - look_back) <= n_timesteps)
1612 timesteps[n_timesteps - (step - look_back) - 1]->sleep(
1613 look_back);
1614 break;
1615 }
1616 }
1617
1618 // make the last few timesteps sleep
1619 for (int step = n_timesteps;
1620 step < static_cast<int>(n_timesteps + timestepping_data.look_back);
1621 ++step)
1622 for (int look_back = 0;
1623 look_back <= static_cast<int>(timestepping_data.look_back);
1624 ++look_back)
1625 switch (direction)
1626 {
1627 case forward:
1628 if ((step - look_back >= 0) &&
1629 (step - look_back < static_cast<int>(n_timesteps)))
1630 timesteps[step - look_back]->sleep(look_back);
1631 break;
1632 case backward:
1633 if ((step - look_back >= 0) &&
1634 (step - look_back < static_cast<int>(n_timesteps)))
1635 timesteps[n_timesteps - (step - look_back) - 1]->sleep(look_back);
1636 break;
1637 };
1638 }
1639
1640 DEAL_II_NAMESPACE_CLOSE
1641
1642 #endif