Debian Codegraph @

include/deal.II/algorithms/theta_timestepping.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_theta_timestepping_h
17 #define dealii_theta_timestepping_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/algorithms/operator.h>
22 #include <deal.II/algorithms/timestep_control.h>
23
24 #include <deal.II/base/observer_pointer.h>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 // Forward declaration
29 #ifndef DOXYGEN
30 class ParameterHandler;
31 #endif
32
33 namespace Algorithms
34 {
35 /**
36 * A little structure, gathering the size of a timestep and the current
37 * time. Time stepping schemes can use this to provide time step information
38 * to the classes actually performing a single step.
39 *
40 * The definition of what is considered "current time" depends on the
41 * scheme. For an explicit scheme, this is the time at the beginning of the
42 * step. For an implicit scheme, it is usually the time at the end.
43 */
44 struct TimestepData
45 {
46 /// The current time
47 double time;
48 /// The current step size times something
49 double step;
50 };
51
52 /**
53 * Application class performing the theta timestepping scheme.
54 *
55 * The theta scheme is an abstraction of implicit and explicit Euler
56 * schemes, the Crank-Nicolson scheme and linear combinations of those. The
57 * choice of the actual scheme is controlled by the parameter #theta as
58 * follows.
59 * <ul>
60 * <li> #theta=0: explicit Euler scheme
61 * <li> #theta=1: implicit Euler scheme
62 * <li> #theta=½: Crank-Nicolson scheme
63 * </ul>
64 *
65 * For fixed #theta, the Crank-Nicolson scheme is the only second order
66 * scheme. Nevertheless, further stability may be achieved by choosing
67 * #theta larger than ½, thereby introducing a first order error term. In
68 * order to avoid a loss of convergence order, the adaptive theta scheme can
69 * be used, where <i>#theta=½+c dt</i>.
70 *
71 * Assume that we want to solve the equation <i>u' + F(u) = 0</i> with a
72 * step size <i>k</i>. A step of the theta scheme can be written as
73 *
74 * @f[
75 * M u_{n+1} + \theta k F(u_{n+1}) = M u_n - (1-\theta)k F(u_n).
76 * @f]
77 *
78 * Here, <i>M</i> is the @ref GlossMassMatrix "mass matrix". We see, that the right hand side
79 * amounts to an explicit Euler step with modified step size in weak form
80 * (up to inversion of M). The left hand side corresponds to an implicit
81 * Euler step with modified step size (right hand side given). Thus, the
82 * implementation of the theta scheme will use two Operator objects, one for
83 * the explicit, one for the implicit part. Each of these will use its own
84 * TimestepData to account for the modified step sizes (and different times
85 * if the problem is not autonomous). Note that once the explicit part has
86 * been computed, the left hand side actually constitutes a linear or
87 * nonlinear system which has to be solved.
88 *
89 * <h3>Usage AnyData</h3>
90 *
91 * ThetaTimestepping uses AnyData for communicating vectors and time step
92 * information. With outer or inner Operator objects. It does not use itself
93 * the input vectors provided, but forwards them to the explicit and
94 * implicit operators.
95 *
96 * <h4>Vector data</h4>
97 *
98 * The explicit Operator #op_explicit receives in its input in first place
99 * the vector "Previous iterate", which is the solution value after the
100 * previous timestep. It is followed by all vectors provided to
101 * ThetaTimestepping::operator() as input argument. #op_explicit is supposed
102 * to write its result into the first position of its output argument,
103 * labeled "Result".
104 *
105 * The implicit Operator #op_implicit receives the result of #op_explicit in
106 * its first input vector labeled "Previous time". It is followed by all
107 * vectors provided to ThetaTimestepping::operator() as input argument. The
108 * output of #op_implicit is directly written into the output argument given
109 * to ThetaTimestepping.
110 *
111 * <h4>Scalar data</h4>
112 *
113 * Since the introduction of AnyData, ThetaTimestepping is able to
114 * communicate the current time step information through AnyData as well.
115 * Therefore, the AnyData objects handed as input to #op_explicit and
116 * #op_implicit contain two entries of type `const double*` named "Time" and
117 * "Timestep". Note that "Time" refers to the time at the beginning of the
118 * current step for #op_explicit and at the end for #op_implicit,
119 * respectively.
120 *
121 * <h3>Usage of ThetaTimestepping</h3>
122 *
123 * The use ThetaTimestepping is more complicated than for instance Newton,
124 * since the inner operators will usually need to access the TimeStepData.
125 * Thus, we have a circular dependency of information, and we include the
126 * following example for its use.
127 *
128 * First, we define the two operators used by ThetaTimestepping and call
129 * them <code>Implicit</code> and <code>Explicit</code>. They both share the
130 * public interface of Operator, and additionally provide storage for the
131 * matrices to be used and a pointer to TimestepData. Note that we do not
132 * use a ObserverPointer here, since the TimestepData will be destroyed before
133 * the operator.
134 *
135 * @code
136 * class Explicit : public OperatorBase
137 * {
138 * public:
139 * Explicit(const FullMatrix<double> &matrix);
140 * void operator()(AnyData &out, const AnyData &in);
141 *
142 * private:
143 * ObserverPointer<const FullMatrix<double>, Explicit> matrix;
144 * FullMatrix<double> m;
145 * };
146 *
147 * class Implicit : public OperatorBase
148 * {
149 * public:
150 * Implicit(const FullMatrix<double> &matrix);
151 * void operator()(AnyData &out, const AnyData &in);
152 *
153 * private:
154 * ObserverPointer<const FullMatrix<double>, Implicit> matrix;
155 * FullMatrix<double> m;
156 * };
157 * @endcode
158 *
159 * These operators will be implemented after the main program. But let us
160 * look first at how they get used. First, let us define a matrix to be used
161 * for our system and also an OutputOperator in order to write the data of
162 * each timestep to a file.
163 *
164 * @code
165 * int main()
166 * {
167 * FullMatrix<double> matrix(2);
168 * matrix(0, 0) = 0.;
169 * matrix(1, 1) = 0.;
170 * matrix(0, 1) = 3.14;
171 * matrix(1, 0) = -3.14;
172 *
173 * OutputOperator<Vector<double>> out;
174 * out.initialize_stream(std::cout);
175 * @endcode
176 *
177 * Now we create objects for the implicit and explicit parts of the steps as
178 * well as the ThetaTimestepping itself. We initialize the timestepping with
179 * the output operator in order to be able to see the output in every step.
180 *
181 * @code
182 * Explicit op_explicit(matrix);
183 * Implicit op_implicit(matrix);
184 * ThetaTimestepping<Vector<double>> solver(op_explicit, op_implicit);
185 * solver.set_output(out);
186 * @endcode
187 *
188 * The next step is providing the vectors to be used. <tt>value</tt> is
189 * filled with the initial value and is also the vector where the solution
190 * at each timestep will be. Because the interface of Operator has to be
191 * able to handle several vectors, we need to store it in an AnyData object.
192 * Since our problem has no additional parameters, the input AnyData object
193 * remains empty.
194 *
195 * @code
196 * Vector<double> value(2);
197 * value(0) = 1.;
198 * AnyData indata;
199 * AnyData outdata;
200 * outdata.add(&value, "value");
201 * @endcode
202 *
203 * Finally, we are ready to tell the solver, that we are starting at the
204 * initial timestep and run it.
205 *
206 * @code
207 * solver.notify(Events::initial);
208 * solver(outdata, indata);
209 * }
210 * @endcode
211 *
212 * Besides the main function, we need to define the members functions
213 * of the implicit and explicit operators.
214 * First the constructor, which simply copies the system matrix into the
215 * member pointer for later use.
216 *
217 * @code
218 * Explicit::Explicit(const FullMatrix<double> &M)
219 * : matrix(&M)
220 * {
221 * m.reinit(M.m(), M.n());
222 * }
223 * @endcode
224 *
225 * Now we need to study the application of the implicit and explicit
226 * operator. We assume that the pointer <code>matrix</code> points to the
227 * matrix created in the main program (the constructor did this for us).
228 * Here, we first get the time step size from the AnyData object that was
229 * provided as input. Then, if we are in the first step or if the timestep
230 * has changed, we fill the local matrix $m$, such that with the given
231 * matrix $M$, it becomes \f[ m = I - \Delta t M. \f] After we have worked
232 * off the notifications, we clear them, such that the matrix is only
233 * generated when necessary.
234 *
235 * @code
236 * void Explicit::operator()(AnyData &out, const AnyData &in)
237 * {
238 * const double timestep = *in.read_ptr<double>("Timestep");
239 * if (this->notifications.test(Events::initial) ||
240 * this->notifications.test(Events::new_timestep_size))
241 * {
242 * m.equ(-timestep, *matrix);
243 * for (unsigned int i = 0; i < m.m(); ++i)
244 * m(i, i) += 1.;
245 * }
246 * this->notifications.clear();
247 * @endcode
248 *
249 * Now we multiply the input vector with the new matrix and store on output.
250 *
251 * @code
252 * m.vmult(*out.entry<Vector<double> *>(0),
253 * *in.read_ptr<Vector<double>>("Previous iterate"));
254 * }
255 * @endcode
256 *
257 * The code for the implicit operator is almost the same, except
258 * that we change the sign in front of the timestep and use the inverse of
259 * the matrix.
260 *
261 * @code
262 * Implicit::Implicit(const FullMatrix<double> &M)
263 * : matrix(&M)
264 * {
265 * m.reinit(M.m(), M.n());
266 * }
267 *
268 * void Implicit::operator()(AnyData &out, const AnyData &in)
269 * {
270 * const double timestep = *in.read_ptr<double>("Timestep");
271 * if (this->notifications.test(Events::initial) ||
272 * this->notifications.test(Events::new_timestep_size))
273 * {
274 * m.equ(timestep, *matrix);
275 * for (unsigned int i = 0; i < m.m(); ++i)
276 * m(i, i) += 1.;
277 * m.gauss_jordan();
278 * }
279 * this->notifications.clear();
280 * m.vmult(*out.entry<Vector<double> *>(0),
281 * *in.read_ptr<Vector<double>>("Previous time"));
282 * }
283 * @endcode
284 */
285 template <typename VectorType>
286 class ThetaTimestepping : public OperatorBase
287 {
288 public:
289 /**
290 * Constructor, receiving the two operators stored in #op_explicit and
291 * #op_implicit. For their meaning, see the description of those
292 * variables.
293 */
294 ThetaTimestepping(OperatorBase &op_explicit, OperatorBase &op_implicit);
295
296 /**
297 * The timestepping scheme.
298 *
299 * @param in is ignored by ThetaTimestepping, but is merged into the
300 * AnyData objects used as input for the operators #op_explicit and
301 * #op_implicit.
302 *
303 * @param out in its first argument must contain a pointer to a VectorType
304 * instance, which contains the initial value when the operator is called.
305 * It contains the final value when the operator returns.
306 */
307 virtual void
308 operator()(AnyData &out, const AnyData &in) override;
309
310 /**
311 * Register an event triggered by an outer iteration.
312 */
313 virtual void
314 notify(const Event &) override;
315
316 /**
317 * Define an operator which will output the result in each step. Note that
318 * no output will be generated without this.
319 */
320 void
321 set_output(OutputOperator<VectorType> &output);
322
323 /**
324 * Declare parameters in a parameter handler.
325 */
326 static void
327 declare_parameters(ParameterHandler &param);
328
329 /**
330 * Read the parameters in the ParameterHandler.
331 */
332 void
333 parse_parameters(ParameterHandler &param);
334
335 /**
336 * The current time in the timestepping scheme.
337 */
338 double
339 current_time() const;
340
341 /**
342 * The weight between implicit and explicit part.
343 */
344 double
345 theta() const;
346
347 /**
348 * Set a new weight and return the old
349 */
350 double
351 theta(double new_theta);
352
353 /**
354 * The data handed to the #op_explicit time stepping operator.
355 *
356 * The time in here is the time at the beginning of the current step, the
357 * time step is (1-#theta) times the actual time step.
358 */
359 const TimestepData &
360 explicit_data() const;
361
362 /**
363 * The data handed to the #op_implicit time stepping operator.
364 *
365 * The time in here is the time at the beginning of the current step, the
366 * time step is #theta times the actual time step.
367 */
368 const TimestepData &
369 implicit_data() const;
370
371 /**
372 * Allow access to the control object.
373 */
374 TimestepControl &
375 timestep_control();
376
377 private:
378 /**
379 * The object controlling the time step size and computing the new time in
380 * each step.
381 */
382 TimestepControl control;
383
384 /**
385 * The control parameter theta in the range <tt>[0,1]</tt>. It defaults to
386 * 0.5.
387 */
388 double vtheta;
389 /**
390 * Use adaptive #theta if <tt>true</tt>. Not yet implemented.
391 */
392 bool adaptive;
393
394 /**
395 * The data for the explicit part of the scheme.
396 */
397 TimestepData d_explicit;
398
399 /**
400 * The data for the implicit part of the scheme.
401 */
402 TimestepData d_implicit;
403
404
405 /**
406 * The operator computing the explicit part of the scheme. This will
407 * receive in its input data the value at the current time with name
408 * "Current time solution". It should obtain the current time and time
409 * step size from explicit_data().
410 *
411 * Its return value is $ Mu+cF(u) $, where $u$ is the current state
412 * vector, $M$ the @ref GlossMassMatrix "mass matrix", $F$ the operator in space and $c$ is the
413 * adjusted time step size $(1-\theta) \Delta t$.
414 */
415 ObserverPointer<OperatorBase, ThetaTimestepping<VectorType>> op_explicit;
416
417 /**
418 * The operator solving the implicit part of the scheme. It will receive
419 * in its input data the vector "Previous time". Information on the
420 * timestep should be obtained from implicit_data().
421 *
422 * Its return value is the solution <i>u</i> of <i>Mu-cF(u)=f</i>, where
423 * <i>f</i> is the dual space vector found in the "Previous time" entry of
424 * the input data, <i>M</i> the @ref GlossMassMatrix "mass matrix", <i>F</i> the operator in
425 * space and <i>c</i> is the adjusted time step size $ \theta \Delta t$
426 */
427 ObserverPointer<OperatorBase, ThetaTimestepping<VectorType>> op_implicit;
428
429 /**
430 * The operator writing the output in each time step
431 */
432 ObserverPointer<OutputOperator<VectorType>, ThetaTimestepping<VectorType>>
433 output;
434 };
435
436
437 template <typename VectorType>
438 inline const TimestepData &
439 ThetaTimestepping<VectorType>::explicit_data() const
440 {
441 return d_explicit;
442 }
443
444
445 template <typename VectorType>
446 inline const TimestepData &
447 ThetaTimestepping<VectorType>::implicit_data() const
448 {
449 return d_implicit;
450 }
451
452
453 template <typename VectorType>
454 inline TimestepControl &
455 ThetaTimestepping<VectorType>::timestep_control()
456 {
457 return control;
458 }
459
460 template <typename VectorType>
461 inline void
462 ThetaTimestepping<VectorType>::set_output(OutputOperator<VectorType> &out)
463 {
464 output = &out;
465 }
466
467
468 template <typename VectorType>
469 inline double
470 ThetaTimestepping<VectorType>::theta() const
471 {
472 return vtheta;
473 }
474
475
476 template <typename VectorType>
477 inline double
478 ThetaTimestepping<VectorType>::theta(double new_theta)
479 {
480 const double tmp = vtheta;
481 vtheta = new_theta;
482 return tmp;
483 }
484
485
486 template <typename VectorType>
487 inline double
488 ThetaTimestepping<VectorType>::current_time() const
489 {
490 return control.now();
491 }
492 } // namespace Algorithms
493
494 DEAL_II_NAMESPACE_CLOSE
495
496 #endif