Debian Codegraph @

include/deal.II/fe/fe_coupling_values.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2023 - 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_fe_coupling_values_h
16 #define dealii_fe_coupling_values_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/algorithms/general_data_storage.h>
21
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/point.h>
24 #include <deal.II/base/std_cxx20/iota_view.h>
25 #include <deal.II/base/thread_local_storage.h>
26 #include <deal.II/base/utilities.h>
27
28 #include <deal.II/fe/fe_values_views.h>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declaration
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 class FEValuesBase;
36 #endif
37
38 namespace FEValuesViews
39 {
40 /**
41 * A class that stores the renumbering of degrees of freedom and quadrature
42 * points for the RenumberedView class. This class is common to all possible
43 * renumbered views, and therefore it can be shared between all views that use
44 * the same set of renumbering vectors.
45 *
46 * The renumbering is stored in two vectors, one for the degrees of freedom
47 * and one for the quadrature points, and it is used by the
48 * FEValuesViews::RenumberedView class.
49 */
50 struct RenumberingData
51 {
52 /**
53 * Construct a new renumbering data object.
54 *
55 * The @p dof_renumbering vector is used to renumber the degrees of freedom,
56 * while the @p quadrature_renumbering vector is used to renumber the
57 * quadrature points. An empty renumbering vector simply means that no
58 * renumbering is performed.
59 *
60 * @note The renumbering vectors are *not* required to match the dimensions
61 * of the underlying view, i.e., you could use this class to only run over
62 * half of the degrees of freedom, and integrating only over half of the
63 * current cell by selecting a subset of quadrature points, if you wish to
64 * do so, or to run over some of the degrees of freedom more than once with
65 * regard to the underlying view. The important part is that every entry of
66 * each renumbering vector is a legal index within the underlying view
67 * object. We allow the dof renumbering vector to contain
68 * `numbers::invalid_unsigned_int` values, which are ignored, and produce
69 * zero values, gradients, hessians, etc. for the corresponding shape
70 * function.
71 *
72 * An example of the renumbering ordering is the following. Assume that you
73 * have an FE_Q(1) finite element in dimension two (i.e., four degrees of
74 * freedom), and that you are manually taking care of an additional degree
75 * of freedom (say, a custom shape function in the middle of the cell),
76 * which, for your own convenience, should be numbered locally in the middle
77 * of the others. You would like your loops on degrees of freedom to run
78 * over all degrees of freedom, and to have the same structure as if the
79 * additional degree of freedom was not there. Then the renumbering data
80 * object should look like this:
81 * @code
82 * ...
83 * RenumberingData data({{0, 1, numbers::invalid_unsigned_int, 2, 3}});
84 * @endcode
85 *
86 * Using this RenumberingData object, the RenumberedView will return zero
87 * when we ask for values, gradients, etc., of the shape function with index
88 * two.
89 */
90 RenumberingData(
91 const unsigned int n_inner_dofs = numbers::invalid_unsigned_int,
92 const unsigned int n_inner_quadrature_points =
93 numbers::invalid_unsigned_int,
94 const std::vector<unsigned int> &dof_renumbering = {},
95 const std::vector<unsigned int> &quadrature_renumbering = {});
96
97 /**
98 * Make sure we never copy this object, for performance reasons.
99 */
100 RenumberingData(const RenumberingData &other) = delete;
101
102 /**
103 * The number of dofs in the underlying view (before any renumbering).
104 */
105 const unsigned int n_inner_dofs;
106
107 /**
108 * The number of dofs in the renumbered view.
109 */
110 const unsigned int n_dofs;
111
112 /**
113 * The number of quadrature points in the underlying view (before any
114 * renumbering).
115 */
116 const unsigned int n_inner_quadrature_points;
117
118 /**
119 * The number of quadrature points in the renumbered view.
120 */
121 const unsigned int n_quadrature_points;
122
123 /**
124 * The renumbering of degrees of freedom.
125 */
126 const std::vector<unsigned int> dof_renumbering;
127
128 /**
129 * The renumbering of quadrature points.
130 */
131 const std::vector<unsigned int> quadrature_renumbering;
132
133 /**
134 * General data storage to store temporary vectors.
135 *
136 * When the renumbering vectors are non empty, the RenumberedView class may
137 * need to construct temporary vectors to store the values of the solution
138 * and/or of its gradients with the sizes given by the underlying view
139 * object. Unfortunately, we don't know beforehand the Number types with
140 * which the vectors will be instantiated, so we cannot use a simple cache
141 * internally, and we use a GeneralDataStorage object to avoid allocating
142 * memory at each call.
143 */
144 mutable Threads::ThreadLocalStorage<GeneralDataStorage> data_storage;
145 };
146
147 /**
148 * A class that provides a renumbered view to a given FEValuesViews object.
149 *
150 * In general, the order of the degrees of freedom and quadrature points
151 * follows the one of the FEValues object, which itself uses the numbering
152 * provided by the FiniteElement and Quadrature objects it uses. However, in
153 * some cases, it is convenient to group together degrees of freedom and
154 * quadrature points in a different order, to select only a subset of the
155 * degrees of freedom, or to combine two different sets of degrees of freedom
156 * together. This class provides a view to a given FEValuesViews object, where
157 * the degrees of freedom and quadrature points are renumbered according to
158 * the given RenumberingData object (see there for a documentation of how the
159 * renumbering is interpreted).
160 *
161 * Users will typically not use this class directly, but rather pass an
162 * extractor from the FEValuesExtractors namespace to the FECouplingValues
163 * class, which returns an object of this type. This is the same mechanism
164 * used in the FEValues classes, where passing an extractor returns an
165 * FEValuesViews object, and the user rarely instantiates an object of this
166 * type.
167 */
168 template <typename ViewType>
169 class RenumberedView
170 {
171 public:
172 /**
173 * An alias for the data type of values of the underlying view.
174 */
175 using value_type = typename ViewType::value_type;
176
177 /**
178 * An alias for the data type of gradients of the underlying view.
179 */
180 using gradient_type = typename ViewType::gradient_type;
181
182 /**
183 * An alias for the data type of the product of a @p Number and the values
184 * of the underlying view type.
185 */
186 template <typename Number>
187 using solution_value_type =
188 typename ViewType::template solution_value_type<Number>;
189
190 /**
191 * An alias for the data type of the product of a @p Number and the gradients
192 * of the underlying view type.
193 */
194 template <typename Number>
195 using solution_gradient_type =
196 typename ViewType::template solution_gradient_type<Number>;
197
198 /**
199 * Construct a new RenumberedView object.
200 *
201 * The renumbering information is taken from the class RenumberingData (see
202 * there for a documentation of how the renumbering is interpreted).
203 *
204 * @note The renumbering information is stored as a reference in this
205 * object, so you have to make sure that the RenumberingData object lives
206 * longer than this object.
207 *
208 * @param view The underlying FEValuesViews object.
209 * @param data A RenumberingData object, containing renumbering information.
210 */
211 RenumberedView(const ViewType &view, const RenumberingData &data);
212
213 /**
214 * Return the value of the underlying view, for the shape function and
215 * quadrature point selected by the arguments.
216 *
217 * @param shape_function Number of the shape function to be evaluated. Note
218 * that this number runs from zero to size of the renumbering vector
219 * provided at construction time, or to `dofs_per_cell`, if the renumbering
220 * vector is empty.
221 *
222 * @param q_point Number of the quadrature point at which the function is to
223 * be evaluated. Note that this number runs from zero to the size of the
224 * renumbering vector provided at construction time, or to
225 * `n_quadrature_points`, if the renumbering vector is empty.
226 *
227 * @dealiiRequiresUpdateFlags{update_values}
228 */
229 value_type
230 value(const unsigned int shape_function, const unsigned int q_point) const;
231
232 /**
233 * Return the gradient of the underlying view, for the shape function and
234 * quadrature point selected by the arguments.
235 *
236 * @param shape_function Number of the shape function to be evaluated. This
237 * number runs from zero to size of the renumbering vector provided at
238 * construction time, or to `dofs_per_cell`, if the renumbering vector is
239 * empty.
240 *
241 * @param q_point Number of the quadrature point at which the function is to
242 * be evaluated. This number runs from zero to the size of the renumbering
243 * vector provided at construction time, or to `n_quadrature_points`, if the
244 * renumbering vector is empty.
245 *
246 * @dealiiRequiresUpdateFlags{update_gradients}
247 */
248 gradient_type
249 gradient(const unsigned int shape_function,
250 const unsigned int q_point) const;
251
252 /**
253 * Return the values of the underlying view characterized by
254 * <tt>fe_function</tt> at the renumbered quadrature points.
255 *
256 * This function is the equivalent of the FEValuesBase::get_function_values
257 * function but it only works on the selected view.
258 *
259 * The data type stored by the output vector must be what you get when you
260 * multiply the values of shape functions (i.e., @p value_type) times the
261 * type used to store the values of the unknowns $U_j$ of your finite
262 * element vector $U$ (represented by the @p fe_function argument).
263 *
264 * @dealiiRequiresUpdateFlags{update_values}
265 */
266 template <typename Number>
267 void
268 get_function_values(const ReadVector<Number> &fe_function,
269 std::vector<solution_value_type<Number>> &values) const;
270
271 /**
272 * Same as above, but using a vector of renumbered local degree-of-freedom
273 * values. In other words, instead of extracting the nodal values of the
274 * degrees of freedom located on the current cell from a global vector
275 * associated with a DoFHandler object (as the function above does), this
276 * function instead takes these local nodal values through its first
277 * argument.
278 *
279 * @param[in] dof_values A vector of local nodal values. This vector must
280 * have a length equal to the size of the dof renumbering vector.
281 *
282 * @param[out] values A vector of values of the given finite element field,
283 * at the renumbered quadrature points on the current object.
284 *
285 * @tparam InputVector The @p InputVector type must allow creation of an
286 * ArrayView object from it; this is satisfied by the `std::vector` class,
287 * among others.
288 *
289 * @dealiiRequiresUpdateFlags{update_values}
290 */
291 template <class InputVector>
292 void
293 get_function_values_from_local_dof_values(
294 const InputVector &dof_values,
295 std::vector<solution_value_type<typename InputVector::value_type>>
296 &values) const;
297
298 /**
299 * Return the gradients of the underlying view characterized by
300 * <tt>fe_function</tt> at the renumbered quadrature points.
301 *
302 * This function is the equivalent of the
303 * FEValuesBase::get_function_gradients function but it only works on the
304 * selected view.
305 *
306 * The data type stored by the output vector must be what you get when you
307 * multiply the gradients of shape functions (i.e., @p value_type) times the
308 * type used to store the gradients of the unknowns $U_j$ of your finite
309 * element vector $U$ (represented by the @p fe_function argument).
310 *
311 * @dealiiRequiresUpdateFlags{update_gradients}
312 */
313 template <typename Number>
314 void
315 get_function_gradients(
316 const ReadVector<Number> &fe_function,
317 std::vector<solution_gradient_type<Number>> &gradients) const;
318
319 /**
320 * Same as above, but using a vector of renumbered local degree-of-freedom
321 * gradients. In other words, instead of extracting the nodal values of the
322 * degrees of freedom located on the current cell from a global vector
323 * associated with a DoFHandler object (as the function above does), this
324 * function instead takes these local nodal values through its first
325 * argument.
326 *
327 * @param[in] dof_values A vector of local nodal values. This vector must
328 * have a length equal to the size of the dof renumbering vector.
329 *
330 * @param[out] gradients A vector of gradients of the given finite element
331 * field, at the renumbered quadrature points on the current object.
332 *
333 * @tparam InputVector The @p InputVector type must allow creation of an
334 * ArrayView object from it; this is satisfied by the `std::vector` class,
335 * among others.
336 *
337 * @dealiiRequiresUpdateFlags{update_gradients}
338 */
339 template <class InputVector>
340 void
341 get_function_gradients_from_local_dof_values(
342 const InputVector &dof_values,
343 std::vector<solution_gradient_type<typename InputVector::value_type>>
344 &gradients) const;
345
346 private:
347 /**
348 * The data structure that stores the renumbering of the degrees of freedom
349 * and of the quadrature points.
350 */
351 const RenumberingData &data;
352
353
354 /**
355 * Helper function that constructs a unique name for a container, based on a
356 * string prefix, on its size, and on the type stored in the container.
357 *
358 * When the renumbering vectors are non empty, this class may need to
359 * construct temporary vectors to store the values of the solution and/or of
360 * its gradients with the sizes given by the underlying view object.
361 * Unfortunately, we don't know before hand the Number types with which the
362 * vectors will be instantiated, so we cannot use a simple cache internally,
363 * and we use a GeneralDataStorage object to avoid allocating memory at each
364 * call.
365 *
366 * This function constructs a unique name for temporary containers that will
367 * be stored upon the first request in the internal GeneralDataStorage
368 * object, to access the
369 */
370 template <typename Number>
371 std::string
372 get_unique_container_name(const std::string &prefix,
373 const unsigned int size,
374 const Number &exemplar_number) const;
375
376 /**
377 * Produce an inner vector compatible with the inner view, after copying the
378 * values with the correct numbering from the outer vector.
379 */
380 template <typename InputVector>
381 const InputVector &
382 outer_to_inner_dofs(const InputVector &outer_vector) const;
383
384 /**
385 * Produce an inner vector compatible with the inner view, and zero out its
386 * entries if necessary.
387 */
388 template <typename ValueType>
389 std::vector<ValueType> &
390 outer_to_inner_values(std::vector<ValueType> &outer_values) const;
391
392 /**
393 * Return the outer argument renumbered according to the quadrature
394 * renumbering. The values in the inner values are copied to the right
395 * position in the outer vector.
396 */
397 template <typename ValueType>
398 void
399 inner_to_outer_values(const std::vector<ValueType> &inner_values,
400 std::vector<ValueType> &outer_values) const;
401
402 /**
403 * Store a reference to the underlying view.
404 */
405 const ViewType &view;
406 };
407 } // namespace FEValuesViews
408
409
410 /**
411 * Quadrature coupling options when assembling quadrature formulas for double
412 * integrals.
413 *
414 * When computing the approximation of double integrals of the form
415 *
416 * \f[
417 * \int_{T_1} \int{T_2} K(x_1, x_2) f(x_1) g(x_2) dT_1 dT_2,
418 * \f]
419 *
420 * where $T_1$ and $T_2$ are two arbitrary sets (cells, faces, edges, or any
421 * combination thereof), and $K$ is a (possibly singular) coupling kernel, one
422 * needs to combine quadrature formulas from two different FEValuesBase objects.
423 *
424 * This enum class provides a way to specify how the quadrature points and
425 * weights should be combined. In general, the two FEValuesBase objects provide
426 * different quadrature rules, and these can be interpreted in different ways,
427 * depending on the kernel function that is being integrated, and on how the two
428 * quadrature rules were constructed.
429 *
430 * This enum is used in the constructor of FECouplingValues to specify how to
431 * interpret and manipulate the quadrature points and weights of the two
432 * FEValuesBase objects.
433 */
434 enum class QuadratureCouplingType
435 {
436 /**
437 * The FEValuesBase objects provide different quadrature rules, and the
438 * resulting quadrature points and weights should be constructed as the tensor
439 * product of the two quadrature rules. This is generally used for non-local
440 * and non-singular kernels, where the quadrature points of the two
441 * FEValuesBase objects are independent of each other.
442 */
443 tensor_product,
444
445 /**
446 * Both FEValuesBase objects provide the same number of (generally different)
447 * quadrature points, that should be used as is to implement the double
448 * integration. This is equivalent to rewriting double integrals as a single
449 * sum over unrolled indices, and it is useful, for example, when performing
450 * integration of singular kernels, which require special quadrature rules
451 * both on the inside and on the outside integral. An exception is thrown if
452 * the two FEValuesBase objects do not provide the same number of quadrature
453 * points, but otherwise the two sets of points and weights can be arbitrary.
454 */
455 unrolled,
456
457 /**
458 * The FEValuesBase objects provide the same quadrature rule over the same
459 * set, with the same orientation. This is similar to the unrolled case, in
460 * the sense that the quadrature formulas are used as is, but both objects are
461 * assumed to return the same quadrature points and weights. This is useful
462 * when integrating over faces of neighboring cells, and when the reordering
463 * of the quadrature points is known to match a priori. An exception is thrown
464 * if the quadrature points and weights of the two FEValuesBase objects do not
465 * match one-to-one.
466 */
467 matching,
468
469 /**
470 * The FEValuesBase objects provide the same quadrature rule over the same
471 * set, but with possibly different orientations. The quadrature points are
472 * reordered internally, so that the resulting quadrature points and weights
473 * are the same as in the matching case. An exception is thrown if the
474 * quadrature points and weights of the two FEValuesBase cannot be reordered
475 * to match one-to-one.
476 */
477 reorder,
478
479 /**
480 * The FEValuesBase objects provide partially overlapping quadrature rules
481 * over two intersecting sets, with possibly different orientations. The
482 * quadrature points are reordered and matched internally, so that the
483 * resulting quadrature points and weights are only the ones that match
484 * between the two objects. If no overlapping points and weights can be found,
485 * an empty set is used to integrate, and the resulting integral is zero. No
486 * exception is thrown in this case.
487 */
488 overlapping,
489 };
490
491 /**
492 * DoF coupling options when assembling double integrals.
493 *
494 * When computing the approximation of double integrals of the form
495 *
496 * \f[
497 * \int_{T_1} \int{T_2} K(x_1, x_2) v_i(x_1) w_j(x_2) dT_1 dT_2,
498 * \f]
499 *
500 * where $T_1$ and $T_2$ are two arbitrary sets (cells, faces, edges, or any
501 * combination thereof), and $K$ is a (possibly singular) coupling kernel, one
502 * may want to combine degrees from two different FEValuesBase objects (i.e.,
503 * basis functions $v_i$ and $w_j$ in the examples above).
504 *
505 * This enum class provides a way to specify how the degrees of freedom should
506 * be combined. There are two cases of interest:
507 *
508 * 1. the two FEValuesBase objects refer to different DoFHandlers
509 * 2. the two FEValuesBase objects refer to the same DoFHandler
510 *
511 * In the first case, one usually treats the two sets of degrees of freedom as
512 * independent of each other, and the resulting matrix is generally rectangular.
513 *
514 * In the second case, one may choose to treat the two sets of degrees of
515 * freedom either as independent or to group them together. A similar approach
516 * is used in the FEInterfaceValues class, where the degrees of freedom of the
517 * two FEValuesBase objects are grouped together, in a contiguous way, so that
518 * the resulting basis functions are interpreted in the following way:
519 *
520 * \f[
521 * \phi_{1,i}(x) = \begin{cases} v_i(x) & \text{ if } i \in [0,n_l) \\
522 * 0 & \text{ if } i \in [n_1, n_1+n_2] \end{cases},\quad \phi_{1,i}(x) =
523 * \begin{cases} 0(x) & \text{ if } i \in [0,n_1) \\
524 * w_{i-n_1}(x) & \text{ if } i \in [n_1, n_1+n_2] \end{cases},
525 * \f]
526 *
527 * where $\phi_{1,i}$ is the first basis function with index $i$ and $n_{1,2}$
528 * are the number of local dofs on the first and second FEValuesBase objects.
529 *
530 * This enum is used in the constructor of FECouplingValues to specify how to
531 * interpret and manipulate the local dof indices of the two FEValuesBase
532 * objects.
533 */
534 enum class DoFCouplingType
535 {
536 /**
537 * The FEValuesBase objects may have different dof indices, possibly indexing
538 * different DoFHandler objects, and we are interested in assembling a
539 * generally rectangular matrix, where there is no relationship between the
540 * two index spaces.
541 */
542 independent,
543
544 /**
545 * The FEValuesBase objects may have different dof indices, but they both
546 * index the same DoFHandler objects, and we are interested in assembling them
547 * all together in a single matrix. In this coupling type, the DoF indices are
548 * grouped together, one after the other, first the first dof indices, and
549 * then the second dof indices. This is useful when one wants to assemble four
550 * matrices at the same time, corresponding to the four possible combinations
551 * of the two FEValuesBase objects, (i.e., first coupled with first, first
552 * coupled with second, second coupled with first, and second coupled with
553 * second) and then sum them together to obtain the final system. This is
554 * similar to what is done in the FEInterfaceValues class.
555 */
556 contiguous,
557 };
558
559 /**
560 * FECouplingValues is a class that facilitates the integration of finite
561 * element data between two different finite element objects, possibly living on
562 * different grids, and with possibly different topological dimensions (i.e.,
563 * cells, faces, edges, and any combination thereof).
564 *
565 * This class provides a way to simplify the implementation of the following
566 * abstract operation:
567 *
568 * \f[
569 * \int_{T_1} \int{T_2} K(x_1, x_2) \phi^1_i(x_1) \phi^2_j(x_2) dT_1 dT_2
570 * \f]
571 *
572 * for three different types of Kernels $K$:
573 * - $K(x_1, x_2)$ is a non-singular Kernel function, for example, it is a
574 * function of positive powers $\alpha$ of the distance between the quadrature
575 * points $|x_1-x_2|^\alpha$;
576 * - $K(x_1, x_2)$ is a singular Kernel function, for example, it is a function
577 * of negative powers $\alpha$ of the distance between the quadrature points
578 * $|x_1-x_2|^\alpha$;
579 * - $K(x_1, x_2)$ is a Dirac delta distribution $\delta(x_1-x_2)$, such that
580 * the integral above is actually a single integral over the intersection of
581 * the two sets $T_1$ and $T_2$.
582 *
583 * For the first case, one may think that the only natural way to proceed is to
584 * compute the double integral by simply nesting two loops:
585 * \f[
586 * \int_{T_1} \int{T_2} K(x_1, x_2) \phi^1_i(x_1) \phi^2_j(x_2) dT_1 dT_2
587 * \approx \sum_{q_1} \sum_{q_2} K(x_1^{q_1}, x_2^{q_2}) \phi^1_i(x_1^{q_1})
588 * \phi^2_j(x_2^{q_2}) w_1^{q_1} w_2^{q_2},
589 * \f]
590 *
591 * where $x_1^{q_1}$ and $x_2^{q_2}$ are the quadrature points in $T_1$ and
592 * $T_2$ respectively, and $w_1^{q_1}$ and $w_2^{q_2}$ are the corresponding
593 * quadrature weights.
594 *
595 * This, however is not the only way to proceed. In fact, such an integral can
596 * be rewritten as a single loop over corresponding elements of two arrays of
597 * points with the same length that can be thought of as a single quadrature
598 * rule on the set $T_1\times T_2$. For singular kernels, for example, this is
599 * often the only way to proceed, since the quadrature formula on $T_1\times
600 * T_2$ is usually not written as a tensor product quadrature formula, and one
601 * needs to build a custom quadrature formula for this purpose.
602 *
603 * This class allows one to treat the three cases above in the same way, and to
604 * approximate the integral as follows:
605 *
606 * \f[
607 * \int_{T_1} \int{T_2} K(x_1, x_2) \phi^1_i(x_1) \phi^2_j(x_2) dT_1 dT_2
608 * \approx \sum_{i=1}^{N_q} K(x_1^{i}, x_2^{i}) \phi^1_i(x_1^{i})
609 * \phi^2_j(x_2^{i}) w_1^{i} w_2^i,
610 * \f]
611 *
612 * Since the triple of objects $(\{q\}, \{w\}, \{\phi\})$ is usually provided by
613 * a class derived from the FEValuesBase class, this is the type that the class
614 * needs at construction time. $T_1$ and $T_2$ can be two arbitrary cells,
615 * faces, or edges belonging to possibly different meshes (or to meshes with
616 * different topological dimensions), $\phi^1_i$ and $\phi^2_j$ are basis
617 * functions defined on $T_1$ and $T_2$, respectively.
618 *
619 * The case of the Dirac distribution is when $T_1$ and $T_2$
620 * correspond to the common face of two neighboring cells. In this case, this
621 * class provides a functionality which is similar to the FEInterfaceValues
622 * class, and gives you a way to access values of basis functions on the
623 * neighboring cells, as well as their gradients and Hessians, in a unified
624 * fashion, on the face.
625 *
626 * Similarly, this class can be used to couple bulk and surface meshes across
627 * the faces of the bulk mesh. In this case, the two FEValuesBase objects will
628 * have different topological dimension (i.e., one will be a cell in a
629 * co-dimension one triangulation, and the other a face of a bulk grid with
630 * co-dimension zero), and the QuadratureCouplingType argument is usually chosen
631 * to be QuadratureCouplingType::reorder, since the quadrature points of the two
632 * different FEValuesBase objects are not necessarily generated with the same
633 * ordering.
634 *
635 * The type of integral to compute is controlled by the QuadratureCouplingType
636 * argument (see the documentation of that enum class for more details), while
637 * the type degrees of freedom coupling is controlled by the DoFCouplingType
638 * argument (see the documentation of that enum class for more details).
639 *
640 * As an example usage of this class, consider the a bilinear form of the form:
641 * \f[
642 * \int_{T_1} \int{T_2} K_1(x_1, x_2) v_i(x_1) u_j(x_2) dT_1 dT_2 +
643 * \int_{T_1} \int{T_2} K_2(x_1, x_2) p_i(x_1) q_j(x_2) dT_1 dT_2
644 * \f]
645 * where the finite dimensional space has two scalar components. We indicate
646 * with $v_i$ and $p_i$ the trial functions, and with $u_j$ and
647 * $q_j$ the corresponding test functions. $K_1$ and $K_2$ are coupling kernels:
648 * such a formulation is used, for example, to write the bilinear forms of
649 * Galerkin boundary element methods.
650 *
651 * The corresponding implementation would look like the following:
652 *
653 * @code
654 * ... // double loop over cells that yields cell_1 and cell_2
655 *
656 * fe_values_1.reinit(cell_1);
657 * fe_values_2.reinit(cell_2);
658 *
659 * CouplingFEValues<dim, dim, spacedim> cfv(fe_values1, fe_values2,
660 * DoFCouplingType::independent,
661 * QuadratureCouplingType::tensor_product);
662 *
663 * FullMatrix<double> local_matrix(fe_values1.dofs_per_cell,
664 * fe_values2.dofs_per_cell);
665 *
666 * // Extractor on first cell
667 * const auto v1 = cfv.get_first_extractor(FEValuesExtractor::Scalar(0));
668 * const auto p1 = cfv.get_first_extractor(FEValuesExtractor::Scalar(1));
669 *
670 * // Extractor on second cell
671 * const auto u2 = cfv.get_second_extractor(FEValuesExtractor::Scalar(0));
672 * const auto q2 = cfv.get_second_extractor(FEValuesExtractor::Scalar(1));
673 *
674 * ...
675 *
676 * for (const unsigned int q : cfv.quadrature_point_indices()) {
677 * const auto &[x_q,y_q] = cfv.quadrature_point(q);
678 *
679 * for (const unsigned int i : cfv.first_dof_indices())
680 * {
681 * const auto &v_i = cfv[v1].value(i, q);
682 * const auto &p_i = cfv[p1].value(i, q);
683 *
684 * for (const unsigned int j : cfv.second_dof_indices())
685 * {
686 * const auto &u_j = cfv[u2].value(j, q);
687 * const auto &q_j = cfv[q2].value(j, q);
688 *
689 * local_matrix(i, j) += (K1(x_q, y_q) * v_i * u_j +
690 * K2(x_q, y_q) * p_i * q_j) *
691 * cfv[0].JxW(q) *
692 * cfv[1].JxW(q);
693 * }
694 * }
695 * }
696 * @endcode
697 *
698 * In the above loop, the quadrature points of the two FEValuesBase objects are
699 * grouped together in a single loop, while the dof indices are kept separate.
700 *
701 * Internally, this class provides an abstraction to organize coupling terms
702 * between two arbitrary FEValuesBase objects, and provides a unified way to
703 * access the values of the two basis, and of the two sets of quadrature points
704 * and weights. The underlying data is stored in the two FEValuesBase objects,
705 * and this class provides access to two RenumberedView objects, which can be
706 * obtained by calling the `operator[]` method of this class with the arguments
707 * constructed by calling the get_first_extractor() and get_second_extractor()
708 * methods of this class with a standard FEValuesExtractors object, i.e.,
709 *
710 * @code
711 * // extract the first scalar component of the basis
712 * FEValuesExtractor scalar(0);
713 * ...
714 *
715 * FECouplingValues<dim> fe_coupling(fev1, fev1);
716 *
717 * // Extractors for the two FEValuesBase objects are returned by the
718 * // get_first_extractor() and
719 * // get_second_extractor() methods
720 *
721 * const auto first = fe_coupling.get_first_extractor(scalar);
722 * const auto second = fe_coupling.get_second_extractor(scalar);
723 *
724 * // Now we can use the augmented extractors to access the values of the two
725 * // FEValuesBase objects
726 * const auto & first_vi = fe_coupling[first].value(i, q);
727 * const auto & second_vi = fe_coupling[second].value(i, q);
728 * @endcode
729 */
730 template <int dim1, int dim2 = dim1, int spacedim = dim1>
731 class FECouplingValues
732 {
733 public:
734 /**
735 * Construct the FECouplingValues in an invalid state. Before you can use this
736 * object, you must call the reinit() function.
737 */
738 FECouplingValues();
739
740 /**
741 * Construct the FECouplingValues with two arbitrary FEValuesBase objects.
742 * This class assumes that the FEValuesBase objects that are given at
743 * construction time are initialized and ready to use (i.e., that you have
744 * called the reinit() function on them before calling this constructor).
745 *
746 * Notice that the actual renumbering of the degrees of freedom and quadrature
747 * points is done at construction time, or upon calling the reinit() function.
748 * If you change the underlying FEValuesBase objects after construction, you
749 * must call the reinit() function to update the renumbering. This may or may
750 * not be necessary, depending on the type of coupling that you are using.
751 *
752 * This really depends on the application and on the specific type of
753 * coupling. For example, for volume/volume coupling, i.e., for operators with
754 * non-local and non-singular kernels of type
755 * \f[
756 * \int_K \int_T f(\phi_i(x)-\phi_j(y), x-y) dx dy
757 * \f]
758 * you may initialize FECouplingValues once, and just reinit the underlying
759 * FEValuesBase objects on different cells K and T, without the need to
760 * recompute the coupling (i.e., the numbering is always the same, and nothing
761 * differs from what happened in the first call).
762 *
763 * For cell/surface coupling, the same cell may couple with different faces,
764 * so the renumbering must be really computed from scratch for each pair of
765 * FEValuesBase objects, so reinitializing the underlying cells and faces will
766 * make the renumbering itself invalid, and FECouplingValues must be
767 * reinitialized (o constructed from scratch) after calling
768 * `fe_values_1.reinit(K)` and `fe_values_1.reinit(T)`.
769 *
770 * @param fe_values_1 The first FEValuesBase object.
771 * @param fe_values_2 The second FEValuesBase object.
772 * @param dof_coupling_type The type of dof coupling to use.
773 * @param quadrature_coupling_type The type of quadrature to use for the coupling.
774 */
775 FECouplingValues(
776 const FEValuesBase<dim1, spacedim> &fe_values_1,
777 const FEValuesBase<dim2, spacedim> &fe_values_2,
778 const DoFCouplingType &dof_coupling_type = DoFCouplingType::independent,
779 const QuadratureCouplingType &quadrature_coupling_type =
780 QuadratureCouplingType::tensor_product);
781
782 /**
783 * Reinitialize the FECouplingValues with two arbitrary FEValuesBase objects.
784 * The FEValuesBase objects must be initialized and ready to use, i.e., you
785 * must have called the reinit() function on them before calling this method.
786 *
787 * This method computes the actual renumbering of the degrees of freedom and
788 * quadrature points. If you change the underlying FEValuesBase objects after
789 * calling this method, you may need to call the reinit() function to update
790 * the renumbering. This may or may not be necessary, depending on the type of
791 * coupling that you are using.
792 *
793 * This really depends on the application and on the specific type of
794 * coupling. For example, for volume/volume coupling, i.e., for operators with
795 * non-local and non-singular kernels of type
796 * \f[
797 * \int_K \int_T f(\phi_i(x)-\phi_j(y), x-y) dx dy
798 * \f]
799 * you may initialize FECouplingValues once, and just reinit the underlying
800 * FEValuesBase objects on different cells K and T, without the need to
801 * recompute the coupling (i.e., the numbering is always the same, and nothing
802 * differs from what happened in the first call).
803 *
804 * For cell/surface coupling, the same cell may couple with different faces,
805 * so the renumbering must be really computed from scratch for each pair of
806 * FEValuesBase objects, so reinitializing the underlying cells and faces will
807 * make the renumbering itself invalid, and FECouplingValues must be
808 * reinitialized (o constructed from scratch) after calling
809 * `fe_values_1.reinit(K)` and `fe_values_1.reinit(T)`.
810 *
811 * @param fe_values_1 The first FEValuesBase object.
812 * @param fe_values_2 The second FEValuesBase object.
813 * @param dof_coupling_type The type of dof coupling to use.
814 * @param quadrature_coupling_type The type of quadrature to use for the coupling.
815 */
816 void
817 reinit(
818 const FEValuesBase<dim1, spacedim> &fe_values_1,
819 const FEValuesBase<dim2, spacedim> &fe_values_2,
820 const DoFCouplingType &dof_coupling_type = DoFCouplingType::independent,
821 const QuadratureCouplingType &quadrature_coupling_type =
822 QuadratureCouplingType::tensor_product);
823
824
825 /**
826 * Return a FirstCoupling object that can be used to extract values from the
827 * first FEValuesBase object.
828 */
829 template <typename Extractor>
830 FEValuesExtractors::FirstCoupling<Extractor>
831 get_first_extractor(const Extractor &extractor) const;
832
833 /**
834 * Return a SecondCoupling object that can be used to extract values from the
835 * second FEValuesBase object.
836 */
837 template <typename Extractor>
838 FEValuesExtractors::SecondCoupling<Extractor>
839 get_second_extractor(const Extractor &extractor) const;
840
841 /**
842 * Return the value of JxW at the given quadrature point.
843 *
844 * @dealiiRequiresUpdateFlags{update_JxW_values}
845 */
846 double
847 JxW(const unsigned int quadrature_point) const;
848
849 /**
850 * Return the two quadrature points in real space at the given quadrature
851 * point index, corresponding to a quadrature point in the set $T_1\times
852 * T_2$.
853 *
854 * @dealiiRequiresUpdateFlags{update_quadrature_points}
855 */
856 std::pair<Point<spacedim>, Point<spacedim>>
857 quadrature_point(const unsigned int quadrature_point) const;
858
859 /**
860 * Return an object that can be thought of as an array containing all
861 * indices from zero to `n_quadrature_points`. This allows to write code
862 * using range-based `for` loops.
863 *
864 * @see CPP11
865 */
866 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
867 quadrature_point_indices() const;
868
869 /**
870 * Return an object that can be thought of as an array containing all
871 * indices from zero (inclusive) to `n_first_dofs()` (exclusive).
872 * This allows one to write code using range-based `for` loops.
873 */
874 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
875 first_dof_indices() const;
876
877 /**
878 * Return an object that can be thought of as an array containing all
879 * indices from zero (inclusive) to `n_second_dofs()` (exclusive).
880 * This allows one to write code using range-based `for` loops.
881 */
882 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
883 second_dof_indices() const;
884
885 /**
886 * Return an object that can be thought of as an array containing all indices
887 * from zero (inclusive) to `n_coupling_dof_indices()` (exclusive). This
888 * allows one to write code using range-based `for` loops.
889 *
890 * This function only makes sense when the dof coupling type is
891 * DoFCouplingType::contiguous, and, in this case, n_coupling_dof_indices() is
892 * the sum of n_first_dofs() and n_second_dofs(). If
893 * DoFCouplingType::independent is used, you should call first_dof_indices()
894 * or second_dof_indices() instead, and calling this function will throw an
895 * exception.
896 */
897 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
898 coupling_dof_indices() const;
899
900 /**
901 * Return the set of joint DoF indices, possibly offset by the given values.
902 *
903 * For coupled problems, the DoF indices of the two FEValuesBase objects are
904 * generally constructed from different DoFHandler objects. According to how
905 * the user wants to construct the coupling matrices, the two dof indices may
906 * map local dof indices to global dof indices starting from zero (i.e., we
907 * are assembling a single rectangular matrix, and the first dof indices run
908 * on rows of the matrix, while the second dof indices run on columns of the
909 * matrix), or the user may be wanting to map the coupling matrix to a block
910 * of a larger block matrix. In this second case the dof indices of either or
911 * both blocks may need to be shifted by a fixed amount, to fall within the
912 * right range of the target block matrix. This is usually required if the
913 * user wants to keep their solution vectors in a single block vector, where
914 * each block corresponds to a different DoFHandler object. In this case, all
915 * dofs referring to the first FEValuesBase object are offset by the value of
916 * dofs_offset_1, while all dofs referring to the second FEValuesBase object
917 * are offset by the value of dofs_offset_2, i.e., the following relationship
918 * is satisfied:
919 * @code
920 * fe_values_1.get_dof_indices(dof_indices_1);
921 * fe_values_2.get_dof_indices(dof_indices_2);
922 * auto coupling_dof_indices = fe_coupling_values.
923 * get_coupling_dof_indices(dof_indices_1, dof_indices_2,
924 * dofs_offset_1, dofs_offset_2);
925 * for(const auto &i : fe_coupling_values.coupling_dof_indices()) {
926 * auto [id1, id2] = fe_coupling_values.coupling_dof_to_dof_indices(i);
927 * if (id1 != numbers::invalid_unsigned_int)
928 * // always true
929 * coupling_dof_indices[i] == dof_indices_1[id1] + dofs_offset_1;
930 * if (id2 != numbers::invalid_unsigned_int)
931 * // always true
932 * coupling_dof_indices[i] == dof_indices_2[id2] + dofs_offset_2;
933 * }
934 * @endcode
935 *
936 * This method only makes sense when the dof coupling type is
937 * DoFCouplingType::contiguous. If DoFCouplingType::independent is used,
938 * calling this function will result in an exception.
939 */
940 std::vector<types::global_dof_index>
941 get_coupling_dof_indices(
942 const std::vector<types::global_dof_index> &dof_indices_1,
943 const std::vector<types::global_dof_index> &dof_indices_2,
944 const types::global_dof_index dofs_offset_1 = 0,
945 const types::global_dof_index dofs_offset_2 = 0) const;
946
947 /**
948 * Convert a coupling dof index into the corresponding local DoF indices of
949 * the two FEValuesObjects. If a DoF is only active on one of the
950 * FEValuesObjects, the other index will be numbers::invalid_unsigned_int.
951 */
952 std::pair<unsigned int, unsigned int>
953 coupling_dof_to_dof_indices(const unsigned int coupling_dof_index) const;
954
955 /**
956 * Convert a quadrature index into the corresponding local quadrature indices
957 * of the two FEValuesObjects. Both indices are guaranteed to be valid within
958 * the corresponding FEValuesObject.
959 */
960 std::pair<unsigned int, unsigned int>
961 coupling_quadrature_to_quadrature_indices(
962 const unsigned int quadrature_point) const;
963
964 /**
965 * @name Extractors Methods to extract individual components
966 * @{
967 */
968
969 /**
970 * Create a combined view of the first FECouplingValues object that represents
971 * a view of the possibly vector-valued finite element. The concept of views
972 * is explained in the documentation of the namespace FEValuesViews.
973 */
974 template <typename Extractor>
975 const FEValuesViews::RenumberedView<
976 FEValuesViews::View<dim1, spacedim, Extractor>>
977 operator[](
978 const FEValuesExtractors::FirstCoupling<Extractor> &extractor) const;
979
980 /**
981 * Create a combined view of the second FECouplingValues object that
982 * represents a view of the possibly vector-valued finite element. The concept
983 * of views is explained in the documentation of the namespace FEValuesViews.
984 */
985 template <typename Extractor>
986 const FEValuesViews::RenumberedView<
987 FEValuesViews::View<dim2, spacedim, Extractor>>
988 operator[](
989 const FEValuesExtractors::SecondCoupling<Extractor> &extractor) const;
990
991 /**
992 * @}
993 */
994
995 /**
996 * Return the number of coupling DoF indices. If DoFCouplingType::independent
997 * is used, this function returns numbers::invalid_unsigned_int, otherwise it
998 * returns the sum of n_first_dofs() and n_second_dofs().
999 */
1000 unsigned int
1001 n_coupling_dofs() const;
1002
1003 /**
1004 * Return the number of first DoF indices. This generally coincides with
1005 * n_dofs_per_cell of the first FEValuesBase object.
1006 */
1007 unsigned int
1008 n_first_dofs() const;
1009
1010 /**
1011 * Return the number of second DoF indices. This generally coincides with
1012 * n_dofs_per_cell of the second FEValuesBase object.
1013 */
1014 unsigned int
1015 n_second_dofs() const;
1016
1017 /**
1018 * Return the number of quadrature points.
1019 */
1020 unsigned int
1021 n_quadrature_points() const;
1022
1023 private:
1024 /**
1025 * The dof coupling type used by this object.
1026 */
1027 DoFCouplingType dof_coupling_type;
1028
1029 /**
1030 * The quadrature coupling type used by this object.
1031 */
1032 QuadratureCouplingType quadrature_coupling_type;
1033
1034 /**
1035 * Pointer to first FEValuesBase object.
1036 */
1037 ObserverPointer<const FEValuesBase<dim1, spacedim>> first_fe_values;
1038
1039 /**
1040 * Pointer to second FEValuesBase object.
1041 */
1042 ObserverPointer<const FEValuesBase<dim2, spacedim>> second_fe_values;
1043
1044 /**
1045 * Renumbering data for the first FEValuesBase object.
1046 */
1047 std::unique_ptr<const FEValuesViews::RenumberingData> first_renumbering_data;
1048
1049 /**
1050 * Renumbering data for the second FEValuesBase object.
1051 */
1052 std::unique_ptr<const FEValuesViews::RenumberingData> second_renumbering_data;
1053
1054 /**
1055 * Number of quadrature points.
1056 */
1057 unsigned int n_quadrature_points_;
1058
1059 /**
1060 * Number of coupling DoF indices. If DoFCouplingType::independent is used,
1061 * this is numbers::invalid_unsigned_int, while it is n_first_dofs() +
1062 * n_second_dofs() in the the case of DoFCouplingType::contiguous.
1063 */
1064 unsigned int n_coupling_dofs_;
1065 };
1066
1067
1068 #ifndef DOXYGEN
1069
1070
1071 /*------------------------ Inline functions: namespace FEValuesViews --------*/
1072
1073 namespace FEValuesViews
1074 {
1075 RenumberingData::RenumberingData(
1076 const unsigned int n_inner_dofs,
1077 const unsigned int n_inner_quadrature_points,
1078 const std::vector<unsigned int> &dof_renumbering,
1079 const std::vector<unsigned int> &quadrature_renumbering)
1080 : n_inner_dofs(n_inner_dofs)
1081 , n_dofs(dof_renumbering.empty() ? n_inner_dofs : dof_renumbering.size())
1082 , n_inner_quadrature_points(n_inner_quadrature_points)
1083 , n_quadrature_points(quadrature_renumbering.empty() ?
1084 n_inner_quadrature_points :
1085 quadrature_renumbering.size())
1086 , dof_renumbering(dof_renumbering)
1087 , quadrature_renumbering(quadrature_renumbering)
1088 {
1089 // Check that the renumbering vectors are valid.
1090 if constexpr (running_in_debug_mode())
1091 {
1092 // While for dofs we admit invalid values, this is not the case for
1093 // quadrature points.
1094 for (const auto i : dof_renumbering)
1095 Assert(i < n_inner_dofs || i == numbers::invalid_unsigned_int,
1096 ExcIndexRange(i, 0, n_inner_dofs));
1097
1098 for (const auto q : quadrature_renumbering)
1099 AssertIndexRange(q, n_inner_quadrature_points);
1100 }
1101 }
1102
1103
1104
1105 template <typename ViewType>
1106 RenumberedView<ViewType>::RenumberedView(const ViewType &view,
1107 const RenumberingData &data)
1108 : view(view)
1109 , data(data)
1110 {}
1111
1112
1113
1114 template <typename ViewType>
1115 template <typename Number>
1116 inline std::string
1117 RenumberedView<ViewType>::get_unique_container_name(
1118 const std::string &prefix,
1119 const unsigned int size,
1120 const Number &exemplar_number) const
1121 {
1122 return prefix + "_" + Utilities::int_to_string(size) + "_" +
1123 Utilities::type_to_string(exemplar_number);
1124 }
1125
1126
1127
1128 template <typename ViewType>
1129 typename RenumberedView<ViewType>::value_type
1130 RenumberedView<ViewType>::value(const unsigned int shape_function,
1131 const unsigned int q_point) const
1132 {
1133 AssertIndexRange(shape_function, data.n_dofs);
1134 AssertIndexRange(q_point, data.n_quadrature_points);
1135
1136 const auto inner_shape_function = data.dof_renumbering.empty() ?
1137 shape_function :
1138 data.dof_renumbering[shape_function];
1139 const auto inner_q_point = data.quadrature_renumbering.empty() ?
1140 q_point :
1141 data.quadrature_renumbering[q_point];
1142 if (inner_shape_function == numbers::invalid_unsigned_int)
1143 return value_type(0);
1144 else
1145 {
1146 AssertIndexRange(inner_shape_function, data.n_inner_dofs);
1147 AssertIndexRange(inner_q_point, data.n_inner_quadrature_points);
1148 return view.value(inner_shape_function, inner_q_point);
1149 }
1150 }
1151
1152
1153
1154 template <typename ViewType>
1155 typename RenumberedView<ViewType>::gradient_type
1156 RenumberedView<ViewType>::gradient(const unsigned int shape_function,
1157 const unsigned int q_point) const
1158 {
1159 AssertIndexRange(shape_function, data.n_dofs);
1160 AssertIndexRange(q_point, data.n_quadrature_points);
1161
1162 const auto inner_shape_function = data.dof_renumbering.empty() ?
1163 shape_function :
1164 data.dof_renumbering[shape_function];
1165 const auto inner_q_point = data.quadrature_renumbering.empty() ?
1166 q_point :
1167 data.quadrature_renumbering[q_point];
1168 if (inner_shape_function == numbers::invalid_unsigned_int)
1169 return gradient_type();
1170 else
1171 return view.gradient(inner_shape_function, inner_q_point);
1172 }
1173
1174
1175
1176 template <typename ViewType>
1177 template <typename ValueType>
1178 std::vector<ValueType> &
1179 RenumberedView<ViewType>::outer_to_inner_values(
1180 std::vector<ValueType> &outer_values) const
1181 {
1182 AssertDimension(outer_values.size(), data.n_quadrature_points);
1183 if (data.quadrature_renumbering.empty())
1184 {
1185 return outer_values;
1186 }
1187 else
1188 {
1189 const auto name =
1190 get_unique_container_name("RenumberedView::outer_to_inner_values",
1191 data.n_inner_quadrature_points,
1192 outer_values[0]);
1193 auto &inner_values =
1194 data.data_storage.get()
1195 .template get_or_add_object_with_name<std::vector<ValueType>>(
1196 name, data.n_inner_quadrature_points);
1197 return inner_values;
1198 }
1199 }
1200
1201
1202
1203 template <typename ViewType>
1204 template <typename VectorType>
1205 const VectorType &
1206 RenumberedView<ViewType>::outer_to_inner_dofs(
1207 const VectorType &outer_dofs) const
1208 {
1209 AssertDimension(outer_dofs.size(), data.n_dofs);
1210 if (data.dof_renumbering.empty())
1211 {
1212 return outer_dofs;
1213 }
1214 else
1215 {
1216 const auto name =
1217 get_unique_container_name("RenumberedView::outer_to_inner_dofs",
1218 data.n_inner_dofs,
1219 outer_dofs[0]);
1220
1221 auto &inner_dofs = data.data_storage.get()
1222 .template get_or_add_object_with_name<VectorType>(
1223 name, data.n_inner_dofs);
1224 for (unsigned int i = 0; i < data.n_dofs; ++i)
1225 {
1226 const auto inner_i = data.dof_renumbering[i];
1227 if (inner_i != numbers::invalid_unsigned_int)
1228 {
1229 AssertIndexRange(inner_i, data.n_inner_dofs);
1230 inner_dofs[inner_i] = outer_dofs[i];
1231 }
1232 }
1233 return inner_dofs;
1234 }
1235 }
1236
1237
1238
1239 template <typename ViewType>
1240 template <typename ValueType>
1241 void
1242 RenumberedView<ViewType>::inner_to_outer_values(
1243 const std::vector<ValueType> &inner_values,
1244 std::vector<ValueType> &outer_values) const
1245 {
1246 AssertDimension(outer_values.size(), data.n_quadrature_points);
1247 AssertDimension(inner_values.size(), data.n_inner_quadrature_points);
1248 if (data.quadrature_renumbering.empty())
1249 {
1250 Assert(&inner_values == &outer_values, ExcInternalError());
1251 return;
1252 }
1253 for (unsigned int i = 0; i < data.quadrature_renumbering.size(); ++i)
1254 {
1255 outer_values[i] = inner_values[data.quadrature_renumbering[i]];
1256 }
1257 }
1258
1259
1260
1261 template <typename ViewType>
1262 template <typename Number>
1263 void
1264 RenumberedView<ViewType>::get_function_values(
1265 const ReadVector<Number> &fe_function,
1266 std::vector<solution_value_type<Number>> &values) const
1267 {
1268 auto &inner_values = outer_to_inner_values(values);
1269 view.get_function_values(fe_function, inner_values);
1270 inner_to_outer_values(inner_values, values);
1271 }
1272
1273
1274
1275 template <typename ViewType>
1276 template <typename InputVector>
1277 void
1278 RenumberedView<ViewType>::get_function_values_from_local_dof_values(
1279 const InputVector &dof_values,
1280 std::vector<solution_value_type<typename InputVector::value_type>> &values)
1281 const
1282 {
1283 const auto &inner_dof_values = outer_to_inner_dofs(dof_values);
1284 auto &inner_values = outer_to_inner_values(values);
1285
1286 view.get_function_values_from_local_dof_values(inner_dof_values,
1287 inner_values);
1288 inner_to_outer_values(inner_values, values);
1289 }
1290
1291
1292 template <typename ViewType>
1293 template <typename Number>
1294 void
1295 RenumberedView<ViewType>::get_function_gradients(
1296 const ReadVector<Number> &fe_function,
1297 std::vector<solution_gradient_type<Number>> &gradients) const
1298 {
1299 auto &inner_gradients = outer_to_inner_values(gradients);
1300 view.get_function_gradients(fe_function, inner_gradients);
1301 inner_to_outer_values(inner_gradients, gradients);
1302 }
1303
1304
1305
1306 template <typename ViewType>
1307 template <typename InputVector>
1308 void
1309 RenumberedView<ViewType>::get_function_gradients_from_local_dof_values(
1310 const InputVector &dof_values,
1311 std::vector<solution_gradient_type<typename InputVector::value_type>>
1312 &gradients) const
1313 {
1314 const auto &inner_dof_values = outer_to_inner_dofs(dof_values);
1315 auto &inner_gradients = outer_to_inner_values(gradients);
1316
1317 view.get_function_gradients_from_local_dof_values(inner_dof_values,
1318 inner_gradients);
1319 inner_to_outer_values(inner_gradients, gradients);
1320 }
1321 } // namespace FEValuesViews
1322
1323 /*-------------- Inline functions FECouplingValues ---------------------*/
1324
1325 template <int dim1, int dim2, int spacedim>
1326 std::vector<types::global_dof_index>
1327 FECouplingValues<dim1, dim2, spacedim>::get_coupling_dof_indices(
1328 const std::vector<types::global_dof_index> &dof_indices_1,
1329 const std::vector<types::global_dof_index> &dof_indices_2,
1330 const types::global_dof_index dofs_offset_1,
1331 const types::global_dof_index dofs_offset_2) const
1332 {
1333 AssertThrow(
1334 n_coupling_dofs_ != numbers::invalid_unsigned_int,
1335 ExcMessage(
1336 "Dofs are independent. You cannot ask for coupling dof indices."));
1337 AssertDimension(dof_indices_1.size(), first_fe_values->dofs_per_cell);
1338 AssertDimension(dof_indices_2.size(), second_fe_values->dofs_per_cell);
1339
1340 std::vector<types::global_dof_index> coupling_dof_indices(
1341 dof_indices_1.size() + dof_indices_2.size());
1342 unsigned int idx = 0;
1343 for (const auto &i : dof_indices_1)
1344 coupling_dof_indices[idx++] = i + dofs_offset_1;
1345 for (const auto &i : dof_indices_2)
1346 coupling_dof_indices[idx++] = i + dofs_offset_2;
1347 return coupling_dof_indices;
1348 }
1349
1350
1351
1352 template <int dim1, int dim2, int spacedim>
1353 FECouplingValues<dim1, dim2, spacedim>::FECouplingValues()
1354 : first_fe_values(nullptr)
1355 , second_fe_values(nullptr)
1356 , quadrature_coupling_type(QuadratureCouplingType::unrolled)
1357 , n_quadrature_points_(0)
1358 , n_coupling_dofs_(numbers::invalid_unsigned_int)
1359 {}
1360
1361
1362
1363 template <int dim1, int dim2, int spacedim>
1364 FECouplingValues<dim1, dim2, spacedim>::FECouplingValues(
1365 const FEValuesBase<dim1, spacedim> &fe_values_1,
1366 const FEValuesBase<dim2, spacedim> &fe_values_2,
1367 const DoFCouplingType &dof_coupling_type,
1368 const QuadratureCouplingType &quadrature_coupling_type)
1369 : FECouplingValues() // delegate to other constructor
1370 {
1371 reinit(fe_values_1, fe_values_2, dof_coupling_type, quadrature_coupling_type);
1372 }
1373
1374
1375
1376 template <int dim1, int dim2, int spacedim>
1377 void
1378 FECouplingValues<dim1, dim2, spacedim>::reinit(
1379 const FEValuesBase<dim1, spacedim> &fe_values_1,
1380 const FEValuesBase<dim2, spacedim> &fe_values_2,
1381 const DoFCouplingType &dof_coupling_type,
1382 const QuadratureCouplingType &quadrature_coupling_type)
1383 {
1384 first_fe_values = &fe_values_1;
1385 second_fe_values = &fe_values_2;
1386 this->dof_coupling_type = dof_coupling_type;
1387 this->quadrature_coupling_type = quadrature_coupling_type;
1388
1389 // Gather information about the inner objects
1390 unsigned int first_n_inner_dofs = fe_values_1.dofs_per_cell;
1391 unsigned int second_n_inner_dofs = fe_values_2.dofs_per_cell;
1392
1393 unsigned int first_n_inner_quadrature_points =
1394 fe_values_1.n_quadrature_points;
1395 unsigned int second_n_inner_quadrature_points =
1396 fe_values_2.n_quadrature_points;
1397
1398 // Initialize counters and renumbering vectors to zero
1399 std::vector<unsigned int> first_dofs_map;
1400 std::vector<unsigned int> second_dofs_map;
1401
1402 std::vector<unsigned int> first_quad_map;
1403 std::vector<unsigned int> second_quad_map;
1404
1405 // Local relative tolerance for comparing quadrature points
1406 const double tol = std::min(fe_values_1.get_cell()->diameter(),
1407 fe_values_2.get_cell()->diameter()) *
1408 1e-6;
1409
1410 // Now fill the renumbering vectors
1411 switch (dof_coupling_type)
1412 {
1413 case DoFCouplingType::independent:
1414 {
1415 n_coupling_dofs_ = numbers::invalid_unsigned_int;
1416 first_dofs_map.clear();
1417 second_dofs_map.clear();
1418 break;
1419 }
1420 case DoFCouplingType::contiguous:
1421 {
1422 n_coupling_dofs_ =
1423 fe_values_1.dofs_per_cell + fe_values_2.dofs_per_cell;
1424
1425 first_dofs_map.resize(n_coupling_dofs_);
1426 second_dofs_map.resize(n_coupling_dofs_);
1427
1428 unsigned int idx = 0;
1429 for (const unsigned int &i : fe_values_1.dof_indices())
1430 {
1431 first_dofs_map[idx] = i;
1432 second_dofs_map[idx++] = numbers::invalid_unsigned_int;
1433 }
1434 for (const unsigned int &i : fe_values_2.dof_indices())
1435 {
1436 first_dofs_map[idx] = numbers::invalid_unsigned_int;
1437 second_dofs_map[idx++] = i;
1438 }
1439 // Make sure we have the right number of dofs
1440 AssertDimension(idx, n_coupling_dofs_);
1441 break;
1442 }
1443 default:
1444 AssertThrow(false, ExcNotImplemented());
1445 }
1446 // Compute the quadrature maps
1447 switch (quadrature_coupling_type)
1448 {
1449 case QuadratureCouplingType::tensor_product:
1450 {
1451 const auto &quadrature_points_1 = fe_values_1.get_quadrature_points();
1452 const auto &quadrature_points_2 = fe_values_2.get_quadrature_points();
1453
1454 n_quadrature_points_ =
1455 quadrature_points_1.size() * quadrature_points_2.size();
1456
1457 first_quad_map.resize(n_quadrature_points_);
1458 second_quad_map.resize(n_quadrature_points_);
1459
1460 unsigned int idx = 0;
1461 for (const unsigned int &i : fe_values_1.quadrature_point_indices())
1462 for (const unsigned int &j : fe_values_2.quadrature_point_indices())
1463 {
1464 first_quad_map[idx] = i;
1465 second_quad_map[idx] = j;
1466 ++idx;
1467 }
1468 break;
1469 }
1470 case QuadratureCouplingType::unrolled:
1471 {
1472 Assert(fe_values_1.get_quadrature_points().size() ==
1473 fe_values_2.get_quadrature_points().size(),
1474 ExcMessage("The two FEValuesBase objects must have the same "
1475 "number of quadrature points"));
1476
1477 n_quadrature_points_ = fe_values_1.get_quadrature_points().size();
1478
1479 first_quad_map.clear();
1480 second_quad_map.clear();
1481
1482 break;
1483 }
1484 case QuadratureCouplingType::matching:
1485 {
1486 const auto &quadrature_points_1 = fe_values_1.get_quadrature_points();
1487 const auto &quadrature_points_2 = fe_values_2.get_quadrature_points();
1488
1489 Assert(quadrature_points_1.size() == quadrature_points_2.size(),
1490 ExcMessage("The two FEValuesBase objects must have the same "
1491 "number of quadrature points"));
1492
1493 for (const unsigned int &i : fe_values_1.quadrature_point_indices())
1494 {
1495 Assert(quadrature_points_1[i].distance(quadrature_points_2[i]) <
1496 tol,
1497 ExcMessage(
1498 "The two FEValuesBase objects must have the same "
1499 "quadrature points"));
1500 }
1501
1502 n_quadrature_points_ = fe_values_1.get_quadrature_points().size();
1503
1504 first_quad_map.clear();
1505 second_quad_map.clear();
1506
1507 break;
1508 }
1509 case QuadratureCouplingType::reorder:
1510 {
1511 const auto &quadrature_points_1 = fe_values_1.get_quadrature_points();
1512 const auto &quadrature_points_2 = fe_values_2.get_quadrature_points();
1513
1514 Assert(quadrature_points_1.size() == quadrature_points_2.size(),
1515 ExcMessage("The two FEValuesBase objects must have the same "
1516 "number of quadrature points"));
1517
1518 n_quadrature_points_ = fe_values_1.get_quadrature_points().size();
1519
1520 // The first is the id. The second is renumbered.
1521 first_quad_map.clear();
1522 second_quad_map.resize(fe_values_1.get_quadrature_points().size());
1523
1524 // [TODO]: Avoid quadratic complexity here
1525 for (const unsigned int &i : fe_values_1.quadrature_point_indices())
1526 {
1527 auto id = numbers::invalid_unsigned_int;
1528 for (const unsigned int &j :
1529 fe_values_2.quadrature_point_indices())
1530 if (quadrature_points_1[i].distance(quadrature_points_2[j]) <
1531 tol)
1532 {
1533 id = i;
1534 second_quad_map[i] = j;
1535 break;
1536 }
1537 Assert(id != numbers::invalid_unsigned_int,
1538 ExcMessage(
1539 "The two FEValuesBase objects must have the same "
1540 "quadrature points, even if not in the same order."));
1541 }
1542 break;
1543 }
1544 case QuadratureCouplingType::overlapping:
1545 {
1546 const auto &quadrature_points_1 = fe_values_1.get_quadrature_points();
1547 const auto &quadrature_points_2 = fe_values_2.get_quadrature_points();
1548
1549 // [TODO]: Avoid quadratic complexity here
1550 for (const unsigned int &i : fe_values_1.quadrature_point_indices())
1551 {
1552 for (const unsigned int &j :
1553 fe_values_2.quadrature_point_indices())
1554 if (quadrature_points_1[i].distance(quadrature_points_2[j]) <
1555 tol)
1556 {
1557 first_quad_map.emplace_back(i);
1558 second_quad_map.emplace_back(j);
1559 break;
1560 }
1561 }
1562 n_quadrature_points_ = first_quad_map.size();
1563
1564 break;
1565 }
1566 default:
1567 Assert(false, ExcInternalError());
1568 }
1569
1570 first_renumbering_data = std::make_unique<FEValuesViews::RenumberingData>(
1571 first_n_inner_dofs,
1572 first_n_inner_quadrature_points,
1573 first_dofs_map,
1574 first_quad_map);
1575
1576 second_renumbering_data = std::make_unique<FEValuesViews::RenumberingData>(
1577 second_n_inner_dofs,
1578 second_n_inner_quadrature_points,
1579 second_dofs_map,
1580 second_quad_map);
1581 }
1582
1583
1584 template <int dim1, int dim2, int spacedim>
1585 inline double
1586 FECouplingValues<dim1, dim2, spacedim>::JxW(const unsigned int q) const
1587 {
1588 AssertIndexRange(q, n_quadrature_points_);
1589
1590 const auto first_q = first_renumbering_data->quadrature_renumbering.empty() ?
1591 q :
1592 first_renumbering_data->quadrature_renumbering[q];
1593
1594 if (quadrature_coupling_type == QuadratureCouplingType::tensor_product ||
1595 quadrature_coupling_type == QuadratureCouplingType::unrolled)
1596 {
1597 const auto second_q =
1598 second_renumbering_data->quadrature_renumbering.empty() ?
1599 q :
1600 second_renumbering_data->quadrature_renumbering[q];
1601 return first_fe_values->JxW(first_q) * second_fe_values->JxW(second_q);
1602 }
1603 else
1604 return first_fe_values->JxW(first_q);
1605 }
1606
1607
1608
1609 template <int dim1, int dim2, int spacedim>
1610 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1611 FECouplingValues<dim1, dim2, spacedim>::quadrature_point_indices() const
1612 {
1613 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
1614 0U, n_quadrature_points_);
1615 }
1616
1617
1618
1619 template <int dim1, int dim2, int spacedim>
1620 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1621 FECouplingValues<dim1, dim2, spacedim>::coupling_dof_indices() const
1622 {
1623 AssertThrow(n_coupling_dofs_ != numbers::invalid_unsigned_int,
1624 ExcMessage(
1625 "Dofs are independent. You cannot ask for coupling dofs."));
1626 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
1627 0U, n_coupling_dofs_);
1628 }
1629
1630
1631
1632 template <int dim1, int dim2, int spacedim>
1633 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1634 FECouplingValues<dim1, dim2, spacedim>::first_dof_indices() const
1635 {
1636 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
1637 0U, n_first_dofs());
1638 }
1639
1640
1641
1642 template <int dim1, int dim2, int spacedim>
1643 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1644 FECouplingValues<dim1, dim2, spacedim>::second_dof_indices() const
1645 {
1646 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
1647 0U, n_second_dofs());
1648 }
1649
1650
1651
1652 template <int dim1, int dim2, int spacedim>
1653 inline unsigned int
1654 FECouplingValues<dim1, dim2, spacedim>::n_coupling_dofs() const
1655 {
1656 AssertThrow(n_coupling_dofs_ != numbers::invalid_unsigned_int,
1657 ExcMessage(
1658 "Dofs are independent. You cannot ask for coupling dofs."));
1659 return n_coupling_dofs_;
1660 }
1661
1662
1663
1664 template <int dim1, int dim2, int spacedim>
1665 inline unsigned int
1666 FECouplingValues<dim1, dim2, spacedim>::n_first_dofs() const
1667 {
1668 return first_renumbering_data->n_dofs;
1669 }
1670
1671
1672
1673 template <int dim1, int dim2, int spacedim>
1674 inline unsigned int
1675 FECouplingValues<dim1, dim2, spacedim>::n_second_dofs() const
1676 {
1677 return second_renumbering_data->n_dofs;
1678 }
1679
1680
1681
1682 template <int dim1, int dim2, int spacedim>
1683 inline unsigned int
1684 FECouplingValues<dim1, dim2, spacedim>::n_quadrature_points() const
1685 {
1686 return n_quadrature_points_;
1687 }
1688
1689
1690
1691 template <int dim1, int dim2, int spacedim>
1692 std::pair<Point<spacedim>, Point<spacedim>>
1693 FECouplingValues<dim1, dim2, spacedim>::quadrature_point(
1694 const unsigned int quadrature_point) const
1695 {
1696 AssertIndexRange(quadrature_point, n_quadrature_points_);
1697 const auto first_q = first_fe_values->quadrature_point(
1698 first_renumbering_data->quadrature_renumbering.empty() ?
1699 quadrature_point :
1700 first_renumbering_data->quadrature_renumbering[quadrature_point]);
1701
1702 const auto second_q = second_fe_values->quadrature_point(
1703 second_renumbering_data->quadrature_renumbering.empty() ?
1704 quadrature_point :
1705 second_renumbering_data->quadrature_renumbering[quadrature_point]);
1706
1707 return {first_q, second_q};
1708 }
1709
1710
1711
1712 template <int dim1, int dim2, int spacedim>
1713 std::pair<unsigned int, unsigned int>
1714 FECouplingValues<dim1, dim2, spacedim>::
1715 coupling_quadrature_to_quadrature_indices(
1716 const unsigned int quadrature_point) const
1717 {
1718 AssertIndexRange(quadrature_point, n_quadrature_points_);
1719 const auto first_id =
1720 first_renumbering_data->quadrature_renumbering.empty() ?
1721 quadrature_point :
1722 first_renumbering_data->quadrature_renumbering[quadrature_point];
1723
1724 const auto second_id =
1725 second_renumbering_data->quadrature_renumbering.empty() ?
1726 quadrature_point :
1727 second_renumbering_data->quadrature_renumbering[quadrature_point];
1728 return std::make_pair(first_id, second_id);
1729 }
1730
1731
1732
1733 template <int dim1, int dim2, int spacedim>
1734 std::pair<unsigned int, unsigned int>
1735 FECouplingValues<dim1, dim2, spacedim>::coupling_dof_to_dof_indices(
1736 const unsigned int coupling_dof_index) const
1737 {
1738 AssertIndexRange(coupling_dof_index, n_coupling_dofs_);
1739 const auto first_id =
1740 first_renumbering_data->dof_renumbering.empty() ?
1741 coupling_dof_index :
1742 first_renumbering_data->dof_renumbering[coupling_dof_index];
1743
1744 const auto second_id =
1745 second_renumbering_data->dof_renumbering.empty() ?
1746 coupling_dof_index :
1747 second_renumbering_data->dof_renumbering[coupling_dof_index];
1748 return std::make_pair(first_id, second_id);
1749 }
1750
1751
1752
1753 template <int dim1, int dim2, int spacedim>
1754 template <typename Extractor>
1755 inline FEValuesExtractors::FirstCoupling<Extractor>
1756 FECouplingValues<dim1, dim2, spacedim>::get_first_extractor(
1757 const Extractor &extractor) const
1758 {
1759 return FEValuesExtractors::FirstCoupling<Extractor>(extractor);
1760 }
1761
1762
1763
1764 template <int dim1, int dim2, int spacedim>
1765 template <typename Extractor>
1766 inline FEValuesExtractors::SecondCoupling<Extractor>
1767 FECouplingValues<dim1, dim2, spacedim>::get_second_extractor(
1768 const Extractor &extractor) const
1769 {
1770 return FEValuesExtractors::SecondCoupling<Extractor>(extractor);
1771 }
1772
1773
1774
1775 template <int dim1, int dim2, int spacedim>
1776 template <typename Extractor>
1777 inline const FEValuesViews::RenumberedView<
1778 FEValuesViews::View<dim1, spacedim, Extractor>>
1779 FECouplingValues<dim1, dim2, spacedim>::operator[](
1780 const FEValuesExtractors::FirstCoupling<Extractor> &extractor) const
1781 {
1782 return FEValuesViews::RenumberedView<
1783 typename FEValuesViews::View<dim1, spacedim, Extractor>>(
1784 (*first_fe_values)[extractor.extractor], *first_renumbering_data);
1785 }
1786
1787
1788
1789 template <int dim1, int dim2, int spacedim>
1790 template <typename Extractor>
1791 inline const FEValuesViews::RenumberedView<
1792 typename FEValuesViews::View<dim2, spacedim, Extractor>>
1793 FECouplingValues<dim1, dim2, spacedim>::operator[](
1794 const FEValuesExtractors::SecondCoupling<Extractor> &extractor) const
1795 {
1796 return FEValuesViews::RenumberedView<
1797 typename FEValuesViews::View<dim2, spacedim, Extractor>>(
1798 (*second_fe_values)[extractor.extractor], *second_renumbering_data);
1799 }
1800
1801 #endif // DOXYGEN
1802
1803 DEAL_II_NAMESPACE_CLOSE
1804
1805 #endif