Debian Codegraph @

include/deal.II/base/parsed_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2007 - 2025 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
16 #ifndef dealii_parsed_function_h
17 #define dealii_parsed_function_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/auto_derivative_function.h>
22 #include <deal.II/base/function_parser.h>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 #ifndef DOXYGEN
27 class ParameterHandler;
28 #endif
29
30 namespace Functions
31 {
32 /**
33 * Friendly interface to the FunctionParser class. This class is meant as a
34 * wrapper for the FunctionParser class. It is used in the step-34 and step-86
35 * tutorial programs.
36 *
37 * It provides two methods to declare and parse a ParameterHandler object
38 * and creates the Function object declared in the parameter file. This
39 * class is derived from the AutoDerivativeFunction class, so you don't need
40 * to specify derivatives. An example of usage of this class is as follows:
41 *
42 * @code
43 * // A parameter handler
44 * ParameterHandler prm;
45 *
46 * // Declare a section for the function we need
47 * prm.enter_subsection("My vector function");
48 * ParsedFunction<dim>::declare_parameters(prm, dim);
49 * prm.leave_subsection();
50 *
51 * // Create a ParsedFunction
52 * ParsedFunction<dim> my_vector_function(dim);
53 *
54 * // Parse an input file.
55 * prm.parse_input(some_input_file);
56 *
57 * // Initialize the ParsedFunction object with the given file
58 * prm.enter_subsection("My vector function");
59 * my_vector_function.parse_parameters(prm);
60 * prm.leave_subsection();
61 *
62 * @endcode
63 *
64 * And here is an example of how the input parameter could look like (see
65 * the documentation of the FunctionParser class for a detailed description
66 * of the syntax of the function definition):
67 *
68 * @code
69 *
70 * # A test two dimensional vector function, depending on time
71 * subsection My vector function
72 * set Function constants = kappa=.1, lambda=2.
73 * set Function expression = if(y>.5, kappa*x*(1-x),0); t^2*cos(lambda*pi*x)
74 * set Variable names = x,y,t
75 * end
76 *
77 * @endcode
78 *
79 * @ingroup functions
80 */
81 template <int dim>
82 class ParsedFunction : public AutoDerivativeFunction<dim>
83 {
84 public:
85 /**
86 * Construct a vector function. The vector function which is generated has
87 * @p n_components components (defaults to 1). The parameter @p h is used
88 * to initialize the AutoDerivativeFunction class from which this class is
89 * derived.
90 */
91 ParsedFunction(const unsigned int n_components = 1, const double h = 1e-8);
92
93 /**
94 * Declare parameters needed by this class. The parameter @p
95 * n_components is used to generate the right code according to the number
96 * of components of the function that will parse this ParameterHandler. If
97 * the number of components which is parsed does not match the number of
98 * components of this object, an assertion is thrown and the program is
99 * aborted. The additional parameter @p expr is used to declare the default
100 * expression used by the function. The default behavior for this class is
101 * to declare the following entries:
102 *
103 * @code
104 *
105 * set Function constants =
106 * set Function expression = 0
107 * set Variable names = x,y,t
108 *
109 * @endcode
110 */
111 static void
112 declare_parameters(ParameterHandler &prm,
113 const unsigned int n_components = 1,
114 const std::string &input_expr = "");
115
116 /**
117 * Parse parameters needed by this class. If the number of components
118 * which is parsed does not match the number of components of this object,
119 * an assertion is thrown and the program is aborted. In order for the
120 * class to function properly, we follow the same conventions declared in
121 * the FunctionParser class (look there for a detailed description of the
122 * syntax for function declarations).
123 *
124 * The three variables that can be parsed from a parameter file are the
125 * following:
126 *
127 * @code
128 *
129 * set Function constants =
130 * set Function expression =
131 * set Variable names =
132 *
133 * @endcode
134 *
135 * %Function constants is a collection of pairs in the form name=value,
136 * separated by commas, for example:
137 *
138 * @code
139 *
140 * set Function constants = lambda=1., alpha=2., gamma=3.
141 *
142 * @endcode
143 *
144 * These constants can be used in the declaration of the function
145 * expression, which follows the convention of the FunctionParser class.
146 * In order to specify vector functions, semicolons have to be used to
147 * separate the different components, e.g.:
148 *
149 * @code
150 *
151 * set Function expression = cos(pi*x); cos(pi*y)
152 *
153 * @endcode
154 *
155 * The variable names entry can be used to customize the name of the
156 * variables used in the Function. It defaults to
157 *
158 * @code
159 *
160 * set Variable names = x,t
161 *
162 * @endcode
163 *
164 * for one dimensional problems,
165 *
166 * @code
167 *
168 * set Variable names = x,y,t
169 *
170 * @endcode
171 *
172 * for two dimensional problems and
173 *
174 * @code
175 *
176 * set Variable names = x,y,z,t
177 *
178 * @endcode
179 *
180 * for three dimensional problems.
181 *
182 * The time variable can be set according to specifications in the
183 * FunctionTime base class.
184 */
185 void
186 parse_parameters(ParameterHandler &prm);
187
188 /**
189 * Return all components of a vector-valued function at the given point @p
190 * p.
191 */
192 virtual void
193 vector_value(const Point<dim> &p, Vector<double> &values) const override;
194
195 /**
196 * Return the value of the function at the given point. Unless there is
197 * only one component (i.e. the function is scalar), you should state the
198 * component you want to have evaluated; it defaults to zero, i.e. the
199 * first component.
200 */
201 virtual double
202 value(const Point<dim> &p, const unsigned int component = 0) const override;
203
204 /**
205 * Set the time to a specific value for time-dependent functions.
206 *
207 * We need to overwrite this to set the time also in the accessor
208 * FunctionParser<dim>.
209 */
210 virtual void
211 set_time(const double newtime) override;
212
213 private:
214 /**
215 * The object with which we do computations.
216 */
217 FunctionParser<dim> function_object;
218 };
219 } // namespace Functions
220
221 DEAL_II_NAMESPACE_CLOSE
222
223 #endif