Debian Codegraph @

include/deal.II/base/tensor_function_parser.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 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_tensor_function_parser_h
16 #define dealii_tensor_function_parser_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/function_parser.h>
23 #include <deal.II/base/mu_parser_internal.h>
24 #include <deal.II/base/point.h>
25 #include <deal.II/base/tensor.h>
26 #include <deal.II/base/tensor_function.h>
27
28 #include <map>
29 #include <vector>
30
31 DEAL_II_NAMESPACE_OPEN
32
33 // Forward declaration
34 #ifndef DOXYGEN
35 template <typename>
36 class Vector;
37 #endif
38
39 /**
40 * This class implements a tensor function object that gets its value by parsing
41 * a string describing this function. It is a wrapper class for the muparser
42 * library (see http://muparser.beltoforion.de/). This class is essentially an
43 * extension of the FunctionParser class to read in a TensorFunction. The class
44 * reads in an expression of length dim<sup>rank</sup> (separated by a
45 * semicolon) where the components of the tensor function are filled according
46 * to the C++ convention (fastest index is the most right one).
47 *
48 * @note In contrast to the FunctionParser class the TensorFunctionParser class does not support
49 * automatic differentiation.
50 *
51 * A minimal example for the usage of the class would be:
52 * @code
53 * // set up time dependent tensor function:
54 * const std::string variables = "x,y,t";
55 * const std::string expression =
56 * "exp(-t)*cos(x+y);-sin(pi*x*y-t);sin(pi*x*y-t);exp(t)*cos(x+y)";
57 * std::map<std::string,double> constants;
58 * constants["pi"] = numbers::PI;
59 *
60 * // TensorFunctionParser with 2+1 variables (space + time) in 2d of rank 2.
61 * // It is necessary to tell the parser that there is an additional variable
62 * // to be taken into account (t).
63 * TensorFunctionParser<2,2> tfp;
64 * tfp.initialize(variables,
65 * expression,
66 * constants,
67 * true); // flag for time dependence
68 *
69 * // Point at which we want to evaluate the function
70 * Point<2> point(0.0, 1.0);
71 *
72 * // evaluate the expression at 'point':
73 * double result = tfp.value(point);
74 *
75 * deallog << "Function '" << expression << "'"
76 * << " @ " << point
77 * << " is: "
78 * << std::endl
79 * << result[0][0] << ' ' << result[0][1] << std::endl
80 * << result[1][0] << ' ' << result[1][1]
81 * << std::endl;
82 * @endcode
83 *
84 * See also the documentation of the FunctionParser class.
85 *
86 * This class overloads the virtual method value() and value_list() of the
87 * TensorFunction base class with the byte compiled versions of the expressions
88 * given to the initialize() methods. Note that the class will not work unless
89 * you first call the initialize() method that accepts the text description of
90 * the function as an argument (among other things).
91 *
92 * The syntax to describe a function follows usual programming practice, and
93 * is explained in detail at the homepage of the underlying muparser library
94 * at http://muparser.beltoforion.de/ .
95 *
96 *
97 * Vector-valued functions can either be declared using strings where the
98 * function components are separated by semicolons, or using a vector of
99 * strings each defining one vector component.
100 *
101 *
102 * @ingroup functions
103 */
104 template <int rank, int dim, typename Number = double>
105 class TensorFunctionParser
106 : public TensorFunction<rank, dim, Number>,
107 protected internal::FunctionParser::ParserImplementation<dim, Number>
108 {
109 public:
110 /**
111 * Standard constructor. Only set initial time. This object needs to be
112 * initialized with the initialize() method before you can use it. If an
113 * attempt to use this function is made before the initialize() method has
114 * been called, then an exception is thrown.
115 */
116 TensorFunctionParser(const double initial_time = 0.0);
117
118 /**
119 * Constructor for parsed functions. This object needs to be initialized
120 * with the initialize() method before you can use it. If an attempt to
121 * use this function is made before the initialize() method has been called,
122 * then an exception is thrown.
123 * Takes a semicolon separated list of expressions (one for each component
124 * of the tensor function), an optional comma-separated list of constants.
125 */
126 TensorFunctionParser(
127 const std::string &expression,
128 const std::string &constants = "",
129 const std::string &variable_names = default_variable_names() + ",t");
130
131 /**
132 * Copy constructor. Objects of this type can not be copied, and
133 * consequently this constructor is deleted.
134 */
135 TensorFunctionParser(const TensorFunctionParser &) = delete;
136
137 /**
138 * Move constructor. Objects of this type can not be moved, and
139 * consequently this constructor is deleted.
140 */
141 TensorFunctionParser(TensorFunctionParser &&) = delete;
142
143 /**
144 * Copy operator. Objects of this type can not be copied, and
145 * consequently this operator is deleted.
146 */
147 TensorFunctionParser &
148 operator=(const TensorFunctionParser &) = delete;
149
150 /**
151 * Move operator. Objects of this type can not be moved, and
152 * consequently this operator is deleted.
153 */
154 TensorFunctionParser &
155 operator=(TensorFunctionParser &&) = delete;
156
157 /**
158 * Type for the constant map. Used by the initialize() method.
159 */
160 using ConstMap = std::map<std::string, double>;
161
162
163 /**
164 * Initialize the tensor function. This method accepts the following
165 * parameters:
166 *
167 * @param[in] vars A string with the variables that will be used by the
168 * expressions to be evaluated. Note that the variables can have any name
169 * (of course different from the function names defined above!), but the
170 * order IS important. The first variable will correspond to the first
171 * component of the point in which the function is evaluated, the second
172 * variable to the second component and so forth. If this function is also
173 * time dependent, then it is necessary to specify it by setting the
174 * <code>time_dependent</code> parameter to true. An exception is thrown if
175 * the number of variables specified here is different from dim (if this
176 * function is not time-dependent) or from dim+1 (if it is time-dependent).
177 *
178 * @param[in] expressions A vector of strings containing the expressions that
179 * will be byte compiled by the internal parser (TensorFunctionParser). Note
180 * that the size of this vector must match exactly the number of components of
181 * the TensorFunctionParser, as declared in the constructor. If this is not
182 * the case, an exception is thrown.
183 *
184 * @param[in] constants A map of constants used to pass any necessary constant
185 * that we want to specify in our expressions (in the example above the
186 * number pi). An expression is valid if and only if it contains only
187 * defined variables and defined constants (other than the functions
188 * specified above). If a constant is given whose name is not valid (eg:
189 * <code>constants["sin"] = 1.5;</code>) an exception is thrown.
190 *
191 * @param[in] time_dependent If this is a time dependent function, then the
192 * last variable declared in <b>vars</b> is assumed to be the time variable,
193 * and this->get_time() is used to initialize it when evaluating the
194 * function. Naturally the number of variables parsed by the initialize()
195 * method in this case is dim+1. The value of this parameter defaults to
196 * false, i.e. do not consider time.
197 */
198 virtual void
199 initialize(const std::string &vars,
200 const std::vector<std::string> &expressions,
201 const ConstMap &constants,
202 const bool time_dependent = false) override;
203
204 /**
205 * Initialize the function. Same as above, but accepts a string rather than
206 * a vector of strings. If this is a vector valued function, its components
207 * are expected to be separated by a semicolon. An exception is thrown if
208 * this method is called and the number of components successfully parsed
209 * does not match the number of components of the base function.
210 */
211 void
212 initialize(const std::string &vars,
213 const std::string &expression,
214 const ConstMap &constants,
215 const bool time_dependent = false);
216
217 /**
218 * A function that returns default names for variables, to be used in the
219 * first argument of the initialize() functions: it returns "x" in 1d, "x,y"
220 * in 2d, and "x,y,z" in 3d.
221 */
222 static std::string
223 default_variable_names();
224
225 /**
226 * Return the value of the tensor function at the given point.
227 */
228 virtual Tensor<rank, dim, Number>
229 value(const Point<dim> &p) const override;
230
231 /**
232 * Return the value of the tensor function at the given point.
233 */
234 virtual void
235 value_list(const std::vector<Point<dim>> &p,
236 std::vector<Tensor<rank, dim, Number>> &values) const override;
237
238 /**
239 * Return an array of function expressions (one per component), used to
240 * initialize this function.
241 */
242 const std::vector<std::string> &
243 get_expressions() const;
244
245 /**
246 * @addtogroup Exceptions
247 * @{
248 */
249 DeclException2(ExcParseError,
250 int,
251 std::string,
252 << "Parsing Error at Column " << arg1
253 << ". The parser said: " << arg2);
254
255 DeclException2(ExcInvalidExpressionSize,
256 int,
257 int,
258 << "The number of components (" << arg1
259 << ") is not equal to the number of expressions (" << arg2
260 << ").");
261
262 /** @} */
263 private:
264 /**
265 * Number of components is equal dim<sup>rank</sup>.
266 */
267 unsigned int n_components;
268 };
269
270
271 template <int rank, int dim, typename Number>
272 std::string
273 TensorFunctionParser<rank, dim, Number>::default_variable_names()
274 {
275 switch (dim)
276 {
277 case 1:
278 return "x";
279 case 2:
280 return "x,y";
281 case 3:
282 return "x,y,z";
283 default:
284 DEAL_II_NOT_IMPLEMENTED();
285 }
286 return "";
287 }
288
289
290
291 DEAL_II_NAMESPACE_CLOSE
292
293 #endif