| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2003 - 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_raviart_thomas_h |
| 16 |
#define dealii_fe_raviart_thomas_h |
| 17 |
|
| 18 |
#include <deal.II/base/config.h> |
| 19 |
|
| 20 |
#include <deal.II/base/mutex.h> |
| 21 |
#include <deal.II/base/table.h> |
| 22 |
|
| 23 |
#include <deal.II/fe/fe.h> |
| 24 |
#include <deal.II/fe/fe_poly_tensor.h> |
| 25 |
|
| 26 |
#include <vector> |
| 27 |
|
| 28 |
DEAL_II_NAMESPACE_OPEN |
| 29 |
|
| 30 |
/** |
| 31 |
* @addtogroup fe |
| 32 |
* @{ |
| 33 |
*/ |
| 34 |
|
| 35 |
/** |
| 36 |
* Implementation of Raviart-Thomas (RT) elements. The Raviart-Thomas space |
| 37 |
* is designed to solve problems in which the solution only lives in the |
| 38 |
* space |
| 39 |
* $H^\text{div}=\{ {\mathbf u} \in L_2: \text{div}\, {\mathbf u} \in L_2\}$, |
| 40 |
* rather than in the more commonly used space |
| 41 |
* $H^1=\{ u \in L_2: \nabla u \in L_2\}$. In other words, the solution must |
| 42 |
* be a vector field whose divergence is square integrable, but for which the |
| 43 |
* gradient may not be square integrable. The typical application for this |
| 44 |
* space (and these elements) is to the mixed formulation of the Laplace |
| 45 |
* equation and related situations, see for example step-20. The defining |
| 46 |
* characteristic of functions in $H^\text{div}$ is that they are in |
| 47 |
* general discontinuous -- but that if you draw a line in 2d (or a |
| 48 |
* surface in 3d), then the <i>normal</i> component of the vector |
| 49 |
* field must be continuous across the line (or surface) even though |
| 50 |
* the tangential component may not be. As a consequence, the |
| 51 |
* Raviart-Thomas element is constructed in such a way that (i) it is |
| 52 |
* @ref vector_valued "vector-valued", |
| 53 |
* (ii) the shape functions are |
| 54 |
* discontinuous, but (iii) the normal component of the vector field |
| 55 |
* represented by each shape function is continuous across the faces |
| 56 |
* of cells. |
| 57 |
* |
| 58 |
* Other properties of the Raviart-Thomas element are that (i) it is |
| 59 |
* @ref GlossPrimitive "not a primitive element" |
| 60 |
* ; (ii) the shape functions |
| 61 |
* are defined so that certain integrals over the faces are either zero |
| 62 |
* or one, rather than the common case of certain point values being |
| 63 |
* either zero or one. (There is, however, the FE_RaviartThomasNodal |
| 64 |
* element that uses point values.) |
| 65 |
* |
| 66 |
* We follow the commonly used -- though confusing -- definition of the "degree" |
| 67 |
* of RT elements. Specifically, the "degree" of the element denotes |
| 68 |
* the polynomial degree of the <i>largest complete polynomial subspace</i> |
| 69 |
* contained in the finite element space, even if the space may contain shape |
| 70 |
* functions of higher polynomial degree. The lowest order element is |
| 71 |
* consequently FE_RaviartThomas(0), i.e., the Raviart-Thomas element "of |
| 72 |
* degree zero", even though the functions of this space are in general |
| 73 |
* polynomials of degree one in each variable. This choice of "degree" |
| 74 |
* implies that the approximation order of the function itself is |
| 75 |
* <i>degree+1</i>, as with usual polynomial spaces. The numbering so chosen |
| 76 |
* implies the sequence |
| 77 |
* @f[ |
| 78 |
* Q_{k+1} |
| 79 |
* \stackrel{\text{grad}}{\rightarrow} |
| 80 |
* \text{Nedelec}_k |
| 81 |
* \stackrel{\text{curl}}{\rightarrow} |
| 82 |
* \text{RaviartThomas}_k |
| 83 |
* \stackrel{\text{div}}{\rightarrow} |
| 84 |
* DGQ_{k} |
| 85 |
* @f] |
| 86 |
* |
| 87 |
* This class is not implemented for the codimension one case (<tt>spacedim != |
| 88 |
* dim</tt>). |
| 89 |
* |
| 90 |
* |
| 91 |
* <h3>Interpolation</h3> |
| 92 |
* |
| 93 |
* The |
| 94 |
* @ref GlossInterpolation "interpolation" |
| 95 |
* operators associated with the RT element are constructed such that |
| 96 |
* interpolation and computing the divergence are commuting operations. We |
| 97 |
* require this from interpolating arbitrary functions as well as the |
| 98 |
* #restriction matrices. It can be achieved by two interpolation schemes, |
| 99 |
* the simplified one in FE_RaviartThomasNodal and the original one here: |
| 100 |
* |
| 101 |
* <h4>Node values on edges/faces</h4> |
| 102 |
* |
| 103 |
* On edges or faces, the |
| 104 |
* @ref GlossNodes "node values" |
| 105 |
* are the moments of the normal component of the interpolated function with |
| 106 |
* respect to the traces of the RT polynomials. Since the normal trace of the |
| 107 |
* RT space of degree <i>k</i> on an edge/face is the space |
| 108 |
* <i>Q<sub>k</sub></i>, the moments are taken with respect to this space. |
| 109 |
* |
| 110 |
* <h4>Interior node values</h4> |
| 111 |
* |
| 112 |
* Higher order RT spaces have interior nodes. These are moments taken with |
| 113 |
* respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell |
| 114 |
* (this space is the matching space for RT<sub>k</sub> in a mixed |
| 115 |
* formulation). |
| 116 |
* |
| 117 |
* <h4>Generalized support points</h4> |
| 118 |
* |
| 119 |
* The node values above rely on integrals, which will be computed by |
| 120 |
* quadrature rules themselves. The generalized support points are a set of |
| 121 |
* points such that this quadrature can be performed with sufficient accuracy. |
| 122 |
* The points needed are those of QGauss<sub>k+1</sub> on each face as well as |
| 123 |
* QGauss<sub>k+1</sub> in the interior of the cell (or none for |
| 124 |
* RT<sub>0</sub>). |
| 125 |
*/ |
| 126 |
template <int dim> |
| 127 |
class FE_RaviartThomas : public FE_PolyTensor<dim> |
| 128 |
{ |
| 129 |
public: |
| 130 |
/** |
| 131 |
* Constructor for the Raviart-Thomas element of degree @p p. |
| 132 |
*/ |
| 133 |
FE_RaviartThomas(const unsigned int p); |
| 134 |
|
| 135 |
/** |
| 136 |
* Return a string that uniquely identifies a finite element. This class |
| 137 |
* returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree |
| 138 |
* replaced by appropriate values. |
| 139 |
*/ |
| 140 |
virtual std::string |
| 141 |
get_name() const override; |
| 142 |
|
| 143 |
// documentation inherited from the base class |
| 144 |
virtual std::unique_ptr<FiniteElement<dim, dim>> |
| 145 |
clone() const override; |
| 146 |
|
| 147 |
/** |
| 148 |
* Compute the lexicographic to hierarchic numbering underlying this class, |
| 149 |
* necessary for the creation of the respective vector polynomial space. |
| 150 |
*/ |
| 151 |
static std::vector<unsigned int> |
| 152 |
get_lexicographic_numbering(const unsigned int degree); |
| 153 |
|
| 154 |
/** |
| 155 |
* This function returns @p true, if the shape function @p shape_index has |
| 156 |
* non-zero function values somewhere on the face @p face_index. |
| 157 |
* |
| 158 |
* Right now, this is only implemented for RT0 in 1d. Otherwise, returns |
| 159 |
* always @p true. |
| 160 |
*/ |
| 161 |
virtual bool |
| 162 |
has_support_on_face(const unsigned int shape_index, |
| 163 |
const unsigned int face_index) const override; |
| 164 |
|
| 165 |
// documentation inherited from the base class |
| 166 |
virtual void |
| 167 |
convert_generalized_support_point_values_to_dof_values( |
| 168 |
const std::vector<Vector<double>> &support_point_values, |
| 169 |
std::vector<double> &nodal_values) const override; |
| 170 |
|
| 171 |
/** |
| 172 |
* Return a list of constant modes of the element. This method is currently |
| 173 |
* not correctly implemented because it returns ones for all components. |
| 174 |
*/ |
| 175 |
virtual std::pair<Table<2, bool>, std::vector<unsigned int>> |
| 176 |
get_constant_modes() const override; |
| 177 |
|
| 178 |
virtual std::size_t |
| 179 |
memory_consumption() const override; |
| 180 |
|
| 181 |
private: |
| 182 |
/** |
| 183 |
* Only for internal use. Its full name is @p get_dofs_per_object_vector |
| 184 |
* function and it creates the @p dofs_per_object vector that is needed |
| 185 |
* within the constructor to be passed to the constructor of @p |
| 186 |
* FiniteElementData. |
| 187 |
*/ |
| 188 |
static std::vector<unsigned int> |
| 189 |
get_dpo_vector(const unsigned int degree); |
| 190 |
|
| 191 |
/** |
| 192 |
* Initialize the @p generalized_support_points field of the FiniteElement |
| 193 |
* class and fill the tables with interpolation weights (#boundary_weights |
| 194 |
* and #interior_weights). Called from the constructor. |
| 195 |
*/ |
| 196 |
void |
| 197 |
initialize_support_points(const unsigned int rt_degree); |
| 198 |
|
| 199 |
/** |
| 200 |
* Initialize the interpolation from functions on refined mesh cells onto |
| 201 |
* the parent cell. According to the philosophy of the Raviart-Thomas |
| 202 |
* element, this restriction operator preserves the divergence of a function |
| 203 |
* weakly. |
| 204 |
*/ |
| 205 |
void |
| 206 |
initialize_restriction(); |
| 207 |
|
| 208 |
/** |
| 209 |
* These are the factors multiplied to a function in the |
| 210 |
* #generalized_face_support_points when computing the integration. They are |
| 211 |
* organized such that there is one row for each generalized face support |
| 212 |
* point and one column for each degree of freedom on the face. |
| 213 |
* |
| 214 |
* See the |
| 215 |
* @ref GlossGeneralizedSupport "glossary entry on generalized support points" |
| 216 |
* for more information. |
| 217 |
*/ |
| 218 |
Table<2, double> boundary_weights; |
| 219 |
|
| 220 |
/** |
| 221 |
* Precomputed factors for interpolation of interior degrees of freedom. The |
| 222 |
* rationale for this Table is the same as for #boundary_weights. Only, this |
| 223 |
* table has a third coordinate for the space direction of the component |
| 224 |
* evaluated. |
| 225 |
*/ |
| 226 |
Table<3, double> interior_weights; |
| 227 |
|
| 228 |
/** |
| 229 |
* Fill the necessary tables defined in base classes such as |
| 230 |
* <code>adjust_quad_dof_index_for_face_orientation_table</code> declared in |
| 231 |
* fe.cc. We need to fill it with the correct values in case of non-standard, |
| 232 |
* flipped (rotated by +180 degrees) or rotated (rotated by +90 degrees) |
| 233 |
* faces. These are given in the form three flags (face_orientation, |
| 234 |
* face_flip, face_rotation), see the documentation in GeometryInfo<dim> and |
| 235 |
* this |
| 236 |
* @ref GlossCombinedOrientation "glossary entry on face orientations". |
| 237 |
* |
| 238 |
* <h3>Example: Raviart-Thomas Elements of order 2 (tensor polynomial |
| 239 |
* degree 3)</h3> |
| 240 |
* |
| 241 |
* The dofs on a face are connected to a $n\times n$ |
| 242 |
* matrix where here <code>n=3</code>. In our example we can imagine the |
| 243 |
* following dofs on a quad (face): |
| 244 |
* |
| 245 |
* @verbatim |
| 246 |
* ___________ |
| 247 |
* | | |
| 248 |
* | 6 7 8 | |
| 249 |
* | | |
| 250 |
* | 3 4 5 | |
| 251 |
* | | |
| 252 |
* | 0 1 2 | |
| 253 |
* |___________| |
| 254 |
* @endverbatim |
| 255 |
* |
| 256 |
* We have for a local <code>face_dof_index=i+n*j</code> with index |
| 257 |
* <code>i</code> in x-direction and index <code>j</code> in y-direction |
| 258 |
* running from 0 to <code>n-1</code>. To extract <code>i</code> and |
| 259 |
* <code>j</code> we can use <code>i = face_dof_index % n</code> and <code>j = |
| 260 |
* dof_index / n</code> (integer division). The indices <code>i</code> and |
| 261 |
* <code>j</code> can then be used to compute the offset. |
| 262 |
* |
| 263 |
* For our example of Raviart-Thomas elements this means if the |
| 264 |
* switches are <code>(true | true | true)</code> that means we rotate the |
| 265 |
* face first by + 90 degree(counterclockwise) then by another +180 |
| 266 |
* degrees but we do not flip it since the face has standard |
| 267 |
* orientation. The flip axis is the diagonal from the lower left to the upper |
| 268 |
* right corner of the face. With these flags the configuration above becomes: |
| 269 |
* |
| 270 |
* @verbatim |
| 271 |
* ___________ |
| 272 |
* | | |
| 273 |
* | 2 5 8 | |
| 274 |
* | | |
| 275 |
* | 1 4 7 | |
| 276 |
* | | |
| 277 |
* | 0 3 6 | |
| 278 |
* |___________| |
| 279 |
* @endverbatim |
| 280 |
* |
| 281 |
* Note that the necessity of a permutation depends on the combination of the |
| 282 |
* three flags. |
| 283 |
* |
| 284 |
* There is also a pattern for the sign change of the permuted shape functions |
| 285 |
* that depends on the combination of the switches. In the above example it |
| 286 |
* would be |
| 287 |
* |
| 288 |
* @verbatim |
| 289 |
* ___________ |
| 290 |
* | | |
| 291 |
* | + - + | |
| 292 |
* | | |
| 293 |
* | + - + | |
| 294 |
* | | |
| 295 |
* | + - + | |
| 296 |
* |___________| |
| 297 |
* @endverbatim |
| 298 |
* |
| 299 |
* The relevant table for the sign changes is declared in FE_PolyTensor. |
| 300 |
*/ |
| 301 |
void |
| 302 |
initialize_quad_dof_index_permutation_and_sign_change(); |
| 303 |
|
| 304 |
// Allow access from other dimensions. |
| 305 |
template <int dim1> |
| 306 |
friend class FE_RaviartThomas; |
| 307 |
}; |
| 308 |
|
| 309 |
|
| 310 |
|
| 311 |
/** |
| 312 |
* The Raviart-Thomas elements with node functionals defined as point values |
| 313 |
* in Gauss-Lobatto points. |
| 314 |
* |
| 315 |
* <h3>Description of node values</h3> |
| 316 |
* |
| 317 |
* For this Raviart-Thomas element, the node values are not cell and face |
| 318 |
* moments with respect to certain polynomials, but the values at quadrature |
| 319 |
* points. Following the general scheme for numbering degrees of freedom, the |
| 320 |
* node values on faces (edges in 2d, quads in 3d) are first, face by face, |
| 321 |
* according to the natural ordering of the faces of a cell. The interior |
| 322 |
* degrees of freedom are last. |
| 323 |
* |
| 324 |
* For an RT-element of degree <i>k</i>, we choose <i>(k+1)<sup>d-1</sup></i> |
| 325 |
* Gauss-Lobatto points on each face, as defined by QGaussLobatto. For degree |
| 326 |
* $k=0$, the midpoint is chosen. These points are ordered lexicographically |
| 327 |
* with respect to the orientation of the face. This way, the normal component |
| 328 |
* which is in <i>Q<sub>k</sub></i>, is uniquely determined. |
| 329 |
* |
| 330 |
* These face polynomials are extended into the interior by the means of a |
| 331 |
* QGaussLobatto formula for the normal direction. In other words, the |
| 332 |
* polynomials are the tensor product of Lagrange polynomials on the points of |
| 333 |
* a QGaussLobatto formula with $(k+2)$ points in the normal direction with |
| 334 |
* Lagrange polynomials on the points of a QGaussLobatto quadrature formula |
| 335 |
* with $(k+1)$ points. |
| 336 |
* |
| 337 |
* @note The degree stored in the member variable |
| 338 |
* FiniteElementData<dim>::degree is higher by one than the constructor |
| 339 |
* argument! |
| 340 |
*/ |
| 341 |
template <int dim> |
| 342 |
class FE_RaviartThomasNodal : public FE_PolyTensor<dim> |
| 343 |
{ |
| 344 |
public: |
| 345 |
/** |
| 346 |
* Constructor for the Raviart-Thomas element of degree @p p. |
| 347 |
*/ |
| 348 |
FE_RaviartThomasNodal(const unsigned int p); |
| 349 |
|
| 350 |
/** |
| 351 |
* Return a string that uniquely identifies a finite element. This class |
| 352 |
* returns <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with @p dim and @p |
| 353 |
* degree replaced by appropriate values. |
| 354 |
*/ |
| 355 |
virtual std::string |
| 356 |
get_name() const override; |
| 357 |
|
| 358 |
// documentation inherited from the base class |
| 359 |
virtual std::unique_ptr<FiniteElement<dim, dim>> |
| 360 |
clone() const override; |
| 361 |
|
| 362 |
virtual void |
| 363 |
get_face_interpolation_matrix(const FiniteElement<dim> &source, |
| 364 |
FullMatrix<double> &matrix, |
| 365 |
const unsigned int face_no = 0) const override; |
| 366 |
|
| 367 |
virtual void |
| 368 |
get_subface_interpolation_matrix( |
| 369 |
const FiniteElement<dim> &source, |
| 370 |
const unsigned int subface, |
| 371 |
FullMatrix<double> &matrix, |
| 372 |
const unsigned int face_no = 0) const override; |
| 373 |
|
| 374 |
virtual void |
| 375 |
convert_generalized_support_point_values_to_dof_values( |
| 376 |
const std::vector<Vector<double>> &support_point_values, |
| 377 |
std::vector<double> &nodal_values) const override; |
| 378 |
|
| 379 |
virtual bool |
| 380 |
hp_constraints_are_implemented() const override; |
| 381 |
|
| 382 |
virtual std::vector<std::pair<unsigned int, unsigned int>> |
| 383 |
hp_vertex_dof_identities(const FiniteElement<dim> &fe_other) const override; |
| 384 |
|
| 385 |
virtual std::vector<std::pair<unsigned int, unsigned int>> |
| 386 |
hp_line_dof_identities(const FiniteElement<dim> &fe_other) const override; |
| 387 |
|
| 388 |
virtual std::vector<std::pair<unsigned int, unsigned int>> |
| 389 |
hp_quad_dof_identities(const FiniteElement<dim> &fe_other, |
| 390 |
const unsigned int face_no = 0) const override; |
| 391 |
|
| 392 |
/** |
| 393 |
* @copydoc FiniteElement::compare_for_domination() |
| 394 |
*/ |
| 395 |
virtual FiniteElementDomination::Domination |
| 396 |
compare_for_domination(const FiniteElement<dim> &fe_other, |
| 397 |
const unsigned int codim = 0) const override final; |
| 398 |
|
| 399 |
virtual const FullMatrix<double> & |
| 400 |
get_restriction_matrix( |
| 401 |
const unsigned int child, |
| 402 |
const RefinementCase<dim> &refinement_case = |
| 403 |
RefinementCase<dim>::isotropic_refinement) const override; |
| 404 |
|
| 405 |
virtual const FullMatrix<double> & |
| 406 |
get_prolongation_matrix( |
| 407 |
const unsigned int child, |
| 408 |
const RefinementCase<dim> &refinement_case = |
| 409 |
RefinementCase<dim>::isotropic_refinement) const override; |
| 410 |
|
| 411 |
private: |
| 412 |
/** |
| 413 |
* This function returns @p true, if the shape function @p shape_index has |
| 414 |
* non-zero function values somewhere on the face @p face_index. |
| 415 |
*/ |
| 416 |
virtual bool |
| 417 |
has_support_on_face(const unsigned int shape_index, |
| 418 |
const unsigned int face_index) const override; |
| 419 |
|
| 420 |
/** |
| 421 |
* Initialize the permutation pattern and the pattern of sign change. |
| 422 |
*/ |
| 423 |
void |
| 424 |
initialize_quad_dof_index_permutation_and_sign_change(); |
| 425 |
|
| 426 |
/** |
| 427 |
* Mutex variables used for protecting the initialization of restriction |
| 428 |
* and embedding matrices. |
| 429 |
*/ |
| 430 |
mutable Threads::Mutex restriction_matrix_mutex; |
| 431 |
mutable Threads::Mutex prolongation_matrix_mutex; |
| 432 |
}; |
| 433 |
|
| 434 |
/** @} */ |
| 435 |
|
| 436 |
/* -------------- declaration of explicit specializations ------------- */ |
| 437 |
|
| 438 |
#ifndef DOXYGEN |
| 439 |
|
| 440 |
template <> |
| 441 |
void |
| 442 |
FE_RaviartThomas<1>::initialize_restriction(); |
| 443 |
|
| 444 |
#endif // DOXYGEN |
| 445 |
|
| 446 |
DEAL_II_NAMESPACE_CLOSE |
| 447 |
|
| 448 |
#endif |