| 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 |