Debian Codegraph @

include/deal.II/base/tensor_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_tensor_function_h
16 #define dealii_tensor_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.h>
24 #include <deal.II/base/function_time.h>
25 #include <deal.II/base/observer_pointer.h>
26 #include <deal.II/base/point.h>
27
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * This class is a model for a tensor valued function. The interface of the
34 * class is mostly the same as that for the Function class, with the exception
35 * that it does not support vector-valued functions with several components,
36 * but that the return type is always tensor-valued. The returned values of
37 * the evaluation of objects of this type are always whole tensors, while for
38 * the <tt>Function</tt> class, one can ask for a specific component only, or
39 * use the <tt>vector_value</tt> function, which however does not return the
40 * value, but rather writes it into the address provided by its second
41 * argument. The reason for the different behavior of the classes is that in
42 * the case of tensor valued functions, the size of the argument is known to
43 * the compiler a priori, such that the correct amount of memory can be
44 * allocated on the stack for the return value; on the other hand, for the
45 * vector valued functions, the size is not known to the compiler, so memory
46 * has to be allocated on the heap, resulting in relatively expensive copy
47 * operations. One can therefore consider this class a specialization of the
48 * <tt>Function</tt> class for which the size is known. An additional benefit
49 * is that tensors of arbitrary rank can be returned, not only vectors, as for
50 * them the size can be determined similarly simply.
51 *
52 * @ingroup functions
53 */
54 template <int rank, int dim, typename Number = double>
55 class TensorFunction
56 : public FunctionTime<typename numbers::NumberTraits<Number>::real_type>,
57 public EnableObserverPointer
58 {
59 public:
60 /**
61 * Alias for the return types of the <tt>value</tt> function.
62 */
63 using value_type = Tensor<rank, dim, Number>;
64
65 /**
66 * Alias for the return types of the <tt>gradient</tt> functions.
67 */
68 using gradient_type = Tensor<rank + 1, dim, Number>;
69
70 /**
71 * The scalar-valued real type used for representing time.
72 */
73 using time_type = typename FunctionTime<
74 typename numbers::NumberTraits<Number>::real_type>::time_type;
75
76 /**
77 * Constructor. May take an initial value for the time variable, which
78 * defaults to zero.
79 */
80 TensorFunction(const time_type initial_time = time_type(0.0));
81
82 /**
83 * Virtual destructor; absolutely necessary in this case, as classes are
84 * usually not used by their true type, but rather through pointers to this
85 * base class.
86 */
87 virtual ~TensorFunction() override = default;
88
89 /**
90 * Return the value of the function at the given point.
91 */
92 virtual value_type
93 value(const Point<dim> &p) const;
94
95 /**
96 * Set <tt>values</tt> to the point values of the function at the
97 * <tt>points</tt>. It is assumed that <tt>values</tt> already has the
98 * right size, i.e. the same size as the <tt>points</tt> array.
99 */
100 virtual void
101 value_list(const std::vector<Point<dim>> &points,
102 std::vector<value_type> &values) const;
103
104 /**
105 * Return the gradient of the function at the given point.
106 */
107 virtual gradient_type
108 gradient(const Point<dim> &p) const;
109
110 /**
111 * Set <tt>gradients</tt> to the gradients of the function at the
112 * <tt>points</tt>. It is assumed that <tt>values</tt> already has the
113 * right size, i.e. the same size as the <tt>points</tt> array.
114 */
115 virtual void
116 gradient_list(const std::vector<Point<dim>> &points,
117 std::vector<gradient_type> &gradients) const;
118 };
119
120
121
122 /**
123 * Provide a tensor valued function which always returns a constant tensor
124 * value. Obviously, all derivatives of this function are zero.
125 *
126 * @ingroup functions
127 */
128 template <int rank, int dim, typename Number = double>
129 class ConstantTensorFunction : public TensorFunction<rank, dim, Number>
130 {
131 public:
132 /**
133 * The scalar-valued real type used for representing time.
134 */
135 using time_type = typename TensorFunction<rank, dim, Number>::time_type;
136
137 /**
138 * Constructor; takes the constant tensor value as an argument. The
139 * reference value is copied internally.
140 *
141 * An initial value for the time variable may be specified, otherwise it
142 * defaults to zero.
143 */
144 ConstantTensorFunction(const dealii::Tensor<rank, dim, Number> &value,
145 const time_type initial_time = 0.0);
146
147 virtual ~ConstantTensorFunction() override = default;
148
149 virtual typename dealii::TensorFunction<rank, dim, Number>::value_type
150 value(const Point<dim> &p) const override;
151
152 virtual void
153 value_list(
154 const std::vector<Point<dim>> &points,
155 std::vector<typename dealii::TensorFunction<rank, dim, Number>::value_type>
156 &values) const override;
157
158 virtual typename dealii::TensorFunction<rank, dim, Number>::gradient_type
159 gradient(const Point<dim> &p) const override;
160
161 virtual void
162 gradient_list(
163 const std::vector<Point<dim>> &points,
164 std::vector<
165 typename dealii::TensorFunction<rank, dim, Number>::gradient_type>
166 &gradients) const override;
167
168 private:
169 const dealii::Tensor<rank, dim, Number> _value;
170 };
171
172
173
174 /**
175 * Provide a tensor valued function which always returns zero. Obviously, all
176 * derivatives of this function are zero.
177 *
178 * @ingroup functions
179 */
180 template <int rank, int dim, typename Number = double>
181 class ZeroTensorFunction : public ConstantTensorFunction<rank, dim, Number>
182 {
183 public:
184 /**
185 * The scalar-valued real type used for representing time.
186 */
187 using time_type =
188 typename ConstantTensorFunction<rank, dim, Number>::time_type;
189
190 /**
191 * Constructor.
192 *
193 * An initial value for the time variable may be specified, otherwise it
194 * defaults to zero.
195 */
196 ZeroTensorFunction(const time_type initial_time = 0.0);
197 };
198
199
200 DEAL_II_NAMESPACE_CLOSE
201
202 #endif