Debian Codegraph @

include/deal.II/numerics/vector_tools_constraints.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_constraints_h
17 #define dealii_vector_tools_constraints_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/dofs/dof_handler.h>
22
23 #include <deal.II/multigrid/mg_constrained_dofs.h>
24
25 #include <map>
26 #include <set>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 template <typename number>
31 class AffineConstraints;
32 template <int dim, int spacedim>
33 struct StaticMappingQ1;
34 template <int dim, typename Number>
35 class Function;
36 template <int dim, int spacedim>
37 class Mapping;
38
39
40 namespace VectorTools
41 {
42 /**
43 * @name Interpolation and projection
44 */
45 /** @{ */
46
47 /**
48 * This function computes the constraints that correspond to boundary
49 * conditions of the form $\vec u \cdot \vec n=\vec u_\Gamma \cdot \vec n$,
50 * i.e., normal flux constraints where $\vec u$ is a vector-valued solution
51 * variable and $\vec u_\Gamma$ is a prescribed vector field whose normal
52 * component we want to be equal to the normal component of the solution.
53 * These conditions have exactly the form handled by the
54 * AffineConstraints class, in that they relate a <i>linear
55 * combination</i> of boundary degrees of freedom to a corresponding
56 * value (the inhomogeneity of the constraint). Consequently, the current
57 * function creates a list of constraints that are written into an
58 * AffineConstraints container. This object may already have some
59 * content, for example from hanging node constraints, that remains
60 * untouched. These constraints have to be applied to the linear system
61 * like any other such constraints, i.e., you have to condense the linear
62 * system with the constraints before solving, and you have to distribute
63 * the solution vector afterwards.
64 *
65 * This function treats a more general case than
66 * VectorTools::compute_no_normal_flux_constraints() (which can only handle
67 * the case where $\vec u_\Gamma \cdot \vec n = 0$, and is used in
68 * step-31 and step-32). However, because everything that would apply
69 * to that function also applies as a special case to the current
70 * function, the following discussion is relevant to both.
71 *
72 * @note This function doesn't make much sense in 1d, so it throws an
73 * exception if @p dim equals one.
74 *
75 *
76 * <h4>Arguments to this function</h4>
77 *
78 * The second argument of this function denotes the first vector component
79 * in the finite element that corresponds to the vector function that you
80 * want to constrain. For example, if we were solving a Stokes equation in
81 * 2d and the finite element had components $(u,v,p)$, then @p
82 * first_vector_component needs to be zero if you intend to constraint
83 * the vector $(u,v)^T \cdot \vec n = \vec u_\Gamma \cdot \vec n$.
84 * On the other hand, if we solved the
85 * Maxwell equations in 3d and the finite element has components
86 * $(E_x,E_y,E_z,B_x,B_y,B_z)$ and we want the boundary condition $\vec
87 * B\cdot \vec n=\vec B_\Gamma\cdot \vec n$, then @p first_vector_component
88 * would be 3. Vectors are implicitly assumed to have exactly
89 * <code>dim</code> components that are ordered in the same way as we
90 * usually order the coordinate directions, i.e. $x$-, $y$-, and finally
91 * $z$-component. The function assumes, but can't check, that the vector
92 * components in the range
93 * <code>[first_vector_component,first_vector_component+dim)</code> come
94 * from the same base finite element. For example, in the Stokes example
95 * above, it would not make sense to use a
96 * <code>FESystem@<dim@>(FE_Q@<dim@>(2), 1, FE_Q@<dim@>(1), dim)</code>
97 * (note that the first velocity vector component is a $Q_2$ element,
98 * whereas all the other ones are $Q_1$ elements) as there would be points
99 * on the boundary where the $x$-velocity is defined but no corresponding
100 * $y$- or $z$-velocities.
101 *
102 * The third argument denotes the set of boundary indicators on which the
103 * boundary condition is to be enforced. Note that, as explained below, this
104 * is one of the few functions where it makes a difference where we call the
105 * function multiple times with only one boundary indicator, or whether we
106 * call the function once with the whole set of boundary indicators at once.
107 *
108 * Argument four (@p function_map) describes the boundary function $\vec
109 * u_\Gamma$ for each boundary id. The function <code>function_map[id]</code>
110 * is used on boundary with id @p id taken from the set @p boundary_ids.
111 * Each function in @p function_map is expected to have @p dim
112 * components, which are used independent of @p first_vector_component.
113 *
114 * The mapping argument is used to compute the location of points on the
115 * boundary at which the function needs to request the normal vector
116 * $\vec n$ from the Manifold description if @p use_manifold_for_normal is
117 * set. If this parameter is not set, the mapping is used for computing the
118 * normal. This is useful, e.g., in the case that the mapping describes
119 * a deformation (e.g., MappingQCache, MappingQEulerian, MappingFEField).
120 *
121 * @note When combining adaptively refined meshes with hanging node
122 * constraints and boundary conditions like from the current function within
123 * one AffineConstraints object, the hanging node constraints should always
124 * be set first, and then the boundary conditions since boundary conditions
125 * are not set in the second operation on degrees of freedom that are
126 * already constrained. This makes sure that the discretization remains
127 * conforming as is needed. See the discussion on conflicting constraints in
128 * the topic on
129 * @ref constraints.
130 *
131 *
132 * <h4>Computing constraints in 2d</h4>
133 *
134 * Computing these constraints requires some smarts. The main question
135 * revolves around the question what the normal vector is. Consider the
136 * following situation:
137 *
138 * <p ALIGN="center">
139 * @image html no_normal_flux_1.png
140 * </p>
141 *
142 * Here, we have two cells that use a bilinear mapping (i.e.,
143 * MappingQ(1)). Consequently, for each of the cells, the normal
144 * vector is perpendicular to the straight edge. If the two edges at the top
145 * and right are meant to approximate a curved boundary (as indicated by the
146 * dashed line), then neither of the two computed normal vectors are equal
147 * to the exact normal vector (though they approximate it as the mesh is
148 * refined further). What is worse, if we constrain $\vec u \cdot \vec n=
149 * \vec u_\Gamma \cdot \vec n$ at the common vertex with the normal vector
150 * from both cells, then we constrain the vector $\vec u$ with respect to
151 * two linearly independent vectors; consequently, the constraint would be
152 * $\vec u=\vec u_\Gamma$ at this point (i.e. <i>all</i> components of the
153 * vector), which is not what we wanted.
154 *
155 * To deal with this situation, the algorithm works in the following way: at
156 * each point where we want to constrain $\vec u$, we first collect all
157 * normal vectors that adjacent cells might compute at this point. We then
158 * do not constrain $\vec u \cdot \vec n=\vec u_\Gamma \cdot \vec n$ for
159 * <i>each</i> of these normal vectors but only for the <i>average</i> of
160 * the normal vectors. In the example above, we therefore record only a
161 * single constraint $\vec u \cdot \vec {\bar n}=\vec u_\Gamma \cdot \vec
162 * {\bar n}$, where $\vec {\bar n}$ is the average of the two indicated
163 * normal vectors.
164 *
165 * Unfortunately, this is not quite enough. Consider the situation here:
166 *
167 * <p ALIGN="center">
168 * @image html no_normal_flux_2.png
169 * </p>
170 *
171 * If again the top and right edges approximate a curved boundary, and the
172 * left boundary a separate boundary (for example straight) so that the
173 * exact boundary has indeed a corner at the top left vertex, then the above
174 * construction would not work: here, we indeed want the constraint that
175 * $\vec u$ at this point (because the normal velocities with respect to
176 * both the left normal as well as the top normal vector should be zero),
177 * not that the velocity in the direction of the average normal vector is
178 * zero.
179 *
180 * Consequently, we use the following heuristic to determine whether all
181 * normal vectors computed at one point are to be averaged: if two normal
182 * vectors for the same point are computed on <i>different</i> cells, then
183 * they are to be averaged. This covers the first example above. If they are
184 * computed from the same cell, then the fact that they are different is
185 * considered indication that they come from different parts of the boundary
186 * that might be joined by a real corner, and must not be averaged.
187 *
188 * There is one problem with this scheme. If, for example, the same domain
189 * we have considered above, is discretized with the following mesh, then we
190 * get into trouble:
191 *
192 * <p ALIGN="center">
193 * @image html no_normal_flux_3.png
194 * </p>
195 *
196 * Here, the algorithm assumes that the boundary does not have a corner at
197 * the point where faces $F1$ and $F2$ join because at that point there are
198 * two different normal vectors computed from different cells. If you intend
199 * for there to be a corner of the exact boundary at this point, the only
200 * way to deal with this is to assign the two parts of the boundary
201 * different boundary indicators and call this function twice, once for each
202 * boundary indicators; doing so will yield only one normal vector at this
203 * point per invocation (because we consider only one boundary part at a
204 * time), with the result that the normal vectors will not be averaged. This
205 * situation also needs to be taken into account when using this function
206 * around reentrant corners on Cartesian meshes. If normal-flux boundary
207 * conditions are to be enforced on non-Cartesian meshes around reentrant
208 * corners, one may even get cycles in the constraints as one will in
209 * general constrain different components from the two sides. In that case,
210 * set a no-slip constraint on the reentrant vertex first.
211 *
212 *
213 * <h4>Computing constraints in 3d</h4>
214 *
215 * The situation is more complicated in 3d. Consider the following case
216 * where we want to compute the constraints at the marked vertex:
217 *
218 * <p ALIGN="center">
219 * @image html no_normal_flux_4.png
220 * </p>
221 *
222 * Here, we get four different normal vectors, one from each of the four
223 * faces that meet at the vertex. Even though they may form a complete set
224 * of vectors, it is not our intent to constrain all components of the
225 * vector field at this point. Rather, we would like to still allow
226 * tangential flow, where the term "tangential" has to be suitably defined.
227 *
228 * In a case like this, the algorithm proceeds as follows: for each cell
229 * that has computed two tangential vectors at this point, we compute the
230 * unconstrained direction as the outer product of the two tangential
231 * vectors (if necessary multiplied by minus one). We then average these
232 * tangential vectors. Finally, we compute constraints for the two
233 * directions perpendicular to this averaged tangential direction.
234 *
235 * There are cases where one cell contributes two tangential directions and
236 * another one only one; for example, this would happen if both top and
237 * front faces of the left cell belong to the boundary selected whereas only
238 * the top face of the right cell belongs to it, maybe indicating that the
239 * entire front part of the domain is a smooth manifold whereas the top
240 * really forms two separate manifolds that meet in a ridge, and that
241 * normal-flux boundary conditions are only desired on the front manifold
242 * and the right one on top. In cases like these, it's difficult to define
243 * what should happen. The current implementation simply ignores the one
244 * contribution from the cell that only contributes one normal vector. In
245 * the example shown, this is acceptable because the normal vector for the
246 * front face of the left cell is the same as the normal vector provided by
247 * the front face of the right cell (the surface is planar) but it would be
248 * a problem if the front manifold would be curved. Regardless, it is
249 * unclear how one would proceed in this case and ignoring the single cell
250 * is likely the best one can do.
251 *
252 *
253 * <h4>Results</h4>
254 *
255 * Because it makes for good pictures, here are two images of vector fields
256 * on a circle and on a sphere to which the constraints computed by this
257 * function have been applied (for illustration purposes, we enforce zero
258 * normal flux, which can more easily be computed using
259 * VectorTools::compute_no_normal_flux_constraints(), as this must
260 * lead to a <i>tangential</i> vector field):
261 *
262 * <p ALIGN="center">
263 * @image html no_normal_flux_5.png
264 * @image html no_normal_flux_6.png
265 * </p>
266 *
267 * The vectors fields are not physically reasonable but the tangentiality
268 * constraint is clearly enforced. The fact that the vector fields are zero
269 * at some points on the boundary is an artifact of the way it is created,
270 * it is not constrained to be zero at these points.
271 *
272 *
273 * <h4>Further reading</h4>
274 *
275 * A description of some of the techniques used in this function,
276 * along with a discussion of difficulties encountered with this
277 * kind of boundary conditions can be found in @cite Engelman1982 .
278 *
279 * @ingroup constraints
280 *
281 * @see
282 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
283 */
284 template <int dim, int spacedim>
285 void
286 compute_nonzero_normal_flux_constraints(
287 const DoFHandler<dim, spacedim> &dof_handler,
288 const unsigned int first_vector_component,
289 const std::set<types::boundary_id> &boundary_ids,
290 const std::map<types::boundary_id, const Function<spacedim, double> *>
291 &function_map,
292 AffineConstraints<double> &constraints,
293 const Mapping<dim, spacedim> &mapping =
294 (ReferenceCells::get_hypercube<dim>()
295 #ifndef _MSC_VER
296 .template get_default_linear_mapping<dim, spacedim>()
297 #else
298 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
299 #endif
300 ),
301 const bool use_manifold_for_normal = true);
302
303 /**
304 * This function does the same as
305 * compute_nonzero_normal_flux_constraints(), but for the case of multigrid
306 * levels.
307 * @ingroup constraints
308 *
309 * @see
310 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
311 */
312 template <int dim, int spacedim>
313 void
314 compute_nonzero_normal_flux_constraints_on_level(
315 const DoFHandler<dim, spacedim> &dof_handler,
316 const unsigned int first_vector_component,
317 const std::set<types::boundary_id> &boundary_ids,
318 const std::map<types::boundary_id, const Function<spacedim, double> *>
319 &function_map,
320 AffineConstraints<double> &constraints,
321 const Mapping<dim, spacedim> &mapping =
322 (ReferenceCells::get_hypercube<dim>()
323 #ifndef _MSC_VER
324 .template get_default_linear_mapping<dim, spacedim>()
325 #else
326 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
327 #endif
328 ),
329 const IndexSet &refinement_edge_indices = IndexSet(),
330 const unsigned int level = numbers::invalid_unsigned_int,
331 const bool use_manifold_for_normal = true);
332
333 /**
334 * This function does the same as the
335 * compute_nonzero_normal_flux_constraints() function (see there for more
336 * information), but for the simpler case of homogeneous normal-flux
337 * constraints, i.e., for imposing the condition
338 * $\vec u \cdot \vec n= 0$. This function is used in step-31 and step-32.
339 *
340 * To compute no normal-flux constraints for a specific multigrid level for
341 * the geometric multigrid method, see
342 * compute_no_normal_flux_constraints_on_level().
343 *
344 * @ingroup constraints
345 *
346 * @see
347 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
348 */
349 template <int dim, int spacedim, typename number>
350 void
351 compute_no_normal_flux_constraints(
352 const DoFHandler<dim, spacedim> &dof_handler,
353 const unsigned int first_vector_component,
354 const std::set<types::boundary_id> &boundary_ids,
355 AffineConstraints<number> &constraints,
356 const Mapping<dim, spacedim> &mapping =
357 (ReferenceCells::get_hypercube<dim>()
358 #ifndef _MSC_VER
359 .template get_default_linear_mapping<dim, spacedim>()
360 #else
361 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
362 #endif
363 ),
364 const bool use_manifold_for_normal = true);
365
366 /**
367 * This function does the same as
368 * compute_no_normal_flux_constraints(), but for the case of geometric
369 * multigrid on the specified @p level. The @p refinement_edge_indices
370 * can be obtained by MGConstrainedDoFs::get_refinement_edge_indices()
371 * and should contain all indices of DoFs that are on refinement edges
372 * of the adaptively refined mesh.
373 *
374 * Also see compute_nonzero_normal_flux_constraints() for a detailed
375 * description about the implementation of this routine.
376 *
377 * @ingroup constraints
378 *
379 * @see
380 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
381 */
382 template <int dim, int spacedim>
383 void
384 compute_no_normal_flux_constraints_on_level(
385 const DoFHandler<dim, spacedim> &dof_handler,
386 const unsigned int first_vector_component,
387 const std::set<types::boundary_id> &boundary_ids,
388 AffineConstraints<double> &constraints,
389 const Mapping<dim, spacedim> &mapping =
390 (ReferenceCells::get_hypercube<dim>()
391 #ifndef _MSC_VER
392 .template get_default_linear_mapping<dim, spacedim>()
393 #else
394 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
395 #endif
396 ),
397 const IndexSet &refinement_edge_indices = IndexSet(),
398 const unsigned int level = numbers::invalid_unsigned_int,
399 const bool use_manifold_for_normal = true);
400
401 /**
402 * Compute the constraints that correspond to boundary conditions of the
403 * form $\vec u \times \vec n=\vec u_\Gamma \times \vec n$, i.e., tangential
404 * flow constraints where $\vec u$ is a vector-valued solution
405 * variable and $\vec u_\Gamma$ is prescribed vector field whose tangential
406 * component(s) we want to be equal to the tangential component(s) of the
407 * solution. This function constrains exactly those dim-1 vector-valued
408 * components that are left unconstrained by
409 * VectorTools::compute_no_normal_flux_constraints(), and leaves the one
410 * component unconstrained that is constrained by that function.
411 *
412 *
413 * <h4>Further reading</h4>
414 *
415 * A description of some of the techniques used in this function,
416 * along with a discussion of difficulties encountered with this
417 * kind of boundary conditions can be found in @cite Engelman1982 .
418 *
419 * @ingroup constraints
420 *
421 * @see
422 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
423 */
424 template <int dim, int spacedim>
425 void
426 compute_nonzero_tangential_flux_constraints(
427 const DoFHandler<dim, spacedim> &dof_handler,
428 const unsigned int first_vector_component,
429 const std::set<types::boundary_id> &boundary_ids,
430 const std::map<types::boundary_id, const Function<spacedim, double> *>
431 &function_map,
432 AffineConstraints<double> &constraints,
433 const Mapping<dim, spacedim> &mapping =
434 (ReferenceCells::get_hypercube<dim>()
435 #ifndef _MSC_VER
436 .template get_default_linear_mapping<dim, spacedim>()
437 #else
438 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
439 #endif
440 ),
441 const bool use_manifold_for_normal = true);
442
443 /**
444 * Same as above for homogeneous tangential-flux constraints.
445 *
446 * @ingroup constraints
447 *
448 * @see
449 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
450 */
451 template <int dim, int spacedim>
452 void
453 compute_normal_flux_constraints(
454 const DoFHandler<dim, spacedim> &dof_handler,
455 const unsigned int first_vector_component,
456 const std::set<types::boundary_id> &boundary_ids,
457 AffineConstraints<double> &constraints,
458 const Mapping<dim, spacedim> &mapping =
459 (ReferenceCells::get_hypercube<dim>()
460 #ifndef _MSC_VER
461 .template get_default_linear_mapping<dim, spacedim>()
462 #else
463 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
464 #endif
465 ),
466 const bool use_manifold_for_normal = true);
467
468 /** @} */
469 } // namespace VectorTools
470
471 DEAL_II_NAMESPACE_CLOSE
472
473 #endif // dealii_vector_tools_constraints_h