Debian Codegraph @

include/deal.II/numerics/vector_tools_point_gradient.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_vector_tools_point_gradient_h
16 #define dealii_vector_tools_point_gradient_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/template_constraints.h>
22
23 #include <vector>
24
25
26 DEAL_II_NAMESPACE_OPEN
27
28 template <int dim, int spacedim>
29 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
30 class DoFHandler;
31
32 template <int dim, typename Number>
33 class Function;
34 template <int dim, int spacedim>
35 class Mapping;
36
37 template <int dim, typename Number>
38 DEAL_II_CXX20_REQUIRES(dim >= 0)
39 class Point;
40
41 template <int rank_, int dim, typename Number>
42 class Tensor;
43 template <typename Number>
44 class Vector;
45 namespace hp
46 {
47 template <int dim, int spacedim>
48 class MappingCollection;
49 } // namespace hp
50
51 namespace VectorTools
52 {
53 /**
54 * @name Evaluation of functions and errors
55 */
56 /** @{ */
57
58 /**
59 * Evaluate a possibly vector-valued finite element function defined by the
60 * given DoFHandler and nodal vector at the given point, and return the
61 * (vector) gradient of this function through the last argument.
62 *
63 * This is a wrapper function using a Q1-mapping for cell boundaries to call
64 * the other point_gradient() function.
65 *
66 * This function is not particularly cheap. This is because it first
67 * needs to find which cell a given point is in, then find the point
68 * on the reference cell that matches the given evaluation point,
69 * and then evaluate the shape functions there. You probably do not
70 * want to use this function to evaluate the solution at <i>many</i>
71 * points. For this kind of application, the FEFieldFunction class
72 * offers at least some optimizations. On the other hand, if you
73 * want to evaluate <i>many solutions</i> at the same point, you may
74 * want to look at the VectorTools::create_point_source_vector()
75 * function.
76 *
77 * @note If the cell in which the point is found is not locally owned, an
78 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
79 *
80 * @note This function needs to find the cell within which a point lies,
81 * and this can only be done up to a certain numerical tolerance of course.
82 * Consequently, for points that are on, or close to, the boundary of
83 * a cell, you may get the gradient of the finite element field either
84 * here or there, depending on which cell the point is found in. Since
85 * the gradient is, for most elements, discontinuous from one cell or
86 * the other, you will get unpredictable values for
87 * points on or close to the boundary of the cell, as one would expect
88 * when trying to evaluate point values of discontinuous functions.
89 *
90 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
91 */
92 template <int dim, typename VectorType, int spacedim>
93 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
94 void point_gradient(
95 const DoFHandler<dim, spacedim> &dof,
96 const VectorType &fe_function,
97 const Point<spacedim, double> &point,
98 std::vector<Tensor<1, spacedim, typename VectorType::value_type>> &value);
99
100 /**
101 * Same as above for hp.
102 *
103 * @note If the cell in which the point is found is not locally owned, an
104 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
105 *
106 * @note This function needs to find the cell within which a point lies,
107 * and this can only be done up to a certain numerical tolerance of course.
108 * Consequently, for points that are on, or close to, the boundary of
109 * a cell, you may get the gradient of the finite element field either
110 * here or there, depending on which cell the point is found in. Since
111 * the gradient is, for most elements, discontinuous from one cell or
112 * the other, you will get unpredictable values for
113 * points on or close to the boundary of the cell, as one would expect
114 * when trying to evaluate point values of discontinuous functions.
115 *
116 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
117 */
118 template <int dim, typename VectorType, int spacedim>
119 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
120 void point_gradient(
121 const DoFHandler<dim, spacedim> &dof,
122 const VectorType &fe_function,
123 const Point<spacedim, double> &point,
124 std::vector<Tensor<1, spacedim, typename VectorType::value_type>> &value);
125
126 /**
127 * Evaluate a scalar finite element function defined by the given DoFHandler
128 * and nodal vector at the given point, and return the gradient of this
129 * function.
130 *
131 * Compared with the other function of the same name, this is a wrapper
132 * function using a Q1-mapping for cells.
133 *
134 * This function is not particularly cheap. This is because it first
135 * needs to find which cell a given point is in, then find the point
136 * on the reference cell that matches the given evaluation point,
137 * and then evaluate the shape functions there. You probably do not
138 * want to use this function to evaluate the solution at <i>many</i>
139 * points. For this kind of application, the FEFieldFunction class
140 * offers at least some optimizations. On the other hand, if you
141 * want to evaluate <i>many solutions</i> at the same point, you may
142 * want to look at the VectorTools::create_point_source_vector()
143 * function.
144 *
145 * @note If the cell in which the point is found is not locally owned, an
146 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
147 *
148 * @note This function needs to find the cell within which a point lies,
149 * and this can only be done up to a certain numerical tolerance of course.
150 * Consequently, for points that are on, or close to, the boundary of
151 * a cell, you may get the gradient of the finite element field either
152 * here or there, depending on which cell the point is found in. Since
153 * the gradient is, for most elements, discontinuous from one cell or
154 * the other, you will get unpredictable values for
155 * points on or close to the boundary of the cell, as one would expect
156 * when trying to evaluate point values of discontinuous functions.
157 *
158 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
159 */
160 template <int dim, typename VectorType, int spacedim>
161 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
162 Tensor<1, spacedim, typename VectorType::value_type> point_gradient(
163 const DoFHandler<dim, spacedim> &dof,
164 const VectorType &fe_function,
165 const Point<spacedim, double> &point);
166
167 /**
168 * Same as above for hp.
169 *
170 * @note If the cell in which the point is found is not locally owned, an
171 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
172 *
173 * @note This function needs to find the cell within which a point lies,
174 * and this can only be done up to a certain numerical tolerance of course.
175 * Consequently, for points that are on, or close to, the boundary of
176 * a cell, you may get the gradient of the finite element field either
177 * here or there, depending on which cell the point is found in. Since
178 * the gradient is, for most elements, discontinuous from one cell or
179 * the other, you will get unpredictable values for
180 * points on or close to the boundary of the cell, as one would expect
181 * when trying to evaluate point values of discontinuous functions.
182 *
183 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
184 */
185 template <int dim, typename VectorType, int spacedim>
186 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
187 Tensor<1, spacedim, typename VectorType::value_type> point_gradient(
188 const DoFHandler<dim, spacedim> &dof,
189 const VectorType &fe_function,
190 const Point<spacedim, double> &point);
191
192 /**
193 * Evaluate a possibly vector-valued finite element function defined by the
194 * given DoFHandler and nodal vector at the given point, and return the
195 * gradients of this function through the last argument.
196 *
197 * Compared with the other function of the same name, this function uses an
198 * arbitrary mapping for evaluation.
199 *
200 * This function is not particularly cheap. This is because it first
201 * needs to find which cell a given point is in, then find the point
202 * on the reference cell that matches the given evaluation point,
203 * and then evaluate the shape functions there. You probably do not
204 * want to use this function to evaluate the solution at <i>many</i>
205 * points. For this kind of application, the FEFieldFunction class
206 * offers at least some optimizations. On the other hand, if you
207 * want to evaluate <i>many solutions</i> at the same point, you may
208 * want to look at the VectorTools::create_point_source_vector()
209 * function.
210 *
211 * @note If the cell in which the point is found is not locally owned, an
212 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
213 *
214 * @note This function needs to find the cell within which a point lies,
215 * and this can only be done up to a certain numerical tolerance of course.
216 * Consequently, for points that are on, or close to, the boundary of
217 * a cell, you may get the gradient of the finite element field either
218 * here or there, depending on which cell the point is found in. Since
219 * the gradient is, for most elements, discontinuous from one cell or
220 * the other, you will get unpredictable values for
221 * points on or close to the boundary of the cell, as one would expect
222 * when trying to evaluate point values of discontinuous functions.
223 *
224 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
225 */
226 template <int dim, typename VectorType, int spacedim>
227 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
228 void point_gradient(
229 const Mapping<dim, spacedim> &mapping,
230 const DoFHandler<dim, spacedim> &dof,
231 const VectorType &fe_function,
232 const Point<spacedim, double> &point,
233 std::vector<Tensor<1, spacedim, typename VectorType::value_type>> &value);
234
235 /**
236 * Same as above for hp.
237 *
238 * @note If the cell in which the point is found is not locally owned, an
239 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
240 *
241 * @note This function needs to find the cell within which a point lies,
242 * and this can only be done up to a certain numerical tolerance of course.
243 * Consequently, for points that are on, or close to, the boundary of
244 * a cell, you may get the gradient of the finite element field either
245 * here or there, depending on which cell the point is found in. Since
246 * the gradient is, for most elements, discontinuous from one cell or
247 * the other, you will get unpredictable values for
248 * points on or close to the boundary of the cell, as one would expect
249 * when trying to evaluate point values of discontinuous functions.
250 *
251 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
252 */
253 template <int dim, typename VectorType, int spacedim>
254 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
255 void point_gradient(
256 const hp::MappingCollection<dim, spacedim> &mapping,
257 const DoFHandler<dim, spacedim> &dof,
258 const VectorType &fe_function,
259 const Point<spacedim, double> &point,
260 std::vector<Tensor<1, spacedim, typename VectorType::value_type>> &value);
261
262 /**
263 * Evaluate a scalar finite element function defined by the given DoFHandler
264 * and nodal vector at the given point, and return the gradient of this
265 * function.
266 *
267 * Compared with the other function of the same name, this function uses an
268 * arbitrary mapping for evaluation.
269 *
270 * This function is not particularly cheap. This is because it first
271 * needs to find which cell a given point is in, then find the point
272 * on the reference cell that matches the given evaluation point,
273 * and then evaluate the shape functions there. You probably do not
274 * want to use this function to evaluate the solution at <i>many</i>
275 * points. For this kind of application, the FEFieldFunction class
276 * offers at least some optimizations. On the other hand, if you
277 * want to evaluate <i>many solutions</i> at the same point, you may
278 * want to look at the VectorTools::create_point_source_vector()
279 * function.
280 *
281 * @note If the cell in which the point is found is not locally owned, an
282 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
283 *
284 * @note This function needs to find the cell within which a point lies,
285 * and this can only be done up to a certain numerical tolerance of course.
286 * Consequently, for points that are on, or close to, the boundary of
287 * a cell, you may get the gradient of the finite element field either
288 * here or there, depending on which cell the point is found in. Since
289 * the gradient is, for most elements, discontinuous from one cell or
290 * the other, you will get unpredictable values for
291 * points on or close to the boundary of the cell, as one would expect
292 * when trying to evaluate point values of discontinuous functions.
293 *
294 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
295 */
296 template <int dim, typename VectorType, int spacedim>
297 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
298 Tensor<1, spacedim, typename VectorType::value_type> point_gradient(
299 const Mapping<dim, spacedim> &mapping,
300 const DoFHandler<dim, spacedim> &dof,
301 const VectorType &fe_function,
302 const Point<spacedim, double> &point);
303
304 /**
305 * Same as above for hp.
306 *
307 * @note If the cell in which the point is found is not locally owned, an
308 * exception of type VectorTools::ExcPointNotAvailableHere is thrown.
309 *
310 * @note This function needs to find the cell within which a point lies,
311 * and this can only be done up to a certain numerical tolerance of course.
312 * Consequently, for points that are on, or close to, the boundary of
313 * a cell, you may get the gradient of the finite element field either
314 * here or there, depending on which cell the point is found in. Since
315 * the gradient is, for most elements, discontinuous from one cell or
316 * the other, you will get unpredictable values for
317 * points on or close to the boundary of the cell, as one would expect
318 * when trying to evaluate point values of discontinuous functions.
319 *
320 * @dealiiConceptRequires{concepts::is_dealii_vector_type<VectorType>}
321 */
322 template <int dim, typename VectorType, int spacedim>
323 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<VectorType>)
324 Tensor<1, spacedim, typename VectorType::value_type> point_gradient(
325 const hp::MappingCollection<dim, spacedim> &mapping,
326 const DoFHandler<dim, spacedim> &dof,
327 const VectorType &fe_function,
328 const Point<spacedim, double> &point);
329
330 /** @} */
331 } // namespace VectorTools
332
333 DEAL_II_NAMESPACE_CLOSE
334
335 #endif // dealii_vector_tools_point_gradient_h