Debian Codegraph @

include/deal.II/base/symbolic_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_symbolic_function_h
16 #define dealii_symbolic_function_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/function.h>
23 #include <deal.II/base/point.h>
24 #include <deal.II/base/symmetric_tensor.h>
25 #include <deal.II/base/tensor.h>
26
27 #include <deal.II/differentiation/sd.h>
28
29 #include <functional>
30 #include <iostream>
31 #include <vector>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 // Forward declarations
36 #ifndef DOXYGEN
37 template <typename number>
38 class Vector;
39 namespace Functions
40 {
41 template <int dim, typename RangeNumberType>
42 class SymbolicFunction;
43 }
44 #endif
45
46 namespace Functions
47 {
48 #ifdef DEAL_II_WITH_SYMENGINE
49 /**
50 * A Function class that leverages symbolic differentiation to compute
51 * gradients, Laplacians, Hessians, and time derivatives.
52 *
53 * This class can be used to define functions using methods provided by the
54 * Differentiation::SD namespace. In particular, one can define a symbolic
55 * evaluation point (the argument of the function), as well as a symbolic
56 * expression.
57 *
58 * The symbolic gradients and the symbolic Hessians are computed at
59 * construction time, and when a substitution in the symbolic functions is
60 * requested by the user using the method update_user_substitution_map().
61 *
62 * Whenever one of the evaluation methods is called, a substitution is
63 * attempted with the coordinate symbols argument replaced by the evaluation
64 * point and the symbolic time replaced by the current time, as returned by
65 * the get_time() method. The user has to make sure that at evaluation time
66 * argument substitution provides a fully evaluated expression (i.e., no other
67 * symbols are contained in the function expression, except numerical values),
68 * or an exception will be thrown. Additional symbols can be partially
69 * evaluated or substituted by storing them in a user supplied substitution
70 * maps, that can be updated by calling update_user_substitution_map() or the
71 * set_additional_function_arguments() methods.
72 *
73 * The simplest use case of this class is given in the following example:
74 * @code
75 * SymbolicFunction<2> fun("x^2+y; t*x*y");
76 * fun.set_time(3.0);
77 * Point<2> p(1.0, 2.0);
78 *
79 * auto a = fun.value(p, / * component * / 0); // a = 3.0
80 * auto b = fun.value(p, / * component * / 1); // b = 6.0
81 *
82 * auto df_dt = fun.time_derivative();
83 *
84 * auto c = df_dt.value(p, / * component * / 0); // c = 0.0
85 * auto d = df_dt.value(p, / * component * / 1); // d = 2.0
86 * @endcode
87 * where a Function with two components is defined using a string containing
88 * their expressions separated by semicolons.
89 *
90 * A more involved example, that explicitly uses
91 * Differentiation::SD::Expression objects, is given by
92 * @code
93 * using namespace Differentiation::SD;
94 * // Create a position Tensor<1,2,Differentiation::SD::Expression>
95 * // with symbols "x" and "y", and the symbol "t"
96 * const auto x = SymbolicFunction<2>::get_default_coordinate_symbols();
97 * const auto t = make_symbol("t");
98 *
99 * // Use directly x[0] (the symbol "x"), x[1] (the symbol "y"), and t
100 * // (the symbol "t").
101 * Expression f = std::sin(x[0])*std::cos(x[1])*std::sin(t);
102 * // Alternatively, you can achieve the same result parsing a string:
103 * // Expression f("sin(x)*cos(y)*sin(t)", true);
104 * SymbolicFunction<2> function({f}, x);
105 *
106 * // Evaluate the function, its gradient, and its Laplacian
107 * Point<2> p(1.0, 2.0);
108 * auto fp = function.value(p);
109 * auto gradfp = function.gradient(p);
110 * auto lapfp = function.laplacian(p);
111 *
112 * // Evaluate the time derivative of the function, its gradient, and its
113 * // Laplacian
114 * auto time_derivative = function.time_derivative();
115 * auto dt_fp = time_derivative.value(p);
116 * auto dt_gradfp = time_derivative.gradient(p);
117 * auto dt_lapfp = time_derivative.laplacian(p);
118 * @endcode
119 *
120 * Partial substitution is possible (i.e., you can define the function using
121 * additional symbols). However, as soon as you evaluate the function, you
122 * have to make sure that all extraneous symbols (i.e., those not referring
123 * to the spatial @p coordinate_symbols or to the @p time_symbol variable)
124 * have been substituted with numerical values, or expressions of the spatial
125 * or temporal argument, by calling the update_user_substitution_map() or the
126 * set_additional_function_arguments() methods.
127 *
128 * If your function requires additional arguments to be evaluated, you can
129 * specify them by calling the set_additional_function_arguments() method.
130 *
131 * If you call update_user_substitution_map() and
132 * set_additional_function_arguments() with the same argument, the effect on
133 * the function evaluation will be the same, however, the internal behavior
134 * and function derivatives will be different. The method
135 * update_user_substitution_map() performs the substitution once (the first
136 * time it is required), and then stores internally a copy of the resulting
137 * expression, together with its derivatives (if required). These are then
138 * used in all subsequent evaluations. Calling
139 * set_additional_function_arguments() will evaluate the passed
140 * substitution map on the fly during evaluation time, *after* all
141 * derivatives have been computed.
142 *
143 * @note The difference between this class and the FunctionParser class is
144 * that this class allows to compute first and second order derivatives (in a
145 * symbolic way), while the FunctionParser class computes first order
146 * derivatives only, using finite differences. For complicated expressions,
147 * this class may be slower than the FunctionParser class.
148 *
149 * @ingroup functions
150 */
151 template <int dim, typename RangeNumberType = double>
152 class SymbolicFunction : public Function<dim, RangeNumberType>
153 {
154 public:
155 /**
156 * Constructor.
157 *
158 * The resulting Function object will have as many components as there
159 * are entries in the vector of symbolic expressions @p function.
160 *
161 * The vector @p function should contain a list of symbolic expression
162 * involving the coordinate symbols argument @p coordinate_symbols and
163 * possibly the symbolic time argument @p time_symbol. It is possible to
164 * define it in terms of other symbols, as long as the optional parameter
165 * @p user_substitution_map replaces all symbols except
166 * @p coordinate_symbols and @p time_symbol.
167 * This is useful if, for example, you want to express formulas in terms of
168 * material parameters that you want to name symbolically, rather than
169 * through their numeric values when defining the formula, or when you want
170 * to express your formula in terms of polar coordinates rather than
171 * cartesian ones, and you want the symbolic engine to compute the
172 * derivatives for you.
173 * You may later update the symbol map contained in @p user_substitution_map
174 * by calling update_user_substitution_map().
175 *
176 * @param function A vector of symbolic expressions of type
177 * Differentiation::SD::Expression, representing the components of this
178 * Function.
179 *
180 * @param coordinate_symbols A tensor of symbols representing coordinates,
181 * used as input argument in the symbolic expressions contained in the
182 * @p function vector. The default @p coordinate_symbols is a
183 * Tensor<1,dim,Differentiation::SD::Expression>
184 * containing the symbols "x" for `dim` equal to one, "x", "y" for `dim`
185 * equal to two, and "x", "y", "z" for `dim` equal to three.
186 *
187 * @param time_symbol A symbolic variable representing time. It defaults
188 * to a symbolic variable named "t".
189 *
190 * @param user_substitution_map Any other symbol that may be contained in
191 * the symbolic function needs to be specified in this map. The map may be
192 * empty, and the functions may still contain unevaluated symbols, provided
193 * that you call update_user_substitution_map() and provide a replacement of
194 * all symbols except @p coordinate_symbols and @p time_symbol before any
195 * evaluation occurs.
196 */
197 SymbolicFunction(
198 const std::vector<Differentiation::SD::Expression> &function,
199 const Tensor<1, dim, Differentiation::SD::Expression>
200 &coordinate_symbols = get_default_coordinate_symbols(),
201 const Differentiation::SD::Expression &time_symbol =
202 Differentiation::SD::make_symbol("t"),
203 const Differentiation::SD::types::substitution_map
204 &user_substitution_map = {});
205
206 /**
207 * Constructor that takes a single string that describes the function
208 * expression as a semicolon separated list of expressions.
209 *
210 * The symbolic expression can use the default argument and the default
211 * symbolic time variable, plus any additional symbols that you may
212 * need, provided that you update the user substitution map that substitutes
213 * all of them before you try to evaluate the function or its derivatives,
214 * by calling update_user_substitution_map(), and that you provide all the
215 * additional function arguments of your function using the method
216 * set_additional_function_arguments().
217 */
218 SymbolicFunction(const std::string &expressions);
219
220 /**
221 * Store and apply the substitution map @p substitutions to each symbolic
222 * component of this Function object.
223 *
224 * Notice that this method will trigger a recomputation of the
225 * gradients, Hessians, and Laplacians of each component.
226 */
227 void
228 update_user_substitution_map(
229 const Differentiation::SD::types::substitution_map &substitutions);
230
231 /**
232 * Set the additional @p arguments to be substituted in next evaluation
233 * step.
234 *
235 * Notice that the @p arguments are substituted *after* evaluating the
236 * @p permanent_user_substitution_map, and after all derivatives are
237 * computed. If the additional arguments you pass still depend on the
238 * coordinate or time symbols, then evaluation of derivatives will result in
239 * a partial derivative evaluation.
240 *
241 * This method provides a way to evaluate functions that depend on more
242 * arguments than simply the coordinates and time. If you want to compute
243 * the total derivative w.r.t. to complicated symbolic expressions, you
244 * should call update_user_substitution_map() instead.
245 */
246 void
247 set_additional_function_arguments(
248 const Differentiation::SD::types::substitution_map &arguments);
249
250 /**
251 * Return a tensor of coordinate symbols that can be used to define the
252 * expressions of this symbolic function object.
253 *
254 * The default argument is a Tensor<1,dim,Differentiation::SD::Expression>
255 * containing the symbols "x" for `dim` equal to one, "x", "y" for `dim`
256 * equal to two, and "x", "y", "z" for `dim` equal to three.
257 */
258 static Tensor<1, dim, Differentiation::SD::Expression>
259 get_default_coordinate_symbols();
260
261 /**
262 * Get the actual arguments used for the coordinates in the symbolic
263 * function. This object does not include any user-defined arguments.
264 */
265 const Tensor<1, dim, Differentiation::SD::Expression> &
266 get_coordinate_symbols() const;
267
268 /**
269 * Get the actual symbolic time in use in this symbolic function.
270 */
271 const Differentiation::SD::Expression &
272 get_time_symbol() const;
273
274 /**
275 * Get the actual symbolic expressions used in this symbolic function.
276 */
277 const std::vector<Differentiation::SD::Expression> &
278 get_symbolic_function_expressions() const;
279
280 /**
281 * Get the currently stored @p user_substitution_map.
282 */
283 const Differentiation::SD::types::substitution_map &
284 get_user_substitution_map() const;
285
286 /**
287 * Return a SymbolicFunction object that represents the time derivative of
288 * this function. The spatial argument, the symbolic time, and the currently
289 * stored user substitution map are forwarded to the new function.
290 */
291 SymbolicFunction<dim, RangeNumberType>
292 time_derivative() const;
293
294 // documentation inherited from the base class
295 virtual RangeNumberType
296 value(const Point<dim> &p, const unsigned int component = 0) const override;
297
298 // documentation inherited from the base class
299 virtual Tensor<1, dim, RangeNumberType>
300 gradient(const Point<dim> &p,
301 const unsigned int component = 0) const override;
302
303 // documentation inherited from the base class
304 virtual RangeNumberType
305 laplacian(const Point<dim> &p,
306 const unsigned int component = 0) const override;
307
308 // documentation inherited from the base class
309 virtual SymmetricTensor<2, dim, RangeNumberType>
310 hessian(const Point<dim> &p,
311 const unsigned int component = 0) const override;
312
313 /**
314 * Print the stored arguments and function expression, as it would be
315 * evaluated when calling the method value().
316 */
317 template <typename StreamType>
318 StreamType &
319 print(StreamType &out) const;
320
321 private:
322 /**
323 * Return a substitution map that replaces the argument with the values of
324 * @p point, the symbolic time with the value of this->get_time(), and any
325 * additional arguments with the substitution map given by
326 * @p additional_function_arguments.
327 */
328 Differentiation::SD::types::substitution_map
329 create_evaluation_substitution_map(const Point<dim> &point) const;
330
331 /**
332 * Recompute the symbolic value of the function, applying the user
333 * substitution map. This may be an expensive computation, and it is called
334 * only if necessary.
335 */
336 void
337 update_values() const;
338
339 /**
340 * Recompute the symbolic gradient of the function, applying the user
341 * substitution map. This may be an expensive computation, and it is called
342 * only if necessary.
343 */
344 void
345 update_first_derivatives() const;
346
347 /**
348 * Recompute the symbolic Hessian and the symbolic Lapalacian of the
349 * function. This may be an expensive computation, and it is called
350 * only if necessary.
351 */
352 void
353 update_second_derivatives() const;
354
355 /**
356 * The components of this symbolic function, before any subustitution took
357 * place. This is immutable, and generated at construction time.
358 *
359 * Before any evaluation takes place, the @p user_substitution_map is
360 * applied to this object, and the result is stored in the internal variable
361 * function.
362 *
363 * During evaluation, the @p symbolic_coordinate, the @p symbolic_time, and
364 * any remaining symbols are substituted with the input evaluation point,
365 * the current time, and the content of @p additional_function_arguments.
366 */
367 const std::vector<Differentiation::SD::Expression> user_function;
368
369 /**
370 * Store the user substitution map used for expression substitutions. This
371 * may be updated with a call to update_user_substitution_map(). Notice that
372 * the function may still have unresolved symbols, provided that they are
373 * resolved by a call to set_additional_function_arguments().
374 */
375 Differentiation::SD::types::substitution_map user_substitution_map;
376
377 /**
378 * Store a user substitution map used for additional argument
379 * substitutions. This will be updated by a call to
380 * set_additional_function_arguments().
381 */
382 Differentiation::SD::types::substitution_map additional_function_arguments;
383
384 /**
385 * The actual components of this symbolic function. This is obtained from
386 * the @p user_function, after applying the @p user_substitution_map.
387 */
388 mutable std::vector<Differentiation::SD::Expression> function;
389
390 /**
391 * The gradients of each component of this symbolic function. This is
392 * obtained by computing the symbolic gradient of the object @p function,
393 * that is, after applying the @p user_substitution_map to @p user_function.
394 */
395 mutable std::vector<Tensor<1, dim, Differentiation::SD::Expression>>
396 function_gradient;
397
398 /**
399 * The Hessians of each component of this symbolic function. This is
400 * obtained by computing the symbolic Hessian of the object @p function,
401 * that is, after applying the @p user_substitution_map to @p user_function.
402 */
403 mutable std::vector<Tensor<2, dim, Differentiation::SD::Expression>>
404 function_hessian;
405
406 /**
407 * The Laplacians of each component of this symbolic function. This is
408 * obtained by computing the symbolic Laplacian of the object @p function,
409 * that is, after applying the @p user_substitution_map to @p user_function.
410 */
411 mutable std::vector<Differentiation::SD::Expression> function_laplacian;
412
413 /**
414 * The coordinate symbols argument of the function.
415 */
416 Tensor<1, dim, Differentiation::SD::Expression> coordinate_symbols;
417
418 /**
419 * The symbolic time argument of the function.
420 */
421 mutable Differentiation::SD::Expression time_symbol;
422 };
423
424 /**
425 * Allow output using the bitwise left shift operator.
426 */
427 template <int dim, typename RangeNumberType>
428 inline std::ostream &
429 operator<<(std::ostream &out, const SymbolicFunction<dim, RangeNumberType> &f)
430 {
431 return f.print(out);
432 }
433
434
435
436 // Inline and template functions
437 template <int dim, typename RangeNumberType>
438 template <typename StreamType>
439 StreamType &
440 SymbolicFunction<dim, RangeNumberType>::print(StreamType &out) const
441 {
442 for (unsigned int i = 0; i < dim; ++i)
443 out << coordinate_symbols[i] << ", ";
444 for (const auto &argument_pair : additional_function_arguments)
445 out << argument_pair.first << ", ";
446 out << time_symbol << " -> " << user_function[0];
447 for (unsigned int i = 1; i < user_function.size(); ++i)
448 out << "; " << user_function[i];
449 if (!user_substitution_map.empty())
450 {
451 out << " # ( ";
452 std::string sep = "";
453 for (const auto &substitution : user_substitution_map)
454 {
455 out << sep << substitution.first << " = " << substitution.second;
456 sep = ", ";
457 }
458 out << " )";
459 }
460 return out;
461 }
462 #else
463 template <int dim, typename RangeNumberType = double>
464 class SymbolicFunction
465 {
466 public:
467 SymbolicFunction()
468 {
469 AssertThrow(
470 false,
471 ExcMessage(
472 "This class is not available if you did not enable SymEngine "
473 "when compiling deal.II."));
474 }
475 };
476 #endif
477 } // namespace Functions
478
479 DEAL_II_NAMESPACE_CLOSE
480
481 #endif