Debian Codegraph @

include/deal.II/base/auto_derivative_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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_auto_derivative_function_h
16 #define dealii_auto_derivative_function_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/function.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 /**
27 * This class automatically computes the gradient of a function by employing
28 * numerical difference quotients. This only, if the user function does not
29 * provide the gradient function himself.
30 *
31 * The following example of an user defined function overloads and implements
32 * only the value() function but not the gradient() function. If the
33 * gradient() function is invoked then the gradient function implemented by
34 * the AutoDerivativeFunction is called, where the latter function employs
35 * numerical difference quotients.
36 *
37 * @code
38 * class UserFunction: public AutoDerivativeFunction
39 * {
40 * // access to one component at one point
41 * double value (const Point<dim> &p,
42 * const unsigned int component = 0) const override
43 * {
44 * // Implementation ....
45 * };
46 * };
47 *
48 * UserFunction user_function;
49 *
50 * // gradient by employing difference quotients.
51 * Tensor<1,dim> grad=user_function.gradient(some_point);
52 * @endcode
53 *
54 * If the user overloads and implements also the gradient function, then, of
55 * course, the users gradient function is called.
56 *
57 * Note, that the usage of the value() and gradient() functions explained
58 * above, also applies to the value_list() and gradient_list() functions as
59 * well as to the vector valued versions of these functions, see e.g.
60 * vector_value(), vector_gradient(), vector_value_list() and
61 * vector_gradient_list().
62 *
63 * The gradient() and gradient_list() functions make use of the
64 * Function::value() function. The vector_gradient() and
65 * vector_gradient_list() make use of the Function::vector_value() function.
66 * Make sure that the user defined function implements the value() function
67 * and the vector_value() function, respectively.
68 *
69 * Furthermore note, that an object of this class does <b>not</b> represent
70 * the derivative of a function, like FunctionDerivative, that gives a
71 * directional derivative by calling the value() function. In fact, this class
72 * (the AutoDerivativeFunction class) can substitute the Function class as
73 * base class for user defined classes. This class implements the gradient()
74 * functions for automatic computation of numerical difference quotients and
75 * serves as intermediate class between the base Function class and the user
76 * defined function class.
77 *
78 * @ingroup functions
79 */
80 template <int dim>
81 class AutoDerivativeFunction : public Function<dim>
82 {
83 public:
84 /**
85 * Names of difference formulas.
86 */
87 enum DifferenceFormula
88 {
89 /**
90 * The symmetric Euler formula of second order:
91 * @f[
92 * u'(t) \approx
93 * \frac{u(t+h) -
94 * u(t-h)}{2h}.
95 * @f]
96 */
97 Euler,
98 /**
99 * The upwind Euler formula of first order:
100 * @f[
101 * u'(t) \approx
102 * \frac{u(t) -
103 * u(t-h)}{h}.
104 * @f]
105 */
106 UpwindEuler,
107 /**
108 * The fourth order scheme
109 * @f[
110 * u'(t) \approx
111 * \frac{u(t-2h) - 8u(t-h)
112 * + 8u(t+h) - u(t+2h)}{12h}.
113 * @f]
114 */
115 FourthOrder
116 };
117
118 /**
119 * Constructor. Takes the difference step size <tt>h</tt>. It's within the
120 * user's responsibility to choose an appropriate value here. <tt>h</tt>
121 * should be chosen taking into account the absolute value as well as the
122 * amount of local variation of the function. Setting <tt>h=1e-6</tt> might
123 * be a good choice for functions with an absolute value of about 1, that
124 * furthermore does not vary to much.
125 *
126 * <tt>h</tt> can be changed later using the set_h() function.
127 *
128 * Sets DifferenceFormula <tt>formula</tt> to the default <tt>Euler</tt>
129 * formula of the set_formula() function. Change this preset formula by
130 * calling the set_formula() function.
131 */
132 AutoDerivativeFunction(const double h,
133 const unsigned int n_components = 1,
134 const double initial_time = 0.0);
135
136 /**
137 * Virtual destructor; absolutely necessary in this case.
138 */
139 virtual ~AutoDerivativeFunction() override = default;
140
141 /**
142 * Choose the difference formula. See the enum #DifferenceFormula for
143 * available choices.
144 */
145 void
146 set_formula(const DifferenceFormula formula = Euler);
147
148 /**
149 * Takes the difference step size <tt>h</tt>. It's within the user's
150 * responsibility to choose an appropriate value here. <tt>h</tt> should be
151 * chosen taking into account the absolute value of as well as the amount of
152 * local variation of the function. Setting <tt>h=1e-6</tt> might be a good
153 * choice for functions with an absolute value of about 1, that furthermore
154 * does not vary to much.
155 */
156 void
157 set_h(const double h);
158
159 /**
160 * Return the gradient of the specified component of the function at the
161 * given point.
162 *
163 * Compute numerical difference quotients using the preset
164 * #DifferenceFormula.
165 */
166 virtual Tensor<1, dim>
167 gradient(const Point<dim> &p,
168 const unsigned int component = 0) const override;
169
170 /**
171 * Return the gradient of all components of the function at the given point.
172 *
173 * Compute numerical difference quotients using the preset
174 * #DifferenceFormula.
175 */
176 virtual void
177 vector_gradient(const Point<dim> &p,
178 std::vector<Tensor<1, dim>> &gradients) const override;
179
180 /**
181 * Set <tt>gradients</tt> to the gradients of the specified component of the
182 * function at the <tt>points</tt>. It is assumed that <tt>gradients</tt>
183 * already has the right size, i.e. the same size as the <tt>points</tt>
184 * array.
185 *
186 * Compute numerical difference quotients using the preset
187 * #DifferenceFormula.
188 */
189 virtual void
190 gradient_list(const std::vector<Point<dim>> &points,
191 std::vector<Tensor<1, dim>> &gradients,
192 const unsigned int component = 0) const override;
193
194 /**
195 * Set <tt>gradients</tt> to the gradients of the function at the
196 * <tt>points</tt>, for all components. It is assumed that
197 * <tt>gradients</tt> already has the right size, i.e. the same size as the
198 * <tt>points</tt> array.
199 *
200 * The outer loop over <tt>gradients</tt> is over the points in the list,
201 * the inner loop over the different components of the function.
202 *
203 * Compute numerical difference quotients using the preset
204 * #DifferenceFormula.
205 */
206 virtual void
207 vector_gradient_list(
208 const std::vector<Point<dim>> &points,
209 std::vector<std::vector<Tensor<1, dim>>> &gradients) const override;
210
211 /**
212 * Return a #DifferenceFormula of the order <tt>ord</tt> at minimum.
213 */
214 static DifferenceFormula
215 get_formula_of_order(const unsigned int ord);
216
217
218 private:
219 /**
220 * Step size of the difference formula. Set by the set_h() function.
221 */
222 double h;
223
224 /**
225 * Includes the unit vectors scaled by <tt>h</tt>.
226 */
227 std::vector<Tensor<1, dim>> ht;
228
229 /**
230 * Difference formula. Set by the set_formula() function.
231 */
232 DifferenceFormula formula;
233 };
234
235
236 DEAL_II_NAMESPACE_CLOSE
237
238 #endif