| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2000 - 2025 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_fe_tools_H |
| 16 |
#define dealii_fe_tools_H |
| 17 |
|
| 18 |
|
| 19 |
|
| 20 |
#include <deal.II/base/config.h> |
| 21 |
|
| 22 |
#include <deal.II/base/enable_observer_pointer.h> |
| 23 |
#include <deal.II/base/exceptions.h> |
| 24 |
#include <deal.II/base/geometry_info.h> |
| 25 |
#include <deal.II/base/symmetric_tensor.h> |
| 26 |
#include <deal.II/base/tensor.h> |
| 27 |
|
| 28 |
#include <deal.II/distributed/tria.h> |
| 29 |
|
| 30 |
#include <deal.II/fe/component_mask.h> |
| 31 |
|
| 32 |
#include <deal.II/lac/la_parallel_vector.h> |
| 33 |
|
| 34 |
#include <memory> |
| 35 |
#include <string> |
| 36 |
#include <vector> |
| 37 |
|
| 38 |
|
| 39 |
DEAL_II_NAMESPACE_OPEN |
| 40 |
|
| 41 |
// Forward declarations |
| 42 |
#ifndef DOXYGEN |
| 43 |
template <typename number> |
| 44 |
class FullMatrix; |
| 45 |
template <int dim> |
| 46 |
class Quadrature; |
| 47 |
template <int dim, int spacedim> |
| 48 |
class FiniteElement; |
| 49 |
template <int dim, int spacedim> |
| 50 |
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>)) |
| 51 |
class DoFHandler; |
| 52 |
template <int dim> |
| 53 |
class FiniteElementData; |
| 54 |
template <typename number> |
| 55 |
class AffineConstraints; |
| 56 |
#endif |
| 57 |
|
| 58 |
|
| 59 |
/** |
| 60 |
* @addtogroup feall |
| 61 |
* @{ |
| 62 |
*/ |
| 63 |
|
| 64 |
|
| 65 |
/** |
| 66 |
* This namespace offers interpolations and extrapolations of discrete |
| 67 |
* functions of one @p FiniteElement @p fe1 to another @p FiniteElement @p |
| 68 |
* fe2. |
| 69 |
* |
| 70 |
* It also provides the local interpolation matrices that interpolate on each |
| 71 |
* cell. Furthermore it provides the difference matrix $id-I_h$ that is needed |
| 72 |
* for evaluating $(id-I_h)z$ for e.g. the dual solution $z$. |
| 73 |
* |
| 74 |
* For more information about the <tt>spacedim</tt> template parameter check |
| 75 |
* the documentation of FiniteElement or the one of Triangulation. |
| 76 |
*/ |
| 77 |
namespace FETools |
| 78 |
{ |
| 79 |
/** |
| 80 |
* A base class for factory objects creating finite elements of a given |
| 81 |
* degree. Derived classes are called whenever one wants to have a |
| 82 |
* transparent way to create a finite element object. |
| 83 |
* |
| 84 |
* This class is used in the FETools::get_fe_by_name() and |
| 85 |
* FETools::add_fe_name() functions. |
| 86 |
*/ |
| 87 |
template <int dim, int spacedim = dim> |
| 88 |
class FEFactoryBase : public EnableObserverPointer |
| 89 |
{ |
| 90 |
public: |
| 91 |
/** |
| 92 |
* Create a FiniteElement and return a pointer to it. |
| 93 |
*/ |
| 94 |
virtual std::unique_ptr<FiniteElement<dim, spacedim>> |
| 95 |
get(const unsigned int degree) const = 0; |
| 96 |
|
| 97 |
/** |
| 98 |
* Create a FiniteElement from a quadrature formula (currently only |
| 99 |
* implemented for FE_Q) and return a pointer to it. |
| 100 |
*/ |
| 101 |
|
| 102 |
virtual std::unique_ptr<FiniteElement<dim, spacedim>> |
| 103 |
get(const Quadrature<1> &quad) const = 0; |
| 104 |
|
| 105 |
/** |
| 106 |
* Virtual destructor doing nothing but making the compiler happy. |
| 107 |
*/ |
| 108 |
virtual ~FEFactoryBase() override = default; |
| 109 |
}; |
| 110 |
|
| 111 |
/** |
| 112 |
* A concrete class for factory objects creating finite elements of a given |
| 113 |
* degree. |
| 114 |
* |
| 115 |
* The class's get() function generates a finite element object of the type |
| 116 |
* given as template argument, and with the degree (however the finite |
| 117 |
* element class wishes to interpret this number) given as argument to |
| 118 |
* get(). |
| 119 |
*/ |
| 120 |
template <class FE> |
| 121 |
class FEFactory : public FEFactoryBase<FE::dimension, FE::space_dimension> |
| 122 |
{ |
| 123 |
public: |
| 124 |
/** |
| 125 |
* Create a FiniteElement and return a pointer to it. |
| 126 |
*/ |
| 127 |
virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>> |
| 128 |
get(const unsigned int degree) const override; |
| 129 |
|
| 130 |
/** |
| 131 |
* Create a FiniteElement from a quadrature formula (currently only |
| 132 |
* implemented for FE_Q) and return a pointer to it. |
| 133 |
*/ |
| 134 |
virtual std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>> |
| 135 |
get(const Quadrature<1> &quad) const override; |
| 136 |
}; |
| 137 |
|
| 138 |
/** |
| 139 |
* @warning In most cases, you will probably want to use |
| 140 |
* compute_base_renumbering(). |
| 141 |
* |
| 142 |
* Compute the vector required to renumber the dofs of a cell by component. |
| 143 |
* Furthermore, compute the vector storing the start indices of each |
| 144 |
* component in the local block vector. |
| 145 |
* |
| 146 |
* The second vector is organized such that there is a vector for each base |
| 147 |
* element containing the start index for each component served by this base |
| 148 |
* element. |
| 149 |
* |
| 150 |
* While the first vector is checked to have the correct size, the second |
| 151 |
* one is reinitialized for convenience. |
| 152 |
*/ |
| 153 |
template <int dim, int spacedim> |
| 154 |
void |
| 155 |
compute_component_wise(const FiniteElement<dim, spacedim> &fe, |
| 156 |
std::vector<unsigned int> &renumbering, |
| 157 |
std::vector<std::vector<unsigned int>> &start_indices); |
| 158 |
|
| 159 |
/** |
| 160 |
* Compute the vector required to renumber the dofs of a cell by block. |
| 161 |
* Furthermore, compute the vector storing either the start indices or the |
| 162 |
* size of each local block vector. |
| 163 |
* |
| 164 |
* If the @p bool parameter is true, @p block_data is filled with the start |
| 165 |
* indices of each local block. If it is false, then the block sizes are |
| 166 |
* returned. |
| 167 |
* |
| 168 |
* The vector <tt>renumbering</tt> will be indexed by the standard numbering |
| 169 |
* of local degrees of freedom, namely the first vertex, then the second |
| 170 |
* vertex, after vertices lines, quads, and hexes. For each index, the entry |
| 171 |
* indicates the index which this degree of freedom receives in a numbering |
| 172 |
* scheme, where the first block is numbered completely before the second. |
| 173 |
*/ |
| 174 |
template <int dim, int spacedim> |
| 175 |
void |
| 176 |
compute_block_renumbering(const FiniteElement<dim, spacedim> &fe, |
| 177 |
std::vector<types::global_dof_index> &renumbering, |
| 178 |
std::vector<types::global_dof_index> &block_data, |
| 179 |
bool return_start_indices = true); |
| 180 |
|
| 181 |
/** |
| 182 |
* @name Generation of local matrices |
| 183 |
* @{ |
| 184 |
*/ |
| 185 |
/** |
| 186 |
* Compute the interpolation matrix that interpolates a @p fe1-function to a |
| 187 |
* @p fe2-function on each cell. The interpolation_matrix needs to be of |
| 188 |
* size <tt>(fe2.n_dofs_per_cell(), fe1.n_dofs_per_cell())</tt>. |
| 189 |
* |
| 190 |
* Note, that if the finite element space @p fe1 is a subset of the finite |
| 191 |
* element space @p fe2 then the @p interpolation_matrix is an embedding |
| 192 |
* matrix. |
| 193 |
*/ |
| 194 |
template <int dim, typename number, int spacedim> |
| 195 |
void |
| 196 |
get_interpolation_matrix(const FiniteElement<dim, spacedim> &fe1, |
| 197 |
const FiniteElement<dim, spacedim> &fe2, |
| 198 |
FullMatrix<number> &interpolation_matrix); |
| 199 |
|
| 200 |
/** |
| 201 |
* Compute the interpolation matrix that interpolates a @p fe1-function to a |
| 202 |
* @p fe2-function, and interpolates this to a second @p fe1-function on |
| 203 |
* each cell. The interpolation_matrix needs to be of size |
| 204 |
* <tt>(fe1.n_dofs_per_cell(), fe1.n_dofs_per_cell())</tt>. |
| 205 |
* |
| 206 |
* Note, that this function only makes sense if the finite element space due |
| 207 |
* to @p fe1 is not a subset of the finite element space due to @p fe2, as |
| 208 |
* if it were a subset then the @p interpolation_matrix would be only the |
| 209 |
* unit matrix. |
| 210 |
*/ |
| 211 |
template <int dim, typename number, int spacedim> |
| 212 |
void |
| 213 |
get_back_interpolation_matrix(const FiniteElement<dim, spacedim> &fe1, |
| 214 |
const FiniteElement<dim, spacedim> &fe2, |
| 215 |
FullMatrix<number> &interpolation_matrix); |
| 216 |
|
| 217 |
/** |
| 218 |
* Compute the identity matrix minus the back interpolation matrix. |
| 219 |
* The @p difference_matrix will be of size <tt>(fe1.n_dofs_per_cell(), |
| 220 |
* fe1.n_dofs_per_cell())</tt> after this function. Previous content |
| 221 |
* of the argument will be overwritten. |
| 222 |
* |
| 223 |
* This function computes the matrix that transforms a @p fe1 function $z$ to |
| 224 |
* $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1 |
| 225 |
* space to the @p fe2 space. This matrix hence is useful to evaluate |
| 226 |
* error-representations where $z$ denotes the dual solution. |
| 227 |
*/ |
| 228 |
template <int dim, typename number, int spacedim> |
| 229 |
void |
| 230 |
get_interpolation_difference_matrix(const FiniteElement<dim, spacedim> &fe1, |
| 231 |
const FiniteElement<dim, spacedim> &fe2, |
| 232 |
FullMatrix<number> &difference_matrix); |
| 233 |
|
| 234 |
/** |
| 235 |
* Compute the local $L^2$-projection matrix from fe1 to fe2. |
| 236 |
*/ |
| 237 |
template <int dim, typename number, int spacedim> |
| 238 |
void |
| 239 |
get_projection_matrix(const FiniteElement<dim, spacedim> &fe1, |
| 240 |
const FiniteElement<dim, spacedim> &fe2, |
| 241 |
FullMatrix<number> &matrix); |
| 242 |
|
| 243 |
/** |
| 244 |
* This is a rather specialized function used during the construction of |
| 245 |
* finite element objects. It is used to build the basis of shape functions |
| 246 |
* for an element, given a set of polynomials and interpolation points. The |
| 247 |
* function is only implemented for finite elements with exactly @p dim |
| 248 |
* vector components. In particular, this applies to classes derived from |
| 249 |
* the FE_PolyTensor class. |
| 250 |
* |
| 251 |
* Specifically, the purpose of this function is as follows: FE_PolyTensor |
| 252 |
* receives, from its derived classes, an argument that describes a polynomial |
| 253 |
* space. This space may be parameterized in terms of monomials, or in some |
| 254 |
* other way, but is in general not in the form that we use for finite |
| 255 |
* elements where we typically want to use a basis that is derived from |
| 256 |
* some kind of node functional (e.g., the interpolation at specific points). |
| 257 |
* Concretely, assume that the basis used by the polynomial space is |
| 258 |
* $\{\tilde\varphi_j(\mathbf x)\}_{j=1}^N$, and that the node functionals |
| 259 |
* of the finite element are $\{\Psi_i\}_{i=1}^N$. We then want to compute a |
| 260 |
* basis $\{\varphi_j(\mathbf x)\}_{j=1}^N$ for the finite element space so |
| 261 |
* that $\Psi_i[\varphi_j] = \delta_{ij}$. To do this, we can set |
| 262 |
* $\varphi_j(\mathbf x) = \sum_{k=1}^N c_{jk} \tilde\varphi_k(\mathbf x)$ |
| 263 |
* where we need to determine the expansion coefficients $c_{jk}$. We do this |
| 264 |
* by applying $\Psi_i$ to both sides of the equation, to obtain |
| 265 |
* @f{align*}{ |
| 266 |
* \Psi_i [\varphi_j] = \sum_{k=1}^N c_{jk} \Psi_i[\tilde\varphi_k], |
| 267 |
* @f} |
| 268 |
* and we know that the left hand side equals $\delta_{ij}$. |
| 269 |
* If you think of this as a system of $N\times N$ equations for the |
| 270 |
* elements of a matrix on the left and on the right, then this can be |
| 271 |
* written as |
| 272 |
* @f{align*}{ |
| 273 |
* I = C X^T |
| 274 |
* @f} |
| 275 |
* where $C$ is the matrix of coefficients $c_{jk}$ and |
| 276 |
* $X_{ik} = \Psi_i[\tilde\varphi_k]$. Consequently, in order to compute |
| 277 |
* the expansion coefficients $C=X^{-T}$, we need to apply the node |
| 278 |
* functionals to all functions of the "raw" basis of the polynomial space. |
| 279 |
* |
| 280 |
* Until the finite element receives this matrix $X$ back, it describes its |
| 281 |
* shape functions (e.g., in FiniteElement::shape_value()) in the form |
| 282 |
* $\tilde\varphi_j$. After it calls this function, it has the expansion |
| 283 |
* coefficients and can describe its shape functions as $\varphi_j$. |
| 284 |
* |
| 285 |
* This function therefore computes this matrix $X$, for the following |
| 286 |
* specific circumstances: |
| 287 |
* - That the node functionals $\Psi_i$ are point evaluations at points |
| 288 |
* $\mathbf x_i$ that the finite element in question describes via its |
| 289 |
* "generalized" support points (through |
| 290 |
* FiniteElement::get_generalized_support_points(), see also |
| 291 |
* @ref GlossGeneralizedSupport "this glossary entry"). These point |
| 292 |
* evaluations need to necessarily evaluate the <i>value</i> of a shape |
| 293 |
* function at that point (the shape function may be vector-valued, and |
| 294 |
* so the functional may be a linear combination of the individual |
| 295 |
* components of the values); but, in particular, the nodal functions may |
| 296 |
* not be <i>integrals</i> over entire edges or faces, |
| 297 |
* or other non-local functionals. In other words, we assume that |
| 298 |
* $\Psi_i[\tilde\varphi_j] = f_j(\tilde\varphi_j(\mathbf x_i))$ |
| 299 |
* where $f_j$ is a function of the (possibly vector-valued) argument |
| 300 |
* that returns a scalar. |
| 301 |
* - That the finite element has exactly @p dim vector components. |
| 302 |
* - That the function $f_j$ is given by whatever the element implements |
| 303 |
* through the |
| 304 |
* FiniteElement::convert_generalized_support_point_values_to_dof_values() |
| 305 |
* function. |
| 306 |
* |
| 307 |
* @param fe The finite element for which the operations above are to be |
| 308 |
* performed. |
| 309 |
* @return The matrix $X$ as discussed above. |
| 310 |
*/ |
| 311 |
template <int dim, int spacedim> |
| 312 |
FullMatrix<double> |
| 313 |
compute_node_matrix(const FiniteElement<dim, spacedim> &fe); |
| 314 |
|
| 315 |
/** |
| 316 |
* For all possible (isotropic and anisotropic) refinement cases compute the |
| 317 |
* embedding matrices from a coarse cell to the child cells. Each column of |
| 318 |
* the resulting matrices contains the representation of a coarse grid basis |
| 319 |
* function by the fine grid basis; the matrices are split such that there |
| 320 |
* is one matrix for every child. |
| 321 |
* |
| 322 |
* This function computes the coarse grid function in a sufficiently large |
| 323 |
* number of quadrature points and fits the fine grid functions using least |
| 324 |
* squares approximation. Therefore, the use of this function is restricted |
| 325 |
* to the case that the finite element spaces are actually nested. |
| 326 |
* |
| 327 |
* Note, that <code>matrices[refinement_case-1][child]</code> includes the |
| 328 |
* embedding (or prolongation) matrix of child <code>child</code> for the |
| 329 |
* RefinementCase <code>refinement_case</code>. Here, we use |
| 330 |
* <code>refinement_case-1</code> instead of <code>refinement_case</code> as |
| 331 |
* for RefinementCase::no_refinement(=0) there are no prolongation matrices |
| 332 |
* available. |
| 333 |
* |
| 334 |
* Typically this function is called by the various implementations of |
| 335 |
* FiniteElement classes in order to fill the respective |
| 336 |
* FiniteElement::prolongation matrices. |
| 337 |
* |
| 338 |
* @param fe The finite element class for which we compute the embedding |
| 339 |
* matrices. |
| 340 |
* |
| 341 |
* @param matrices A reference to RefinementCase<dim>::isotropic_refinement |
| 342 |
* vectors of FullMatrix objects. Each vector corresponds to one |
| 343 |
* RefinementCase @p refinement_case and is of the vector size |
| 344 |
* GeometryInfo<dim>::n_children(refinement_case). This is the format used |
| 345 |
* in FiniteElement, where we want to use this function mostly. |
| 346 |
* |
| 347 |
* @param isotropic_only Set to <code>true</code> if you only want to |
| 348 |
* compute matrices for isotropic refinement. |
| 349 |
* |
| 350 |
* @param threshold is the gap allowed in the least squares algorithm |
| 351 |
* computing the embedding. |
| 352 |
*/ |
| 353 |
template <int dim, typename number, int spacedim> |
| 354 |
void |
| 355 |
compute_embedding_matrices( |
| 356 |
const FiniteElement<dim, spacedim> &fe, |
| 357 |
std::vector<std::vector<FullMatrix<number>>> &matrices, |
| 358 |
const bool isotropic_only = false, |
| 359 |
const double threshold = 1.e-12); |
| 360 |
|
| 361 |
/** |
| 362 |
* Compute the embedding matrices on faces needed for constraint matrices. |
| 363 |
* |
| 364 |
* @param fe The finite element for which to compute these matrices. |
| 365 |
* |
| 366 |
* @param matrices An array of <i>GeometryInfo<dim>::subfaces_per_face = |
| 367 |
* 2<sup>dim-1</sup></i> FullMatrix objects, holding the embedding matrix for |
| 368 |
* each subface. |
| 369 |
* |
| 370 |
* @param face_coarse The number of the face on the coarse side of the face |
| 371 |
* for which this is computed. |
| 372 |
* |
| 373 |
* @param face_fine The number of the face on the refined side of the face |
| 374 |
* for which this is computed. |
| 375 |
* |
| 376 |
* @param threshold is the gap allowed in the least squares algorithm |
| 377 |
* computing the embedding. |
| 378 |
* |
| 379 |
* @warning This function will be used in computing constraint matrices. It |
| 380 |
* is not sufficiently tested yet. |
| 381 |
*/ |
| 382 |
template <int dim, typename number, int spacedim> |
| 383 |
void |
| 384 |
compute_face_embedding_matrices(const FiniteElement<dim, spacedim> &fe, |
| 385 |
const ArrayView<FullMatrix<number>> &matrices, |
| 386 |
const unsigned int face_coarse, |
| 387 |
const unsigned int face_fine, |
| 388 |
const double threshold = 1.e-12); |
| 389 |
|
| 390 |
/** |
| 391 |
* For all possible (isotropic and anisotropic) refinement cases compute the |
| 392 |
* <i>L<sup>2</sup></i>-projection matrices from the children to a coarse |
| 393 |
* cell. |
| 394 |
* |
| 395 |
* Note, that <code>matrices[refinement_case-1][child]</code> includes the |
| 396 |
* projection (or restriction) matrix of child <code>child</code> for the |
| 397 |
* RefinementCase <code>refinement_case</code>. Here, we use |
| 398 |
* <code>refinement_case-1</code> instead of <code>refinement_case</code> as |
| 399 |
* for RefinementCase::no_refinement(=0) there are no projection matrices |
| 400 |
* available. |
| 401 |
* |
| 402 |
* Typically this function is called by the various implementations of |
| 403 |
* FiniteElement classes in order to fill the respective |
| 404 |
* FiniteElement::restriction matrices. |
| 405 |
* |
| 406 |
* @arg[in] fe The finite element class for which we compute the projection |
| 407 |
* matrices. |
| 408 |
* |
| 409 |
* @arg[out] matrices A reference to a set of |
| 410 |
* <tt>RefinementCase<dim>::isotropic_refinement</tt> vectors of FullMatrix |
| 411 |
* objects. Each vector corresponds to one RefinementCase @p refinement_case |
| 412 |
* and is of the vector size |
| 413 |
* <tt>GeometryInfo<dim>::n_children(refinement_case)</tt>. This is the |
| 414 |
* format used in FiniteElement, where we want to use this function mostly. |
| 415 |
* |
| 416 |
* @arg[in] isotropic_only If set to <code>true</code>, then this |
| 417 |
* function only computes data for the isotropic refinement case. The |
| 418 |
* other elements of the output vector are left untouched (but still |
| 419 |
* exist). |
| 420 |
*/ |
| 421 |
template <int dim, typename number, int spacedim> |
| 422 |
void |
| 423 |
compute_projection_matrices( |
| 424 |
const FiniteElement<dim, spacedim> &fe, |
| 425 |
std::vector<std::vector<FullMatrix<number>>> &matrices, |
| 426 |
const bool isotropic_only = false); |
| 427 |
|
| 428 |
/** |
| 429 |
* Project scalar data defined in quadrature points to a finite element |
| 430 |
* space on a single cell. |
| 431 |
* |
| 432 |
* What this function does is the following: assume that there is scalar |
| 433 |
* data <tt>u<sub>q</sub>, 0 <= q < Q:=quadrature.size()</tt> defined at the |
| 434 |
* quadrature points of a cell, with the points defined by the given |
| 435 |
* <tt>rhs_quadrature</tt> object. We may then want to ask for that finite |
| 436 |
* element function (on a single cell) <tt>v<sub>h</sub></tt> in the |
| 437 |
* finite-dimensional space defined by the given FE object that is the |
| 438 |
* projection of <tt>u</tt> in the following sense: |
| 439 |
* |
| 440 |
* Usually, the projection <tt>v<sub>h</sub></tt> is that function that |
| 441 |
* satisfies <tt>(v<sub>h</sub>,w)=(u,w)</tt> for all discrete test |
| 442 |
* functions <tt>w</tt>. In the present case, we can't evaluate the right |
| 443 |
* hand side, since <tt>u</tt> is only defined in the quadrature points |
| 444 |
* given by <tt>rhs_quadrature</tt>, so we replace it by a quadrature |
| 445 |
* approximation. Likewise, the left hand side is approximated using the |
| 446 |
* <tt>lhs_quadrature</tt> object; if this quadrature object is chosen |
| 447 |
* appropriately, then the integration of the left hand side can be done |
| 448 |
* exactly, without any approximation. The use of different quadrature |
| 449 |
* objects is necessary if the quadrature object for the right hand side has |
| 450 |
* too few quadrature points -- for example, if data <tt>q</tt> is only |
| 451 |
* defined at the cell center, then the corresponding one-point quadrature |
| 452 |
* formula is obviously insufficient to approximate the scalar product on |
| 453 |
* the left hand side by a definite form. |
| 454 |
* |
| 455 |
* After these quadrature approximations, we end up with a nodal |
| 456 |
* representation <tt>V<sub>h</sub></tt> of <tt>v<sub>h</sub></tt> that |
| 457 |
* satisfies the following system of linear equations: <tt>M V<sub>h</sub> = |
| 458 |
* Q U</tt>, where <tt>M<sub>ij</sub>=(phi_i,phi_j)</tt> is the @ref GlossMassMatrix "mass matrix" |
| 459 |
* approximated by <tt>lhs_quadrature</tt>, and <tt>Q</tt> is the matrix |
| 460 |
* <tt>Q<sub>iq</sub>=phi<sub>i</sub>(x<sub>q</sub>) w<sub>q</sub></tt> |
| 461 |
* where <tt>w<sub>q</sub></tt> are quadrature weights; <tt>U</tt> is the |
| 462 |
* vector of quadrature point data <tt>u<sub>q</sub></tt>. |
| 463 |
* |
| 464 |
* In order to then get the nodal representation <tt>V<sub>h</sub></tt> of |
| 465 |
* the projection of <tt>U</tt>, one computes <tt>V<sub>h</sub> = X U, |
| 466 |
* X=M<sup>-1</sup> Q</tt>. The purpose of this function is to compute the |
| 467 |
* matrix <tt>X</tt> and return it through the last argument of this |
| 468 |
* function. |
| 469 |
* |
| 470 |
* Note that this function presently only supports scalar data. An extension |
| 471 |
* of the mass matrix is of course trivial, but one has to define the order |
| 472 |
* of data in the vector <tt>U</tt> if it contains vector valued data in all |
| 473 |
* quadrature points. |
| 474 |
* |
| 475 |
* A use for this function is described in the introduction to the step-18 |
| 476 |
* example program. |
| 477 |
* |
| 478 |
* The opposite of this function, interpolation of a finite element function |
| 479 |
* onto quadrature points is essentially what the |
| 480 |
* <tt>FEValues::get_function_values</tt> functions do; to make things a |
| 481 |
* little simpler, the |
| 482 |
* <tt>FETools::compute_interpolation_to_quadrature_points_matrix</tt> |
| 483 |
* provides the matrix form of this. |
| 484 |
* |
| 485 |
* Note that this function works on a single cell, rather than an entire |
| 486 |
* triangulation. In effect, it therefore doesn't matter if you use a |
| 487 |
* continuous or discontinuous version of the finite element. |
| 488 |
* |
| 489 |
* It is worth noting that there are a few confusing cases of this function. |
| 490 |
* The first one is that it really only makes sense to project onto a finite |
| 491 |
* element that has at most as many degrees of freedom per cell as there are |
| 492 |
* quadrature points; the projection of N quadrature point data into a space |
| 493 |
* with M>N unknowns is well-defined, but often yields funny and |
| 494 |
* non-intuitive results. Secondly, one would think that if the quadrature |
| 495 |
* point data is defined in the support points of the finite element, i.e. the |
| 496 |
* quadrature points of <tt>rhs_quadrature</tt> equal |
| 497 |
* <tt>fe.get_unit_support_points()</tt>, then the projection should be the |
| 498 |
* identity, i.e. each degree of freedom of the finite element equals the |
| 499 |
* value of the given data in the support point of the corresponding shape |
| 500 |
* function. However, this is not generally the case: while the matrix |
| 501 |
* <tt>Q</tt> in that case is the identity matrix, the mass matrix |
| 502 |
* <tt>M</tt> is not equal to the identity matrix, except for the special |
| 503 |
* case that the quadrature formula <tt>lhs_quadrature</tt> also has its |
| 504 |
* quadrature points in the support points of the finite element. |
| 505 |
* |
| 506 |
* Finally, this function only defines a cell wise projection, while one |
| 507 |
* frequently wants to apply it to all cells in a triangulation. However, if |
| 508 |
* it is applied to one cell after the other, the results from later cells |
| 509 |
* may overwrite nodal values computed already from previous cells if |
| 510 |
* degrees of freedom live on the interfaces between cells. The function is |
| 511 |
* therefore most useful for discontinuous elements. |
| 512 |
*/ |
| 513 |
template <int dim, int spacedim> |
| 514 |
void |
| 515 |
compute_projection_from_quadrature_points_matrix( |
| 516 |
const FiniteElement<dim, spacedim> &fe, |
| 517 |
const Quadrature<dim> &lhs_quadrature, |
| 518 |
const Quadrature<dim> &rhs_quadrature, |
| 519 |
FullMatrix<double> &X); |
| 520 |
|
| 521 |
/** |
| 522 |
* Given a (scalar) local finite element function, compute the matrix that |
| 523 |
* maps the vector of nodal values onto the vector of values of this |
| 524 |
* function at quadrature points as given by the second argument. In a |
| 525 |
* sense, this function does the opposite of the |
| 526 |
* FETools::compute_projection_from_quadrature_points_matrix function. |
| 527 |
*/ |
| 528 |
template <int dim, int spacedim> |
| 529 |
void |
| 530 |
compute_interpolation_to_quadrature_points_matrix( |
| 531 |
const FiniteElement<dim, spacedim> &fe, |
| 532 |
const Quadrature<dim> &quadrature, |
| 533 |
FullMatrix<double> &I_q); |
| 534 |
|
| 535 |
/** |
| 536 |
* Compute the projection of tensorial (first-order tensor) data stored at |
| 537 |
* the quadrature points @p vector_of_tensors_at_qp to data @p |
| 538 |
* vector_of_tensors_at_nodes at the support points of the cell. The data |
| 539 |
* in @p vector_of_tensors_at_qp is ordered sequentially following the |
| 540 |
* quadrature point numbering. The size of @p vector_of_tensors_at_qp must |
| 541 |
* correspond to the number of columns of @p projection_matrix. The size of |
| 542 |
* @p vector_of_tensors_at_nodes must correspond to the number of rows of @p |
| 543 |
* vector_of_tensors_at_nodes . The projection matrix @p projection_matrix |
| 544 |
* describes the projection of scalar data from the quadrature points and |
| 545 |
* can be obtained from the |
| 546 |
* FETools::compute_projection_from_quadrature_points_matrix function. |
| 547 |
*/ |
| 548 |
template <int dim> |
| 549 |
void |
| 550 |
compute_projection_from_quadrature_points( |
| 551 |
const FullMatrix<double> &projection_matrix, |
| 552 |
const std::vector<Tensor<1, dim>> &vector_of_tensors_at_qp, |
| 553 |
std::vector<Tensor<1, dim>> &vector_of_tensors_at_nodes); |
| 554 |
|
| 555 |
|
| 556 |
|
| 557 |
/** |
| 558 |
* same as last function but for a @p SymmetricTensor . |
| 559 |
*/ |
| 560 |
template <int dim> |
| 561 |
void |
| 562 |
compute_projection_from_quadrature_points( |
| 563 |
const FullMatrix<double> &projection_matrix, |
| 564 |
const std::vector<SymmetricTensor<2, dim>> &vector_of_tensors_at_qp, |
| 565 |
std::vector<SymmetricTensor<2, dim>> &vector_of_tensors_at_nodes); |
| 566 |
|
| 567 |
|
| 568 |
|
| 569 |
/** |
| 570 |
* This method implements the |
| 571 |
* FETools::compute_projection_from_quadrature_points_matrix method for |
| 572 |
* faces of a mesh. The matrix that it returns, X, is face specific and its |
| 573 |
* size is fe.n_dofs_per_cell() by rhs_quadrature.size(). The dimension, dim |
| 574 |
* must be larger than 1 for this class, since Quadrature<dim-1> objects are |
| 575 |
* required. See the documentation on the Quadrature class for more |
| 576 |
* information. |
| 577 |
*/ |
| 578 |
template <int dim, int spacedim> |
| 579 |
void |
| 580 |
compute_projection_from_face_quadrature_points_matrix( |
| 581 |
const FiniteElement<dim, spacedim> &fe, |
| 582 |
const Quadrature<dim - 1> &lhs_quadrature, |
| 583 |
const Quadrature<dim - 1> &rhs_quadrature, |
| 584 |
const typename DoFHandler<dim, spacedim>::active_cell_iterator &cell, |
| 585 |
const unsigned int face, |
| 586 |
FullMatrix<double> &X); |
| 587 |
|
| 588 |
/** |
| 589 |
* @brief Compute the nodal quadrature rule associated with an element. |
| 590 |
* |
| 591 |
* Many common finite elements (e.g., FE_Q) are interpolatory - i.e., they are |
| 592 |
* multidimensional generalizations of Lagrange interpolating polynomials and |
| 593 |
* are collectively referred to as @ref GlossLagrange "Lagrange elements". |
| 594 |
* |
| 595 |
* Since these elements define a polynomial interpolation, they implicitly |
| 596 |
* also define a Quadrature rule. For example, the weights of QTrapezoid are |
| 597 |
* the integrals of multilinear shape functions and the quadrature points are |
| 598 |
* the vertices of the reference hypercube - i.e., QTrapezoid is the nodal |
| 599 |
* rule corresponding to FE_Q(1). Some elements, such as FE_SimplexP(2), do |
| 600 |
* not correspond to useful nodal quadrature rules since the integrals of some |
| 601 |
* shape functions (in this case, the ones with support points at vertices) |
| 602 |
* are zero. Other elements, like FE_RaviartThomas, are noninterpolatory and |
| 603 |
* therefore also do not correspond to nodal quadrature rules. |
| 604 |
* |
| 605 |
* Given a FiniteElement with support points, this function determines the |
| 606 |
* associated quadrature rule by setting the weights equal to the integrals of |
| 607 |
* its shape functions (even if they are zero or negative) and points equal to |
| 608 |
* the support points of the FiniteElement. |
| 609 |
* |
| 610 |
* @note If @p fe is an FE_Q or FE_DGQ with the default support points (i.e., |
| 611 |
* it was constructed with a polynomial order argument and not with a custom |
| 612 |
* list of support points) then the corresponding nodal quadrature rule has |
| 613 |
* the same points and weights as QGaussLobatto (but they will generally be in |
| 614 |
* a different order). |
| 615 |
* |
| 616 |
* @note This function is only implemented for scalar (i.e., one block and one |
| 617 |
* component) elements which have |
| 618 |
* @ref GlossSupport "support points". |
| 619 |
*/ |
| 620 |
template <int dim, int spacedim = dim> |
| 621 |
Quadrature<dim> |
| 622 |
compute_nodal_quadrature(const FiniteElement<dim, spacedim> &fe); |
| 623 |
|
| 624 |
/** |
| 625 |
* Wrapper around |
| 626 |
* FiniteElement::convert_generalized_support_point_values_to_dof_values() |
| 627 |
* that works with arbitrary number types. |
| 628 |
* |
| 629 |
* @param[in] finite_element The FiniteElement to compute dof values for. |
| 630 |
* @param[in] support_point_values An array of size @p dofs_per_cell |
| 631 |
* (which equals the number of points the get_generalized_support_points() |
| 632 |
* function will return) where each element is a vector with as many entries |
| 633 |
* as the element has vector components. This array should contain |
| 634 |
* the values of a function at the generalized support points of the |
| 635 |
* finite element. |
| 636 |
* @param[out] dof_values An array of size @p dofs_per_cell that contains |
| 637 |
* the node functionals of the element applied to the given function. |
| 638 |
*/ |
| 639 |
template <int dim, int spacedim, typename number> |
| 640 |
void |
| 641 |
convert_generalized_support_point_values_to_dof_values( |
| 642 |
const FiniteElement<dim, spacedim> &finite_element, |
| 643 |
const std::vector<Vector<number>> &support_point_values, |
| 644 |
std::vector<number> &dof_values); |
| 645 |
|
| 646 |
|
| 647 |
|
| 648 |
/** @} */ |
| 649 |
/** |
| 650 |
* @name Functions which should be in DoFTools or VectorTools |
| 651 |
*/ |
| 652 |
/** @{ */ |
| 653 |
/** |
| 654 |
* Compute the interpolation of a the @p dof1-function @p u1 to a @p |
| 655 |
* dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on |
| 656 |
* the same triangulation. |
| 657 |
* |
| 658 |
* If the elements @p fe1 and @p fe2 are either both continuous or both |
| 659 |
* discontinuous then this interpolation is the usual point interpolation. |
| 660 |
* The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous |
| 661 |
* finite element. For the case that @p fe1 is a discontinuous and @p fe2 is |
| 662 |
* a continuous finite element there is no point interpolation defined at |
| 663 |
* the discontinuities. Therefore the mean value is taken at the DoF values |
| 664 |
* on the discontinuities. |
| 665 |
* |
| 666 |
* Note that for continuous elements on grids with hanging nodes (i.e. |
| 667 |
* locally refined grids) this function does not give the expected output. |
| 668 |
* Indeed, the resulting output vector does not necessarily respect |
| 669 |
* continuity requirements at hanging nodes: if, for example, you are |
| 670 |
* interpolating a Q2 field to a Q1 field, then at hanging nodes the output |
| 671 |
* field will have the function value of the input field, which however is |
| 672 |
* not usually the mean value of the two adjacent nodes. It is thus not part |
| 673 |
* of the Q1 function space on the whole triangulation, although it is of |
| 674 |
* course Q1 on each cell. |
| 675 |
* |
| 676 |
* For this case (continuous elements on grids with hanging nodes), please |
| 677 |
* use the @p interpolate() function with an additional AffineConstraints |
| 678 |
* object as argument, see below, or make the field conforming yourself |
| 679 |
* by calling the @p distribute function of your hanging node constraints |
| 680 |
* object. |
| 681 |
* |
| 682 |
* @note There are also various interpolation-related functions in |
| 683 |
* namespace VectorTools. |
| 684 |
*/ |
| 685 |
template <int dim, int spacedim, class InVector, class OutVector> |
| 686 |
void |
| 687 |
interpolate(const DoFHandler<dim, spacedim> &dof1, |
| 688 |
const InVector &u1, |
| 689 |
const DoFHandler<dim, spacedim> &dof2, |
| 690 |
OutVector &u2); |
| 691 |
|
| 692 |
/** |
| 693 |
* Compute the interpolation of a the @p dof1-function @p u1 to a @p |
| 694 |
* dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on |
| 695 |
* the same triangulation. @p constraints is a hanging node constraints object |
| 696 |
* corresponding to @p dof2. This object is particular important when |
| 697 |
* interpolating onto continuous elements on grids with hanging nodes (locally |
| 698 |
* refined grids). |
| 699 |
* |
| 700 |
* If the elements @p fe1 and @p fe2 are either both continuous or both |
| 701 |
* discontinuous then this interpolation is the usual point interpolation. |
| 702 |
* The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous |
| 703 |
* finite element. For the case that @p fe1 is a discontinuous and @p fe2 is |
| 704 |
* a continuous finite element there is no point interpolation defined at |
| 705 |
* the discontinuities. Therefore the mean value is taken at the DoF values |
| 706 |
* at the discontinuities. |
| 707 |
* |
| 708 |
* @note There are also various interpolation-related functions in |
| 709 |
* namespace VectorTools. |
| 710 |
*/ |
| 711 |
template <int dim, int spacedim, class InVector, class OutVector> |
| 712 |
void |
| 713 |
interpolate( |
| 714 |
const DoFHandler<dim, spacedim> &dof1, |
| 715 |
const InVector &u1, |
| 716 |
const DoFHandler<dim, spacedim> &dof2, |
| 717 |
const AffineConstraints<typename OutVector::value_type> &constraints, |
| 718 |
OutVector &u2); |
| 719 |
|
| 720 |
/** |
| 721 |
* Compute the interpolation of the @p fe1-function @p u1 to a @p |
| 722 |
* fe2-function, and interpolate this to a second @p fe1-function named @p |
| 723 |
* u1_interpolated. |
| 724 |
* |
| 725 |
* Note, that this function does not work on continuous elements at hanging |
| 726 |
* nodes. For that case use the @p back_interpolate function, below, that |
| 727 |
* takes an additional @p AffineConstraints object. |
| 728 |
* |
| 729 |
* Furthermore note, that for the specific case when the finite element |
| 730 |
* space corresponding to @p fe1 is a subset of the finite element space |
| 731 |
* corresponding to @p fe2, this function is simply an identity mapping. |
| 732 |
*/ |
| 733 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 734 |
void |
| 735 |
back_interpolate(const DoFHandler<dim, spacedim> &dof1, |
| 736 |
const InVector &u1, |
| 737 |
const FiniteElement<dim, spacedim> &fe2, |
| 738 |
OutVector &u1_interpolated); |
| 739 |
|
| 740 |
/** |
| 741 |
* Compute the interpolation of the @p dof1-function @p u1 to a @p |
| 742 |
* dof2-function, and interpolate this to a second @p dof1-function named |
| 743 |
* @p u1_interpolated. @p constraints1 and @p constraints2 are the hanging |
| 744 |
* node constraints corresponding to @p dof1 and @p dof2, respectively. |
| 745 |
* These objects are particular important when continuous elements on grids |
| 746 |
* with hanging nodes (locally refined grids) are involved. |
| 747 |
* |
| 748 |
* Furthermore note, that for the specific case when the finite element |
| 749 |
* space corresponding to @p dof1 is a subset of the finite element space |
| 750 |
* corresponding to @p dof2, this function is simply an identity mapping. |
| 751 |
*/ |
| 752 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 753 |
void |
| 754 |
back_interpolate( |
| 755 |
const DoFHandler<dim, spacedim> &dof1, |
| 756 |
const AffineConstraints<typename OutVector::value_type> &constraints1, |
| 757 |
const InVector &u1, |
| 758 |
const DoFHandler<dim, spacedim> &dof2, |
| 759 |
const AffineConstraints<typename OutVector::value_type> &constraints2, |
| 760 |
OutVector &u1_interpolated); |
| 761 |
|
| 762 |
/** |
| 763 |
* Compute $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is |
| 764 |
* the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is |
| 765 |
* written into @p z1_difference. |
| 766 |
* |
| 767 |
* Note, that this function does not work for continuous elements at hanging |
| 768 |
* nodes. For that case use the @p interpolation_difference function, below, |
| 769 |
* that takes an additional @p AffineConstraints object. |
| 770 |
*/ |
| 771 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 772 |
void |
| 773 |
interpolation_difference(const DoFHandler<dim, spacedim> &dof1, |
| 774 |
const InVector &z1, |
| 775 |
const FiniteElement<dim, spacedim> &fe2, |
| 776 |
OutVector &z1_difference); |
| 777 |
|
| 778 |
/** |
| 779 |
* Compute $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is |
| 780 |
* the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is |
| 781 |
* written into @p z1_difference. @p constraints1 and @p constraints2 are |
| 782 |
* the hanging node constraints corresponding to @p dof1 and @p dof2, |
| 783 |
* respectively. These objects are particular important when continuous |
| 784 |
* elements on grids with hanging nodes (locally refined grids) are |
| 785 |
* involved. |
| 786 |
* |
| 787 |
* For parallel computations, supply @p z1 with ghost elements and @p |
| 788 |
* z1_difference without ghost elements. |
| 789 |
*/ |
| 790 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 791 |
void |
| 792 |
interpolation_difference( |
| 793 |
const DoFHandler<dim, spacedim> &dof1, |
| 794 |
const AffineConstraints<typename OutVector::value_type> &constraints1, |
| 795 |
const InVector &z1, |
| 796 |
const DoFHandler<dim, spacedim> &dof2, |
| 797 |
const AffineConstraints<typename OutVector::value_type> &constraints2, |
| 798 |
OutVector &z1_difference); |
| 799 |
|
| 800 |
|
| 801 |
|
| 802 |
/** |
| 803 |
* $L^2$ projection for discontinuous elements. Operates the same direction |
| 804 |
* as interpolate. |
| 805 |
* |
| 806 |
* The global projection can be computed by local matrices if the finite |
| 807 |
* element spaces are discontinuous. With continuous elements, this is |
| 808 |
* impossible, since a global @ref GlossMassMatrix "mass matrix" must be inverted. |
| 809 |
*/ |
| 810 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 811 |
void |
| 812 |
project_dg(const DoFHandler<dim, spacedim> &dof1, |
| 813 |
const InVector &u1, |
| 814 |
const DoFHandler<dim, spacedim> &dof2, |
| 815 |
OutVector &u2); |
| 816 |
|
| 817 |
/** |
| 818 |
* Compute the patchwise extrapolation of a @p dof1 function @p z1 to a @p |
| 819 |
* dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects |
| 820 |
* based on the same triangulation. This function is used, for example, for |
| 821 |
* extrapolating patchwise a piecewise linear solution to a piecewise |
| 822 |
* quadratic solution. |
| 823 |
* |
| 824 |
* The function's name is historical and probably not particularly well |
| 825 |
* chosen. The function performs the following operations, one after the |
| 826 |
* other: |
| 827 |
* |
| 828 |
* - It interpolates directly from every cell of @p dof1 to the |
| 829 |
* corresponding cell of `dof2` using the interpolation matrix of the finite |
| 830 |
* element spaces used on these cells and provided by the finite element |
| 831 |
* objects involved. This step is done using the FETools::interpolate() |
| 832 |
* function. |
| 833 |
* - It then performs a loop over all non-active cells of `dof2`. |
| 834 |
* If such a non-active cell has at least one active child, then we call the |
| 835 |
* children of this cell a "patch". We then interpolate from the children of |
| 836 |
* this patch to the patch, using the finite element space associated with |
| 837 |
* `dof2` and immediately interpolate back to the children. In essence, this |
| 838 |
* information throws away all information in the solution vector that lives |
| 839 |
* on a scale smaller than the patch cell. |
| 840 |
* - Since we traverse non-active cells from the coarsest to the finest |
| 841 |
* levels, we may find patches that correspond to child cells of previously |
| 842 |
* treated patches if the mesh had been refined adaptively (this cannot |
| 843 |
* happen if the mesh has been refined globally because there the children |
| 844 |
* of a patch are all active). We also perform the operation described above |
| 845 |
* on these patches, which means that the final DoF values will always |
| 846 |
* originate from the most refined patches. |
| 847 |
* |
| 848 |
* The name of the function originates from the fact that it can be used to |
| 849 |
* construct a representation of a function of higher polynomial degree on a |
| 850 |
* once coarser mesh. For example, if you imagine that you start with a |
| 851 |
* $Q_1$ function on a globally refined mesh, and that @p dof2 is associated |
| 852 |
* with a $Q_2$ element, then this function computes the equivalent of the |
| 853 |
* operator $I_{2h}^{(2)}$ interpolating the original piecewise linear |
| 854 |
* function onto a quadratic function on a once coarser mesh with mesh size |
| 855 |
* $2h$ (but representing this function on the original mesh with size $h$). |
| 856 |
* If the exact solution is sufficiently smooth, then |
| 857 |
* $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to the exact |
| 858 |
* solution $u$ of the PDE than $u_h$ is. In other words, this function |
| 859 |
* provides a postprocessing step that improves the solution in a similar |
| 860 |
* way one often obtains by extrapolating a sequence of solutions, |
| 861 |
* explaining the origin of the function's name. |
| 862 |
* |
| 863 |
* @note The resulting field does not satisfy continuity requirements of the |
| 864 |
* given finite elements if the algorithm outlined above is used. When you |
| 865 |
* use continuous elements on grids with hanging nodes, please use the @p |
| 866 |
* extrapolate function with an additional AffineConstraints argument, see |
| 867 |
* below. |
| 868 |
* |
| 869 |
* @note Since this function operates on patches of cells, it requires that |
| 870 |
* the underlying grid is refined at least once for every coarse grid cell. |
| 871 |
* If this is not the case, an exception will be raised. |
| 872 |
*/ |
| 873 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 874 |
void |
| 875 |
extrapolate(const DoFHandler<dim, spacedim> &dof1, |
| 876 |
const InVector &z1, |
| 877 |
const DoFHandler<dim, spacedim> &dof2, |
| 878 |
OutVector &z2); |
| 879 |
|
| 880 |
/** |
| 881 |
* Compute the patchwise extrapolation of a @p dof1 function @p z1 to a @p |
| 882 |
* dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects |
| 883 |
* based on the same triangulation. @p constraints is a hanging node |
| 884 |
* constraints object corresponding to @p dof2. This object is necessary |
| 885 |
* when interpolating onto continuous elements on grids with hanging nodes |
| 886 |
* (locally refined grids). |
| 887 |
* |
| 888 |
* Otherwise, the function does the same as the other @p extrapolate |
| 889 |
* function above (for which the documentation provides an extensive |
| 890 |
* description of its operation). |
| 891 |
*/ |
| 892 |
template <int dim, class InVector, class OutVector, int spacedim> |
| 893 |
void |
| 894 |
extrapolate( |
| 895 |
const DoFHandler<dim, spacedim> &dof1, |
| 896 |
const InVector &z1, |
| 897 |
const DoFHandler<dim, spacedim> &dof2, |
| 898 |
const AffineConstraints<typename OutVector::value_type> &constraints, |
| 899 |
OutVector &z2); |
| 900 |
|
| 901 |
/** @} */ |
| 902 |
/** |
| 903 |
* The numbering of the degrees of freedom in continuous finite elements is |
| 904 |
* hierarchic, i.e. in such a way that we first number the vertex dofs, in |
| 905 |
* the order of the vertices as defined by the triangulation, then the line |
| 906 |
* dofs in the order and respecting the direction of the lines, then the |
| 907 |
* dofs on quads, etc. However, we could have, as well, numbered them in a |
| 908 |
* lexicographic way, i.e. with indices first running in x-direction, then |
| 909 |
* in y-direction and finally in z-direction. Discontinuous elements of |
| 910 |
* class FE_DGQ() are numbered in this way, for example. |
| 911 |
* |
| 912 |
* This function returns a vector containing information about the |
| 913 |
* lexicographic index each degree of freedom in the hierarchic numbering |
| 914 |
* would have to a given degree of a continuous finite element. |
| 915 |
*/ |
| 916 |
template <int dim> |
| 917 |
std::vector<unsigned int> |
| 918 |
hierarchic_to_lexicographic_numbering(unsigned int degree); |
| 919 |
|
| 920 |
/** |
| 921 |
* This is the reverse function to the above one, generating the map from |
| 922 |
* the lexicographic to the hierarchical numbering for a given polynomial |
| 923 |
* degree of a continuous finite element. All the remarks made about the |
| 924 |
* above function are also valid here. |
| 925 |
*/ |
| 926 |
template <int dim> |
| 927 |
std::vector<unsigned int> |
| 928 |
lexicographic_to_hierarchic_numbering(unsigned int degree); |
| 929 |
|
| 930 |
/** |
| 931 |
* Given the polynomial degree, direction, and numbering options, this |
| 932 |
* function returns a pair of vectors mapping cell DoFs to face patch DoFs |
| 933 |
* in lexicographic order. |
| 934 |
* |
| 935 |
* This function works for scalar finite elements, specifically those derived |
| 936 |
* from FE_Q and FE_DGQ. It computes the mapping from the DoFs of |
| 937 |
* two adjacent cells sharing a face perpendicular to @p direction in |
| 938 |
* reference space, to the DoFs on the face patch. The result is a pair of |
| 939 |
* vectors: the first for the DoFs on the first cell, the second for the |
| 940 |
* DoFs on the second cell. The @p cell_hierarchical_numbering flag |
| 941 |
* determines whether hierarchical or lexicographic numbering is assumed for |
| 942 |
* the cell DoFs. The @p is_continuous flag indicates whether the finite |
| 943 |
* element space is continuous (i.e., FE_Q). |
| 944 |
* |
| 945 |
* @param degree Polynomial degree of the finite element. |
| 946 |
* @param direction Axis perpendicular to the considered face. |
| 947 |
* @param cell_hierarchical_numbering If true, use hierarchical numbering for cell DoFs. |
| 948 |
* @param is_continuous If true, assumes the finite element space is continuous (FE_Q). |
| 949 |
* @return A pair of vectors mapping cell DoFs to face patch DoFs in lexicographic order. |
| 950 |
*/ |
| 951 |
template <int dim> |
| 952 |
std::pair<std::vector<unsigned int>, std::vector<unsigned int>> |
| 953 |
cell_to_face_patch(const unsigned int °ree, |
| 954 |
const unsigned int &direction, |
| 955 |
const bool &cell_hierarchical_numbering, |
| 956 |
const bool &is_continuous); |
| 957 |
|
| 958 |
/** |
| 959 |
* A namespace that contains functions that help setting up internal |
| 960 |
* data structures when implementing FiniteElement which are build |
| 961 |
* from simpler ("base") elements, for example FESystem. The things |
| 962 |
* computed by these functions typically serve as constructor |
| 963 |
* arguments to the FiniteElement base class of the derived finite |
| 964 |
* element object being constructed. |
| 965 |
* |
| 966 |
* There are generally two ways in which one can build more complex |
| 967 |
* elements, and this is reflected by several of the functions in |
| 968 |
* this namespace having arguments called |
| 969 |
* <code>do_tensor_product</code>: |
| 970 |
* |
| 971 |
* <ol> |
| 972 |
* <li> Tensor product construction (<code>do_tensor_product=true</code>): |
| 973 |
* The tensor product construction, in the simplest case, builds a |
| 974 |
* vector-valued element from scalar elements (see |
| 975 |
* @ref vector_valued "this documentation topic" |
| 976 |
* and |
| 977 |
* @ref GlossComponent "this glossary entry" |
| 978 |
* for more information). |
| 979 |
* To give an example, consider creating a vector-valued element with |
| 980 |
* two vector components, where the first should have linear shape |
| 981 |
* functions and the second quadratic shape functions. In 1d, the |
| 982 |
* shape functions (on the reference cell) of the base elements are then |
| 983 |
* @f{align*}{ |
| 984 |
* Q_1 &= \{ 1-x, x \}, |
| 985 |
* \\ Q_2 &= \{ 2(\frac 12 - x)(1-x), 2(x - \frac 12)x, 4x(1-x) \}, |
| 986 |
* @f} |
| 987 |
* where shape functions are ordered in the usual way (first on the |
| 988 |
* first vertex, then on the second vertex, then in the interior of |
| 989 |
* the cell). The tensor product construction will create an element with |
| 990 |
* the following shape functions: |
| 991 |
* @f{align*}{ |
| 992 |
* Q_1 \times Q_2 &= |
| 993 |
* \left\{ |
| 994 |
* \begin{pmatrix} 1-x \\ 0 \end{pmatrix}, |
| 995 |
* \begin{pmatrix} 0 \\ 2(\frac 12 - x)(1-x) \end{pmatrix}, |
| 996 |
* \begin{pmatrix} x \\ 0 \end{pmatrix}, |
| 997 |
* \begin{pmatrix} 0 \\ 2(x - \frac 12)x \end{pmatrix}, |
| 998 |
* \begin{pmatrix} 0 \\ 4x(1-x) \end{pmatrix} |
| 999 |
* \right\}. |
| 1000 |
* @f} |
| 1001 |
* The list here is again in standard order. |
| 1002 |
* |
| 1003 |
* Of course, the procedure also works if the base elements are |
| 1004 |
* already vector valued themselves: in that case, the composed |
| 1005 |
* element simply has as many vector components as the base elements |
| 1006 |
* taken together. |
| 1007 |
* |
| 1008 |
* <li> Combining shape functions |
| 1009 |
* (<code>do_tensor_product=false</code>): In contrast to the |
| 1010 |
* previous strategy, combining shape functions simply takes |
| 1011 |
* <i>all</i> of the shape functions together. In the case above, |
| 1012 |
* this would yield the following element: |
| 1013 |
* @f{align*}{ |
| 1014 |
* Q_1 + Q_2 &= \{ 1-x, 2(\frac 12 - x)(1-x), |
| 1015 |
* x, 2(x - \frac 12)x, 4x(1-x) \}. |
| 1016 |
* @f} |
| 1017 |
* In other words, if the base elements are scalar, the resulting |
| 1018 |
* element will also be. In general, the base elements all will |
| 1019 |
* have to have the same number of vector components. |
| 1020 |
* |
| 1021 |
* The element constructed above of course no longer has a linearly |
| 1022 |
* independent set of shape functions. As a consequence, any matrix |
| 1023 |
* one creates by treating all shape functions of the composed |
| 1024 |
* element in the same way will be singular. In practice, this |
| 1025 |
* strategy is therefore typically used in situations where one |
| 1026 |
* explicitly makes sure that certain shape functions are treated |
| 1027 |
* differently (e.g., by multiplying them with weight functions), or |
| 1028 |
* in cases where the shape functions one combines are not linearly |
| 1029 |
* dependent. |
| 1030 |
* |
| 1031 |
* </ol> |
| 1032 |
*/ |
| 1033 |
namespace Compositing |
| 1034 |
{ |
| 1035 |
/** |
| 1036 |
* Take vectors of finite elements and multiplicities and multiply out |
| 1037 |
* how many degrees of freedom the composed element has per vertex, |
| 1038 |
* line, etc. |
| 1039 |
* |
| 1040 |
* If @p do_tensor_product is true, the number of components |
| 1041 |
* returned in the FiniteElementData object is the sum over the |
| 1042 |
* product of the number of components in each of the finite |
| 1043 |
* elements times the corresponding multiplicity. Otherwise the |
| 1044 |
* number of components is taken from the first finite element with |
| 1045 |
* non-zero multiplicity, and all other elements with non-zero |
| 1046 |
* multiplicities need to have the same number of vector components. |
| 1047 |
* |
| 1048 |
* See the documentation of namespace FETools::Compositing for more |
| 1049 |
* information about the @p do_tensor_product argument. |
| 1050 |
*/ |
| 1051 |
template <int dim, int spacedim> |
| 1052 |
FiniteElementData<dim> |
| 1053 |
multiply_dof_numbers( |
| 1054 |
const std::vector<const FiniteElement<dim, spacedim> *> &fes, |
| 1055 |
const std::vector<unsigned int> &multiplicities, |
| 1056 |
const bool do_tensor_product = true); |
| 1057 |
|
| 1058 |
/** |
| 1059 |
* Same as above for an arbitrary number of parameters of type |
| 1060 |
* <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned |
| 1061 |
* int></code> and <code>do_tensor_product = true</code>. |
| 1062 |
*/ |
| 1063 |
template <int dim, int spacedim> |
| 1064 |
FiniteElementData<dim> |
| 1065 |
multiply_dof_numbers( |
| 1066 |
const std::initializer_list< |
| 1067 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1068 |
&fe_systems); |
| 1069 |
|
| 1070 |
/** |
| 1071 |
* Same as above but for a specific number of sub-elements. |
| 1072 |
* |
| 1073 |
* @deprecated Use the versions of this function that take a |
| 1074 |
* vector of elements or an initializer list as arguments. |
| 1075 |
*/ |
| 1076 |
template <int dim, int spacedim> |
| 1077 |
DEAL_II_DEPRECATED FiniteElementData<dim> |
| 1078 |
multiply_dof_numbers(const FiniteElement<dim, spacedim> *fe1, |
| 1079 |
const unsigned int N1, |
| 1080 |
const FiniteElement<dim, spacedim> *fe2 = nullptr, |
| 1081 |
const unsigned int N2 = 0, |
| 1082 |
const FiniteElement<dim, spacedim> *fe3 = nullptr, |
| 1083 |
const unsigned int N3 = 0, |
| 1084 |
const FiniteElement<dim, spacedim> *fe4 = nullptr, |
| 1085 |
const unsigned int N4 = 0, |
| 1086 |
const FiniteElement<dim, spacedim> *fe5 = nullptr, |
| 1087 |
const unsigned int N5 = 0); |
| 1088 |
|
| 1089 |
/** |
| 1090 |
* Compute the "restriction is additive" flags (see the |
| 1091 |
* documentation of the FiniteElement class) for a list of finite |
| 1092 |
* elements with multiplicities given in the second argument. |
| 1093 |
* |
| 1094 |
* The "restriction is additive" flags are properties of |
| 1095 |
* individual shape functions that do not depend on whether the |
| 1096 |
* composed element uses the tensor product or combination |
| 1097 |
* strategy outlined in the documentation of the |
| 1098 |
* FETools::Composition namespace. Consequently, this function |
| 1099 |
* does not have a @p do_tensor_product argument. |
| 1100 |
*/ |
| 1101 |
template <int dim, int spacedim> |
| 1102 |
std::vector<bool> |
| 1103 |
compute_restriction_is_additive_flags( |
| 1104 |
const std::vector<const FiniteElement<dim, spacedim> *> &fes, |
| 1105 |
const std::vector<unsigned int> &multiplicities); |
| 1106 |
|
| 1107 |
/** |
| 1108 |
* Same as above for an arbitrary number of parameters of type |
| 1109 |
* <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned |
| 1110 |
* int></code>. |
| 1111 |
*/ |
| 1112 |
template <int dim, int spacedim> |
| 1113 |
std::vector<bool> |
| 1114 |
compute_restriction_is_additive_flags( |
| 1115 |
const std::initializer_list< |
| 1116 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1117 |
&fe_systems); |
| 1118 |
|
| 1119 |
/** |
| 1120 |
* Take a @p FiniteElement object and return a boolean vector |
| 1121 |
* describing the @p restriction_is_additive_flags (see the |
| 1122 |
* documentation of the FiniteElement class) for each shape function |
| 1123 |
* of the mixed element consisting of @p N1, @p N2, ... copies of |
| 1124 |
* the sub-elements @p fe1, @p fe2, ... |
| 1125 |
* |
| 1126 |
* The "restriction is additive" flags are properties of |
| 1127 |
* individual shape functions that do not depend on whether the |
| 1128 |
* composed element uses the tensor product or combination |
| 1129 |
* strategy outlined in the documentation of the |
| 1130 |
* FETools::Composition namespace. Consequently, this function |
| 1131 |
* does not have a @p do_tensor_product argument. |
| 1132 |
* |
| 1133 |
* @deprecated Use the versions of this function that take a |
| 1134 |
* vector of elements or an initializer list as arguments. |
| 1135 |
*/ |
| 1136 |
template <int dim, int spacedim> |
| 1137 |
DEAL_II_DEPRECATED std::vector<bool> |
| 1138 |
compute_restriction_is_additive_flags( |
| 1139 |
const FiniteElement<dim, spacedim> *fe1, |
| 1140 |
const unsigned int N1, |
| 1141 |
const FiniteElement<dim, spacedim> *fe2 = nullptr, |
| 1142 |
const unsigned int N2 = 0, |
| 1143 |
const FiniteElement<dim, spacedim> *fe3 = nullptr, |
| 1144 |
const unsigned int N3 = 0, |
| 1145 |
const FiniteElement<dim, spacedim> *fe4 = nullptr, |
| 1146 |
const unsigned int N4 = 0, |
| 1147 |
const FiniteElement<dim, spacedim> *fe5 = nullptr, |
| 1148 |
const unsigned int N5 = 0); |
| 1149 |
|
| 1150 |
|
| 1151 |
/** |
| 1152 |
* Compute the nonzero components for each shape function of a |
| 1153 |
* composed finite element described by a list of finite elements |
| 1154 |
* with multiplicities given in the second argument. |
| 1155 |
* |
| 1156 |
* If @p do_tensor_product is true, the number of components (and |
| 1157 |
* thus the size of the ComponentMask objects) is the sum over the |
| 1158 |
* product of the number of components in each of the finite |
| 1159 |
* elements times the corresponding multiplicity. Otherwise the |
| 1160 |
* number of components is taken from the first finite element with |
| 1161 |
* non-zero multiplicity, and all other elements with non-zero |
| 1162 |
* multiplicities need to have the same number of vector components. |
| 1163 |
* |
| 1164 |
* See the documentation of namespace FETools::Compositing for more |
| 1165 |
* information about the @p do_tensor_product argument. |
| 1166 |
*/ |
| 1167 |
template <int dim, int spacedim> |
| 1168 |
std::vector<ComponentMask> |
| 1169 |
compute_nonzero_components( |
| 1170 |
const std::vector<const FiniteElement<dim, spacedim> *> &fes, |
| 1171 |
const std::vector<unsigned int> &multiplicities, |
| 1172 |
const bool do_tensor_product = true); |
| 1173 |
|
| 1174 |
/** |
| 1175 |
* Same as above for an arbitrary number of parameters of type |
| 1176 |
* <code>std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned |
| 1177 |
* int></code> and <code>do_tensor_product = true</code>. |
| 1178 |
*/ |
| 1179 |
template <int dim, int spacedim> |
| 1180 |
std::vector<ComponentMask> |
| 1181 |
compute_nonzero_components( |
| 1182 |
const std::initializer_list< |
| 1183 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1184 |
&fe_systems); |
| 1185 |
|
| 1186 |
/** |
| 1187 |
* Compute the non-zero vector components of a composed finite |
| 1188 |
* element. This function is similar to the previous one, except |
| 1189 |
* that the pointers indicate the elements to be composed, and the |
| 1190 |
* arguments @p N1, @p N2, ... the multiplicities. Null pointers |
| 1191 |
* indicate that an argument is to be skipped. |
| 1192 |
* |
| 1193 |
* If @p do_tensor_product is true, the number of components (and |
| 1194 |
* thus the size of the ComponentMask objects) is the sum over the |
| 1195 |
* product of the number of components in each of the finite |
| 1196 |
* elements times the corresponding multiplicity. Otherwise the |
| 1197 |
* number of components is taken from the first finite element with |
| 1198 |
* non-zero multiplicity, and all other elements with non-zero |
| 1199 |
* multiplicities need to have the same number of vector components. |
| 1200 |
* |
| 1201 |
* See the documentation of namespace FETools::Compositing for more |
| 1202 |
* information about the @p do_tensor_product argument. |
| 1203 |
* |
| 1204 |
* @deprecated Use the versions of this function that take a |
| 1205 |
* vector of elements or an initializer list as arguments. |
| 1206 |
*/ |
| 1207 |
template <int dim, int spacedim> |
| 1208 |
DEAL_II_DEPRECATED std::vector<ComponentMask> |
| 1209 |
compute_nonzero_components( |
| 1210 |
const FiniteElement<dim, spacedim> *fe1, |
| 1211 |
const unsigned int N1, |
| 1212 |
const FiniteElement<dim, spacedim> *fe2 = nullptr, |
| 1213 |
const unsigned int N2 = 0, |
| 1214 |
const FiniteElement<dim, spacedim> *fe3 = nullptr, |
| 1215 |
const unsigned int N3 = 0, |
| 1216 |
const FiniteElement<dim, spacedim> *fe4 = nullptr, |
| 1217 |
const unsigned int N4 = 0, |
| 1218 |
const FiniteElement<dim, spacedim> *fe5 = nullptr, |
| 1219 |
const unsigned int N5 = 0, |
| 1220 |
const bool do_tensor_product = true); |
| 1221 |
|
| 1222 |
/** |
| 1223 |
* For a given (composite) @p finite_element build @p |
| 1224 |
* system_to_component_table, @p system_to_base_table and @p |
| 1225 |
* component_to_base_table. |
| 1226 |
* |
| 1227 |
* If @p do_tensor_product is true, the number of components |
| 1228 |
* used for the composite element is the sum over the |
| 1229 |
* product of the number of components in each of the finite |
| 1230 |
* elements times the corresponding multiplicity. Otherwise the |
| 1231 |
* number of components is taken from the first finite element with |
| 1232 |
* non-zero multiplicity, and all other elements with non-zero |
| 1233 |
* multiplicities need to have the same number of vector components. |
| 1234 |
* |
| 1235 |
* See the documentation of namespace FETools::Compositing for more |
| 1236 |
* information about the @p do_tensor_product argument. |
| 1237 |
*/ |
| 1238 |
template <int dim, int spacedim> |
| 1239 |
void |
| 1240 |
build_cell_tables( |
| 1241 |
std::vector<std::pair<std::pair<unsigned int, unsigned int>, |
| 1242 |
unsigned int>> &system_to_base_table, |
| 1243 |
std::vector<std::pair<unsigned int, unsigned int>> |
| 1244 |
&system_to_component_table, |
| 1245 |
std::vector<std::pair<std::pair<unsigned int, unsigned int>, |
| 1246 |
unsigned int>> &component_to_base_table, |
| 1247 |
const FiniteElement<dim, spacedim> &finite_element, |
| 1248 |
const bool do_tensor_product = true); |
| 1249 |
|
| 1250 |
/** |
| 1251 |
* For a given (composite) @p finite_element build @p face_system_to_base_table, |
| 1252 |
* and @p face_system_to_component_table. |
| 1253 |
* |
| 1254 |
* If @p do_tensor_product is true, the number of components |
| 1255 |
* used for the composite element is the sum over the |
| 1256 |
* product of the number of components in each of the finite |
| 1257 |
* elements times the corresponding multiplicity. Otherwise the |
| 1258 |
* number of components is taken from the first finite element with |
| 1259 |
* non-zero multiplicity, and all other elements with non-zero |
| 1260 |
* multiplicities need to have the same number of vector components. |
| 1261 |
* |
| 1262 |
* See the documentation of namespace FETools::Compositing for more |
| 1263 |
* information about the @p do_tensor_product argument. |
| 1264 |
*/ |
| 1265 |
template <int dim, int spacedim> |
| 1266 |
void |
| 1267 |
build_face_tables( |
| 1268 |
std::vector<std::pair<std::pair<unsigned int, unsigned int>, |
| 1269 |
unsigned int>> &face_system_to_base_table, |
| 1270 |
std::vector<std::pair<unsigned int, unsigned int>> |
| 1271 |
&face_system_to_component_table, |
| 1272 |
const FiniteElement<dim, spacedim> &finite_element, |
| 1273 |
const bool do_tensor_product = true, |
| 1274 |
const unsigned int face_no = 0 /*TODO*/); |
| 1275 |
|
| 1276 |
} // namespace Compositing |
| 1277 |
|
| 1278 |
|
| 1279 |
/** |
| 1280 |
* Parse the name of a finite element and generate a finite element object |
| 1281 |
* accordingly. The parser ignores space characters between words (things |
| 1282 |
* matching the regular expression [A-Za-z0-9_]). |
| 1283 |
* |
| 1284 |
* The name must be in the form which is returned by the |
| 1285 |
* FiniteElement::get_name function, where dimension template parameters |
| 1286 |
* <2> etc. can be omitted. Alternatively, the explicit number can be |
| 1287 |
* replaced by <tt>dim</tt> or <tt>d</tt>. If a number is given, it |
| 1288 |
* <b>must</b> match the template parameter of this function. |
| 1289 |
* |
| 1290 |
* The names of FESystem elements follow the pattern |
| 1291 |
* <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code> The powers <code>p1</code> |
| 1292 |
* etc. may either be numbers or can be replaced by <tt>dim</tt> or |
| 1293 |
* <tt>d</tt>. |
| 1294 |
* |
| 1295 |
* |
| 1296 |
* If no finite element can be reconstructed from this string, an exception |
| 1297 |
* of type @p FETools::ExcInvalidFEName is thrown. |
| 1298 |
* |
| 1299 |
* The function returns a std::unique_ptr to a newly created finite element |
| 1300 |
* meaning the caller obtains ownership over the returned object. |
| 1301 |
* |
| 1302 |
* Since the value of the template argument can't be deduced from the |
| 1303 |
* (string) argument given to this function, you have to explicitly specify |
| 1304 |
* it when you call this function. |
| 1305 |
* |
| 1306 |
* This function knows about all the standard elements defined in the |
| 1307 |
* library. However, it doesn't by default know about elements that you may |
| 1308 |
* have defined in your program. To make your own elements known to this |
| 1309 |
* function, use the add_fe_name() function. This function does not work if |
| 1310 |
* one wants to get a codimension 1 finite element. |
| 1311 |
*/ |
| 1312 |
template <int dim, int spacedim = dim> |
| 1313 |
std::unique_ptr<FiniteElement<dim, spacedim>> |
| 1314 |
get_fe_by_name(const std::string &name); |
| 1315 |
|
| 1316 |
/** |
| 1317 |
* Extend the list of finite elements that can be generated by |
| 1318 |
* get_fe_by_name() by the one given as @p name. If get_fe_by_name() is |
| 1319 |
* later called with this name, it will use the object given as second |
| 1320 |
* argument to create a finite element object. |
| 1321 |
* |
| 1322 |
* The format of the @p name parameter should include the name of a finite |
| 1323 |
* element. However, it is safe to use either the class name alone or to use |
| 1324 |
* the result of FiniteElement::get_name (which includes the space dimension |
| 1325 |
* as well as the polynomial degree), since everything after the first |
| 1326 |
* non-name character will be ignored. |
| 1327 |
* |
| 1328 |
* The FEFactory object should be an object newly created with <tt>new</tt>. |
| 1329 |
* FETools will take ownership of this object and delete it once it is not |
| 1330 |
* used anymore. |
| 1331 |
* |
| 1332 |
* In most cases, if you want objects of type <code>MyFE</code> be created |
| 1333 |
* whenever the name <code>my_fe</code> is given to get_fe_by_name, you |
| 1334 |
* will want the second argument to this function be of type |
| 1335 |
* FEFactory@<MyFE@>, but you can of course create your custom finite |
| 1336 |
* element factory class. |
| 1337 |
* |
| 1338 |
* This function takes over ownership of the object given as second |
| 1339 |
* argument, i.e. you should never attempt to destroy it later on. The |
| 1340 |
* object will be deleted at the end of the program's lifetime. |
| 1341 |
* |
| 1342 |
* If the name of the element is already in use, an exception is thrown. |
| 1343 |
* Thus, functionality of get_fe_by_name() can only be added, not changed. |
| 1344 |
* |
| 1345 |
* @note This function manipulates a global table (one table for each space |
| 1346 |
* dimension). It is thread safe in the sense that every access to this |
| 1347 |
* table is secured by a lock. Nevertheless, since each name can be added |
| 1348 |
* only once, user code has to make sure that only one thread adds a new |
| 1349 |
* element. |
| 1350 |
* |
| 1351 |
* Note also that this table exists once for each space dimension. If you |
| 1352 |
* have a program that works with finite elements in different space |
| 1353 |
* dimensions (for example, |
| 1354 |
* @ref step_4 "step-4" |
| 1355 |
* does something like this), then you should call this function for each |
| 1356 |
* space dimension for which you want your finite element added to the map. |
| 1357 |
*/ |
| 1358 |
template <int dim, int spacedim> |
| 1359 |
void |
| 1360 |
add_fe_name(const std::string &name, |
| 1361 |
const FEFactoryBase<dim, spacedim> *factory); |
| 1362 |
|
| 1363 |
/** |
| 1364 |
* The string used for get_fe_by_name() cannot be translated to a finite |
| 1365 |
* element. |
| 1366 |
* |
| 1367 |
* Either the string is badly formatted or you are using a custom element |
| 1368 |
* that must be added using add_fe_name() first. |
| 1369 |
* |
| 1370 |
* @ingroup Exceptions |
| 1371 |
*/ |
| 1372 |
DeclException1(ExcInvalidFEName, |
| 1373 |
std::string, |
| 1374 |
<< "Can't re-generate a finite element from the string '" |
| 1375 |
<< arg1 << "'."); |
| 1376 |
|
| 1377 |
/** |
| 1378 |
* The string used for get_fe_by_name() cannot be translated to a finite |
| 1379 |
* element. |
| 1380 |
* |
| 1381 |
* Dimension arguments in finite element names should be avoided. If they |
| 1382 |
* are there, the dimension should be <tt>dim</tt> or <tt>d</tt>. Here, you |
| 1383 |
* gave a numeric dimension argument, which does not match the template |
| 1384 |
* dimension of the finite element class. |
| 1385 |
* |
| 1386 |
* @ingroup Exceptions |
| 1387 |
*/ |
| 1388 |
DeclException2(ExcInvalidFEDimension, |
| 1389 |
char, |
| 1390 |
int, |
| 1391 |
<< "The dimension " << arg1 |
| 1392 |
<< " in the finite element string must match " |
| 1393 |
<< "the space dimension " << arg2 << '.'); |
| 1394 |
|
| 1395 |
/** |
| 1396 |
* Exception |
| 1397 |
* |
| 1398 |
* @ingroup Exceptions |
| 1399 |
*/ |
| 1400 |
DeclException0(ExcInvalidFE); |
| 1401 |
|
| 1402 |
/** |
| 1403 |
* The finite element must be |
| 1404 |
* @ref GlossPrimitive "primitive". |
| 1405 |
* |
| 1406 |
* @ingroup Exceptions |
| 1407 |
*/ |
| 1408 |
DeclException0(ExcFENotPrimitive); |
| 1409 |
/** |
| 1410 |
* Exception |
| 1411 |
* |
| 1412 |
* @ingroup Exceptions |
| 1413 |
*/ |
| 1414 |
DeclException0(ExcTriangulationMismatch); |
| 1415 |
|
| 1416 |
/** |
| 1417 |
* A continuous element is used on a mesh with hanging nodes, but the |
| 1418 |
* constraint matrices are missing. |
| 1419 |
* |
| 1420 |
* @ingroup Exceptions |
| 1421 |
*/ |
| 1422 |
DeclExceptionMsg(ExcHangingNodesNotAllowed, |
| 1423 |
"You are using continuous elements on a grid with " |
| 1424 |
"hanging nodes but without providing hanging node " |
| 1425 |
"constraints. Use the respective function with " |
| 1426 |
"additional AffineConstraints argument(s), instead."); |
| 1427 |
/** |
| 1428 |
* You need at least two grid levels. |
| 1429 |
* |
| 1430 |
* @ingroup Exceptions |
| 1431 |
*/ |
| 1432 |
DeclException0(ExcGridNotRefinedAtLeastOnce); |
| 1433 |
/** |
| 1434 |
* The dimensions of the matrix used did not match the expected dimensions. |
| 1435 |
* |
| 1436 |
* @ingroup Exceptions |
| 1437 |
*/ |
| 1438 |
DeclException4(ExcMatrixDimensionMismatch, |
| 1439 |
int, |
| 1440 |
int, |
| 1441 |
int, |
| 1442 |
int, |
| 1443 |
<< "This is a " << arg1 << 'x' << arg2 << " matrix, " |
| 1444 |
<< "but should be a " << arg3 << 'x' << arg4 << " matrix."); |
| 1445 |
|
| 1446 |
/** |
| 1447 |
* Exception thrown if an embedding matrix was computed inaccurately. |
| 1448 |
* |
| 1449 |
* @ingroup Exceptions |
| 1450 |
*/ |
| 1451 |
DeclException1(ExcLeastSquaresError, |
| 1452 |
double, |
| 1453 |
<< "Least squares fit leaves a gap of " << arg1); |
| 1454 |
|
| 1455 |
/** |
| 1456 |
* Exception thrown if one variable may not be greater than another. |
| 1457 |
* |
| 1458 |
* @ingroup Exceptions |
| 1459 |
*/ |
| 1460 |
DeclException2(ExcNotGreaterThan, |
| 1461 |
int, |
| 1462 |
int, |
| 1463 |
<< arg1 << " must be greater than " << arg2); |
| 1464 |
} // namespace FETools |
| 1465 |
|
| 1466 |
|
| 1467 |
#ifndef DOXYGEN |
| 1468 |
|
| 1469 |
namespace FETools |
| 1470 |
{ |
| 1471 |
template <class FE> |
| 1472 |
std::unique_ptr<FiniteElement<FE::dimension, FE::space_dimension>> |
| 1473 |
FEFactory<FE>::get(const unsigned int degree) const |
| 1474 |
{ |
| 1475 |
return std::make_unique<FE>(degree); |
| 1476 |
} |
| 1477 |
|
| 1478 |
namespace Compositing |
| 1479 |
{ |
| 1480 |
template <int dim, int spacedim> |
| 1481 |
std::vector<bool> |
| 1482 |
compute_restriction_is_additive_flags( |
| 1483 |
const std::initializer_list< |
| 1484 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1485 |
&fe_systems) |
| 1486 |
{ |
| 1487 |
std::vector<const FiniteElement<dim, spacedim> *> fes; |
| 1488 |
std::vector<unsigned int> multiplicities; |
| 1489 |
|
| 1490 |
const auto extract = |
| 1491 |
[&fes, &multiplicities]( |
| 1492 |
const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, |
| 1493 |
unsigned int> &fe_system) { |
| 1494 |
fes.push_back(fe_system.first.get()); |
| 1495 |
multiplicities.push_back(fe_system.second); |
| 1496 |
}; |
| 1497 |
|
| 1498 |
for (const auto &p : fe_systems) |
| 1499 |
extract(p); |
| 1500 |
|
| 1501 |
return compute_restriction_is_additive_flags(fes, multiplicities); |
| 1502 |
} |
| 1503 |
|
| 1504 |
|
| 1505 |
|
| 1506 |
template <int dim, int spacedim> |
| 1507 |
FiniteElementData<dim> |
| 1508 |
multiply_dof_numbers( |
| 1509 |
const std::initializer_list< |
| 1510 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1511 |
&fe_systems) |
| 1512 |
{ |
| 1513 |
std::vector<const FiniteElement<dim, spacedim> *> fes; |
| 1514 |
std::vector<unsigned int> multiplicities; |
| 1515 |
|
| 1516 |
const auto extract = |
| 1517 |
[&fes, &multiplicities]( |
| 1518 |
const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, |
| 1519 |
unsigned int> &fe_system) { |
| 1520 |
fes.push_back(fe_system.first.get()); |
| 1521 |
multiplicities.push_back(fe_system.second); |
| 1522 |
}; |
| 1523 |
|
| 1524 |
for (const auto &p : fe_systems) |
| 1525 |
extract(p); |
| 1526 |
|
| 1527 |
return multiply_dof_numbers(fes, multiplicities, true); |
| 1528 |
} |
| 1529 |
|
| 1530 |
|
| 1531 |
|
| 1532 |
template <int dim, int spacedim> |
| 1533 |
std::vector<ComponentMask> |
| 1534 |
compute_nonzero_components( |
| 1535 |
const std::initializer_list< |
| 1536 |
std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, unsigned int>> |
| 1537 |
&fe_systems) |
| 1538 |
{ |
| 1539 |
std::vector<const FiniteElement<dim, spacedim> *> fes; |
| 1540 |
std::vector<unsigned int> multiplicities; |
| 1541 |
|
| 1542 |
const auto extract = |
| 1543 |
[&fes, &multiplicities]( |
| 1544 |
const std::pair<std::unique_ptr<FiniteElement<dim, spacedim>>, |
| 1545 |
unsigned int> &fe_system) { |
| 1546 |
fes.push_back(fe_system.first.get()); |
| 1547 |
multiplicities.push_back(fe_system.second); |
| 1548 |
}; |
| 1549 |
|
| 1550 |
for (const auto &p : fe_systems) |
| 1551 |
extract(p); |
| 1552 |
|
| 1553 |
return compute_nonzero_components(fes, multiplicities, true); |
| 1554 |
} |
| 1555 |
} // namespace Compositing |
| 1556 |
} // namespace FETools |
| 1557 |
|
| 1558 |
#endif |
| 1559 |
|
| 1560 |
/** @} */ |
| 1561 |
|
| 1562 |
DEAL_II_NAMESPACE_CLOSE |
| 1563 |
|
| 1564 |
#endif /* dealii_fe_tools_H */ |