Debian Codegraph @

include/deal.II/base/incremental_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2018 - 2023 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_incremental_function_h
16 #define dealii_incremental_function_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/function.h>
22 #include <deal.II/base/mutex.h>
23
24 #include <deal.II/lac/vector.h>
25
26
27 DEAL_II_NAMESPACE_OPEN
28
29 // Forward declaration
30 #ifndef DOXYGEN
31 template <typename number>
32 class Vector;
33 #endif
34
35 namespace Functions
36 {
37 /**
38 * This class represents an incremental function. That is, given an arbitrary
39 * function <code>f</code>, this class will return
40 * <code>f(t) - f(t - delta_t)</code>, where <code>f(t)</code> denotes the
41 * function evaluated at time <code>t</code> and, likewise, <code>f(t -
42 * delta_t)</code> denotes the function evaluated at time <code>t -
43 * delta_t</code>. The decrement <code>delta_t</code> is set by the method
44 * set_decrement(). The main application of this class is to transform a given
45 * Dirichlet boundary condition function into incremental form, as is
46 * required by some implementations of non-linear solution schemes.
47 *
48 * @ingroup functions
49 */
50 template <int dim, typename RangeNumberType = double>
51 class IncrementalFunction : public Function<dim, RangeNumberType>
52 {
53 public:
54 /**
55 * Export the value of the template parameter as a static member constant.
56 * This is sometimes useful in the context of template programming.
57 */
58 static constexpr unsigned int dimension = dim;
59
60 /**
61 * The scalar-valued real type used for representing time.
62 */
63 using time_type = typename Function<dim, RangeNumberType>::time_type;
64
65 /**
66 * Constructor which wraps a given function @p base.
67 *
68 * @note This class stores a non-constant reference to @p base
69 * and will call <code>base.set_time()</code> during evaluation
70 * in order to evaluate the @p base class at any arbitrary time.
71 * It is guaranteed that the temporal state of @p base is returned
72 * to its original settings after each function evaluation in this
73 * class.
74 */
75 IncrementalFunction(Function<dim, RangeNumberType> &base);
76
77 /**
78 * Return the value of the function at the given point.
79 *
80 * Unless there is only one component (i.e. the function is scalar), you
81 * should state the component you want to have evaluated. By default, the
82 * value of the first component is computed.
83 */
84 virtual RangeNumberType
85 value(const Point<dim> &p, const unsigned int component = 0) const override;
86
87 /**
88 * Return all components of a vector-valued function at a given point.
89 *
90 * It is required that the @p values vector have the correct size before
91 * this function is called.
92 */
93 virtual void
94 vector_value(const Point<dim> &p,
95 Vector<RangeNumberType> &values) const override;
96
97 /**
98 * Set the time decrement.
99 *
100 * It is expected that this value be positive.
101 */
102 void
103 set_decrement(const time_type delta_t);
104
105 private:
106 /**
107 * A reference to the function being wrapped.
108 */
109 Function<dim, RangeNumberType> &base;
110
111 /**
112 * The time decrement.
113 */
114 time_type delta_t;
115
116 /**
117 * An auxiliary vector to store values.
118 */
119 mutable Vector<RangeNumberType> values_old;
120
121 /**
122 * Thread mutex for supporting evaluation in multi-threaded contexts.
123 */
124 mutable Threads::Mutex mutex;
125 };
126
127 } // namespace Functions
128
129
130 DEAL_II_NAMESPACE_CLOSE
131
132 #endif