Debian Codegraph @

include/deal.II/base/function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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 #ifndef dealii_function_h
16 #define dealii_function_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/function_time.h>
24 #include <deal.II/base/numbers.h>
25 #include <deal.II/base/point.h>
26 #include <deal.II/base/symmetric_tensor.h>
27 #include <deal.II/base/tensor.h>
28
29 #include <functional>
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 #ifndef DOXYGEN
36 template <typename number>
37 class Vector;
38 template <int rank, int dim, typename Number>
39 class TensorFunction;
40 #endif
41
42 /**
43 * This class is a model for a general function that, given a point at which
44 * to evaluate the function, returns a vector of values with one or more
45 * components.
46 *
47 * The class serves the purpose of representing both scalar and vector valued
48 * functions. To this end, we consider scalar functions as a special case of
49 * vector valued functions, in the former case only having a single component
50 * return vector. Since handling vectors is comparatively expensive, the
51 * interface of this class has functions which only ask for a single component
52 * of the vector-valued results (this is what you will usually need in case
53 * you know that your function is scalar-valued) as well as functions you can
54 * ask for an entire vector of results with as many components as the function
55 * object represents. Access to function objects therefore is through the
56 * following methods:
57 * @code
58 * // access to one component at one point
59 * double
60 * value(const Point<dim> & p,
61 * const unsigned int component = 0) const;
62 *
63 * // return all components at one point
64 * void
65 * vector_value(const Point<dim> &p,
66 * Vector<double> &value) const;
67 * @endcode
68 *
69 * For more efficiency, there are other functions returning one or all
70 * components at a list of points at once:
71 * @code
72 * // access to one component at several points
73 * void
74 * value_list(const std::vector<Point<dim>> &point_list,
75 * std::vector<double> &value_list,
76 * const unsigned int component = 0) const;
77 *
78 * // return all components at several points
79 * void
80 * vector_value_list(const std::vector<Point<dim>> &point_list,
81 * std::vector<Vector<double>> &value_list) const;
82 * @endcode
83 *
84 * Furthermore, there are functions returning the gradient of the function or
85 * even higher derivatives at one or several points.
86 *
87 * You will usually only overload those functions you need; the functions
88 * returning several values at a time (value_list(), vector_value_list(), and
89 * gradient analogs) will call those returning only one value (value(),
90 * vector_value(), and gradient analogs), while those ones will throw an
91 * exception when called but not overloaded.
92 *
93 * Conversely, the functions returning all components of the function at one
94 * or several points (i.e. vector_value(), vector_value_list()), will
95 * <em>not</em> call the function returning one component at one point
96 * repeatedly, once for each point and component. The reason is efficiency:
97 * this would amount to too many virtual function calls. If you have
98 * vector-valued functions, you should therefore also provide overloads of the
99 * virtual functions for all components at a time.
100 *
101 * Also note, that unless only called a very small number of times, you should
102 * overload all sets of functions (returning only one value, as well as those
103 * returning a whole array), since the cost of evaluation of a point value is
104 * often less than the virtual function call itself.
105 *
106 * Support for time dependent functions can be found in the base class
107 * FunctionTime.
108 *
109 *
110 * <h3>Functions that return tensors</h3>
111 *
112 * If the functions you are dealing with have a number of components that are
113 * a priori known (for example, <tt>dim</tt> elements), you might consider
114 * using the TensorFunction class instead. This is, in particular, true if the
115 * objects you return have the properties of a tensor, i.e., they are for
116 * example dim-dimensional vectors or dim-by-dim matrices. On the other hand,
117 * functions like VectorTools::interpolate or
118 * VectorTools::interpolate_boundary_values definitely only want objects of
119 * the current type. You can use the VectorFunctionFromTensorFunction class to
120 * convert the former to the latter.
121 *
122 *
123 * <h3>Functions that return vectors of other data types</h3>
124 *
125 * Most of the time, your functions will have the form $f : \Omega \rightarrow
126 * {\mathbb R}^{n_\text{components}}$. However, there are occasions where you
127 * want the function to return vectors (or scalars) over a different number
128 * field, for example functions that return complex numbers or vectors of
129 * complex numbers: $f : \Omega \rightarrow {\mathbb
130 * C}^{n_\text{components}}$. In such cases, you can choose a value different
131 * than the default @p double for the second template
132 * argument of this class: it describes the scalar type to be used for each
133 * component of your return values. It defaults to @p double, but in the
134 * example above, it could be set to <code>std::complex@<double@></code>.
135 * step-58 is an example of this.
136 *
137 * @tparam dim The space dimension of the range space within which the domain
138 * $\Omega$ of the function lies. Consequently, the function will be
139 * evaluated at objects of type @p Point<dim>.
140 * @tparam RangeNumberType The scalar type of the vector space that is
141 * the range (or image) of this function. As discussed above,
142 * objects of the current type represent functions from ${\mathbb
143 * R}^\text{dim}$ to $S^{n_\text{components}}$ where $S$ is the
144 * underlying scalar type of the vector space. The type of $S$ is
145 * given by the @p RangeNumberType template argument.
146 *
147 * @ingroup functions
148 */
149 template <int dim, typename RangeNumberType = double>
150 class Function : public FunctionTime<
151 typename numbers::NumberTraits<RangeNumberType>::real_type>,
152 public EnableObserverPointer
153 {
154 public:
155 /**
156 * Export the value of the template parameter as a static member constant.
157 * Sometimes useful for some expression template programming.
158 */
159 static constexpr unsigned int dimension = dim;
160
161 /**
162 * Number of vector components.
163 */
164 const unsigned int n_components;
165
166 /**
167 * The scalar-valued real type used for representing time.
168 */
169 using time_type = typename FunctionTime<
170 typename numbers::NumberTraits<RangeNumberType>::real_type>::time_type;
171
172 /**
173 * Constructor. May take an initial value for the number of components
174 * (which defaults to one, i.e. a scalar function), and the time variable,
175 * which defaults to zero.
176 */
177 explicit Function(const unsigned int n_components = 1,
178 const time_type initial_time = 0.0);
179
180 /**
181 * Copy constructor.
182 */
183 Function(const Function &f) = default;
184
185 /**
186 * Virtual destructor; absolutely necessary in this case.
187 *
188 * This destructor is declared pure virtual, such that objects of this class
189 * cannot be created. Since all the other virtual functions have a
190 * pseudo-implementation to avoid overhead in derived classes, they can not be
191 * abstract. As a consequence, we could generate an object of this class
192 * because none of this class's functions are abstract.
193 *
194 * We circumvent this problem by making the destructor of this class
195 * abstract virtual. This ensures that at least one member function is
196 * abstract, and consequently, no objects of type Function can be created.
197 * However, there is no need for derived classes to explicitly implement a
198 * destructor: every class has a destructor, either explicitly implemented
199 * or implicitly generated by the compiler, and this resolves the
200 * abstractness of any derived class even if they do not have an explicitly
201 * declared destructor.
202 *
203 * Nonetheless, since derived classes want to call the destructor of a base
204 * class, this destructor is implemented (despite it being pure virtual).
205 */
206 virtual ~Function() override = 0;
207
208 /**
209 * Assignment operator. This is here only so that you can have objects of
210 * derived classes in containers, or assign them otherwise. It will raise an
211 * exception if the object from which you assign has a different number of
212 * components than the one being assigned to.
213 */
214 Function &
215 operator=(const Function &f);
216
217 /**
218 * Return the value of the function at the given point. Unless there is only
219 * one component (i.e. the function is scalar), you should state the
220 * component you want to have evaluated; it defaults to zero, i.e. the first
221 * component.
222 */
223 virtual RangeNumberType
224 value(const Point<dim> &p, const unsigned int component = 0) const;
225
226 /**
227 * Return all components of a vector-valued function at a given point.
228 *
229 * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
230 *
231 * The default implementation will call value() for each component.
232 */
233 virtual void
234 vector_value(const Point<dim> &p, Vector<RangeNumberType> &values) const;
235
236 /**
237 * Set <tt>values</tt> to the point values of the specified component of the
238 * function at the <tt>points</tt>. It is assumed that <tt>values</tt>
239 * already has the right size, i.e. the same size as the <tt>points</tt>
240 * array.
241 *
242 * By default, this function repeatedly calls value() for each point
243 * separately, to fill the output array.
244 */
245 virtual void
246 value_list(const std::vector<Point<dim>> &points,
247 std::vector<RangeNumberType> &values,
248 const unsigned int component = 0) const;
249
250 /**
251 * Set <tt>values</tt> to the point values of the function at the
252 * <tt>points</tt>. It is assumed that <tt>values</tt> already has the
253 * right size, i.e. the same size as the <tt>points</tt> array, and that
254 * all elements be vectors with the same number of components as this
255 * function has.
256 *
257 * By default, this function repeatedly calls vector_value() for each point
258 * separately, to fill the output array.
259 */
260 virtual void
261 vector_value_list(const std::vector<Point<dim>> &points,
262 std::vector<Vector<RangeNumberType>> &values) const;
263
264 /**
265 * For each component of the function, fill a vector of values, one for each
266 * point.
267 *
268 * The default implementation of this function in Function calls
269 * value_list() for each component. In order to improve performance, this
270 * can be reimplemented in derived classes to speed up performance.
271 */
272 virtual void
273 vector_values(const std::vector<Point<dim>> &points,
274 std::vector<std::vector<RangeNumberType>> &values) const;
275
276 /**
277 * Return the gradient of the specified component of the function at the
278 * given point.
279 */
280 virtual Tensor<1, dim, RangeNumberType>
281 gradient(const Point<dim> &p, const unsigned int component = 0) const;
282
283 /**
284 * Return the gradient of all components of the function at the given point.
285 */
286 virtual void
287 vector_gradient(
288 const Point<dim> &p,
289 std::vector<Tensor<1, dim, RangeNumberType>> &gradients) const;
290
291 /**
292 * Set <tt>gradients</tt> to the gradients of the specified component of the
293 * function at the <tt>points</tt>. It is assumed that <tt>gradients</tt>
294 * already has the right size, i.e. the same size as the <tt>points</tt>
295 * array.
296 */
297 virtual void
298 gradient_list(const std::vector<Point<dim>> &points,
299 std::vector<Tensor<1, dim, RangeNumberType>> &gradients,
300 const unsigned int component = 0) const;
301
302 /**
303 * For each component of the function, fill a vector of gradient values, one
304 * for each point.
305 *
306 * The default implementation of this function in Function calls
307 * value_list() for each component. In order to improve performance, this
308 * can be reimplemented in derived classes to speed up performance.
309 */
310 virtual void
311 vector_gradients(
312 const std::vector<Point<dim>> &points,
313 std::vector<std::vector<Tensor<1, dim, RangeNumberType>>> &gradients) const;
314
315 /**
316 * Set <tt>gradients</tt> to the gradients of the function at the
317 * <tt>points</tt>, for all components. It is assumed that
318 * <tt>gradients</tt> already has the right size, i.e. the same size as the
319 * <tt>points</tt> array.
320 *
321 * The outer loop over <tt>gradients</tt> is over the points in the list,
322 * the inner loop over the different components of the function.
323 */
324 virtual void
325 vector_gradient_list(
326 const std::vector<Point<dim>> &points,
327 std::vector<std::vector<Tensor<1, dim, RangeNumberType>>> &gradients) const;
328
329 /**
330 * Compute the Laplacian of a given component at point <tt>p</tt>.
331 */
332 virtual RangeNumberType
333 laplacian(const Point<dim> &p, const unsigned int component = 0) const;
334
335 /**
336 * Compute the Laplacian of all components at point <tt>p</tt> and store
337 * them in <tt>values</tt>.
338 */
339 virtual void
340 vector_laplacian(const Point<dim> &p, Vector<RangeNumberType> &values) const;
341
342 /**
343 * Compute the Laplacian of one component at a set of points.
344 */
345 virtual void
346 laplacian_list(const std::vector<Point<dim>> &points,
347 std::vector<RangeNumberType> &values,
348 const unsigned int component = 0) const;
349
350 /**
351 * Compute the Laplacians of all components at a set of points.
352 */
353 virtual void
354 vector_laplacian_list(const std::vector<Point<dim>> &points,
355 std::vector<Vector<RangeNumberType>> &values) const;
356
357 /**
358 * Compute the Hessian of a given component at point <tt>p</tt>, that is the
359 * gradient of the gradient of the function.
360 */
361 virtual SymmetricTensor<2, dim, RangeNumberType>
362 hessian(const Point<dim> &p, const unsigned int component = 0) const;
363
364 /**
365 * Compute the Hessian of all components at point <tt>p</tt> and store them
366 * in <tt>values</tt>.
367 */
368 virtual void
369 vector_hessian(
370 const Point<dim> &p,
371 std::vector<SymmetricTensor<2, dim, RangeNumberType>> &values) const;
372
373 /**
374 * Compute the Hessian of one component at a set of points.
375 */
376 virtual void
377 hessian_list(const std::vector<Point<dim>> &points,
378 std::vector<SymmetricTensor<2, dim, RangeNumberType>> &values,
379 const unsigned int component = 0) const;
380
381 /**
382 * Compute the Hessians of all components at a set of points.
383 */
384 virtual void
385 vector_hessian_list(
386 const std::vector<Point<dim>> &points,
387 std::vector<std::vector<SymmetricTensor<2, dim, RangeNumberType>>> &values)
388 const;
389
390
391 /**
392 * Return an estimate for the memory consumption, in bytes, of this object.
393 *
394 * This function is virtual and can be overloaded by derived classes.
395 */
396 virtual std::size_t
397 memory_consumption() const;
398 };
399
400
401 namespace Functions
402 {
403 /**
404 * Provide a function which always returns the constant values handed to the
405 * constructor.
406 *
407 * @ingroup functions
408 */
409 template <int dim, typename RangeNumberType = double>
410 class ConstantFunction : public Function<dim, RangeNumberType>
411 {
412 public:
413 /**
414 * Constructor; set values of all components to the provided one. The
415 * default number of components is one.
416 */
417 explicit ConstantFunction(const RangeNumberType value,
418 const unsigned int n_components = 1);
419
420 /**
421 * Constructor; takes an <tt>std::vector<RangeNumberType></tt> object as an
422 * argument. The number of components is determined by
423 * <tt>values.size()</tt>.
424 */
425 explicit ConstantFunction(const std::vector<RangeNumberType> &values);
426
427 /**
428 * Constructor; takes an <tt>Vector<RangeNumberType></tt> object as an
429 * argument. The number of components is determined by
430 * <tt>values.size()</tt>.
431 */
432 explicit ConstantFunction(const Vector<RangeNumberType> &values);
433
434 /**
435 * Constructor; uses whatever stores in [begin_ptr, begin_ptr+n_components)
436 * to initialize a new object.
437 */
438 ConstantFunction(const RangeNumberType *begin_ptr,
439 const unsigned int n_components);
440
441 virtual RangeNumberType
442 value(const Point<dim> &p, const unsigned int component = 0) const override;
443
444 virtual void
445 vector_value(const Point<dim> &p,
446 Vector<RangeNumberType> &return_value) const override;
447
448 virtual void
449 value_list(const std::vector<Point<dim>> &points,
450 std::vector<RangeNumberType> &return_values,
451 const unsigned int component = 0) const override;
452
453 virtual void
454 vector_value_list(
455 const std::vector<Point<dim>> &points,
456 std::vector<Vector<RangeNumberType>> &return_values) const override;
457
458 virtual Tensor<1, dim, RangeNumberType>
459 gradient(const Point<dim> &p,
460 const unsigned int component = 0) const override;
461
462 virtual void
463 vector_gradient(
464 const Point<dim> &p,
465 std::vector<Tensor<1, dim, RangeNumberType>> &gradients) const override;
466
467 virtual void
468 gradient_list(const std::vector<Point<dim>> &points,
469 std::vector<Tensor<1, dim, RangeNumberType>> &gradients,
470 const unsigned int component = 0) const override;
471
472 virtual void
473 vector_gradient_list(
474 const std::vector<Point<dim>> &points,
475 std::vector<std::vector<Tensor<1, dim, RangeNumberType>>> &gradients)
476 const override;
477
478 virtual SymmetricTensor<2, dim, RangeNumberType>
479 hessian(const Point<dim> &point,
480 const unsigned int component = 0) const override;
481
482 virtual RangeNumberType
483 laplacian(const Point<dim> &point,
484 const unsigned int component = 0) const override;
485
486 virtual std::size_t
487 memory_consumption() const override;
488
489 protected:
490 /**
491 * Store the constant function value vector.
492 */
493 std::vector<RangeNumberType> function_value_vector;
494 };
495
496
497
498 /**
499 * Provide a function which always returns zero. Obviously, also the
500 * derivatives of this function are zero. Also, it returns zero on all
501 * components in case the function is not a scalar one, which can be obtained
502 * by passing the constructor the appropriate number of components.
503 *
504 * This function is of use when you want to implement homogeneous boundary
505 * conditions, or zero initial conditions.
506 *
507 * @ingroup functions
508 */
509 template <int dim, typename RangeNumberType = double>
510 class ZeroFunction : public ConstantFunction<dim, RangeNumberType>
511 {
512 public:
513 /**
514 * Constructor. The number of components is preset to one.
515 */
516 explicit ZeroFunction(const unsigned int n_components = 1);
517 };
518
519 /**
520 * A function whose output is also its input. One possible application of this
521 * function is interpolating or projecting a finite element field that
522 * represents spatial coordinates: e.g., one can set up a finite element field
523 * to interpolate the positions of a Triangulation's cells with this function
524 * (via VectorTools::interpolate()), which is useful when doing calculations
525 * in a Lagrangian reference frame.
526 *
527 * @ingroup functions
528 */
529 template <int dim, typename RangeNumberType = double>
530 class IdentityFunction : public Function<dim, RangeNumberType>
531 {
532 public:
533 /**
534 * Constructor. The number of components is set to dim.
535 */
536 IdentityFunction();
537
538 /**
539 * @copydoc Function::value()
540 */
541 virtual RangeNumberType
542 value(const Point<dim> &p, const unsigned int component = 0) const override;
543
544 /**
545 * @copydoc Function::gradient()
546 */
547 virtual Tensor<1, dim, RangeNumberType>
548 gradient(const Point<dim> &p,
549 const unsigned int component = 0) const override;
550
551 /**
552 * @copydoc Function::laplacian()
553 */
554 virtual RangeNumberType
555 laplacian(const Point<dim> &p,
556 const unsigned int component = 0) const override;
557
558 /**
559 * @copydoc Function::hessian()
560 */
561 virtual SymmetricTensor<2, dim, RangeNumberType>
562 hessian(const Point<dim> &p,
563 const unsigned int component = 0) const override;
564 };
565 } // namespace Functions
566
567 /**
568 * This is a constant vector-valued function, in which one or more components
569 * of the vector have a constant value and all other components are zero. It
570 * is especially useful as a weight function for
571 * VectorTools::integrate_difference, where it allows to integrate only one or
572 * a few vector components, rather than the entire vector-valued solution. In
573 * other words, it acts as a component mask with a single component selected
574 * (see the
575 * @ref GlossComponentMask "the glossary entry on component masks").
576 * See the step-20 tutorial program for a detailed explanation and a use case.
577 *
578 * @ingroup functions
579 */
580 template <int dim, typename RangeNumberType = double>
581 class ComponentSelectFunction
582 : public Functions::ConstantFunction<dim, RangeNumberType>
583 {
584 public:
585 /**
586 * Constructor if only a single component shall be non-zero. Arguments
587 * denote the component selected, the value for that component and the total
588 * number of vector components.
589 */
590 ComponentSelectFunction(const unsigned int selected,
591 const RangeNumberType value,
592 const unsigned int n_components);
593
594 /**
595 * Constructor. As before, but the value for the selected component is
596 * assumed to be one. In essence, this function then works as a mask.
597 */
598 ComponentSelectFunction(const unsigned int selected,
599 const unsigned int n_components);
600
601 /**
602 * Constructor if multiple components shall have non-zero, unit values (i.e.
603 * this should be a mask for multiple components). The first argument
604 * denotes a half-open interval of components (for example std::pair(0,dim)
605 * for the first dim components), and the second argument is the total
606 * number of vector components.
607 */
608 ComponentSelectFunction(const std::pair<unsigned int, unsigned int> &selected,
609 const unsigned int n_components);
610
611
612 /**
613 * Substitute function value with value of a <tt>ConstantFunction@<dim,
614 * RangeNumberType@></tt> object and keep the current selection pattern.
615 *
616 * This is useful if you want to have different values in different
617 * components since the provided constructors of
618 * <tt>ComponentSelectFunction@<dim, RangeNumberType@></tt> class can only
619 * have same value for all components.
620 *
621 * @note We copy the underlying component value data from @p f from its
622 * beginning. So the number of components of @p f cannot be less than the
623 * calling object.
624 */
625 virtual void
626 substitute_function_value_with(
627 const Functions::ConstantFunction<dim, RangeNumberType> &f);
628
629 /**
630 * Return the value of the function at the given point for all components.
631 */
632 virtual void
633 vector_value(const Point<dim> &p,
634 Vector<RangeNumberType> &return_value) const override;
635
636 /**
637 * Set <tt>values</tt> to the point values of the function at the
638 * <tt>points</tt>, for all components. It is assumed that <tt>values</tt>
639 * already has the right size, i.e. the same size as the <tt>points</tt>
640 * array.
641 */
642 virtual void
643 vector_value_list(
644 const std::vector<Point<dim>> &points,
645 std::vector<Vector<RangeNumberType>> &values) const override;
646
647 /**
648 * Return an estimate for the memory consumption, in bytes, of this object.
649 */
650 virtual std::size_t
651 memory_consumption() const override;
652
653 protected:
654 /**
655 * Half-open interval of the indices of selected components.
656 */
657 const std::pair<unsigned int, unsigned int> selected_components;
658 };
659
660
661
662 /**
663 * This class provides a way to convert a scalar function of the kind
664 * @code
665 * RangeNumberType foo (const Point<dim> &);
666 * @endcode
667 * into an object of type Function@<dim@>. Since the argument returns a
668 * scalar, the result is clearly a Function object for which
669 * <code>function.n_components == 1</code>. The class works by storing a pointer
670 * to the given function and every time
671 * <code>function.value(p,component)</code> is called, calls
672 * <code>foo(p)</code> and returns the corresponding value. It also makes sure
673 * that <code>component</code> is in fact zero, as needs be for scalar
674 * functions.
675 *
676 * The class provides an easy way to turn a simple global function into
677 * something that has the required Function@<dim@> interface for operations
678 * like VectorTools::interpolate_boundary_values() etc., and thereby allows
679 * for simpler experimenting without having to write all the boiler plate code
680 * of declaring a class that is derived from Function and implementing the
681 * Function::value() function. An example of this is given in the results
682 * section of step-53.
683 *
684 * The class gains additional expressive power because the argument it takes
685 * does not have to be a pointer to an actual function. Rather, it is a
686 * function object, i.e., it can also be the result of a lambda function or some
687 * other object that can be called with a single argument. For
688 * example, if you need a Function object that returns the norm of a point, you
689 * could write it like so:
690 * @code
691 * template <int dim, typename RangeNumberType>
692 * class Norm : public Function<dim, RangeNumberType>
693 * {
694 * public:
695 * virtual RangeNumberType
696 * value(const Point<dim> & p,
697 * const unsigned int component) const
698 * {
699 * Assert (component == 0, ExcMessage ("This object is scalar!"));
700 * return p.norm();
701 * }
702 * };
703 *
704 * Norm<2> my_norm_object;
705 * @endcode
706 * and then pass the <code>my_norm_object</code> around, or you could write it
707 * like so:
708 * @code
709 * ScalarFunctionFromFunctionObject<dim, RangeNumberType> my_norm_object(
710 * &Point<dim>::norm);
711 * @endcode
712 *
713 * Similarly, to generate an object that computes the distance to a point
714 * <code>q</code>, we could do this:
715 * @code
716 * template <int dim, typename RangeNumberType>
717 * class DistanceTo : public Function<dim, RangeNumberType>
718 * {
719 * public:
720 * DistanceTo (const Point<dim> &q) : q(q) {}
721 *
722 * virtual RangeNumberType
723 * value (const Point<dim> & p,
724 * const unsigned int component) const
725 * {
726 * Assert(component == 0, ExcMessage("This object is scalar!"));
727 * return q.distance(p);
728 * }
729 * private:
730 * const Point<dim> q;
731 * };
732 *
733 * Point<2> q (2, 3);
734 * DistanceTo<2> my_distance_object;
735 * @endcode
736 * or we could write it like so:
737 * @code
738 * ScalarFunctionFromFunctionObject<dim, RangeNumberType> my_distance_object(
739 * [&q](const Point<dim> &p){return q.distance(p);});
740 * @endcode
741 * The savings in work to write this are apparent.
742 *
743 * Finally, these lambda functions can be used as a way to map points in
744 * different ways. As an example, let us assume that we have computed
745 * the solution to a one-dimensional problem and that that solution
746 * resides in the following variables:
747 * @code
748 * DoFHandler<1> dof_handler_1d;
749 * Vector<double> solution_1d;
750 * @endcode
751 * We will denote this solution function described by this DoFHandler
752 * and vector object by $u_h(x)$ where $x$ is a vector with just one
753 * component, and consequently is not shown in boldface. Then assume
754 * that we want this $u_h(x)$ to be used as a boundary condition for a 2d
755 * problem at the line $y=0$. Let's say that this line corresponds to
756 * @ref GlossBoundaryIndicator "boundary indicator"
757 * 123.
758 * If we say that the 2d problem is associated with
759 * @code
760 * DoFHandler<2> dof_handler_2d;
761 * @endcode
762 * then in order to evaluate the boundary conditions for this 2d problem,
763 * we would want to call VectorTools::interpolate_boundary_values()
764 * via
765 * @code
766 * AffineConstraints<double> boundary_values_2d;
767 * VectorTools::interpolate_boundary_values (dof_handler_2d,
768 * 123,
769 * ???,
770 * boundary_values_2d);
771 * @endcode
772 * The question here is what to use as the Function object that can be passed
773 * as third argument. It needs to be a Function<2> object, i.e., it
774 * receives a 2d input point and is supposed to return the value at that
775 * point. What we *want* it to do is to just take the $x$ component of the
776 * input point and evaluate the 1d solution at that point, knowing that at
777 * the boundary with indicator 123, the $y$ component of the input point
778 * must be zero. This all can be achieved via the following function
779 * object:
780 * @code
781 * Functions::FEFieldFunction<1>
782 * solution_1d_as_function_object (dof_handler_1d, solution_1d);
783 * auto boundary_evaluator
784 * = [&] (const Point<2> &p)
785 * {
786 * // First extract the x component of the input point:
787 * const Point<1> point_on_axis (p[0]);
788 *
789 * // Then evaluate the 1d solution at that point:
790 * return solution_1d_as_function_object.value(point_on_axis);
791 * }
792 *
793 * AffineConstraints<double> boundary_values_2d;
794 * VectorTools::interpolate_boundary_values (dof_handler_2d,
795 * 123,
796 * ScalarFunctionFromFunctionObject<2>(boundary_evaluator),
797 * boundary_values_2d);
798 * @endcode
799 *
800 * @ingroup functions
801 */
802 template <int dim, typename RangeNumberType = double>
803 class ScalarFunctionFromFunctionObject : public Function<dim, RangeNumberType>
804 {
805 public:
806 /**
807 * Given a function object that takes a Point and returns a RangeNumberType
808 * value, convert this into an object that matches the Function<dim,
809 * RangeNumberType> interface.
810 */
811 explicit ScalarFunctionFromFunctionObject(
812 const std::function<RangeNumberType(const Point<dim> &)> &function_object);
813
814 /**
815 * Given a function object that takes a time and a Point and returns a
816 * RangeNumberType value, convert this into an object that matches the
817 * Function<dim, RangeNumberType> interface.
818 */
819 explicit ScalarFunctionFromFunctionObject(
820 const std::function<RangeNumberType(const double, const Point<dim> &)>
821 &function_object_t);
822
823 /**
824 * Return the value of the function at the given point. Returns the value
825 * the function given to the constructor produces for this point.
826 */
827 virtual RangeNumberType
828 value(const Point<dim> &p, const unsigned int component = 0) const override;
829
830 private:
831 /**
832 * The function object which we call when this class's value() or
833 * value_list() functions are called.
834 */
835 const std::function<RangeNumberType(const double, const Point<dim> &)>
836 function_object;
837 };
838
839
840
841 /**
842 * This class is similar to the ScalarFunctionFromFunctionObject class in that
843 * it allows for the easy conversion of a function object to something that
844 * satisfies the interface of the Function base class. The difference is that
845 * here, the given function object is still a scalar function (i.e. it has a
846 * single value at each space point) but that the Function object generated is
847 * vector valued. The number of vector components is specified in the
848 * constructor, where one also selects a single one of these vector components
849 * that should be filled by the passed object. The result is a vector Function
850 * object that returns zero in each component except the single selected one
851 * where it returns the value returned by the given as the first argument to
852 * the constructor.
853 *
854 * @note In the above discussion, note the difference between the (scalar)
855 * "function object" (i.e., a C++ object <code>x</code> that can be called as
856 * in <code>x(p)</code>) and the capitalized (vector valued) "Function object"
857 * (i.e., an object of a class that is derived from the Function base class).
858 *
859 * To be more concrete, let us consider the following example:
860 * @code
861 * RangeNumberType
862 * one(const Point<2> &p)
863 * {
864 * return 1.0;
865 * }
866 *
867 * VectorFunctionFromScalarFunctionObject<2, RangeNumberType>
868 * component_mask(&one, 1, 3);
869 * @endcode
870 * Here, <code>component_mask</code> then represents a Function object that
871 * for every point returns the vector $(0, 1, 0)^T$, i.e. a mask function that
872 * could, for example, be passed to VectorTools::integrate_difference(). This
873 * effect can also be achieved using the ComponentSelectFunction class but is
874 * obviously easily extended to functions that are non-constant in their one
875 * component.
876 *
877 * @ingroup functions
878 */
879 template <int dim, typename RangeNumberType = double>
880 class VectorFunctionFromScalarFunctionObject
881 : public Function<dim, RangeNumberType>
882 {
883 public:
884 /**
885 * Given a function object that takes a Point and returns a RangeNumberType
886 * value, convert this into an object that matches the Function@<dim@>
887 * interface.
888 *
889 * @param function_object The scalar function that will form one component
890 * of the resulting Function object.
891 * @param n_components The total number of vector components of the
892 * resulting Function object.
893 * @param selected_component The single component that should be filled by
894 * the first argument.
895 */
896 VectorFunctionFromScalarFunctionObject(
897 const std::function<RangeNumberType(const Point<dim> &)> &function_object,
898 const unsigned int selected_component,
899 const unsigned int n_components);
900
901 /**
902 * Return the value of the function at the given point. Returns the value
903 * the function given to the constructor produces for this point.
904 */
905 virtual RangeNumberType
906 value(const Point<dim> &p, const unsigned int component = 0) const override;
907
908 /**
909 * Return all components of a vector-valued function at a given point.
910 *
911 * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
912 */
913 virtual void
914 vector_value(const Point<dim> &p,
915 Vector<RangeNumberType> &values) const override;
916
917 private:
918 /**
919 * The function object which we call when this class's value() or
920 * value_list() functions are called.
921 */
922 const std::function<RangeNumberType(const Point<dim> &)> function_object;
923
924 /**
925 * The vector component whose value is to be filled by the given scalar
926 * function.
927 */
928 const unsigned int selected_component;
929 };
930
931
932 /**
933 * This class is similar to the ScalarFunctionFromFunctionObject and
934 * VectorFunctionFromFunctionObject classes in that it allows for the easy
935 * conversion of a vector of function objects to something that satisfies the
936 * interface of the Function base class.
937 *
938 * The difference is that here the Function object generated may be vector
939 * valued, and you can specify the gradients of the function. The number of
940 * vector components is deduced from the size of the vector in the constructor.
941 *
942 * To be more concrete, let us consider the following example:
943 *
944 * @code
945 * RangeNumberType
946 * first_component(const Point<2> &p)
947 * {
948 * return 1.0;
949 * }
950 *
951 * RangeNumberType
952 * second_component(const Point<2> &p)
953 * {
954 * return 2.0;
955 * }
956 *
957 * Tensor<1, 2, RangeNumberType>
958 * zero_gradient(const Point<2> &) {
959 * return Tensor<1, 2, RangeNumberType>();
960 * }
961 *
962 * FunctionFromFunctionObjects<2, RangeNumberType>
963 * custom_function({&first_component, &second_component},
964 * {&zero_gradient, &zero_gradient});
965 * @endcode
966 */
967 template <int dim, typename RangeNumberType = double>
968 class FunctionFromFunctionObjects : public Function<dim, RangeNumberType>
969 {
970 public:
971 /**
972 * Default constructor.
973 *
974 * This constructor does not initialize the internal methods. To have a
975 * usable function, you need to call at least the set_function_values()
976 * method. If you need also the gradients of the solution, then you must
977 * also call the set_function_gradients() method.
978 */
979 explicit FunctionFromFunctionObjects(const unsigned int n_components = 1,
980 const double initial_time = 0);
981
982 /**
983 * Constructor for functions of which you only know the values.
984 *
985 * The resulting function will have a number of components equal to the size
986 * of the vector @p values. A call to the FunctionFromFunctionObject::gradient()
987 * method will trigger an exception, unless you first call the
988 * set_function_gradients() method.
989 */
990 explicit FunctionFromFunctionObjects(
991 const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
992 &values,
993 const double initial_time = 0.0);
994
995 /**
996 * Constructor for functions of which you only know the values.
997 *
998 * The resulting function will have a number of components equal @p n_components.
999 * A call to the FunctionFromFunctionObject::gradient()
1000 * method will trigger an exception, unless you first call the
1001 * set_function_gradients() method.
1002 */
1003 explicit FunctionFromFunctionObjects(
1004 const std::function<RangeNumberType(const Point<dim> &, const unsigned int)>
1005 &values,
1006 const unsigned int n_components,
1007 const double initial_time = 0.0);
1008
1009 /**
1010 * Constructor for functions of which you know both the values and the
1011 * gradients.
1012 *
1013 * The resulting function will have a number of components equal to the size
1014 * of the vector @p values. If the size of @p values and @p gradients does not
1015 * match, an exception is triggered.
1016 */
1017 FunctionFromFunctionObjects(
1018 const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
1019 &values,
1020 const std::vector<
1021 std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>>
1022 &gradients,
1023 const double initial_time = 0.0);
1024
1025
1026 /**
1027 * Return the value of the function at the given point. Unless there is only
1028 * one component (i.e. the function is scalar), you should state the
1029 * component you want to have evaluated; it defaults to zero, i.e. the first
1030 * component.
1031 */
1032 virtual RangeNumberType
1033 value(const Point<dim> &p, const unsigned int component = 0) const override;
1034
1035 /**
1036 * Return the gradient of the function at the given point. Unless there is
1037 * only one component (i.e. the function is scalar), you should state the
1038 * component you want to have evaluated; it defaults to zero, i.e. the first
1039 * component.
1040 */
1041 virtual Tensor<1, dim, RangeNumberType>
1042 gradient(const Point<dim> &p,
1043 const unsigned int component = 0) const override;
1044
1045 /**
1046 * Reset the function values of this object. An assertion is thrown if the
1047 * size of the @p values parameter does not match the number of components of
1048 * this object.
1049 */
1050 void
1051 set_function_values(
1052 const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
1053 &values);
1054
1055 /**
1056 * Reset the function gradients of this object. An assertion is thrown if the
1057 * size of the @p gradients parameter does not match the number of components of
1058 * this object.
1059 */
1060 void
1061 set_function_gradients(
1062 const std::vector<
1063 std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>>
1064 &gradients);
1065
1066 private:
1067 /**
1068 * The actual function values.
1069 */
1070 std::function<RangeNumberType(const Point<dim> &, const unsigned int)>
1071 function_values;
1072
1073 /**
1074 * The actual function gradients.
1075 */
1076 std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &,
1077 const unsigned int)>
1078 function_gradients;
1079 };
1080
1081
1082 /**
1083 * This class is built as a means of translating the <code>Tensor<1,dim,
1084 * RangeNumberType> </code> values produced by objects of type TensorFunction
1085 * and returning them as a multiple component version of the same thing as a
1086 * Vector for use in, for example, the VectorTools::interpolate or the many
1087 * other functions taking Function objects. It allows the user to place the
1088 * desired components into an <tt>n_components</tt> long vector starting at
1089 * the <tt>selected_component</tt> location in that vector and have all other
1090 * components be 0.
1091 *
1092 * For example: Say you created a class called
1093 * @code
1094 * class RightHandSide : public TensorFunction<rank,dim, RangeNumberType>
1095 * @endcode
1096 * which extends the TensorFunction class and you have an object
1097 * @code
1098 * RightHandSide<1,dim, RangeNumberType> rhs;
1099 * @endcode
1100 * of that class which you want to interpolate onto your mesh using the
1101 * VectorTools::interpolate function, but the finite element you use for the
1102 * DoFHandler object has 3 copies of a finite element with <tt>dim</tt>
1103 * components, for a total of 3*dim components. To interpolate onto that
1104 * DoFHandler, you need an object of type Function that has 3*dim vector
1105 * components. Creating such an object from the existing <code>rhs</code>
1106 * object is done using this piece of code:
1107 * @code
1108 * RightHandSide<1,dim, RangeNumberType> rhs;
1109 * VectorFunctionFromTensorFunction<dim, RangeNumberType> rhs_vector_function(
1110 * rhs, 0, 3*dim);
1111 * @endcode
1112 * where the <code>dim</code> components of the tensor function are placed
1113 * into the first <code>dim</code> components of the function object.
1114 *
1115 * @ingroup functions
1116 */
1117 template <int dim, typename RangeNumberType = double>
1118 class VectorFunctionFromTensorFunction : public Function<dim, RangeNumberType>
1119 {
1120 public:
1121 /**
1122 * Given a TensorFunction object that takes a <tt>Point</tt> and returns a
1123 * <tt>Tensor<1,dim, RangeNumberType></tt> value, convert this into an object
1124 * that matches the Function@<dim@> interface.
1125 *
1126 * By default, create a Vector object of the same size as
1127 * <tt>tensor_function</tt> returns, i.e., with <tt>dim</tt> components.
1128 *
1129 * @param tensor_function The TensorFunction that will form `dim` components of
1130 * the resulting Vector Function object.
1131 * @param n_components The total number of vector components of the
1132 * resulting TensorFunction object. This clearly has to be at least `dim`.
1133 * @param selected_component The first component that should be filled by
1134 * the first argument. This should be such that the entire `tensor_function`
1135 * fits inside the <tt>n_component</tt> length return vector.
1136 */
1137 explicit VectorFunctionFromTensorFunction(
1138 const TensorFunction<1, dim, RangeNumberType> &tensor_function,
1139 const unsigned int selected_component = 0,
1140 const unsigned int n_components = dim);
1141
1142 /**
1143 * This destructor is defined as virtual so as to coincide with all other
1144 * aspects of class.
1145 */
1146 virtual ~VectorFunctionFromTensorFunction() override = default;
1147
1148 /**
1149 * Return a single component of a vector-valued function at a given point.
1150 */
1151 virtual RangeNumberType
1152 value(const Point<dim> &p, const unsigned int component = 0) const override;
1153
1154 /**
1155 * Return all components of a vector-valued function at a given point.
1156 *
1157 * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
1158 */
1159 virtual void
1160 vector_value(const Point<dim> &p,
1161 Vector<RangeNumberType> &values) const override;
1162
1163 /**
1164 * Return all components of a vector-valued function at a list of points.
1165 *
1166 * <tt>value_list</tt> shall be the same size as <tt>points</tt> and each
1167 * element of the vector will be passed to vector_value() to evaluate the
1168 * function
1169 */
1170 virtual void
1171 vector_value_list(
1172 const std::vector<Point<dim>> &points,
1173 std::vector<Vector<RangeNumberType>> &value_list) const override;
1174
1175 /**
1176 * Return the gradient of the specified component of the function at the given
1177 * point.
1178 */
1179 virtual Tensor<1, dim, RangeNumberType>
1180 gradient(const Point<dim> &p,
1181 const unsigned int component = 0) const override;
1182
1183 /**
1184 * Return the gradient of all components of the function at the given point.
1185 */
1186 virtual void
1187 vector_gradient(
1188 const Point<dim> &p,
1189 std::vector<Tensor<1, dim, RangeNumberType>> &gradients) const override;
1190
1191 /**
1192 * Set <tt>gradients</tt> to the gradients of the specified component of the
1193 * function at the <tt>points</tt>. It is assumed that <tt>gradients</tt>
1194 * already has the right size, i.e. the same size as the <tt>points</tt>
1195 * array.
1196 */
1197 virtual void
1198 gradient_list(const std::vector<Point<dim>> &points,
1199 std::vector<Tensor<1, dim, RangeNumberType>> &gradients,
1200 const unsigned int component = 0) const override;
1201
1202 /**
1203 * For each component of the function, fill a vector of gradient values, one
1204 * for each point.
1205 *
1206 * The default implementation of this function in Function calls
1207 * value_list() for each component. In order to improve performance, this
1208 * can be reimplemented in derived classes to speed up performance.
1209 */
1210 virtual void
1211 vector_gradients(const std::vector<Point<dim>> &points,
1212 std::vector<std::vector<Tensor<1, dim, RangeNumberType>>>
1213 &gradients) const override;
1214
1215 /**
1216 * Set <tt>gradients</tt> to the gradients of the function at the
1217 * <tt>points</tt>, for all components. It is assumed that
1218 * <tt>gradients</tt> already has the right size, i.e. the same size as the
1219 * <tt>points</tt> array.
1220 *
1221 * The outer loop over <tt>gradients</tt> is over the points in the list,
1222 * the inner loop over the different components of the function.
1223 */
1224 virtual void
1225 vector_gradient_list(const std::vector<Point<dim>> &points,
1226 std::vector<std::vector<Tensor<1, dim, RangeNumberType>>>
1227 &gradients) const override;
1228
1229 private:
1230 /**
1231 * The TensorFunction object which we call when this class's vector_value()
1232 * or vector_value_list() functions are called.
1233 */
1234 const TensorFunction<1, dim, RangeNumberType> &tensor_function;
1235
1236 /**
1237 * The first vector component whose value is to be filled by the given
1238 * TensorFunction. The values will be placed in components
1239 * selected_component to selected_component+dim-1 for a
1240 * <tt>TensorFunction<1,dim, RangeNumberType></tt> object.
1241 */
1242 const unsigned int selected_component;
1243 };
1244
1245
1246 /**
1247 * This class is built as a means of translating the <code>Tensor<1,dim,
1248 * RangeNumberType> </code> values produced by function objects that
1249 * for a given point return a tensor,
1250 * and returning them as a multiple component version of the same thing as a
1251 * Vector for use in, for example, the VectorTools::interpolate or the many
1252 * other functions taking Function objects. It allows the user to place the
1253 * desired components into an <tt>n_components</tt> long vector starting at
1254 * the <tt>selected_component</tt> location in that vector and have all other
1255 * components be 0.
1256 *
1257 * For example: Say you created a function object that returns the gravity
1258 * (here, a radially inward pointing vector of magnitude 9.81):
1259 * @code
1260 * const auto gravity
1261 * = [](const Point<dim> &p) -> Tensor<1,dim> { return -9.81 * (p /
1262 * p.norm()); }
1263 * @endcode
1264 * and you want to interpolate this onto your mesh using the
1265 * VectorTools::interpolate function, with a finite element for the
1266 * DoFHandler object has 3 copies of a finite element with <tt>dim</tt>
1267 * components, for a total of 3*dim components. To interpolate onto that
1268 * DoFHandler, you need an object of type Function that has 3*dim vector
1269 * components. Creating such an object from the existing <code>gravity</code>
1270 * object is done using this piece of code:
1271 * @code
1272 * VectorFunctionFromTensorFunctionObject<dim, RangeNumberType>
1273 * gravity_vector_function(gravity, 0, 3*dim);
1274 * @endcode
1275 * where the <code>dim</code> components of the `gravity` function are placed
1276 * into the first <code>dim</code> components of the function object.
1277 *
1278 * @ingroup functions
1279 */
1280 template <int dim, typename RangeNumberType = double>
1281 class VectorFunctionFromTensorFunctionObject
1282 : public Function<dim, RangeNumberType>
1283 {
1284 public:
1285 /**
1286 * Given a function object that takes a <tt>Point</tt> and returns a
1287 * <tt>Tensor<1,dim, RangeNumberType></tt> value, convert this into an object
1288 * that matches the Function@<dim@> interface.
1289 *
1290 * By default, create a Vector object of the same size as
1291 * <tt>tensor_function</tt> returns, i.e., with <tt>dim</tt> components.
1292 *
1293 * @param tensor_function_object The TensorFunction that will form `dim` components of
1294 * the resulting Vector Function object.
1295 * @param n_components The total number of vector components of the
1296 * resulting TensorFunction object. This clearly has to be at least `dim`.
1297 * @param selected_component The first component that should be filled by
1298 * the first argument. This should be such that the entire tensor_function
1299 * fits inside the <tt>n_component</tt> length return vector.
1300 */
1301 explicit VectorFunctionFromTensorFunctionObject(
1302 const std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>
1303 &tensor_function_object,
1304 const unsigned int selected_component = 0,
1305 const unsigned int n_components = dim);
1306
1307 /**
1308 * This destructor is defined as virtual so as to coincide with all other
1309 * aspects of class.
1310 */
1311 virtual ~VectorFunctionFromTensorFunctionObject() override = default;
1312
1313 /**
1314 * Return a single component of a vector-valued function at a given point.
1315 */
1316 virtual RangeNumberType
1317 value(const Point<dim> &p, const unsigned int component = 0) const override;
1318
1319 /**
1320 * Return all components of a vector-valued function at a given point.
1321 *
1322 * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
1323 */
1324 virtual void
1325 vector_value(const Point<dim> &p,
1326 Vector<RangeNumberType> &values) const override;
1327
1328 /**
1329 * Return all components of a vector-valued function at a list of points.
1330 *
1331 * <tt>value_list</tt> shall be the same size as <tt>points</tt> and each
1332 * element of the vector will be passed to vector_value() to evaluate the
1333 * function
1334 */
1335 virtual void
1336 vector_value_list(
1337 const std::vector<Point<dim>> &points,
1338 std::vector<Vector<RangeNumberType>> &value_list) const override;
1339
1340 private:
1341 /**
1342 * The TensorFunction object which we call when this class's vector_value()
1343 * or vector_value_list() functions are called.
1344 */
1345 const std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>
1346 tensor_function_object;
1347
1348 /**
1349 * The first vector component whose value is to be filled by the given
1350 * TensorFunction. The values will be placed in components
1351 * selected_component to selected_component+dim-1 for a
1352 * <tt>TensorFunction<1,dim, RangeNumberType></tt> object.
1353 */
1354 const unsigned int selected_component;
1355 };
1356
1357
1358 #ifndef DOXYGEN
1359 // icc 2018 complains about an undefined reference
1360 // if we put this in the templates.h file
1361 //
1362 // The destructor is pure virtual so we can't default it
1363 // in the declaration.
1364 template <int dim, typename RangeNumberType>
1365 inline Function<dim, RangeNumberType>::~Function() = default;
1366 #endif
1367
1368
1369 DEAL_II_NAMESPACE_CLOSE
1370
1371 #endif