| 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 |