Debian Codegraph @

include/deal.II/numerics/fe_field_function.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2007 - 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_fe_function_h
16 #define dealii_fe_function_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/function.h>
21 #include <deal.II/base/point.h>
22 #include <deal.II/base/tensor.h>
23 #include <deal.II/base/thread_local_storage.h>
24
25 #include <deal.II/dofs/dof_accessor.h>
26 #include <deal.II/dofs/dof_handler.h>
27
28 #include <deal.II/fe/mapping_q1.h>
29
30 #include <deal.II/grid/grid_tools_cache.h>
31
32 #include <deal.II/lac/vector.h>
33
34 #include <optional>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39 // Forward declaration
40 #ifndef DOXYGEN
41 namespace VectorTools
42 {
43 class ExcPointNotAvailableHere;
44 }
45 #endif
46
47 namespace Functions
48 {
49 /**
50 * This is an interpolation function for the given dof handler and the given
51 * solution vector. The points at which this function can be evaluated MUST
52 * be inside the domain of the dof handler, but except from this, no other
53 * requirement is given. This function is rather slow, as it needs to
54 * construct a quadrature object for the point (or set of points) where you
55 * want to evaluate your finite element function. In order to do so, it
56 * needs to find out where the points lie.
57 *
58 * If you know in advance in which cell your points lie, you can accelerate
59 * things a bit, by calling set_active_cell() before asking for values or
60 * gradients of the function. If you don't do this, and your points don't
61 * lie in the cell that is currently stored, the function
62 * GridTools::find_active_cell_around_point is called to find out where the
63 * point is.
64 * You can specify an optional mapping to use when looking for points in
65 * the grid. If you don't do so, this function uses a Q1 mapping.
66 *
67 * Once the FEFieldFunction knows where the points lie, it creates a
68 * quadrature formula for those points, and calls
69 * FEValues::get_function_values or FEValues::get_function_gradients with
70 * the given quadrature points.
71 *
72 * If you only need the quadrature points but not the values of the finite
73 * element function (you might want this for the adjoint interpolation), you
74 * can also use the function compute_point_locations() alone.
75 *
76 * An example of how to use this function is the following:
77 *
78 * @code
79 *
80 * // Generate two triangulations
81 * Triangulation<dim> tria_1;
82 * Triangulation<dim> tria_2;
83 *
84 * // Read the triangulations from files, or build them up, or get them
85 * // from some place. Assume that tria_2 is *entirely* included in tria_1.
86 *
87 * // Associate a dof handler and a solution to the first triangulation
88 * DoFHandler<dim> dh1 (tria_1);
89 * Vector<double> solution_1;
90 *
91 * // On this first domain, set up the various data structures,
92 * // assemble matrices, solve the linear system, and get a Nobel
93 * // prize for the work we have done here:
94 * [...]
95 *
96 * // Then create a DoFHandler and solution vector for the second domain:
97 * DoFHandler<dim> dh2 (tria_2);
98 * Vector<double> solution_2;
99 *
100 * // Finally, project the solution on the first domain onto the
101 * // second domain, assuming that this does not require querying
102 * // values from outside the first domain:
103 * Functions::FEFieldFunction<dim> fe_function_1 (dh_1, solution_1);
104 * VectorTools::project (dh_2, constraints_2, quad,
105 * fe_function_1, solution_2);
106 *
107 * // Alternatively, we could have also interpolated it:
108 * Vector<double> solution_3;
109 * VectorTools::interpolate (dh_2, fe_function_1, solution_3);
110 * @endcode
111 *
112 * The snippet of code above will work assuming that the second
113 * triangulation is entirely included in the first one.
114 *
115 * FEFieldFunction is designed to be an easy way to get the results of your
116 * computations across different, possibly non matching, grids. No knowledge
117 * of the location of the points is assumed in this class, which makes it
118 * rely entirely on the GridTools::find_active_cell_around_point utility for
119 * its job. However the class can be fed an "educated guess" of where the
120 * points that will be computed actually are by using the
121 * FEFieldFunction::set_active_cell method, so if you have a smart way to
122 * tell where your points are, you will save a lot of computational time by
123 * letting this class know.
124 *
125 *
126 * <h3>Using FEFieldFunction with parallel triangulations</h3>
127 *
128 * When using this class with a parallel distributed triangulation object
129 * and evaluating the solution at a particular point, not every processor
130 * will own the cell at which the solution should be evaluated. Rather, it may
131 * be that the cell in which this point is found is in fact a ghost or
132 * artificial cell (see
133 * @ref GlossArtificialCell
134 * and
135 * @ref GlossGhostCell).
136 * The solution can be evaluated on ghost cells, but for artificial cells
137 * we have no access to the solution there and
138 * functions that evaluate the solution at such a point will trigger an
139 * exception of type VectorTools::ExcPointNotAvailableHere.
140 *
141 * To deal with this situation, you will want to use code as follows when,
142 * for example, evaluating the solution at the origin (here using a parallel
143 * TrilinosWrappers vector to hold the solution):
144 * @code
145 * Functions::FEFieldFunction<dim,TrilinosWrappers::MPI::Vector>
146 * solution_function (dof_handler, solution);
147 * Point<dim> origin = Point<dim>();
148 *
149 * double solution_at_origin;
150 * bool point_found = true;
151 * try
152 * {
153 * solution_at_origin = solution_function.value (origin);
154 * }
155 * catch (const VectorTools::ExcPointNotAvailableHere &)
156 * {
157 * point_found = false;
158 * }
159 *
160 * if (point_found == true)
161 * ...do something...;
162 * @endcode
163 * The last part (the `...do something...`) part needs to be application
164 * specific. If you really do need the information on this process, you need
165 * to communicate with the process that actually owns the cell in which the
166 * point at which you want the solution is located. Since you don't know
167 * which process that may be, this will necessarily require a global
168 * communication step. The FERemoteEvaluation class may be useful in this
169 * context.
170 *
171 * Finally, there is the case of the value_list(), gradient_list(),
172 * and similar functions of this class that take a list of points. For these
173 * functions, it may be that some of the points are on locally owned cells,
174 * and others are not -- in which case, again, you will receive an exception.
175 * Because these functions do not return information about which of the points
176 * can and which cannot be evaluated, the correct approach is to call the
177 * `*_list()` function within a `try` block, and if it fails fall back to
178 * calling value(), gradient(), or similar in a loop over the points you
179 * wanted evaluated to find out for which point the call fails.
180 *
181 * @ingroup functions
182 */
183 template <int dim, typename VectorType = Vector<double>, int spacedim = dim>
184 class FEFieldFunction : public Function<dim, typename VectorType::value_type>
185 {
186 public:
187 /**
188 * Construct a vector function. A smart pointers is stored to the dof
189 * handler, so you have to make sure that it make sense for the entire
190 * lifetime of this object. The number of components of this functions is
191 * equal to the number of components of the finite element object. If a
192 * mapping is specified, that is what is used to find out where the points
193 * lay. Otherwise the standard Q1 mapping is used.
194 */
195 FEFieldFunction(
196 const DoFHandler<dim, spacedim> &dh,
197 const VectorType &data_vector,
198 const Mapping<dim> &mapping = StaticMappingQ1<dim>::mapping);
199
200 /**
201 * Set the current cell. If you know in advance where your points lie, you
202 * can tell this object by calling this function. This will speed things
203 * up a little.
204 */
205 void
206 set_active_cell(
207 const typename DoFHandler<dim, spacedim>::active_cell_iterator &newcell);
208
209 /**
210 * Get one vector value at the given point. It is inefficient to use
211 * single points. If you need more than one at a time, use the
212 * vector_value_list() function. For efficiency reasons, it is better if
213 * all the points lie on the same cell. This is not mandatory, however it
214 * does speed things up.
215 *
216 * @note When using this function on a
217 * parallel::distributed::Triangulation you may get an exception when
218 * trying to evaluate the solution at a point that lies on an artificial
219 * cell (see
220 * @ref GlossLocallyOwnedCell).
221 * See the section in the general documentation of this class for more
222 * information.
223 */
224 virtual void
225 vector_value(
226 const Point<dim> &p,
227 Vector<typename VectorType::value_type> &values) const override;
228
229 /**
230 * Return the value of the function at the given point. Unless there is
231 * only one component (i.e. the function is scalar), you should state the
232 * component you want to have evaluated; it defaults to zero, i.e. the
233 * first component. It is inefficient to use single points. If you need
234 * more than one at a time, use the vector_value_list() function. For
235 * efficiency reasons, it is better if all the points lie on the same
236 * cell. This is not mandatory, however it does speed things up.
237 *
238 * @note When using this function on a
239 * parallel::distributed::Triangulation you may get an exception when
240 * trying to evaluate the solution at a point that lies on an artificial
241 * cell (see
242 * @ref GlossLocallyOwnedCell).
243 * See the section in the general documentation of this class for more
244 * information.
245 */
246 virtual typename VectorType::value_type
247 value(const Point<dim> &p, const unsigned int component = 0) const override;
248
249 /**
250 * Set @p values to the point values of the specified component of the
251 * function at the @p points. It is assumed that @p values already has the
252 * right size, i.e. the same size as the points array. This is rather
253 * efficient if all the points lie on the same cell. If this is not the
254 * case, things may slow down a bit.
255 *
256 * @note When using this function on a
257 * parallel::distributed::Triangulation you may get an exception when
258 * trying to evaluate the solution at a point that lies on an artificial
259 * cell (see
260 * @ref GlossLocallyOwnedCell).
261 * See the section in the general documentation of this class for more
262 * information.
263 */
264 virtual void
265 value_list(const std::vector<Point<dim>> &points,
266 std::vector<typename VectorType::value_type> &values,
267 const unsigned int component = 0) const override;
268
269
270 /**
271 * Set @p values to the point values of the function at the @p points. It
272 * is assumed that @p values already has the right size, i.e. the same
273 * size as the points array. This is rather efficient if all the points
274 * lie on the same cell. If this is not the case, things may slow down a
275 * bit.
276 *
277 * @note When using this function on a
278 * parallel::distributed::Triangulation you may get an exception when
279 * trying to evaluate the solution at a point that lies on an artificial
280 * cell (see
281 * @ref GlossLocallyOwnedCell).
282 * See the section in the general documentation of this class for more
283 * information.
284 */
285 virtual void
286 vector_value_list(const std::vector<Point<dim>> &points,
287 std::vector<Vector<typename VectorType::value_type>>
288 &values) const override;
289
290 /**
291 * Return the gradient of all components of the function at the given
292 * point. It is inefficient to use single points. If you need more than
293 * one at a time, use the vector_value_list() function. For efficiency
294 * reasons, it is better if all the points lie on the same cell. This is
295 * not mandatory, however it does speed things up.
296 *
297 * @note When using this function on a
298 * parallel::distributed::Triangulation you may get an exception when
299 * trying to evaluate the solution at a point that lies on an artificial
300 * cell (see
301 * @ref GlossLocallyOwnedCell).
302 * See the section in the general documentation of this class for more
303 * information.
304 */
305 virtual void
306 vector_gradient(const Point<dim> &p,
307 std::vector<Tensor<1, dim, typename VectorType::value_type>>
308 &gradients) const override;
309
310 /**
311 * Return the gradient of the specified component of the function at the
312 * given point. It is inefficient to use single points. If you need more
313 * than one at a time, use the vector_value_list() function. For efficiency
314 * reasons, it is better if all the points lie on the same cell. This is
315 * not mandatory, however it does speed things up.
316 *
317 * @note When using this function on a
318 * parallel::distributed::Triangulation you may get an exception when
319 * trying to evaluate the solution at a point that lies on an artificial
320 * cell (see
321 * @ref GlossLocallyOwnedCell).
322 * See the section in the general documentation of this class for more
323 * information.
324 */
325 virtual Tensor<1, dim, typename VectorType::value_type>
326 gradient(const Point<dim> &p,
327 const unsigned int component = 0) const override;
328
329 /**
330 * Return the gradient of all components of the function at all the given
331 * points. This is rather efficient if all the points lie on the same
332 * cell. If this is not the case, things may slow down a bit.
333 *
334 * @note When using this function on a
335 * parallel::distributed::Triangulation you may get an exception when
336 * trying to evaluate the solution at a point that lies on an artificial
337 * cell (see
338 * @ref GlossLocallyOwnedCell).
339 * See the section in the general documentation of this class for more
340 * information.
341 */
342 virtual void
343 vector_gradient_list(
344 const std::vector<Point<dim>> &p,
345 std::vector<std::vector<Tensor<1, dim, typename VectorType::value_type>>>
346 &gradients) const override;
347
348 /**
349 * Return the gradient of the specified component of the function at all
350 * the given points. This is rather efficient if all the points lie on
351 * the same cell. If this is not the case, things may slow down a bit.
352 *
353 * @note When using this function on a
354 * parallel::distributed::Triangulation you may get an exception when
355 * trying to evaluate the solution at a point that lies on an artificial
356 * cell (see
357 * @ref GlossLocallyOwnedCell).
358 * See the section in the general documentation of this class for more
359 * information.
360 */
361 virtual void
362 gradient_list(
363 const std::vector<Point<dim>> &p,
364 std::vector<Tensor<1, dim, typename VectorType::value_type>> &gradients,
365 const unsigned int component = 0) const override;
366
367
368 /**
369 * Compute the Laplacian of a given component at point <tt>p</tt>.
370 *
371 * @note When using this function on a
372 * parallel::distributed::Triangulation you may get an exception when
373 * trying to evaluate the solution at a point that lies on an artificial
374 * cell (see
375 * @ref GlossLocallyOwnedCell).
376 * See the section in the general documentation of this class for more
377 * information.
378 */
379 virtual typename VectorType::value_type
380 laplacian(const Point<dim> &p,
381 const unsigned int component = 0) const override;
382
383 /**
384 * Compute the Laplacian of all components at point <tt>p</tt> and store
385 * them in <tt>values</tt>.
386 *
387 * @note When using this function on a
388 * parallel::distributed::Triangulation you may get an exception when
389 * trying to evaluate the solution at a point that lies on an artificial
390 * cell (see
391 * @ref GlossLocallyOwnedCell).
392 * See the section in the general documentation of this class for more
393 * information.
394 */
395 virtual void
396 vector_laplacian(
397 const Point<dim> &p,
398 Vector<typename VectorType::value_type> &values) const override;
399
400 /**
401 * Compute the Laplacian of one component at a set of points.
402 *
403 * @note When using this function on a
404 * parallel::distributed::Triangulation you may get an exception when
405 * trying to evaluate the solution at a point that lies on an artificial
406 * cell (see
407 * @ref GlossLocallyOwnedCell).
408 * See the section in the general documentation of this class for more
409 * information.
410 */
411 virtual void
412 laplacian_list(const std::vector<Point<dim>> &points,
413 std::vector<typename VectorType::value_type> &values,
414 const unsigned int component = 0) const override;
415
416 /**
417 * Compute the Laplacians of all components at a set of points.
418 *
419 * @note When using this function on a
420 * parallel::distributed::Triangulation you may get an exception when
421 * trying to evaluate the solution at a point that lies on an artificial
422 * cell (see
423 * @ref GlossLocallyOwnedCell).
424 * See the section in the general documentation of this class for more
425 * information.
426 */
427 virtual void
428 vector_laplacian_list(const std::vector<Point<dim>> &points,
429 std::vector<Vector<typename VectorType::value_type>>
430 &values) const override;
431
432 /**
433 * Given a set of points located in the domain (or, in the case of
434 * a parallel Triangulation, in the locally owned part of the domain
435 * or on the ghost cells for the current processor), sort these
436 * points into buckets for each of the cells on which at least
437 * one of the points is located.
438 *
439 * This function fills three output vectors: @p cells, @p qpoints
440 * and @p maps. The first is a list of the cells that contain the
441 * points, the second is a list of quadrature points matching each
442 * cell of the first list, and the third contains the index of the
443 * given quadrature points, i.e., @p points[maps[3][4]] ends up as
444 * the 5th quadrature point in the 4th cell.
445 *
446 * @return This function returns the number of cells that
447 * collectively contain the set of points give as @p
448 * points. This also equals the lengths of the output arrays.
449 *
450 * This function simply calls GridTools::compute_point_locations :
451 * using the original function avoids computing a
452 * new Cache at every function call.
453 */
454 unsigned int
455 compute_point_locations(
456 const std::vector<Point<dim>> &points,
457 std::vector<typename DoFHandler<dim, spacedim>::active_cell_iterator>
458 &cells,
459 std::vector<std::vector<Point<dim>>> &qpoints,
460 std::vector<std::vector<unsigned int>> &maps) const;
461
462 private:
463 /**
464 * Typedef holding the local cell_hint.
465 */
466 using cell_hint_t = Threads::ThreadLocalStorage<
467 typename DoFHandler<dim, spacedim>::active_cell_iterator>;
468
469 /**
470 * Pointer to the dof handler.
471 */
472 ObserverPointer<const DoFHandler<dim, spacedim>,
473 FEFieldFunction<dim, VectorType, spacedim>>
474 dh;
475
476 /**
477 * A reference to the actual data vector.
478 */
479 const VectorType &data_vector;
480
481 /**
482 * A reference to the mapping being used.
483 */
484 const Mapping<dim> &mapping;
485
486 /**
487 * The Cache object
488 */
489 GridTools::Cache<dim, spacedim> cache;
490
491 /**
492 * The latest cell hint.
493 */
494 mutable cell_hint_t cell_hint;
495
496 /**
497 * Given a cell, return the reference coordinates of the given point
498 * within this cell if it indeed lies within the cell. Otherwise return an
499 * uninitialized std::optional object.
500 */
501 std::optional<Point<dim>>
502 get_reference_coordinates(
503 const typename DoFHandler<dim, spacedim>::active_cell_iterator &cell,
504 const Point<dim> &point) const;
505 };
506 } // namespace Functions
507
508
509 DEAL_II_NAMESPACE_CLOSE
510
511 #endif