Debian Codegraph @

include/deal.II/fe/mapping.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2001 - 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_mapping_h
16 #define dealii_mapping_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/array_view.h>
22 #include <deal.II/base/derivative_form.h>
23
24 #include <deal.II/fe/fe_update_flags.h>
25 #include <deal.II/fe/mapping_related_data.h>
26
27 #include <deal.II/grid/tria.h>
28
29 #include <deal.II/hp/q_collection.h>
30
31 #include <deal.II/non_matching/immersed_surface_quadrature.h>
32
33 #include <boost/container/small_vector.hpp>
34
35 #include <array>
36 #include <cmath>
37 #include <memory>
38
39 DEAL_II_NAMESPACE_OPEN
40
41 template <typename ElementType, typename MemorySpaceType>
42 class ArrayView;
43 template <int dim>
44 class Quadrature;
45 template <int dim, int spacedim>
46 class FEValues;
47 template <int dim, int spacedim>
48 class FEValuesBase;
49 template <int dim, int spacedim>
50 class FEValues;
51 template <int dim, int spacedim>
52 class FEFaceValues;
53 template <int dim, int spacedim>
54 class FESubfaceValues;
55 namespace NonMatching
56 {
57 template <int dim>
58 class FEImmersedSurfaceValues;
59 namespace internal
60 {
61 template <int dim, int spacedim>
62 class ComputeMappingDataHelper;
63 }
64 template <int dim, int spacedim, typename Number>
65 class MappingInfo;
66 } // namespace NonMatching
67
68
69 /**
70 * The transformation kind used for the Mapping::transform() functions.
71 *
72 * Special finite elements may need special Mapping from the reference cell to
73 * the actual mesh cell. In order to be most flexible, this enum provides an
74 * extensible interface for arbitrary transformations. Nevertheless, these
75 * must be implemented in the transform() functions of inheriting classes in
76 * order to work.
77 *
78 * @ingroup mapping
79 */
80 enum MappingKind
81 {
82 /**
83 * No mapping, i.e., shape functions are not mapped from a reference cell
84 * but instead are defined right on the real-space cell.
85 */
86 mapping_none = 0x0000,
87
88 /**
89 * Covariant mapping (see Mapping::transform() for details).
90 */
91 mapping_covariant = 0x0001,
92
93 /**
94 * Contravariant mapping (see Mapping::transform() for details).
95 */
96 mapping_contravariant = 0x0002,
97
98 /**
99 * Mapping of the gradient of a covariant vector field (see
100 * Mapping::transform() for details).
101 */
102 mapping_covariant_gradient = 0x0003,
103
104 /**
105 * Mapping of the gradient of a contravariant vector field (see
106 * Mapping::transform() for details).
107 */
108 mapping_contravariant_gradient = 0x0004,
109
110 /**
111 * The Piola transform usually used for Hdiv elements. Piola transform is
112 * the standard transformation of vector valued elements in H<sup>div</sup>.
113 * It amounts to a contravariant transformation scaled by the inverse of the
114 * volume element.
115 */
116 mapping_piola = 0x0100,
117
118 /**
119 * Transformation for the gradient of a vector field corresponding to a
120 * mapping_piola transformation (see Mapping::transform() for details).
121 */
122 mapping_piola_gradient = 0x0101,
123
124 /**
125 * The mapping used for Nedelec elements.
126 *
127 * Curl-conforming elements are mapped as covariant vectors. Nevertheless,
128 * we introduce a separate mapping kind, such that we can use the same flag
129 * for the vector and its gradient (see Mapping::transform() for details).
130 */
131 mapping_nedelec = 0x0200,
132
133 /**
134 * The mapping used for Raviart-Thomas elements.
135 */
136 mapping_raviart_thomas = 0x0300,
137
138 /**
139 * The mapping used for BDM elements.
140 */
141 mapping_bdm = mapping_raviart_thomas,
142
143 /**
144 * The mappings for 2-forms and third order tensors.
145 *
146 * These are mappings typically applied to hessians transformed to the
147 * reference cell.
148 *
149 * Mapping of the hessian of a covariant vector field (see
150 * Mapping::transform() for details).
151 */
152 mapping_covariant_hessian,
153
154 /**
155 * Mapping of the hessian of a contravariant vector field (see
156 * Mapping::transform() for details).
157 */
158 mapping_contravariant_hessian,
159
160 /**
161 * Mapping of the hessian of a piola vector field (see Mapping::transform()
162 * for details).
163 */
164 mapping_piola_hessian
165 };
166
167
168 /**
169 * @short Abstract base class for mapping classes.
170 *
171 * This class declares the interface for the functionality to describe
172 * mappings from the reference (unit) cell to a cell in real space, as well as
173 * for filling the information necessary to use the FEValues, FEFaceValues,
174 * and FESubfaceValues classes. Concrete implementations of these interfaces
175 * are provided in derived classes.
176 *
177 * <h3>Mathematics of the mapping</h3>
178 *
179 * The mapping is a transformation $\mathbf x = \mathbf F_K(\hat{\mathbf x})$
180 * which maps points $\hat{\mathbf x}$ in the reference cell
181 * $[0,1]^\text{dim}$ to points $\mathbf x$ in the actual grid cell
182 * $K\subset{\mathbb R}^\text{spacedim}$. Many of the applications of such
183 * mappings require the Jacobian of this mapping, $J(\hat{\mathbf x}) =
184 * \hat\nabla {\mathbf F}_K(\hat{\mathbf x})$. For instance, if
185 * dim=spacedim=2, we have
186 * @f[
187 * J(\hat{\mathbf x}) = \left(\begin{matrix}
188 * \frac{\partial x}{\partial \hat x} & \frac{\partial x}{\partial \hat y}
189 * \\
190 * \frac{\partial y}{\partial \hat x} & \frac{\partial y}{\partial \hat y}
191 * \end{matrix}\right)
192 * @f]
193 *
194 * <h4>%Mapping of scalar functions</h4>
195 *
196 * The shape functions of scalar finite elements are typically defined on a
197 * reference cell and are then simply mapped according to the rule
198 * @f[
199 * \varphi(\mathbf x) = \varphi\bigl(\mathbf F_K(\hat{\mathbf x})\bigr)
200 * = \hat \varphi(\hat{\mathbf x}).
201 * @f]
202 *
203 *
204 * <h4>%Mapping of integrals</h4>
205 *
206 * Using simply a change of variables, integrals of scalar functions over a
207 * cell $K$ can be expressed as an integral over the reference cell $\hat K$.
208 * Specifically, The volume form $d\hat x$ is transformed so that
209 * @f[
210 * \int_K u(\mathbf x)\,dx = \int_{\hat K} \hat
211 * u(\hat{\mathbf x}) \left|\text{det}J(\hat{\mathbf x})\right|
212 * \,d\hat x.
213 * @f]
214 *
215 * In expressions where such integrals are approximated by quadrature, this
216 * then leads to terms of the form
217 * @f[
218 * \int_K u(\mathbf x)\,dx
219 * \approx
220 * \sum_{q}
221 * \hat u(\hat{\mathbf x}_q)
222 * \underbrace{\left|\text{det}J(\hat{\mathbf x}_q)\right| w_q}_{=:
223 * \text{JxW}_q}.
224 * @f]
225 * Here, the weights $\text{JxW}_q$ of each quadrature point (where <i>JxW</i>
226 * mnemonically stands for <i>Jacobian times Quadrature Weights</i>) take the
227 * role of the $dx$ in the original integral. Consequently, they appear in all
228 * code that computes integrals approximated by quadrature, and are accessed
229 * by FEValues::JxW().
230 *
231 * @todo Document what happens in the codimension-1 case.
232 *
233 *
234 * <h4>%Mapping of vector fields, differential forms and gradients of vector
235 * fields</h4>
236 *
237 * The transformation of vector fields or differential forms (gradients of
238 * scalar functions) $\mathbf v$, and gradients of vector fields $\mathbf T$
239 * follows the general form
240 *
241 * @f[
242 * \mathbf v(\mathbf x) = \mathbf A(\hat{\mathbf x})
243 * \hat{\mathbf v}(\hat{\mathbf x}),
244 * \qquad
245 * \mathbf T(\mathbf x) = \mathbf A(\hat{\mathbf x})
246 * \hat{\mathbf T}(\hat{\mathbf x}) \mathbf B(\hat{\mathbf x}).
247 * @f]
248 * The differential forms <b>A</b> and <b>B</b> are determined by the kind of
249 * object being transformed. These transformations are performed through the
250 * transform() functions, and the type of object being transformed is
251 * specified by their MappingKind argument. See the documentation there for
252 * possible choices.
253 *
254 * <h4>Derivatives of the mapping</h4>
255 *
256 * Some applications require the derivatives of the mapping, of which the
257 * first order derivative is the mapping Jacobian, $J_{iJ}(\hat{\mathbf
258 * x})=\frac{\partial x_i}{\partial \hat x_J}$, described above. Higher order
259 * derivatives of the mapping are similarly defined, for example the Jacobian
260 * derivative, $\hat H_{iJK}(\hat{\mathbf x}) = \frac{\partial^2
261 * x_i}{\partial \hat x_J \partial \hat x_K}$, and the Jacobian second
262 * derivative, $\hat K_{iJKL}(\hat{\mathbf x}) = \frac{\partial^3
263 * x_i}{\partial \hat x_J \partial \hat x_K \partial \hat x_L}$. It is also
264 * useful to define the "pushed-forward" versions of the higher order
265 * derivatives: the Jacobian pushed-forward derivative, $H_{ijk}(\hat{\mathbf
266 * x}) = \frac{\partial^2 x_i}{\partial \hat x_J \partial \hat
267 * x_K}(J_{jJ})^{-1}(J_{kK})^{-1}$, and the Jacobian pushed-forward second
268 * derivative, $K_{ijkl}(\hat{\mathbf x}) = \frac{\partial^3 x_i}{\partial
269 * \hat x_J \partial \hat x_K \partial \hat
270 * x_L}(J_{jJ})^{-1}(J_{kK})^{-1}(J_{lL})^{-1}$. These pushed-forward versions
271 * can be used to compute the higher order derivatives of functions defined on
272 * the reference cell with respect to the real cell coordinates. For instance,
273 * the Jacobian derivative with respect to the real cell coordinates is given
274 * by:
275 *
276 * @f[
277 * \frac{\partial}{\partial x_j}\left[J_{iJ}(\hat{\mathbf x})\right] =
278 * H_{ikn}(\hat{\mathbf x})J_{nJ}(\hat{\mathbf x}),
279 * @f]
280 * and the derivative of the Jacobian inverse with respect to the real cell
281 * coordinates is similarly given by:
282 * @f[
283 * \frac{\partial}{\partial x_j}\left[\left(J_{iJ}(\hat{\mathbf
284 * x})\right)^{-1}\right] = -H_{nik}(\hat{\mathbf x})\left(J_{nJ}(\hat{\mathbf
285 * x})\right)^{-1}.
286 * @f]
287 *
288 * In a similar fashion, higher order derivatives, with respect to the real
289 * cell coordinates, of functions defined on the reference cell can be defined
290 * using the Jacobian pushed-forward higher-order derivatives. For example,
291 * the derivative, with respect to the real cell coordinates, of the Jacobian
292 * pushed-forward derivative is given by:
293 *
294 * @f[
295 * \frac{\partial}{\partial x_l}\left[H_{ijk}(\hat{\mathbf x})\right] =
296 * K_{ijkl}(\hat{\mathbf x}) -H_{mjl}(\hat{\mathbf x})H_{imk}(\hat{\mathbf
297 * x})-H_{mkl}(\hat{\mathbf x})H_{imj}(\hat{\mathbf x}).
298 * @f]
299 *
300 * <h3>References</h3>
301 *
302 * A general publication on differential geometry and finite elements is the
303 * survey
304 * <ul>
305 * <li>Douglas N. Arnold, Richard S. Falk, and Ragnar Winther. <i>Finite
306 * element exterior calculus: from Hodge theory to numerical stability.</i>
307 * Bull. Amer. Math. Soc. (N.S.), 47:281-354, 2010. <a
308 * href="http://dx.doi.org/10.1090/S0273-0979-10-01278-4">DOI:
309 * 10.1090/S0273-0979-10-01278-4</a>.
310 * </ul>
311 *
312 * The description of the Piola transform has been taken from the <a
313 * href="http://www.math.uh.edu/~rohop/spring_05/downloads/">lecture notes</a>
314 * by Ronald H. W. Hoppe, University of Houston, Chapter 7.
315 *
316 * @ingroup mapping
317 */
318 template <int dim, int spacedim = dim>
319 class Mapping : public EnableObserverPointer
320 {
321 public:
322 /**
323 * Virtual destructor.
324 */
325 virtual ~Mapping() override = default;
326
327 /**
328 * Return a pointer to a copy of the present object. The caller of this copy
329 * then assumes ownership of it.
330 *
331 * The function is declared abstract virtual in this base class, and derived
332 * classes will have to implement it.
333 *
334 * This function is mainly used by the hp::MappingCollection class.
335 */
336 virtual std::unique_ptr<Mapping<dim, spacedim>>
337 clone() const = 0;
338
339 /**
340 * Return the mapped vertices of a cell.
341 *
342 * Most of the time, these values will simply be the coordinates of the
343 * vertices of a cell as returned by <code>cell-@>vertex(v)</code> for
344 * vertex <code>v</code>, i.e., information stored by the triangulation.
345 * However, there are also mappings that add displacements or choose
346 * completely different locations, e.g., MappingQEulerian,
347 * MappingQ1Eulerian, or MappingFEField.
348 *
349 * The default implementation of this function simply returns the
350 * information stored by the triangulation, i.e.,
351 * <code>cell-@>vertex(v)</code>.
352 */
353 virtual boost::container::small_vector<Point<spacedim>,
354 #ifndef _MSC_VER
355 ReferenceCells::max_n_vertices<dim>()
356 #else
357 GeometryInfo<dim>::vertices_per_cell
358 #endif
359 >
360 get_vertices(
361 const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
362
363 /**
364 * Return the mapped vertices of a face.
365 *
366 * Same as above but working on a given face of a cell.
367 *
368 * @param[in] cell The cell containing the face.
369 * @param[in] face_no The number of the face within the cell.
370 */
371 boost::container::small_vector<Point<spacedim>,
372 #ifndef _MSC_VER
373 ReferenceCells::max_n_vertices<dim - 1>()
374 #else
375 GeometryInfo<dim - 1>::vertices_per_cell
376 #endif
377 >
378 get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
379 const unsigned int face_no) const;
380
381 /**
382 * Return one of two possible mapped centers of a cell.
383 *
384 * If you are using a (bi-,tri-)linear mapping that preserves vertex
385 * locations, this function simply returns the value also produced by
386 * `cell->center()`. However, there are also mappings that add displacements
387 * or choose completely different locations, e.g., MappingQEulerian,
388 * MappingQ1Eulerian, or MappingFEField, and mappings based on high order
389 * polynomials, for which the center may not coincide with the average of
390 * the vertex locations.
391 *
392 * By default, this function returns the push forward of the barycenter of the
393 * reference cell. If the parameter
394 * @p map_barycenter_of_reference_cell is set to false, then the returned
395 * value will be the average of the vertex locations, as returned by the
396 * get_vertices() method.
397 *
398 * @param[in] cell The cell for which you want to compute the center
399 * @param[in] map_barycenter_of_reference_cell A flag that switches the
400 * algorithm for the computation of the cell center from
401 * transform_unit_to_real_cell() applied to the center of the reference cell
402 * to computing the vertex averages.
403 */
404 virtual Point<spacedim>
405 get_center(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
406 const bool map_barycenter_of_reference_cell = true) const;
407
408 /**
409 * Return the bounding box of a mapped cell.
410 *
411 * If you are using a (bi-,tri-)linear mapping that preserves vertex
412 * locations, this function simply returns the value also produced by
413 * `cell->bounding_box()`. However, there are also mappings that add
414 * displacements or choose completely different locations, e.g.,
415 * MappingQEulerian, MappingQ1Eulerian, or MappingFEField.
416 *
417 * For linear mappings, this function returns the bounding box containing all
418 * the vertices of the cell, as returned by the get_vertices() method. For
419 * higher order mappings defined through support points, the bounding box is
420 * only guaranteed to contain all the support points, and it is, in general,
421 * only an approximation of the true bounding box, which may be larger.
422 *
423 * @param[in] cell The cell for which you want to compute the bounding box
424 */
425 virtual BoundingBox<spacedim>
426 get_bounding_box(
427 const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
428
429 /**
430 * Return whether the mapping preserves vertex locations. In other words,
431 * this function returns whether the mapped location of the reference cell
432 * vertices (given by ReferenceCell::vertex()) equals the result of
433 * <code>cell-@>vertex()</code> (i.e., information stored by the
434 * triangulation).
435 *
436 * For example, implementations in derived classes return @p true for
437 * MappingQ, MappingCartesian, but @p false for MappingQEulerian,
438 * MappingQ1Eulerian, and MappingFEField.
439 */
440 virtual bool
441 preserves_vertex_locations() const = 0;
442
443 /**
444 * Returns if this instance of Mapping is compatible with the type of cell
445 * in @p reference_cell.
446 */
447 virtual bool
448 is_compatible_with(const ReferenceCell &reference_cell) const = 0;
449
450 /**
451 * @name Mapping points between reference and real cells
452 * @{
453 */
454
455 /**
456 * Map the point @p p on the unit cell to the corresponding point on the
457 * real cell @p cell.
458 *
459 * @param cell Iterator to the cell that will be used to define the mapping.
460 * @param p Location of a point on the reference cell.
461 * @return The location of the reference point mapped to real space using
462 * the mapping defined by the class derived from the current one that
463 * implements the mapping, and the coordinates of the cell identified by the
464 * first argument.
465 */
466 virtual Point<spacedim>
467 transform_unit_to_real_cell(
468 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
469 const Point<dim> &p) const = 0;
470
471 /**
472 * Map the point @p p on the real @p cell to the corresponding point on the
473 * unit cell, and return its coordinates. This function provides the inverse
474 * of the mapping provided by transform_unit_to_real_cell().
475 *
476 * In the codimension one case, this function returns the normal projection
477 * of the real point @p p on the curve or surface identified by the @p cell.
478 *
479 * @note Polynomial mappings from the reference (unit) cell coordinates to
480 * the coordinate system of a real cell are not always invertible if the
481 * point for which the inverse mapping is to be computed lies outside the
482 * cell's boundaries. In such cases, the current function may fail to
483 * compute a point on the reference cell whose image under the mapping
484 * equals the given point @p p. If this is the case then this function
485 * throws an exception of type Mapping::ExcTransformationFailed . Whether
486 * the given point @p p lies outside the cell can therefore be determined by
487 * checking whether the returned reference coordinates lie inside or outside
488 * the reference cell (e.g., using ReferenceCell::contains_point()) or
489 * whether the exception mentioned above has been thrown.
490 *
491 * @param cell Iterator to the cell that will be used to define the mapping.
492 * @param p Location of a point on the given cell.
493 * @return The reference cell location of the point that when mapped to real
494 * space equals the coordinates given by the second argument. This mapping
495 * uses the mapping defined by the class derived from the current one that
496 * implements the mapping, and the coordinates of the cell identified by the
497 * first argument.
498 */
499 virtual Point<dim>
500 transform_real_to_unit_cell(
501 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
502 const Point<spacedim> &p) const = 0;
503
504 /**
505 * Map multiple points from the real point locations to points in reference
506 * locations. The functionality is essentially the same as looping over all
507 * points and calling the Mapping::transform_real_to_unit_cell() function
508 * for each point individually, but it can be much faster for certain
509 * mappings that implement a more specialized version such as
510 * MappingQ. The only difference in behavior is that this function
511 * will never throw an ExcTransformationFailed() exception. If the
512 * transformation fails for `real_points[i]`, the returned `unit_points[i]`
513 * contains std::numeric_limits<double>::lowest() as the first component
514 * of the point, marking this one point as invalid.
515 */
516 virtual void
517 transform_points_real_to_unit_cell(
518 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
519 const ArrayView<const Point<spacedim>> &real_points,
520 const ArrayView<Point<dim>> &unit_points) const;
521
522 /**
523 * Transform the point @p p on the real @p cell to the corresponding point
524 * on the reference cell, and then project this point to a (dim-1)-dimensional
525 * point in the coordinate system of the face with
526 * the given face number @p face_no. Ideally the point @p p is near the face
527 * @p face_no, but any point in the cell can technically be projected.
528 *
529 * This function does not make physical sense when dim=1, so it throws an
530 * exception in this case.
531 */
532 Point<dim - 1>
533 project_real_point_to_unit_point_on_face(
534 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
535 const unsigned int face_no,
536 const Point<spacedim> &p) const;
537
538 /**
539 * @}
540 */
541
542
543 /**
544 * @name Exceptions
545 * @{
546 */
547
548 /**
549 * Exception
550 */
551 DeclException0(ExcInvalidData);
552
553
554 /**
555 * Computing the mapping between a real space point and a point in reference
556 * space failed, typically because the given point lies outside the cell
557 * where the inverse mapping is not unique.
558 *
559 * @ingroup Exceptions
560 */
561 DeclExceptionMsg(
562 ExcTransformationFailed,
563 "Computing the mapping between a real space point and a point in reference "
564 "space failed, typically because the given point lies outside the cell "
565 "where the inverse mapping is not unique.");
566
567 /**
568 * deal.II assumes the Jacobian determinant to be positive. When the cell
569 * geometry is distorted under the image of the mapping, the mapping becomes
570 * invalid and this exception is thrown.
571 *
572 * @ingroup Exceptions
573 */
574 DeclException3(ExcDistortedMappedCell,
575 Point<spacedim>,
576 double,
577 int,
578 << "The image of the mapping applied to cell with center ["
579 << arg1 << "] is distorted. The cell geometry or the "
580 << "mapping are invalid, giving a non-positive volume "
581 << "fraction of " << arg2 << " in quadrature point " << arg3
582 << '.');
583
584 /**
585 * @}
586 */
587
588 /**
589 * @name Interface with FEValues
590 * @{
591 */
592
593 public:
594 /**
595 * Base class for internal data of mapping objects. The internal mechanism
596 * is that upon construction of a FEValues object, it asks the mapping and
597 * finite element classes that are to be used to allocate memory for their
598 * own purpose in which they may store data that only needs to be computed
599 * once. For example, most finite elements will store the values of the
600 * shape functions at the quadrature points in this object, since they do
601 * not change from cell to cell and only need to be computed once. The same
602 * may be true for Mapping classes that want to only evaluate the shape
603 * functions used for mapping once at the quadrature points.
604 *
605 * Since different FEValues objects using different quadrature rules might
606 * access the same mapping object at the same time, it is necessary to
607 * create one such object per FEValues object. FEValues does this by calling
608 * Mapping::get_data(), or in reality the implementation of the
609 * corresponding function in derived classes. Ownership of the object
610 * created by Mapping::get_data() is then transferred to the FEValues
611 * object, but a reference to this object is passed to the mapping object
612 * every time it is asked to compute information on a concrete cell. This
613 * happens when FEValues::reinit() (or the corresponding classes in
614 * FEFaceValues and FESubfaceValues) call Mapping::fill_fe_values() (and
615 * similarly via Mapping::fill_fe_face_values() and
616 * Mapping::fill_fe_subface_values()).
617 *
618 * The purpose of this class is for mapping objects to store information
619 * that can be computed once at the beginning, on the reference cell, and to
620 * access it later when computing information on a concrete cell. As such,
621 * the object handed to Mapping::fill_fe_values() is marked as
622 * <code>const</code>, because the assumption is that at the time this
623 * information is used, it will not need to modified again. However, classes
624 * derived from Mapping can also use such objects for two other purposes:
625 *
626 * - To provide scratch space for computations that are done in
627 * Mapping::fill_fe_values() and similar functions. Some of the derived
628 * classes would like to use scratch arrays and it would be a waste of time
629 * to allocate these arrays every time this function is called, just to
630 * de-allocate it again at the end of the function. Rather, one could allocate
631 * this memory once as a member variable of the current class, and simply
632 * use it in Mapping::fill_fe_values().
633 * - After calling Mapping::fill_fe_values(), FEValues::reinit()
634 * calls FiniteElement::fill_fe_values() where the finite element computes
635 * values, gradients, etc of the shape functions using both information
636 * computed once at the beginning using a mechanism similar to the one
637 * described here (see FiniteElement::InternalDataBase) as well as the data
638 * already computed by Mapping::fill_fe_values(). As part of its work, some
639 * implementations of FiniteElement::fill_fe_values() need to transform
640 * shape function data, and they do so by calling Mapping::transform(). The
641 * call to the latter function also receives a reference to the
642 * Mapping::InternalDataBase object. Since Mapping::transform() may be
643 * called many times on each cell, it is sometimes worth for derived classes
644 * to compute some information only once in Mapping::fill_fe_values() and
645 * reuse it in Mapping::transform(). This information can also be stored in
646 * the classes that derived mapping classes derive from InternalDataBase.
647 *
648 * In both of these cases, the InternalDataBase object being passed around
649 * is "morally const", i.e., no external observer can tell whether a scratch
650 * array or some intermediate data for Mapping::transform() is being
651 * modified by Mapping::fill_fe_values() or not. Consequently, the
652 * InternalDataBase objects are always passed around as <code>const</code>
653 * objects. Derived classes that would like to make use of the two
654 * additional uses outlined above therefore need to mark the member
655 * variables they want to use for these purposes as <code>mutable</code> to
656 * allow for their modification despite the fact that the surrounding object
657 * is marked as <code>const</code>.
658 */
659 class InternalDataBase
660 {
661 public:
662 /**
663 * Constructor. Sets update_flags to @p update_default and @p first_cell
664 * to @p true.
665 */
666 InternalDataBase();
667
668 /**
669 * Copy construction is forbidden.
670 */
671 InternalDataBase(const InternalDataBase &) = delete;
672
673 /**
674 * This function initializes the data fields related to evaluation of the
675 * mapping on cells, implemented by (derived) classes. This function is
676 * used both when setting up a field of this class for the first time or
677 * when a new Quadrature formula should be considered without creating an
678 * entirely new object. This is used when the number of evaluation points
679 * is different on each cell, e.g. when using FEPointEvaluation for
680 * handling particles or with certain non-matching problem settings.
681 */
682 virtual void
683 reinit(const UpdateFlags update_flags, const Quadrature<dim> &quadrature);
684
685 /**
686 * Virtual destructor for derived classes
687 */
688 virtual ~InternalDataBase() = default;
689
690 /**
691 * A set of update flags specifying the kind of information that an
692 * implementation of the Mapping interface needs to compute on each cell
693 * or face, i.e., in Mapping::fill_fe_values() and friends.
694 *
695 * This set of flags is stored here by implementations of
696 * Mapping::get_data(), Mapping::get_face_data(), or
697 * Mapping::get_subface_data(), and is that subset of the update flags
698 * passed to those functions that require re-computation on every cell.
699 * (The subset of the flags corresponding to information that can be
700 * computed once and for all already at the time of the call to
701 * Mapping::get_data() -- or an implementation of that interface -- need
702 * not be stored here because it has already been taken care of.)
703 */
704 UpdateFlags update_each;
705
706 /**
707 * Return an estimate (in bytes) for the memory consumption of this object.
708 */
709 virtual std::size_t
710 memory_consumption() const;
711 };
712
713 protected:
714 /**
715 * Given a set of update flags, compute which other quantities <i>also</i>
716 * need to be computed in order to satisfy the request by the given flags.
717 * Then return the combination of the original set of flags and those just
718 * computed.
719 *
720 * As an example, if @p update_flags contains update_JxW_values (i.e., the
721 * product of the determinant of the Jacobian and the weights provided by
722 * the quadrature formula), a mapping may require the computation of the
723 * full Jacobian matrix in order to compute its determinant. They would then
724 * return not just update_JxW_values, but also update_jacobians. (This is
725 * not how it is actually done internally in the derived classes that
726 * compute the JxW values -- they set update_contravariant_transformation
727 * instead, from which the determinant can also be computed -- but this does
728 * not take away from the instructiveness of the example.)
729 *
730 * An extensive discussion of the interaction between this function and
731 * FEValues can be found in the
732 * @ref FE_vs_Mapping_vs_FEValues
733 * documentation topic.
734 *
735 * @see UpdateFlags
736 */
737 virtual UpdateFlags
738 requires_update_flags(const UpdateFlags update_flags) const = 0;
739
740 /**
741 * Create and return a pointer to an object into which mappings can store
742 * data that only needs to be computed once but that can then be used
743 * whenever the mapping is applied to a concrete cell (e.g., in the various
744 * transform() functions, as well as in the fill_fe_values(),
745 * fill_fe_face_values() and fill_fe_subface_values() that form the
746 * interface of mappings with the FEValues class).
747 *
748 * Derived classes will return pointers to objects of a type derived from
749 * Mapping::InternalDataBase (see there for more information) and may
750 * pre-compute some information already (in accordance with what will be asked
751 * of the mapping in the future, as specified by the update flags) and for
752 * the given quadrature object. Subsequent calls to transform() or
753 * fill_fe_values() and friends will then receive back the object created
754 * here (with the same set of update flags and for the same quadrature
755 * object). Derived classes can therefore pre-compute some information in
756 * their get_data() function and store it in the internal data object.
757 *
758 * The mapping classes do not keep track of the objects created by this
759 * function. Ownership will therefore rest with the caller.
760 *
761 * An extensive discussion of the interaction between this function and
762 * FEValues can be found in the
763 * @ref FE_vs_Mapping_vs_FEValues
764 * documentation topic.
765 *
766 * @param update_flags A set of flags that define what is expected of the
767 * mapping class in future calls to transform() or the fill_fe_values()
768 * group of functions. This set of flags may contain flags that mappings do
769 * not know how to deal with (e.g., for information that is in fact computed
770 * by the finite element classes, such as UpdateFlags::update_values).
771 * Derived classes will need to store these flags, or at least that subset
772 * of flags that will require the mapping to perform any actions in
773 * fill_fe_values(), in InternalDataBase::update_each.
774 * @param quadrature The quadrature object for which mapping information
775 * will have to be computed. This includes the locations and weights of
776 * quadrature points.
777 * @return A pointer to a newly created object of type InternalDataBase (or
778 * a derived class). Ownership of this object passes to the calling
779 * function.
780 */
781 virtual std::unique_ptr<InternalDataBase>
782 get_data(const UpdateFlags update_flags,
783 const Quadrature<dim> &quadrature) const = 0;
784
785 /**
786 * Like get_data(), but in preparation for later calls to transform() or
787 * fill_fe_face_values() that will need information about mappings from the
788 * reference face to a face of a concrete cell.
789 *
790 * @param update_flags A set of flags that define what is expected of the
791 * mapping class in future calls to transform() or the fill_fe_values()
792 * group of functions. This set of flags may contain flags that mappings do
793 * not know how to deal with (e.g., for information that is in fact computed
794 * by the finite element classes, such as UpdateFlags::update_values).
795 * Derived classes will need to store these flags, or at least that subset
796 * of flags that will require the mapping to perform any actions in
797 * fill_fe_values(), in InternalDataBase::update_each.
798 * @param quadrature The quadrature object for which mapping information
799 * will have to be computed. This includes the locations and weights of
800 * quadrature points.
801 * @return A pointer to a newly created object of type InternalDataBase (or
802 * a derived class). Ownership of this object passes to the calling
803 * function.
804 */
805 virtual std::unique_ptr<InternalDataBase>
806 get_face_data(const UpdateFlags update_flags,
807 const hp::QCollection<dim - 1> &quadrature) const;
808
809 /**
810 * @deprecated Use the version taking a hp::QCollection argument.
811 */
812 virtual std::unique_ptr<InternalDataBase>
813 get_face_data(const UpdateFlags update_flags,
814 const Quadrature<dim - 1> &quadrature) const;
815
816 /**
817 * Like get_data() and get_face_data(), but in preparation for later calls
818 * to transform() or fill_fe_subface_values() that will need information
819 * about mappings from the reference face to a child of a face (i.e.,
820 * subface) of a concrete cell.
821 *
822 * @param update_flags A set of flags that define what is expected of the
823 * mapping class in future calls to transform() or the fill_fe_values()
824 * group of functions. This set of flags may contain flags that mappings do
825 * not know how to deal with (e.g., for information that is in fact computed
826 * by the finite element classes, such as UpdateFlags::update_values).
827 * Derived classes will need to store these flags, or at least that subset
828 * of flags that will require the mapping to perform any actions in
829 * fill_fe_values(), in InternalDataBase::update_each.
830 * @param quadrature The quadrature object for which mapping information
831 * will have to be computed. This includes the locations and weights of
832 * quadrature points.
833 * @return A pointer to a newly created object of type InternalDataBase (or
834 * a derived class). Ownership of this object passes to the calling
835 * function.
836 */
837 virtual std::unique_ptr<InternalDataBase>
838 get_subface_data(const UpdateFlags update_flags,
839 const Quadrature<dim - 1> &quadrature) const = 0;
840
841 /**
842 * Compute information about the mapping from the reference cell to the real
843 * cell indicated by the first argument to this function. Derived classes
844 * will have to implement this function based on the kind of mapping they
845 * represent. It is called by FEValues::reinit().
846 *
847 * Conceptually, this function's represents the application of the mapping
848 * $\mathbf x=\mathbf F_K(\hat {\mathbf x})$ from reference coordinates
849 * $\mathbf\in [0,1]^d$ to real space coordinates $\mathbf x$ for a given
850 * cell $K$. Its purpose is to compute the following kinds of data:
851 *
852 * - Data that results from the application of the mapping itself, e.g.,
853 * computing the location $\mathbf x_q = \mathbf F_K(\hat{\mathbf x}_q)$ of
854 * quadrature points on the real cell, and that is directly useful to users
855 * of FEValues, for example during assembly.
856 * - Data that is necessary for finite element implementations to compute
857 * their shape functions on the real cell. To this end, the
858 * FEValues::reinit() function calls FiniteElement::fill_fe_values() after
859 * the current function, and the output of this function serves as input to
860 * FiniteElement::fill_fe_values(). Examples of information that needs to be
861 * computed here for use by the finite element classes is the Jacobian of
862 * the mapping, $\hat\nabla \mathbf F_K(\hat{\mathbf x})$ or its inverse,
863 * for example to transform the gradients of shape functions on the
864 * reference cell to the gradients of shape functions on the real cell.
865 *
866 * The information computed by this function is used to fill the various
867 * member variables of the output argument of this function. Which of the
868 * member variables of that structure should be filled is determined by the
869 * update flags stored in the Mapping::InternalDataBase object passed to
870 * this function.
871 *
872 * An extensive discussion of the interaction between this function and
873 * FEValues can be found in the
874 * @ref FE_vs_Mapping_vs_FEValues
875 * documentation topic.
876 *
877 * @param[in] cell The cell of the triangulation for which this function is
878 * to compute a mapping from the reference cell to.
879 * @param[in] cell_similarity Whether or not the cell given as first
880 * argument is simply a translation, rotation, etc of the cell for which
881 * this function was called the most recent time. This information is
882 * computed simply by matching the vertices (as stored by the Triangulation)
883 * between the previous and the current cell. The value passed here may be
884 * modified by implementations of this function and should then be returned
885 * (see the discussion of the return value of this function).
886 * @param[in] quadrature A reference to the quadrature formula in use for
887 * the current evaluation. This quadrature object is the same as the one
888 * used when creating the @p internal_data object. The object is used both
889 * to map the location of quadrature points, as well as to compute the JxW
890 * values for each quadrature point (which involves the quadrature weights).
891 * @param[in] internal_data A reference to an object previously created by
892 * get_data() and that may be used to store information the mapping can
893 * compute once on the reference cell. See the documentation of the
894 * Mapping::InternalDataBase class for an extensive description of the
895 * purpose of these objects.
896 * @param[out] output_data A reference to an object whose member variables
897 * should be computed. Not all of the members of this argument need to be
898 * filled; which ones need to be filled is determined by the update flags
899 * stored inside the @p internal_data object.
900 * @return An updated value of the @p cell_similarity argument to this
901 * function. The returned value will be used for the corresponding argument
902 * when FEValues::reinit() calls FiniteElement::fill_fe_values(). In most
903 * cases, derived classes will simply want to return the value passed for @p
904 * cell_similarity. However, implementations of this function may downgrade
905 * the level of cell similarity. This is, for example, the case for classes
906 * that take not only into account the locations of the vertices of a cell
907 * (as reported by the Triangulation), but also other information specific
908 * to the mapping. The purpose is that FEValues::reinit() can compute
909 * whether a cell is similar to the previous one only based on the cell's
910 * vertices, whereas the mapping may also consider displacement fields
911 * (e.g., in the MappingQ1Eulerian and MappingFEField classes). In such
912 * cases, the mapping may conclude that the previously computed cell
913 * similarity is too optimistic, and invalidate it for subsequent use in
914 * FiniteElement::fill_fe_values() by returning a less optimistic cell
915 * similarity value.
916 *
917 * @note FEValues ensures that this function is always called with the same
918 * pair of @p internal_data and @p output_data objects. In other words, if
919 * an implementation of this function knows that it has written a piece of
920 * data into the output argument in a previous call, then there is no need
921 * to copy it there again in a later call if the implementation knows that
922 * this is the same value.
923 */
924 virtual CellSimilarity::Similarity
925 fill_fe_values(
926 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
927 const CellSimilarity::Similarity cell_similarity,
928 const Quadrature<dim> &quadrature,
929 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
930 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
931 &output_data) const = 0;
932
933 /**
934 * This function is the equivalent to Mapping::fill_fe_values(), but for
935 * faces of cells. See there for an extensive discussion of its purpose. It
936 * is called by FEFaceValues::reinit().
937 *
938 * @param[in] cell The cell of the triangulation for which this function is
939 * to compute a mapping from the reference cell to.
940 * @param[in] face_no The number of the face of the given cell for which
941 * information is requested.
942 * @param[in] quadrature A reference to the quadrature formula in use for
943 * the current evaluation. This quadrature object is the same as the one
944 * used when creating the @p internal_data object. The object is used both
945 * to map the location of quadrature points, as well as to compute the JxW
946 * values for each quadrature point (which involves the quadrature weights).
947 * @param[in] internal_data A reference to an object previously created by
948 * get_data() and that may be used to store information the mapping can
949 * compute once on the reference cell. See the documentation of the
950 * Mapping::InternalDataBase class for an extensive description of the
951 * purpose of these objects.
952 * @param[out] output_data A reference to an object whose member variables
953 * should be computed. Not all of the members of this argument need to be
954 * filled; which ones need to be filled is determined by the update flags
955 * stored inside the @p internal_data object.
956 */
957 virtual void
958 fill_fe_face_values(
959 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
960 const unsigned int face_no,
961 const hp::QCollection<dim - 1> &quadrature,
962 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
963 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
964 &output_data) const;
965
966 /**
967 * @deprecated Use the version taking a hp::QCollection argument.
968 */
969 virtual void
970 fill_fe_face_values(
971 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
972 const unsigned int face_no,
973 const Quadrature<dim - 1> &quadrature,
974 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
975 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
976 &output_data) const;
977
978 /**
979 * This function is the equivalent to Mapping::fill_fe_values(), but for
980 * subfaces (i.e., children of faces) of cells. See there for an extensive
981 * discussion of its purpose. It is called by FESubfaceValues::reinit().
982 *
983 * @param[in] cell The cell of the triangulation for which this function is
984 * to compute a mapping from the reference cell to.
985 * @param[in] face_no The number of the face of the given cell for which
986 * information is requested.
987 * @param[in] subface_no The number of the child of a face of the given cell
988 * for which information is requested.
989 * @param[in] quadrature A reference to the quadrature formula in use for
990 * the current evaluation. This quadrature object is the same as the one
991 * used when creating the @p internal_data object. The object is used both
992 * to map the location of quadrature points, as well as to compute the JxW
993 * values for each quadrature point (which involves the quadrature weights).
994 * @param[in] internal_data A reference to an object previously created by
995 * get_data() and that may be used to store information the mapping can
996 * compute once on the reference cell. See the documentation of the
997 * Mapping::InternalDataBase class for an extensive description of the
998 * purpose of these objects.
999 * @param[out] output_data A reference to an object whose member variables
1000 * should be computed. Not all of the members of this argument need to be
1001 * filled; which ones need to be filled is determined by the update flags
1002 * stored inside the @p internal_data object.
1003 */
1004 virtual void
1005 fill_fe_subface_values(
1006 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1007 const unsigned int face_no,
1008 const unsigned int subface_no,
1009 const Quadrature<dim - 1> &quadrature,
1010 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
1011 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1012 &output_data) const = 0;
1013
1014 /**
1015 * The equivalent of Mapping::fill_fe_values(), but for the case that the
1016 * quadrature is an ImmersedSurfaceQuadrature. See there for a comprehensive
1017 * description of the input parameters. This function is called by
1018 * FEImmersedSurfaceValues::reinit().
1019 */
1020 virtual void
1021 fill_fe_immersed_surface_values(
1022 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1023 const NonMatching::ImmersedSurfaceQuadrature<dim> &quadrature,
1024 const typename Mapping<dim, spacedim>::InternalDataBase &internal_data,
1025 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1026 &output_data) const;
1027
1028 /**
1029 * @}
1030 */
1031
1032 public:
1033 /**
1034 * @name Functions to transform tensors from reference to real coordinates
1035 * @{
1036 */
1037
1038 /**
1039 * Transform a field of vectors or 1-differential forms according to the
1040 * selected MappingKind.
1041 *
1042 * @note Normally, this function is called by a finite element, filling
1043 * FEValues objects. For this finite element, there should be an alias
1044 * MappingKind like @p mapping_bdm, @p mapping_nedelec, etc. This alias
1045 * should be preferred to using the kinds below.
1046 *
1047 * The mapping kinds currently implemented by derived classes are:
1048 * <ul>
1049 * <li> @p mapping_contravariant: maps a vector field on the reference cell
1050 * to the physical cell through the Jacobian:
1051 * @f[
1052 * \mathbf u(\mathbf x) = J(\hat{\mathbf x})\hat{\mathbf u}(\hat{\mathbf
1053 * x}).
1054 * @f]
1055 * In physics, this is usually referred to as the contravariant
1056 * transformation. Mathematically, it is the push forward of a vector field.
1057 *
1058 * <li> @p mapping_covariant: maps a field of one-forms on the reference
1059 * cell to a field of one-forms on the physical cell. (Theoretically this
1060 * would refer to a DerivativeForm<1,dim,1> but we canonically identify this
1061 * type with a Tensor<1,dim>). Mathematically, it is the pull back of the
1062 * differential form
1063 * @f[
1064 * \mathbf u(\mathbf x) = J(\hat{\mathbf x})(J(\hat{\mathbf x})^{T}
1065 * J(\hat{\mathbf x}))^{-1}\hat{\mathbf u}(\hat{\mathbf x}).
1066 * @f]
1067 * Gradients of scalar differentiable functions are transformed this way.
1068 *
1069 * In the case when dim=spacedim the previous formula reduces to
1070 * @f[
1071 * \mathbf u(\mathbf x) = J(\hat{\mathbf x})^{-T}\hat{\mathbf
1072 * u}(\hat{\mathbf x})
1073 * @f]
1074 * because we assume that the mapping $\mathbf F_K$ is always invertible,
1075 * and consequently its Jacobian $J$ is an invertible matrix.
1076 *
1077 * <li> @p mapping_piola: A field of <i>dim-1</i>-forms on the reference
1078 * cell is also represented by a vector field, but again transforms
1079 * differently, namely by the Piola transform
1080 * @f[
1081 * \mathbf u(\mathbf x) = \frac{1}{\text{det}\;J(\hat{\mathbf x})}
1082 * J(\hat{\mathbf x}) \hat{\mathbf u}(\hat{\mathbf x}).
1083 * @f]
1084 * </ul>
1085 *
1086 * @param[in] input An array (or part of an array) of input objects that
1087 * should be mapped.
1088 * @param[in] kind The kind of mapping to be applied.
1089 * @param[in] internal A pointer to an object of type
1090 * Mapping::InternalDataBase that contains information previously stored by
1091 * the mapping. The object pointed to was created by the get_data(),
1092 * get_face_data(), or get_subface_data() function, and will have been
1093 * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
1094 * fill_fe_subface_values() for the current cell, before calling the current
1095 * function. In other words, this object also represents with respect to
1096 * which cell the transformation should be applied to.
1097 * @param[out] output An array (or part of an array) into which the
1098 * transformed objects should be placed. (Note that the array view is @p
1099 * const, but the tensors it points to are not.)
1100 */
1101 virtual void
1102 transform(const ArrayView<const Tensor<1, dim>> &input,
1103 const MappingKind kind,
1104 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
1105 const ArrayView<Tensor<1, spacedim>> &output) const = 0;
1106
1107 /**
1108 * Transform a field of differential forms from the reference cell to the
1109 * physical cell. It is useful to think of $\mathbf{T} = \nabla \mathbf u$
1110 * and $\hat{\mathbf T} = \hat \nabla \hat{\mathbf u}$, with $\mathbf u$ a
1111 * vector field. The mapping kinds currently implemented by derived classes
1112 * are:
1113 * <ul>
1114 * <li> @p mapping_covariant: maps a field of forms on the reference cell to
1115 * a field of forms on the physical cell. Mathematically, it is the pull
1116 * back of the differential form
1117 * @f[
1118 * \mathbf T(\mathbf x) = \hat{\mathbf T}(\hat{\mathbf x})
1119 * J(\hat{\mathbf x})(J(\hat{\mathbf x})^{T}
1120 * J(\hat{\mathbf x}))^{-1}.
1121 * @f]
1122 * Jacobians of spacedim-vector valued differentiable functions are
1123 * transformed this way.
1124 *
1125 * In the case when dim=spacedim the previous formula reduces to
1126 * @f[
1127 * \mathbf T(\mathbf x) = \hat{\mathbf u}(\hat{\mathbf x})
1128 * J(\hat{\mathbf x})^{-1}.
1129 * @f]
1130 * </ul>
1131 *
1132 * @note It would have been more reasonable to make this transform a
1133 * template function with the rank in <code>DerivativeForm@<1, dim,
1134 * rank@></code>. Unfortunately C++ does not allow templatized virtual
1135 * functions. This is why we identify <code>DerivativeForm@<1, dim,
1136 * 1@></code> with a <code>Tensor@<1,dim@></code> when using
1137 * mapping_covariant() in the function transform() above this one.
1138 *
1139 * @param[in] input An array (or part of an array) of input objects that
1140 * should be mapped.
1141 * @param[in] kind The kind of mapping to be applied.
1142 * @param[in] internal A pointer to an object of type
1143 * Mapping::InternalDataBase that contains information previously stored by
1144 * the mapping. The object pointed to was created by the get_data(),
1145 * get_face_data(), or get_subface_data() function, and will have been
1146 * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
1147 * fill_fe_subface_values() for the current cell, before calling the current
1148 * function. In other words, this object also represents with respect to
1149 * which cell the transformation should be applied to.
1150 * @param[out] output An array (or part of an array) into which the
1151 * transformed objects should be placed. (Note that the array view is @p
1152 * const, but the tensors it points to are not.)
1153 */
1154 virtual void
1155 transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
1156 const MappingKind kind,
1157 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
1158 const ArrayView<Tensor<2, spacedim>> &output) const = 0;
1159
1160 /**
1161 * Transform a tensor field from the reference cell to the physical cell.
1162 * These tensors are usually the Jacobians in the reference cell of vector
1163 * fields that have been pulled back from the physical cell. The mapping
1164 * kinds currently implemented by derived classes are:
1165 * <ul>
1166 * <li> @p mapping_contravariant_gradient: it assumes $\mathbf u(\mathbf x)
1167 * = J \hat{\mathbf u}$ so that
1168 * @f[
1169 * \mathbf T(\mathbf x) =
1170 * J(\hat{\mathbf x}) \hat{\mathbf T}(\hat{\mathbf x})
1171 * J(\hat{\mathbf x})^{-1}.
1172 * @f]
1173 * <li> @p mapping_covariant_gradient: it assumes $\mathbf u(\mathbf x) =
1174 * J^{-T} \hat{\mathbf u}$ so that
1175 * @f[
1176 * \mathbf T(\mathbf x) =
1177 * J(\hat{\mathbf x})^{-T} \hat{\mathbf T}(\hat{\mathbf x})
1178 * J(\hat{\mathbf x})^{-1}.
1179 * @f]
1180 * <li> @p mapping_piola_gradient: it assumes $\mathbf u(\mathbf x) =
1181 * \frac{1}{\text{det}\;J(\hat{\mathbf x})} J(\hat{\mathbf x}) \hat{\mathbf
1182 * u}(\hat{\mathbf x})$ so that
1183 * @f[
1184 * \mathbf T(\mathbf x) =
1185 * \frac{1}{\text{det}\;J(\hat{\mathbf x})}
1186 * J(\hat{\mathbf x}) \hat{\mathbf T}(\hat{\mathbf x})
1187 * J(\hat{\mathbf x})^{-1}.
1188 * @f]
1189 * </ul>
1190 *
1191 * @todo The formulas for mapping_covariant_gradient,
1192 * mapping_contravariant_gradient and mapping_piola_gradient are only true
1193 * as stated for linear mappings. If, for example, the mapping is bilinear
1194 * (or has a higher order polynomial degree) then there is a missing term
1195 * associated with the derivative of $J$.
1196 *
1197 * @param[in] input An array (or part of an array) of input objects that
1198 * should be mapped.
1199 * @param[in] kind The kind of mapping to be applied.
1200 * @param[in] internal A pointer to an object of type
1201 * Mapping::InternalDataBase that contains information previously stored by
1202 * the mapping. The object pointed to was created by the get_data(),
1203 * get_face_data(), or get_subface_data() function, and will have been
1204 * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
1205 * fill_fe_subface_values() for the current cell, before calling the current
1206 * function. In other words, this object also represents with respect to
1207 * which cell the transformation should be applied to.
1208 * @param[out] output An array (or part of an array) into which the
1209 * transformed objects should be placed. (Note that the array view is @p
1210 * const, but the tensors it points to are not.)
1211 */
1212 virtual void
1213 transform(const ArrayView<const Tensor<2, dim>> &input,
1214 const MappingKind kind,
1215 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
1216 const ArrayView<Tensor<2, spacedim>> &output) const = 0;
1217
1218 /**
1219 * Transform a tensor field from the reference cell to the physical cell.
1220 * This tensors are most of times the hessians in the reference cell of
1221 * vector fields that have been pulled back from the physical cell.
1222 *
1223 * The mapping kinds currently implemented by derived classes are:
1224 * <ul>
1225 * <li> @p mapping_covariant_gradient: maps a field of forms on the
1226 * reference cell to a field of forms on the physical cell. Mathematically,
1227 * it is the pull back of the differential form
1228 * @f[
1229 * \mathbf T_{ijk}(\mathbf x) = \hat{\mathbf T}_{iJK}(\hat{\mathbf x})
1230 * J_{jJ}^{\dagger} J_{kK}^{\dagger}@f],
1231 *
1232 * where @f[ J^{\dagger} = J(\hat{\mathbf x})(J(\hat{\mathbf x})^{T}
1233 * J(\hat{\mathbf x}))^{-1}.
1234 * @f]
1235 * </ul>
1236 *
1237 * Hessians of spacedim-vector valued differentiable functions are
1238 * transformed this way (After subtraction of the product of the derivative
1239 * with the Jacobian gradient).
1240 *
1241 * In the case when dim=spacedim the previous formula reduces to
1242 * @f[J^{\dagger} = J^{-1}@f]
1243 *
1244 * @param[in] input An array (or part of an array) of input objects that
1245 * should be mapped.
1246 * @param[in] kind The kind of mapping to be applied.
1247 * @param[in] internal A pointer to an object of type
1248 * Mapping::InternalDataBase that contains information previously stored by
1249 * the mapping. The object pointed to was created by the get_data(),
1250 * get_face_data(), or get_subface_data() function, and will have been
1251 * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
1252 * fill_fe_subface_values() for the current cell, before calling the current
1253 * function. In other words, this object also represents with respect to
1254 * which cell the transformation should be applied to.
1255 * @param[out] output An array (or part of an array) into which the
1256 * transformed objects should be placed. (Note that the array view is @p
1257 * const, but the tensors it points to are not.)
1258 */
1259 virtual void
1260 transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
1261 const MappingKind kind,
1262 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
1263 const ArrayView<Tensor<3, spacedim>> &output) const = 0;
1264
1265 /**
1266 * Transform a field of 3-differential forms from the reference cell to the
1267 * physical cell. It is useful to think of $\mathbf{T}_{ijk} = D^2_{jk}
1268 * \mathbf u_i$ and $\mathbf{\hat T}_{IJK} = \hat D^2_{JK} \mathbf{\hat
1269 * u}_I$, with $\mathbf u_i$ a vector field.
1270 *
1271 * The mapping kinds currently implemented by derived classes are:
1272 * <ul>
1273 * <li> @p mapping_contravariant_hessian: it assumes $\mathbf u_i(\mathbf x)
1274 * = J_{iI} \hat{\mathbf u}_I$ so that
1275 * @f[
1276 * \mathbf T_{ijk}(\mathbf x) =
1277 * J_{iI}(\hat{\mathbf x}) \hat{\mathbf T}_{IJK}(\hat{\mathbf x})
1278 * J_{jJ}(\hat{\mathbf x})^{-1} J_{kK}(\hat{\mathbf x})^{-1}.
1279 * @f]
1280 * <li> @p mapping_covariant_hessian: it assumes $\mathbf u_i(\mathbf x) =
1281 * J_{iI}^{-T} \hat{\mathbf u}_I$ so that
1282 * @f[
1283 * \mathbf T_{ijk}(\mathbf x) =
1284 * J_iI(\hat{\mathbf x})^{-1} \hat{\mathbf T}_{IJK}(\hat{\mathbf x})
1285 * J_{jJ}(\hat{\mathbf x})^{-1} J_{kK}(\hat{\mathbf x})^{-1}.
1286 * @f]
1287 * <li> @p mapping_piola_hessian: it assumes $\mathbf u_i(\mathbf x) =
1288 * \frac{1}{\text{det}\;J(\hat{\mathbf x})} J_{iI}(\hat{\mathbf x})
1289 * \hat{\mathbf u}(\hat{\mathbf x})$ so that
1290 * @f[
1291 * \mathbf T_{ijk}(\mathbf x) =
1292 * \frac{1}{\text{det}\;J(\hat{\mathbf x})}
1293 * J_{iI}(\hat{\mathbf x}) \hat{\mathbf T}_{IJK}(\hat{\mathbf x})
1294 * J_{jJ}(\hat{\mathbf x})^{-1} J_{kK}(\hat{\mathbf x})^{-1}.
1295 * @f]
1296 * </ul>
1297 *
1298 * @param[in] input An array (or part of an array) of input objects that
1299 * should be mapped.
1300 * @param[in] kind The kind of mapping to be applied.
1301 * @param[in] internal A pointer to an object of type
1302 * Mapping::InternalDataBase that contains information previously stored by
1303 * the mapping. The object pointed to was created by the get_data(),
1304 * get_face_data(), or get_subface_data() function, and will have been
1305 * updated as part of a call to fill_fe_values(), fill_fe_face_values(), or
1306 * fill_fe_subface_values() for the current cell, before calling the current
1307 * function. In other words, this object also represents with respect to
1308 * which cell the transformation should be applied to.
1309 * @param[out] output An array (or part of an array) into which the
1310 * transformed objects should be placed.
1311 */
1312 virtual void
1313 transform(const ArrayView<const Tensor<3, dim>> &input,
1314 const MappingKind kind,
1315 const typename Mapping<dim, spacedim>::InternalDataBase &internal,
1316 const ArrayView<Tensor<3, spacedim>> &output) const = 0;
1317
1318 /**
1319 * @}
1320 */
1321
1322
1323 // Give class @p FEValues access to the private <tt>get_...data</tt> and
1324 // <tt>fill_fe_...values</tt> functions.
1325 friend class FEValuesBase<dim, spacedim>;
1326 friend class FEValues<dim, spacedim>;
1327 friend class FEFaceValues<dim, spacedim>;
1328 friend class FESubfaceValues<dim, spacedim>;
1329 friend class NonMatching::FEImmersedSurfaceValues<dim>;
1330 friend class NonMatching::internal::ComputeMappingDataHelper<dim, spacedim>;
1331 template <int, int, typename>
1332 friend class NonMatching::MappingInfo;
1333 };
1334
1335
1336 /**
1337 * Return a default linear mapping that works for the given triangulation.
1338 * Internally, this function calls the function above for the reference
1339 * cell used by the given triangulation, assuming that the triangulation
1340 * uses only a single cell type. If the triangulation uses mixed cell
1341 * types, then this function will trigger an exception.
1342 */
1343 template <int dim, int spacedim>
1344 const Mapping<dim, spacedim> &
1345 get_default_linear_mapping(const Triangulation<dim, spacedim> &triangulation);
1346
1347
1348 DEAL_II_NAMESPACE_CLOSE
1349
1350 #endif