| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2020 - 2024 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 |
|
| 16 |
#ifndef dealii_vector_tools_boundary_h |
| 17 |
#define dealii_vector_tools_boundary_h |
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/dofs/dof_handler.h> |
| 22 |
|
| 23 |
#include <deal.II/hp/mapping_collection.h> |
| 24 |
|
| 25 |
#include <map> |
| 26 |
|
| 27 |
DEAL_II_NAMESPACE_OPEN |
| 28 |
|
| 29 |
template <typename number> |
| 30 |
class AffineConstraints; |
| 31 |
template <int dim, int spacedim> |
| 32 |
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>)) |
| 33 |
class DoFHandler; |
| 34 |
template <int dim, typename Number> |
| 35 |
class Function; |
| 36 |
namespace hp |
| 37 |
{ |
| 38 |
template <int dim> |
| 39 |
class QCollection; |
| 40 |
} // namespace hp |
| 41 |
|
| 42 |
namespace VectorTools |
| 43 |
{ |
| 44 |
/** |
| 45 |
* @name Interpolation and projection |
| 46 |
*/ |
| 47 |
/** @{ */ |
| 48 |
|
| 49 |
/** |
| 50 |
* Compute constraints on the solution that corresponds to the imposition |
| 51 |
* of Dirichlet boundary conditions on parts of the boundary. |
| 52 |
* This function creates a map of |
| 53 |
* degrees of freedom subject to Dirichlet boundary conditions and the |
| 54 |
* corresponding values to be assigned to them, by interpolation around the |
| 55 |
* boundary. For each degree of freedom at the boundary, its boundary value |
| 56 |
* will be overwritten if its index already exists in @p boundary_values. |
| 57 |
* Otherwise, a new entry with proper index and boundary value for this |
| 58 |
* degree of freedom will be inserted into @p boundary_values. |
| 59 |
* |
| 60 |
* The parameter @p function_map provides a list of boundary indicators to |
| 61 |
* be handled by this function and corresponding boundary value functions. |
| 62 |
* The key of this map corresponds to the number @p boundary_id of the face. |
| 63 |
* numbers::internal_face_boundary_id is an illegal value for this key since |
| 64 |
* it is reserved for interior faces. For an example of how to use this |
| 65 |
* argument with a non-empty map, see the step-16 tutorial program. |
| 66 |
* |
| 67 |
* The flags in the last parameter, @p component_mask, denote which |
| 68 |
* components of the finite element space shall be interpolated. If it is |
| 69 |
* left as specified by the default value (i.e. an empty array), all |
| 70 |
* components are interpolated. If it is different from the default value, |
| 71 |
* it is assumed that the number of entries equals the number of components |
| 72 |
* in the boundary functions and the finite element, and those components in |
| 73 |
* the given boundary function will be used for which the respective flag |
| 74 |
* was set in the component mask. See also |
| 75 |
* @ref GlossComponentMask. |
| 76 |
* As an example, assume that you are solving the Stokes equations in 2d, |
| 77 |
* with variables $(u,v,p)$ and that you only want to interpolate boundary |
| 78 |
* values for the velocity, then the component mask should correspond to |
| 79 |
* <code>(true,true,false)</code>. |
| 80 |
* |
| 81 |
* @note Whether a component mask has been specified or not, the number of |
| 82 |
* components of the functions in @p function_map must match that of the |
| 83 |
* finite element used by @p dof. In other words, for the example above, you |
| 84 |
* need to provide a Function object that has 3 components (the two |
| 85 |
* velocities and the pressure), even though you are only interested in the |
| 86 |
* first two of them. interpolate_boundary_values() will then call this |
| 87 |
* function to obtain a vector of 3 values at each interpolation point but |
| 88 |
* only take the first two and discard the third. In other words, you are |
| 89 |
* free to return whatever you like in the third component of the vector |
| 90 |
* returned by Function::vector_value, but the Function object must state |
| 91 |
* that it has 3 components. |
| 92 |
* |
| 93 |
* If the finite element used has shape functions that are non-zero in more |
| 94 |
* than one component (in deal.II speak: they are non-primitive), then these |
| 95 |
* components can presently not be used for interpolating boundary values. |
| 96 |
* Thus, the elements in the component mask corresponding to the components |
| 97 |
* of these non-primitive shape functions must be @p false. |
| 98 |
* |
| 99 |
* @note This function applies the same ComponentMask to all parts of |
| 100 |
* the boundary indicated by keys of the `function_map` argument. |
| 101 |
* If you want to apply different component masks to parts of the boundary |
| 102 |
* represented by different boundary indicators, this function needs to be |
| 103 |
* called multiple times. For performance reasons, it might be reasonable to |
| 104 |
* use the present function by grouping together all boundary indicators with |
| 105 |
* the same ComponentMask. An alternative is to use one of the other |
| 106 |
* functions with this name, which take only one boundary indicator with |
| 107 |
* corresponding boundary function, to be called separately for every |
| 108 |
* boundary indicator. |
| 109 |
* |
| 110 |
* @note Mathematically, boundary conditions can only be applied to a |
| 111 |
* part of the boundary that has a nonzero $(d-1)$-dimensional measure; |
| 112 |
* in other words, it must be the union of *faces* of a mesh, rather than |
| 113 |
* a set of edges in 3d, or even just a few vertices. That is because |
| 114 |
* applying boundary conditions on individual vertices (rather than |
| 115 |
* on the entire face of which this vertex might be a part) would |
| 116 |
* correspond to using Dirac delta functions as boundary values, and |
| 117 |
* this generally leads to singular solutions that can not adequately |
| 118 |
* be resolved with the finite element method. These considerations |
| 119 |
* notwithstanding, people often do apply boundary conditions at individual |
| 120 |
* vertices -- in particular in solid mechanics, where one would then |
| 121 |
* impose constraints on one or all components of the displacement at a |
| 122 |
* vertex. This function does not support this operation: It works solely |
| 123 |
* by looping over faces, checking whether the boundary indicator of the |
| 124 |
* face is one of the ones of interest, and then considers all of the |
| 125 |
* degrees of freedom on the face; it does not consider vertices (or, |
| 126 |
* in 3d, edges) separately from the faces they are part of. But you can |
| 127 |
* impose constraints on individual vertices by looping over all cells, |
| 128 |
* over all vertices of each cell, and identifying whether this is the |
| 129 |
* vertex you care about; then you use DoFAccessor::vertex_dof_index() |
| 130 |
* to obtain the indices of the DoFs located on it. You can then |
| 131 |
* entries for these degrees of freedom by hand to the `std::map` |
| 132 |
* or AffineConstraints object you typically use to represent |
| 133 |
* boundary value constraints. |
| 134 |
* |
| 135 |
* @note When solving a partial differential equation with boundary |
| 136 |
* conditions $u|_{\partial\Omega}=g$ (on the entire boundary |
| 137 |
* $\partial\Omega$, or perhaps only on parts $\Gamma\subset\partial\Omega$ |
| 138 |
* of the boundary), |
| 139 |
* then this boundary condition is in general not satisfiable exactly |
| 140 |
* using finite elements in the form $u_h|_{\partial\Omega}=g$. That is |
| 141 |
* because the function $g$ is generally not a polynomial, whereas |
| 142 |
* $u_h|_{\partial\Omega}$ *is* a polynomial on each face of the |
| 143 |
* mesh that is located at the boundary. In other words, it is in |
| 144 |
* general not possible to *impose* such boundary condition; what one |
| 145 |
* *can* do, however, is to impose |
| 146 |
* @f[ u_h|_{\partial\Omega}=I_h^{\partial\Omega} g, @f] |
| 147 |
* where $I_h^{\partial\Omega} g$ is a function that equals $g$ at each node |
| 148 |
* of the finite element space located on the boundary, and is piecewise |
| 149 |
* polynomial in between. In other words, $I_h^{\partial\Omega}$ is an |
| 150 |
* *interpolation operator* and $I_h^{\partial\Omega} g$ are the |
| 151 |
* interpolated boundary values -- thus the name. The use of |
| 152 |
* $I_h^{\partial\Omega} g$ instead of $g$ as boundary values imposes |
| 153 |
* an additional error (in the same spirit as using quadrature introduces |
| 154 |
* an additional error compared to being able to compute the integrals of |
| 155 |
* the weak form exactly). In most cases, this additional error is of the |
| 156 |
* same order as the other error terms in the finite element method, |
| 157 |
* though there are some subtle differences when measuring the error in |
| 158 |
* the $L^2$ norm. For some details, see @cite Bartels2004 . |
| 159 |
* |
| 160 |
* @note An alternative to using the interpolant, |
| 161 |
* @f[ u_h|_{\partial\Omega}=I_h^{\partial\Omega} g @f] |
| 162 |
* is to use the *projection* of the boundary values $g$ onto the |
| 163 |
* finite element space on the boundary: |
| 164 |
* @f[ u_h|_{\partial\Omega}=\Pi_h^{\partial\Omega} g. @f] |
| 165 |
* The projection is available using the project_boundary_values() |
| 166 |
* function. Using the projection may have some theoretical advantages |
| 167 |
* (see again @cite Bartels2004) but has the practical disadvantage |
| 168 |
* that computing the projection is far more expensive than computing |
| 169 |
* the interpolation because the latter can be done one face at a time |
| 170 |
* whereas the projection requires the solution of a problem on the entire |
| 171 |
* boundary. On the other hand, interpolation is only possible for |
| 172 |
* "nodal" finite element spaces (such as FE_Q, but not |
| 173 |
* FE_Q_Hierarchical), whereas the projection is always possible. |
| 174 |
* |
| 175 |
* See the general documentation of this namespace for more information. |
| 176 |
*/ |
| 177 |
template <int dim, int spacedim, typename number> |
| 178 |
void |
| 179 |
interpolate_boundary_values( |
| 180 |
const Mapping<dim, spacedim> &mapping, |
| 181 |
const DoFHandler<dim, spacedim> &dof, |
| 182 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 183 |
&function_map, |
| 184 |
std::map<types::global_dof_index, number> &boundary_values, |
| 185 |
const ComponentMask &component_mask = {}); |
| 186 |
|
| 187 |
/** |
| 188 |
* Like the previous function, but take a mapping collection to go with |
| 189 |
* DoFHandler objects with hp-capabilities. |
| 190 |
*/ |
| 191 |
template <int dim, int spacedim, typename number> |
| 192 |
void |
| 193 |
interpolate_boundary_values( |
| 194 |
const hp::MappingCollection<dim, spacedim> &mapping, |
| 195 |
const DoFHandler<dim, spacedim> &dof, |
| 196 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 197 |
&function_map, |
| 198 |
std::map<types::global_dof_index, number> &boundary_values, |
| 199 |
const ComponentMask &component_mask = {}); |
| 200 |
|
| 201 |
/** |
| 202 |
* Like the previous functions but without Mapping argument, using |
| 203 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt> internally. |
| 204 |
*/ |
| 205 |
template <int dim, int spacedim, typename number> |
| 206 |
void |
| 207 |
interpolate_boundary_values( |
| 208 |
const DoFHandler<dim, spacedim> &dof, |
| 209 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 210 |
&function_map, |
| 211 |
std::map<types::global_dof_index, number> &boundary_values, |
| 212 |
const ComponentMask &component_mask = {}); |
| 213 |
|
| 214 |
/** |
| 215 |
* Take only one boundary indicator with corresponding boundary function. |
| 216 |
* |
| 217 |
* @see |
| 218 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 219 |
*/ |
| 220 |
template <int dim, int spacedim, typename number> |
| 221 |
void |
| 222 |
interpolate_boundary_values( |
| 223 |
const Mapping<dim, spacedim> &mapping, |
| 224 |
const DoFHandler<dim, spacedim> &dof, |
| 225 |
const types::boundary_id boundary_indicator, |
| 226 |
const Function<spacedim, number> &boundary_function, |
| 227 |
std::map<types::global_dof_index, number> &boundary_values, |
| 228 |
const ComponentMask &component_mask = {}); |
| 229 |
|
| 230 |
/** |
| 231 |
* Like the previous function, but take a mapping collection to go with |
| 232 |
* DoFHandler objects with hp-capabilities. |
| 233 |
*/ |
| 234 |
template <int dim, int spacedim, typename number> |
| 235 |
void |
| 236 |
interpolate_boundary_values( |
| 237 |
const hp::MappingCollection<dim, spacedim> &mapping, |
| 238 |
const DoFHandler<dim, spacedim> &dof, |
| 239 |
const types::boundary_id boundary_indicator, |
| 240 |
const Function<spacedim, number> &boundary_function, |
| 241 |
std::map<types::global_dof_index, number> &boundary_values, |
| 242 |
const ComponentMask &component_mask = {}); |
| 243 |
|
| 244 |
/** |
| 245 |
* Like the previous functions but without Mapping argument, using |
| 246 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt> internally. |
| 247 |
* |
| 248 |
* @see |
| 249 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 250 |
*/ |
| 251 |
template <int dim, int spacedim, typename number> |
| 252 |
void |
| 253 |
interpolate_boundary_values( |
| 254 |
const DoFHandler<dim, spacedim> &dof, |
| 255 |
const types::boundary_id boundary_indicator, |
| 256 |
const Function<spacedim, number> &boundary_function, |
| 257 |
std::map<types::global_dof_index, number> &boundary_values, |
| 258 |
const ComponentMask &component_mask = {}); |
| 259 |
|
| 260 |
|
| 261 |
/** |
| 262 |
* Insert the (algebraic) constraints due to Dirichlet boundary conditions |
| 263 |
* into an AffineConstraints object. This function identifies the |
| 264 |
* degrees of freedom subject to Dirichlet boundary conditions, adds them to |
| 265 |
* the list of constrained DoFs in @p constraints and sets the respective |
| 266 |
* inhomogeneity to the value interpolated around the boundary. If this |
| 267 |
* routine encounters a DoF that already is constrained (for instance by a |
| 268 |
* hanging node constraint, see below, or any other type of constraint, e.g. |
| 269 |
* from periodic boundary conditions), the old setting of the constraint is |
| 270 |
* kept and nothing happens. |
| 271 |
* |
| 272 |
* @note When combining adaptively refined meshes with hanging node |
| 273 |
* constraints and boundary conditions like from the current function within |
| 274 |
* one AffineConstraints object, the hanging node constraints should always |
| 275 |
* be set first and then the boundary conditions, since boundary conditions |
| 276 |
* are not set in the second operation on degrees of freedom that are |
| 277 |
* already constrained. This makes sure that the discretization remains |
| 278 |
* conforming as is needed. See the discussion on conflicting constraints in |
| 279 |
* the topic on @ref constraints. |
| 280 |
* |
| 281 |
* For further information and details on the other function arguments, see |
| 282 |
* the interpolate_boundary_values() function with `std::map` arguments and |
| 283 |
* the general class documentation. |
| 284 |
* |
| 285 |
* @ingroup constraints |
| 286 |
*/ |
| 287 |
template <int dim, int spacedim, typename number> |
| 288 |
void |
| 289 |
interpolate_boundary_values( |
| 290 |
const Mapping<dim, spacedim> &mapping, |
| 291 |
const DoFHandler<dim, spacedim> &dof, |
| 292 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 293 |
&function_map, |
| 294 |
AffineConstraints<number> &constraints, |
| 295 |
const ComponentMask &component_mask = {}); |
| 296 |
|
| 297 |
/** |
| 298 |
* Like the previous function, but take a mapping collection to go with |
| 299 |
* DoFHandler objects with hp-capabilities. |
| 300 |
* |
| 301 |
* @ingroup constraints |
| 302 |
*/ |
| 303 |
template <int dim, int spacedim, typename number> |
| 304 |
void |
| 305 |
interpolate_boundary_values( |
| 306 |
const hp::MappingCollection<dim, spacedim> &mapping, |
| 307 |
const DoFHandler<dim, spacedim> &dof, |
| 308 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 309 |
&function_map, |
| 310 |
AffineConstraints<number> &constraints, |
| 311 |
const ComponentMask &component_mask = {}); |
| 312 |
|
| 313 |
/** |
| 314 |
* Like the previous functions but without Mapping argument, using |
| 315 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt> internally. |
| 316 |
* |
| 317 |
* @ingroup constraints |
| 318 |
*/ |
| 319 |
template <int dim, int spacedim, typename number> |
| 320 |
void |
| 321 |
interpolate_boundary_values( |
| 322 |
const DoFHandler<dim, spacedim> &dof, |
| 323 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 324 |
&function_map, |
| 325 |
AffineConstraints<number> &constraints, |
| 326 |
const ComponentMask &component_mask = {}); |
| 327 |
|
| 328 |
/** |
| 329 |
* Take only one boundary indicator with corresponding boundary function. |
| 330 |
* |
| 331 |
* @ingroup constraints |
| 332 |
* |
| 333 |
* @see |
| 334 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 335 |
*/ |
| 336 |
template <int dim, int spacedim, typename number> |
| 337 |
void |
| 338 |
interpolate_boundary_values( |
| 339 |
const Mapping<dim, spacedim> &mapping, |
| 340 |
const DoFHandler<dim, spacedim> &dof, |
| 341 |
const types::boundary_id boundary_indicator, |
| 342 |
const Function<spacedim, number> &boundary_function, |
| 343 |
AffineConstraints<number> &constraints, |
| 344 |
const ComponentMask &component_mask = {}); |
| 345 |
|
| 346 |
/** |
| 347 |
* Like the previous function, but take a mapping collection to go with |
| 348 |
* DoFHandler objects with hp-capabilities. |
| 349 |
* |
| 350 |
* @ingroup constraints |
| 351 |
*/ |
| 352 |
template <int dim, int spacedim, typename number> |
| 353 |
void |
| 354 |
interpolate_boundary_values( |
| 355 |
const hp::MappingCollection<dim, spacedim> &mapping, |
| 356 |
const DoFHandler<dim, spacedim> &dof, |
| 357 |
const types::boundary_id boundary_indicator, |
| 358 |
const Function<spacedim, number> &boundary_function, |
| 359 |
AffineConstraints<number> &constraints, |
| 360 |
const ComponentMask &component_mask = {}); |
| 361 |
|
| 362 |
/** |
| 363 |
* Like the previous functions but without Mapping argument, using |
| 364 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt> internally. |
| 365 |
* |
| 366 |
* @ingroup constraints |
| 367 |
* |
| 368 |
* @see |
| 369 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 370 |
*/ |
| 371 |
template <int dim, int spacedim, typename number> |
| 372 |
void |
| 373 |
interpolate_boundary_values( |
| 374 |
const DoFHandler<dim, spacedim> &dof, |
| 375 |
const types::boundary_id boundary_indicator, |
| 376 |
const Function<spacedim, number> &boundary_function, |
| 377 |
AffineConstraints<number> &constraints, |
| 378 |
const ComponentMask &component_mask = {}); |
| 379 |
|
| 380 |
|
| 381 |
/** |
| 382 |
* Project a function or a set of functions to the boundary of the domain. |
| 383 |
* In other words, compute the solution of the following problem: Find $u_h |
| 384 |
* \in V_h$ (where $V_h$ is the finite element space represented by the |
| 385 |
* DoFHandler argument of this function) so that |
| 386 |
* @f{align*}{ |
| 387 |
* \int_{\Gamma} \varphi_i u_h |
| 388 |
* = \sum_{k \in {\cal K}} \int_{\Gamma_k} \varphi_i f_k, |
| 389 |
* \qquad \forall \varphi_i \in V_h |
| 390 |
* @f} |
| 391 |
* where $\Gamma = \bigcup_{k \in {\cal K}} \Gamma_k$, $\Gamma_k \subset |
| 392 |
* \partial\Omega$, $\cal K$ is the set of indices and $f_k$ the |
| 393 |
* corresponding boundary functions represented in the function map argument |
| 394 |
* @p boundary_values to this function, and the integrals are evaluated by |
| 395 |
* quadrature. This problem has a non-unique solution in the interior, but |
| 396 |
* it is well defined for the degrees of freedom on the part of the |
| 397 |
* boundary, $\Gamma$, for which we do the integration. The values of |
| 398 |
* $u_h|_\Gamma$, i.e., the nodal values of the degrees of freedom of this |
| 399 |
* function along the boundary, are then what is computed by this function. |
| 400 |
* |
| 401 |
* In case this function is used with $H_{div}$ conforming finite element |
| 402 |
* space, the solution of a different problem is computed, namely: Find |
| 403 |
* $\vec{u}_h \in V_h \subset H(\text{div}; \Omega)$ so that |
| 404 |
* @f{align*}{ |
| 405 |
* \int_{\Gamma} (\vec{\varphi}_i \cdot \vec{n}) (\vec{u}_h \cdot \vec{n}) |
| 406 |
* = \sum_{k \in {\cal K}} \int_{\Gamma_k} (\vec{\varphi}_i \cdot \vec{n}) |
| 407 |
* (\vec{f}_k \cdot \vec{n}), |
| 408 |
* \qquad \forall \vec{\varphi_i} \in V_h, |
| 409 |
* @f} |
| 410 |
* where $\vec{n}$ is an outward normal vector. |
| 411 |
* |
| 412 |
* This function throws an exception if used with $H_\text{curl}$ conforming |
| 413 |
* elements, so the project_boundary_values_curl_conforming_l2() should be |
| 414 |
* used instead. |
| 415 |
* |
| 416 |
* @param[in] mapping The mapping that will be used in the transformations |
| 417 |
* necessary to integrate along the boundary. |
| 418 |
* @param[in] dof The DoFHandler that describes the finite element space and |
| 419 |
* the numbering of degrees of freedom. |
| 420 |
* @param[in] boundary_functions A map from boundary indicators to pointers |
| 421 |
* to functions that describe the desired values on those parts of the |
| 422 |
* boundary marked with this boundary indicator (see |
| 423 |
* @ref GlossBoundaryIndicator "Boundary indicator"). |
| 424 |
* The projection happens on only those parts of the boundary whose |
| 425 |
* indicators are represented in this map. |
| 426 |
* @param[in] q The face quadrature used in the integration necessary to |
| 427 |
* compute the @ref GlossMassMatrix "mass matrix" and right hand side of the projection. |
| 428 |
* @param[out] boundary_values The result of this function. It is a map |
| 429 |
* containing all indices of degrees of freedom at the boundary (as covered |
| 430 |
* by the boundary parts in @p boundary_functions) and the computed dof |
| 431 |
* value for this degree of freedom. For each degree of freedom at the |
| 432 |
* boundary, if its index already exists in @p boundary_values then its |
| 433 |
* boundary value will be overwritten, otherwise a new entry with proper |
| 434 |
* index and boundary value for this degree of freedom will be inserted into |
| 435 |
* @p boundary_values. |
| 436 |
* @param[in] component_mapping It is sometimes convenient to project a |
| 437 |
* vector-valued function onto only parts of a finite element space (for |
| 438 |
* example, to project a function with <code>dim</code> components onto the |
| 439 |
* velocity components of a <code>dim+1</code> component DoFHandler for a |
| 440 |
* Stokes problem). To allow for this, this argument allows components to be |
| 441 |
* remapped. If the vector is not empty, it has to have one entry for each |
| 442 |
* vector component of the finite element used in @p dof. This entry is the |
| 443 |
* component number in @p boundary_functions that should be used for this |
| 444 |
* component in @p dof. By default, no remapping is applied. |
| 445 |
* |
| 446 |
* @note Using the *projection* rather than the *interpolation* of |
| 447 |
* boundary values makes relatively little difference in |
| 448 |
* practice. That said, it is far more computationally expensive |
| 449 |
* to compute projections because the require the solution of a |
| 450 |
* problem that couples all unknowns on the boundary, whereas |
| 451 |
* interpolation works on one face at a time. On the other hand, |
| 452 |
* interpolation is only possible for "nodal" finite element |
| 453 |
* spaces (such as FE_Q, but not FE_Q_Hierarchical), whereas the |
| 454 |
* projection is always possible. (For some more theoretical |
| 455 |
* considerations, see the documentation of the first |
| 456 |
* interpolate_boundary_values() function above.) |
| 457 |
*/ |
| 458 |
template <int dim, int spacedim, typename number> |
| 459 |
void |
| 460 |
project_boundary_values( |
| 461 |
const Mapping<dim, spacedim> &mapping, |
| 462 |
const DoFHandler<dim, spacedim> &dof, |
| 463 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 464 |
&boundary_functions, |
| 465 |
const Quadrature<dim - 1> &q, |
| 466 |
std::map<types::global_dof_index, number> &boundary_values, |
| 467 |
std::vector<unsigned int> component_mapping = {}); |
| 468 |
|
| 469 |
/** |
| 470 |
* Call the project_boundary_values() function, see above, with |
| 471 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt>. |
| 472 |
*/ |
| 473 |
template <int dim, int spacedim, typename number> |
| 474 |
void |
| 475 |
project_boundary_values( |
| 476 |
const DoFHandler<dim, spacedim> &dof, |
| 477 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 478 |
&boundary_function, |
| 479 |
const Quadrature<dim - 1> &q, |
| 480 |
std::map<types::global_dof_index, number> &boundary_values, |
| 481 |
std::vector<unsigned int> component_mapping = {}); |
| 482 |
|
| 483 |
/** |
| 484 |
* Same as above, but with hp-capabilities. |
| 485 |
*/ |
| 486 |
template <int dim, int spacedim, typename number> |
| 487 |
void |
| 488 |
project_boundary_values( |
| 489 |
const hp::MappingCollection<dim, spacedim> &mapping, |
| 490 |
const DoFHandler<dim, spacedim> &dof, |
| 491 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 492 |
&boundary_functions, |
| 493 |
const hp::QCollection<dim - 1> &q, |
| 494 |
std::map<types::global_dof_index, number> &boundary_values, |
| 495 |
std::vector<unsigned int> component_mapping = {}); |
| 496 |
|
| 497 |
/** |
| 498 |
* Call the project_boundary_values() function, see above, with |
| 499 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt>. |
| 500 |
*/ |
| 501 |
template <int dim, int spacedim, typename number> |
| 502 |
void |
| 503 |
project_boundary_values( |
| 504 |
const DoFHandler<dim, spacedim> &dof, |
| 505 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 506 |
&boundary_function, |
| 507 |
const hp::QCollection<dim - 1> &q, |
| 508 |
std::map<types::global_dof_index, number> &boundary_values, |
| 509 |
std::vector<unsigned int> component_mapping = {}); |
| 510 |
|
| 511 |
/** |
| 512 |
* Project a function to the boundary of the domain, using the given |
| 513 |
* quadrature formula for the faces. This function identifies the degrees of |
| 514 |
* freedom subject to Dirichlet boundary conditions, adds them to the list |
| 515 |
* of constrained DoFs in @p constraints and sets the respective |
| 516 |
* inhomogeneity to the value resulting from the projection operation. If |
| 517 |
* this routine encounters a DoF that already is constrained (for instance |
| 518 |
* by a hanging node constraint, see below, or any other type of constraint, |
| 519 |
* e.g. from periodic boundary conditions), the old setting of the |
| 520 |
* constraint (dofs the entry is constrained to, inhomogeneities) is kept |
| 521 |
* and nothing happens. |
| 522 |
* |
| 523 |
* @note When combining adaptively refined meshes with hanging node |
| 524 |
* constraints and boundary conditions like from the current function within |
| 525 |
* one AffineConstraints object, the hanging node constraints should always |
| 526 |
* be set first, and then the boundary conditions since boundary conditions |
| 527 |
* are not set in the second operation on degrees of freedom that are |
| 528 |
* already constrained. This makes sure that the discretization remains |
| 529 |
* conforming as is needed. See the discussion on conflicting constraints in |
| 530 |
* the topic on |
| 531 |
* @ref constraints. |
| 532 |
* |
| 533 |
* If @p component_mapping is empty, it is assumed that the number of |
| 534 |
* components of @p boundary_function matches that of the finite element |
| 535 |
* used by @p dof. |
| 536 |
* |
| 537 |
* In 1d, projection equals interpolation. Therefore, |
| 538 |
* interpolate_boundary_values is called. |
| 539 |
* |
| 540 |
* @arg @p component_mapping: if the components in @p boundary_functions and |
| 541 |
* @p dof do not coincide, this vector allows them to be remapped. If the |
| 542 |
* vector is not empty, it has to have one entry for each component in @p |
| 543 |
* dof. This entry is the component number in @p boundary_functions that |
| 544 |
* should be used for this component in @p dof. By default, no remapping is |
| 545 |
* applied. |
| 546 |
* |
| 547 |
* @ingroup constraints |
| 548 |
*/ |
| 549 |
template <int dim, int spacedim, typename number> |
| 550 |
void |
| 551 |
project_boundary_values( |
| 552 |
const Mapping<dim, spacedim> &mapping, |
| 553 |
const DoFHandler<dim, spacedim> &dof, |
| 554 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 555 |
&boundary_functions, |
| 556 |
const Quadrature<dim - 1> &q, |
| 557 |
AffineConstraints<number> &constraints, |
| 558 |
std::vector<unsigned int> component_mapping = {}); |
| 559 |
|
| 560 |
/** |
| 561 |
* Call the project_boundary_values() function, see above, with |
| 562 |
* <tt>mapping=MappingQ@<dim,spacedim@>(1)</tt>. |
| 563 |
* |
| 564 |
* @ingroup constraints |
| 565 |
*/ |
| 566 |
template <int dim, int spacedim, typename number> |
| 567 |
void |
| 568 |
project_boundary_values( |
| 569 |
const DoFHandler<dim, spacedim> &dof, |
| 570 |
const std::map<types::boundary_id, const Function<spacedim, number> *> |
| 571 |
&boundary_function, |
| 572 |
const Quadrature<dim - 1> &q, |
| 573 |
AffineConstraints<number> &constraints, |
| 574 |
std::vector<unsigned int> component_mapping = {}); |
| 575 |
|
| 576 |
/** |
| 577 |
* This function is an updated version of the |
| 578 |
* project_boundary_values_curl_conforming function. The intention is to fix |
| 579 |
* a problem when using the previous function in conjunction with |
| 580 |
* non-rectangular geometries (i.e. elements with non-rectangular faces). The |
| 581 |
* L2-projection method used has been taken from the paper "Electromagnetic |
| 582 |
* scattering simulation using an H (curl) conforming hp-finite element |
| 583 |
* method in three dimensions" by PD Ledger, K Morgan and O Hassan ( Int. J. |
| 584 |
* Num. Meth. Fluids, Volume 53, Issue 8, pages 1267-1296). |
| 585 |
* |
| 586 |
* This function will compute constraints that correspond to Dirichlet |
| 587 |
* boundary conditions of the form |
| 588 |
* $\vec{n}\times\vec{E}=\vec{n}\times\vec{F}$ i.e. the tangential |
| 589 |
* components of $\vec{E}$ and $f$ shall coincide. |
| 590 |
* |
| 591 |
* <h4>Computing constraints</h4> |
| 592 |
* |
| 593 |
* To compute the constraints we use a projection method based upon the |
| 594 |
* paper mentioned above. In 2d this is done in a single stage for the |
| 595 |
* edge-based shape functions, regardless of the order of the finite element. |
| 596 |
* In 3d this is done in two stages, edges first and then faces. |
| 597 |
* |
| 598 |
* For each cell, each edge, $e$, is projected by solving the linear system |
| 599 |
* $Ax=b$ where $x$ is the vector of constraints on degrees of freedom on the |
| 600 |
* edge and |
| 601 |
* |
| 602 |
* $A_{ij} = \int_{e} (\vec{s}_{i}\cdot\vec{t})(\vec{s}_{j}\cdot\vec{t}) dS$ |
| 603 |
* |
| 604 |
* $b_{i} = \int_{e} (\vec{s}_{i}\cdot\vec{t})(\vec{F}\cdot\vec{t}) dS$ |
| 605 |
* |
| 606 |
* with $\vec{s}_{i}$ the $i^{th}$ shape function and $\vec{t}$ the tangent |
| 607 |
* vector. |
| 608 |
* |
| 609 |
* Once all edge constraints, $x$, have been computed, we may compute the |
| 610 |
* face constraints in a similar fashion, taking into account the residuals |
| 611 |
* from the edges. |
| 612 |
* |
| 613 |
* For each face on the cell, $f$, we solve the linear system $By=c$ where |
| 614 |
* $y$ is the vector of constraints on degrees of freedom on the face and |
| 615 |
* |
| 616 |
* $B_{ij} = \int_{f} (\vec{n} \times \vec{s}_{i}) \cdot (\vec{n} \times |
| 617 |
* \vec{s}_{j}) dS$ |
| 618 |
* |
| 619 |
* $c_{i} = \int_{f} (\vec{n} \times \vec{r}) \cdot (\vec{n} \times |
| 620 |
* \vec{s}_i) dS$ |
| 621 |
* |
| 622 |
* and $\vec{r} = \vec{F} - \sum_{e \in f} \sum{i \in e} x_{i}\vec{s}_i$, |
| 623 |
* the edge residual. |
| 624 |
* |
| 625 |
* The resulting constraints are then given in the solutions $x$ and $y$. |
| 626 |
* |
| 627 |
* If the AffineConstraints @p constraints contained values or other |
| 628 |
* constraints before, the new ones are added or the old ones overwritten, |
| 629 |
* if a node of the boundary part to be used was already in the list of |
| 630 |
* constraints. This is handled by using inhomogeneous constraints. Please |
| 631 |
* note that when combining adaptive meshes and this kind of constraints, |
| 632 |
* the Dirichlet conditions should be set first, and then completed by |
| 633 |
* hanging node constraints, in order to make sure that the discretization |
| 634 |
* remains consistent. See the discussion on conflicting constraints in the |
| 635 |
* topic on |
| 636 |
* @ref constraints. |
| 637 |
* |
| 638 |
* <h4>Arguments to this function</h4> |
| 639 |
* |
| 640 |
* This function is explicitly for use with FE_Nedelec elements, or with |
| 641 |
* FESystem elements which contain FE_Nedelec elements. It will throw an |
| 642 |
* exception if called with any other finite element. The user must ensure |
| 643 |
* that FESystem elements are correctly setup when using this function as |
| 644 |
* this check not possible in this case. |
| 645 |
* |
| 646 |
* The second argument of this function denotes the first vector component |
| 647 |
* of the finite element which corresponds to the vector function that you |
| 648 |
* wish to constrain. For example, if we are solving Maxwell's equations in |
| 649 |
* 3d and have components $(E_x,E_y,E_z,B_x,B_y,B_z)$ and we want the |
| 650 |
* boundary conditions $\vec{n}\times\vec{B}=\vec{n}\times\vec{f}$, then @p |
| 651 |
* first_vector_component would be 3. The @p boundary_function must return 6 |
| 652 |
* components in this example, with the first 3 corresponding to $\vec{E}$ |
| 653 |
* and the second 3 corresponding to $\vec{B}$. Vectors are implicitly |
| 654 |
* assumed to have exactly <code>dim</code> components that are ordered in |
| 655 |
* the same way as we usually order the coordinate directions, i.e. $x$-, |
| 656 |
* $y$-, and finally $z$-component. |
| 657 |
* |
| 658 |
* The parameter @p boundary_component corresponds to the number @p |
| 659 |
* boundary_id of the face. numbers::internal_face_boundary_id is an illegal |
| 660 |
* value, since it is reserved for interior faces. |
| 661 |
* |
| 662 |
* The last argument is denoted to compute the normal vector $\vec{n}$ at |
| 663 |
* the boundary points. |
| 664 |
* |
| 665 |
* |
| 666 |
* @ingroup constraints |
| 667 |
* |
| 668 |
* @see |
| 669 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 670 |
*/ |
| 671 |
template <int dim, typename number> |
| 672 |
void |
| 673 |
project_boundary_values_curl_conforming_l2( |
| 674 |
const DoFHandler<dim, dim> &dof_handler, |
| 675 |
const unsigned int first_vector_component, |
| 676 |
const Function<dim, number> &boundary_function, |
| 677 |
const types::boundary_id boundary_component, |
| 678 |
AffineConstraints<number> &constraints, |
| 679 |
const Mapping<dim> &mapping); |
| 680 |
|
| 681 |
|
| 682 |
/** |
| 683 |
* hp-namespace version of project_boundary_values_curl_conforming_l2 |
| 684 |
* (above). |
| 685 |
* |
| 686 |
* @ingroup constraints |
| 687 |
*/ |
| 688 |
template <int dim, typename number> |
| 689 |
void |
| 690 |
project_boundary_values_curl_conforming_l2( |
| 691 |
const DoFHandler<dim, dim> &dof_handler, |
| 692 |
const unsigned int first_vector_component, |
| 693 |
const Function<dim, number> &boundary_function, |
| 694 |
const types::boundary_id boundary_component, |
| 695 |
AffineConstraints<number> &constraints, |
| 696 |
const hp::MappingCollection<dim, dim> &mapping_collection = |
| 697 |
hp::StaticMappingQ1<dim>::mapping_collection); |
| 698 |
|
| 699 |
|
| 700 |
/** |
| 701 |
* Compute constraints that correspond to boundary conditions of the form |
| 702 |
* $\vec{n}^T\vec{u}=\vec{n}^T\vec{f}$, i.e. the normal components of the |
| 703 |
* solution $u$ and a given $f$ shall coincide. The function $f$ is given by |
| 704 |
* @p boundary_function and the resulting constraints are added to @p |
| 705 |
* constraints for faces with boundary indicator @p boundary_component. |
| 706 |
* |
| 707 |
* This function is explicitly written to use with the FE_RaviartThomas |
| 708 |
* elements. Thus it throws an exception, if it is called with other finite |
| 709 |
* elements. |
| 710 |
* |
| 711 |
* If the AffineConstraints object @p constraints contained values or other |
| 712 |
* constraints before, the new ones are added or the old ones overwritten, |
| 713 |
* if a node of the boundary part to be used was already in the list of |
| 714 |
* constraints. This is handled by using inhomogeneous constraints. Please |
| 715 |
* note that when combining adaptive meshes and this kind of constraints, |
| 716 |
* the Dirichlet conditions should be set first, and then completed by |
| 717 |
* hanging node constraints, in order to make sure that the discretization |
| 718 |
* remains consistent. See the discussion on conflicting constraints in the |
| 719 |
* topic on |
| 720 |
* @ref constraints. |
| 721 |
* |
| 722 |
* The argument @p first_vector_component denotes the first vector component |
| 723 |
* in the finite element that corresponds to the vector function $\vec{u}$ |
| 724 |
* that you want to constrain. Vectors are implicitly assumed to have |
| 725 |
* exactly <code>dim</code> components that are ordered in the same way as |
| 726 |
* we usually order the coordinate directions, i.e., $x$-, $y$-, and finally |
| 727 |
* $z$-component. |
| 728 |
* |
| 729 |
* The parameter @p boundary_component corresponds to the @p boundary_id of |
| 730 |
* the faces where the boundary conditions are applied. |
| 731 |
* numbers::internal_face_boundary_id is an illegal value, since it is |
| 732 |
* reserved for interior faces. The @p mapping is used to compute the normal |
| 733 |
* vector $\vec{n}$ at the boundary points. |
| 734 |
* |
| 735 |
* <h4>Computing constraints</h4> |
| 736 |
* |
| 737 |
* To compute the constraints we use interpolation operator proposed in |
| 738 |
* Brezzi, Fortin (Mixed and Hybrid Finite Element Methods, Springer, 1991) |
| 739 |
* on every face located at the boundary. |
| 740 |
* |
| 741 |
* @ingroup constraints |
| 742 |
* |
| 743 |
* @see |
| 744 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 745 |
*/ |
| 746 |
template <int dim, typename number, typename number2 = number> |
| 747 |
void |
| 748 |
project_boundary_values_div_conforming( |
| 749 |
const DoFHandler<dim, dim> &dof_handler, |
| 750 |
const unsigned int first_vector_component, |
| 751 |
const Function<dim, number2> &boundary_function, |
| 752 |
const types::boundary_id boundary_component, |
| 753 |
AffineConstraints<number> &constraints, |
| 754 |
const Mapping<dim> &mapping); |
| 755 |
|
| 756 |
/** |
| 757 |
* Same as above for the hp-namespace. |
| 758 |
* |
| 759 |
* @ingroup constraints |
| 760 |
* |
| 761 |
* @see |
| 762 |
* @ref GlossBoundaryIndicator "Glossary entry on boundary indicators" |
| 763 |
*/ |
| 764 |
template <int dim, typename number, typename number2 = number> |
| 765 |
void |
| 766 |
project_boundary_values_div_conforming( |
| 767 |
const DoFHandler<dim, dim> &dof_handler, |
| 768 |
const unsigned int first_vector_component, |
| 769 |
const Function<dim, number2> &boundary_function, |
| 770 |
const types::boundary_id boundary_component, |
| 771 |
AffineConstraints<number> &constraints, |
| 772 |
const hp::MappingCollection<dim, dim> &mapping_collection = |
| 773 |
hp::StaticMappingQ1<dim>::mapping_collection); |
| 774 |
|
| 775 |
/** @} */ |
| 776 |
} // namespace VectorTools |
| 777 |
|
| 778 |
DEAL_II_NAMESPACE_CLOSE |
| 779 |
|
| 780 |
#endif // dealii_vector_tools_boundary_h |