Debian Codegraph @

include/deal.II/numerics/vector_tools_boundary.h

raw
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